*    GeoTools - The Open Source Java GIS Toolkit

*    http://geotools.org

*

*    (C) 2005-2008, Open Source Geospatial Foundation (OSGeo)

*

*    This library is free software; you can redistribute it and/or

*    modify it under the terms of the GNU Lesser General Public

*    License as published by the Free Software Foundation;

*    version 2.1 of the License.

*

*    This library is distributed in the hope that it will be useful,

*    but WITHOUT ANY WARRANTY; without even the implied warranty of

*    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

*    Lesser General Public License for more details.

*/

* A coordinate reference system factory backed by the EPSG database tables.

* <p>

* The EPSG database is freely available at <A HREF="http://www.epsg.org">http://www.epsg.org</a>.

* Current version of this class requires EPSG database version 6.6 or above.

* <p>

* This factory makes use of a provided {@link ObjectCache}, and may be deployed in stand aline fashion;

* or as a worker for a {@link MultiEpsgFactory}.

* <p>

* This class is abstract - please see the subclasses for dialect specific implementations:

* <ul>

*   <li>{@link AccessDialectEpsgFactory}</li>

*   <li>{@link AnsiDialectEpsgFactory}</li>

*   <li>{@link OracleDialectEpsgFactory}</li>

* </ul>

*

* These factories accepts names as well as numerical identifiers. For example

* "<cite>NTF (Paris) / France I</cite>" and {@code "27581"} both fetchs the same object.

* However, names may be ambiguous since the same name may be used for more than one object.

* This is the case of "WGS 84" for example. If such an ambiguity is found, an exception

* will be thrown. If names are not wanted as a legal EPSG code, subclasses can override the

* {@link #isPrimaryKey} method.

*

* @since 2.4

*

*

* @source $URL$

* @version $Id$

* @author Yann Cézard

* @author Martin Desruisseaux (IRD)

* @author Rueben Schulz

* @author Matthias Basler

* @author Andrea Aime

*/

    /// Datum shift operation methods

    /** First Bursa-Wolf method.   */

    private static final int BURSA_WOLF_MIN_CODE = 9603;

    /** Last Bursa-Wolf method.   */

    private static final int BURSA_WOLF_MAX_CODE = 9607;

    /** Rotation frame method.   */

    private static final int ROTATION_FRAME_CODE = 9607;

    /** Dummy operation to ignore. */

    private static final int DUMMY_OPERATION     =    1;

    /**

     * The name for the transformation accuracy metadata.

     */

    private static final InternationalString TRANSFORMATION_ACCURACY =

            Vocabulary.formatInternational(VocabularyKeys.TRANSFORMATION_ACCURACY);

    /**

     * The calendar instance for creating {@link java.util.Date} objects from a year

     * (the "epoch" in datum definition). We use the local timezone, which may not be

     * quite accurate. But there is no obvious timezone for "epoch", and the "epoch"

     * is approximative anyway.

     */

    private final Calendar calendar = Calendar.getInstance(); // FIXME: move into factories?

    /**

     * The authority for this database. Will be created only when first needed.

     * This authority will contains the database version in the {@linkplain Citation#getEdition

     * edition} attribute, together with the {@linkplain Citation#getEditionDate edition date}.

     */

    private transient Citation authority; //FIXME: always EPSG

    /**

     * A DataSource to the EPSG database being used.

     */

    protected javax.sql.DataSource dataSource;

    /**

     * The connection to the EPSG database - this is create in a lazy manner from the DataSource.

     * <p>

     * This field is managed as part of our connection lifecycle.

     */

    private Connection connection;

    /**

     * A pool of prepared statements. Key are {@link String} object related to their

     * originating method name (for example "Ellipsoid" for {@link #createEllipsoid},

     * while values are {@link PreparedStatement} objects.

     * <p>

     * <strong>Note:</strong> It is okay to use {@link IdentityHashMap} instead of {@link HashMap}

     * because the keys will always be the exact same object, namely the hard-coded argument given

     * to calls to {@link #prepareStatement} in this class.

     * <p>

     * This field is managed as part of our connection lifecycle.

     */

    private final Map<String,PreparedStatement> statements = new IdentityHashMap<String,PreparedStatement>();

    /**

     * Last object type returned by {@link #createObject}, or -1 if none.

     * This type is an index in the {@link #TABLES_INFO} array and is

     * strictly for {@link #createObject} internal use.

     */

    private int lastObjectType = -1;

    /**

     * The last table in which object name were looked for. This is for internal use

     * by {@link #toPrimaryKey} only.

     */

    private transient String lastTableForName;

    /**

     * Cache for axis names. This service is not provided by {@link BufferedAuthorityFactory}

     * since {@link AxisName} object are particular to the EPSG database.

     *

     * @see #getAxisName

     */

    private final Map<String,AxisName> axisNames = new HashMap<String,AxisName>();

    /**

     * Cache for axis numbers. This service is not provided by {@link BufferedAuthorityFactory}

     * since the number of axis is used internally in this class.

     *

     * @see #getDimensionForCRS

     */

    private final Map<String,Short> axisCounts = new HashMap<String,Short>();

    /**

     * Cache for projection checks. This service is not provided by {@link BufferedAuthorityFactory}

     * since the check that a transformation is a projection is used internally in this class.

     *

     * @see #isProjection

     */

    private final Map<String,Boolean> codeProjection = new HashMap<String,Boolean>();

    /**

     * Pool of naming systems, used for caching.

     * There is usually few of them (about 15).

     */

    private final Map<String,LocalName> scopes = new HashMap<String,LocalName>();

    /**

     * The properties to be given the objects to construct.

     * Reused every time {@link #createProperties} is invoked.

     */

    private final Map<String,Object> properties = new HashMap<String,Object>();

    /**

     * A safety guard for preventing never-ending loops in recursive calls to

     * {@link #createDatum}. This is used by {@link #createBursaWolfParameters},

     * which need to create a target datum. The target datum could have its own

     * Bursa-Wolf parameters, with one of them pointing again to the source datum.

     */

    private final Set<String> safetyGuard = new HashSet<String>();

    public AbstractEpsgFactory(final Hints userHints ) throws FactoryException {

        super( MAXIMUM_PRIORITY-20 );

        // The following hints have no effect on this class behaviour,

        // but tell to the user what this factory do about axis order.

        hints.put(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.FALSE);

        hints.put(Hints.FORCE_STANDARD_AXIS_DIRECTIONS,   Boolean.FALSE);

        hints.put(Hints.FORCE_STANDARD_AXIS_UNITS,        Boolean.FALSE);

        //

        // We need to obtain our DataSource

        if (userHints != null) {

            Object hint = userHints.get(Hints.EPSG_DATA_SOURCE);

            if( hint instanceof String ){

                String name = (String) hint;

                try {

                    dataSource = (DataSource) GeoTools.getInitialContext(userHints).lookup(name);

                } catch (NamingException e) {

                    throw new FactoryException("A EPSG_DATA_SOURCE hint is required:"+e);

                }

                hints.put(Hints.EPSG_DATA_SOURCE, dataSource );

            }

            else if( hint instanceof DataSource ){

                dataSource = (DataSource) hint;

                hints.put(Hints.EPSG_DATA_SOURCE, dataSource );

            }

            else {

                throw new FactoryException("A EPSG_DATA_SOURCE hint is required.");

            }

        }

        else {

            throw new FactoryException("A EPSG_DATA_SOURCE hint is required.");

        }

    }

    public AbstractEpsgFactory(final Hints userHints, final javax.sql.DataSource dataSource) {

      super( MAXIMUM_PRIORITY-20 );

      this.dataSource = dataSource;

        // The following hints have no effect on this class behaviour,

        // but tell to the user what this factory do about axis order.

        hints.put(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.FALSE);

        hints.put(Hints.FORCE_STANDARD_AXIS_DIRECTIONS,   Boolean.FALSE);

        hints.put(Hints.FORCE_STANDARD_AXIS_UNITS,        Boolean.FALSE);

        hints.put(Hints.EPSG_DATA_SOURCE, dataSource );

    }

    /**

     * Constructs an authority factory using the specified connection.

     *

     * @param userHints The underlying factories used for objects creation.

     * @param connection The connection to the underlying EPSG database.

     */

    public AbstractEpsgFactory(final Hints userHints, final Connection connection) {

        super(MAXIMUM_PRIORITY-20, userHints );

        // The following hints have no effect on this class behaviour,

        // but tell to the user what this factory do about axis order.

        hints.put(Hints.FORCE_LONGITUDE_FIRST_AXIS_ORDER, Boolean.FALSE);

        hints.put(Hints.FORCE_STANDARD_AXIS_DIRECTIONS,   Boolean.FALSE);

        hints.put(Hints.FORCE_STANDARD_AXIS_UNITS,        Boolean.FALSE);

        this.connection = connection;

        ensureNonNull("connection", connection);