Package org.apache.sis.referencing.factory.sql

## Class EPSGFactory

- Object
- - AbstractFactory
  - - GeodeticAuthorityFactory
    - - ConcurrentAuthorityFactory<EPSGDataAccess>
      - - EPSGFactory

- All Implemented Interfaces:
    `AutoCloseable`, `Localized`, `AuthorityFactory`, `CRSAuthorityFactory`, `CSAuthorityFactory`, `DatumAuthorityFactory`, `CoordinateOperationAuthorityFactory`, `Factory`

      public class EPSGFactory
      extends ConcurrentAuthorityFactory<EPSGDataAccess>
      implements CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory, Localized

  A geodetic object factory backed by the EPSG database. This class creates JDBC connections to the EPSG database when first needed using the `DataSource` specified at construction time. The geodetic objects are cached for reuse and the idle connections are closed after a timeout.

  If no data source has been specified to the constructor, then `EPSGFactory` searches for a default data source in JNDI, or in the directory given by the `SIS_DATA` environment variable, or in the directory given by the `"derby​​.system​​.home"` property, in that order. See the package documentation for more information.

  EPSG dataset installation
  This class tries to automatically detect the schema that contains the EPSG tables (see `SQLTranslator` for examples of tables to look for). If the tables are not found, then the `install(Connection)` method will be invoked for creating the EPSG schema. The `install(…)` method can perform its work only if the definition files are reachable on the classpath, or if the directory containing the files have been specified.
  Data Access Object (DAO)
  If there is no cached object for a given code, then `EPSGFactory` creates an `EPSGDataAccess` instance for performing the actual creation work. Developers who need to customize the geodetic object creation can override the `newDataAccess(Connection, SQLTranslator)` method in order to return their own `EPSGDataAccess` subclass.
  Since:
    0.7
  See Also:
    `EPSGDataAccess`, `SQLTranslator`, List of authority codes

  Defined in the `sis-referencing` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected CoordinateOperationFactory` | `copFactory` | The factory to use for creating `CoordinateOperation` instances from the properties read in the database.
    `protected CRSFactory` | `crsFactory` | The factory to use for creating `CoordinateReferenceSystem` instances from the properties read in the database.
    `protected CSFactory` | `csFactory` | The factory to use for creating `CoordinateSystem` instances from the properties read in the database.
    `protected DataSource` | `dataSource` | The factory to use for creating `Connection`s to the EPSG database.
    `protected DatumFactory` | `datumFactory` | The factory to use for creating `Datum` instances from the properties read in the database.
    `protected MathTransformFactory` | `mtFactory` | The factory to use for creating `MathTransform` instances.
    `protected NameFactory` | `nameFactory` | The factory to use for creating `GenericName` instances.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `EPSGFactory​(Map<String,​?> properties)` | Creates a factory using the given configuration.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `canClose​(EPSGDataAccess factory)` | Returns `true` if the given Data Access Object (DAO) can be closed.
    `Set<String>` | `getCodeSpaces()` | Returns the namespace of EPSG codes.
    `Locale` | `getLocale()` | Returns the locale used by this factory for producing error messages.
    `void` | `install​(Connection connection)` | Creates the EPSG schema in the database and populates the tables with geodetic definitions.
    `protected boolean` | `isCacheable​(String code, Object object)` | Returns whether the given object can be cached.
    `protected EPSGDataAccess` | `newDataAccess()` | Creates the factory which will perform the actual geodetic object creation work.
    `protected EPSGDataAccess` | `newDataAccess​(Connection connection, SQLTranslator translator)` | Creates the factory which will perform the actual geodetic object creation from a given connection.

    - ### Methods inherited from class ConcurrentAuthorityFactory

      `close, createCartesianCS, createCompoundCRS, createCoordinateOperation, createCoordinateReferenceSystem, createCoordinateSystem, createCoordinateSystemAxis, createCylindricalCS, createDatum, createDerivedCRS, createEllipsoid, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createExtent, createFromCoordinateReferenceSystemCodes, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createObject, createOperationMethod, createParameterDescriptor, createPolarCS, createPrimeMeridian, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createUnit, createVerticalCRS, createVerticalCS, createVerticalDatum, getAuthority, getAuthorityCodes, getDescriptionText, getTimeout, newIdentifiedObjectFinder, normalizeCode, printCacheContent, setTimeout, toString`

    - ### Methods inherited from class GeodeticAuthorityFactory

      `createParametricCRS, createParametricCS, createParametricDatum, trimNamespace`

    - ### Methods inherited from class AbstractFactory

      `getVendor`

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface AuthorityFactory

      `createObject, getAuthority, getAuthorityCodes, getDescriptionText`

    - ### Methods inherited from interface CoordinateOperationAuthorityFactory

      `createCoordinateOperation, createFromCoordinateReferenceSystemCodes, createOperationMethod`

    - ### Methods inherited from interface CRSAuthorityFactory

      `createCompoundCRS, createCoordinateReferenceSystem, createDerivedCRS, createEngineeringCRS, createGeocentricCRS, createGeographicCRS, createImageCRS, createProjectedCRS, createTemporalCRS, createVerticalCRS`

    - ### Methods inherited from interface CSAuthorityFactory

      `createCartesianCS, createCoordinateSystem, createCoordinateSystemAxis, createCylindricalCS, createEllipsoidalCS, createPolarCS, createSphericalCS, createTimeCS, createUnit, createVerticalCS`

    - ### Methods inherited from interface DatumAuthorityFactory

      `createDatum, createEllipsoid, createEngineeringDatum, createGeodeticDatum, createImageDatum, createPrimeMeridian, createTemporalDatum, createVerticalDatum`

    - ### Methods inherited from interface Factory

      `getVendor`

- - ### Field Detail

    - #### dataSource

          protected final DataSource dataSource

      The factory to use for creating `Connection`s to the EPSG database.

    - #### nameFactory

          protected final NameFactory nameFactory

      The factory to use for creating `GenericName` instances.

    - #### datumFactory

          protected final DatumFactory datumFactory

      The factory to use for creating `Datum` instances from the properties read in the database.

    - #### csFactory

          protected final CSFactory csFactory

      The factory to use for creating `CoordinateSystem` instances from the properties read in the database.

    - #### crsFactory

          protected final CRSFactory crsFactory

      The factory to use for creating `CoordinateReferenceSystem` instances from the properties read in the database.

    - #### copFactory

          protected final CoordinateOperationFactory copFactory

      The factory to use for creating `CoordinateOperation` instances from the properties read in the database.

    - #### mtFactory

          protected final MathTransformFactory mtFactory

      The factory to use for creating `MathTransform` instances. The math transforms are created as part of `CoordinateOperation` creation process.

  - ### Constructor Detail

    - #### EPSGFactory

          public EPSGFactory​(Map<String,​?> properties)
                      throws FactoryException

      Creates a factory using the given configuration. The properties recognized by this constructor are listed in the table below. Any property not listed below will be ignored by this constructor. All properties are optional and can `null` or omitted, in which case default values are used. Those default values are implementation-specific and may change in any future SIS version.

      Recognized properties
      Key | Value class | Description
      --- | --- | ---
      `dataSource` | `DataSource` | The factory to use for creating `Connection`s to the EPSG database.
      `nameFactory` | `NameFactory` | The factory to use for creating `GenericName` instances.
      `datumFactory` | `DatumAuthorityFactory` | The factory to use for creating `Datum` instances.
      `csFactory` | `CSAuthorityFactory` | The factory to use for creating `CoordinateSystem` instances.
      `crsFactory` | `CRSAuthorityFactory` | The factory to use for creating `CoordinateReferenceSystem` instances.
      `copFactory` | `CoordinateOperationAuthorityFactory` | The factory to use for creating `CoordinateOperation` instances.
      `mtFactory` | `MathTransformFactory` | The factory to use for creating `MathTransform` instances.
      `catalog` | `String` | The database catalog that contains the EPSG schema (see install).
      `schema` | `String` | The database schema that contains the EPSG tables (see install).
      `scriptProvider` | `InstallationScriptProvider` | A provider of SQL scripts to use if `EPSGFactory` needs to create the database.
      `locale` | `Locale` | The locale for producing error messages on a best effort basis.

      Default values

      - If no `dataSource` is specified, this constructor defaults to the search algorithm described in the package documentation.
      - If no `catalog` or `schema` is specified, `SQLTranslator` will try to auto-detect the schema that contains the EPSG tables.
      - If no `locale` is specified, this constructor defaults to the display locale.
      Parameters:
        `properties` - the data source, authority factories and other configuration properties, or `null` for the default values.
      Throws:
        `ClassCastException` - if a property value is not of the expected class.
        `IllegalArgumentException` - if a property value is invalid.
        `FactoryException` - if an error occurred while creating the EPSG factory.

  - ### Method Detail

    - #### getCodeSpaces

          public Set<String> getCodeSpaces()

      Returns the namespace of EPSG codes.
      Overrides:
        `getCodeSpaces` in class `GeodeticAuthorityFactory`
      Returns:
        the `"EPSG"` string in a singleton map.

    - #### getLocale

          public Locale getLocale()

      Returns the locale used by this factory for producing error messages. This locale does not change the way data are read from the EPSG database.
      Specified by:
        `getLocale` in interface `Localized`
      Returns:
        the locale for error messages.

    - #### install

          public void install​(Connection connection)
                       throws UnavailableFactoryException

      Creates the EPSG schema in the database and populates the tables with geodetic definitions. This method is invoked automatically when `newDataAccess()` detects that the EPSG dataset is not installed. Users can also invoke this method explicitly if they wish to force the dataset installation.

      This method uses the following properties from the map specified at construction time:

      - `catalog`:
        a `String` giving the name of the database catalog where to create the EPSG schema. If non-null, that catalog shall exist prior this method call (this method does not create any catalog). If no catalog is specified or if the catalog is an empty string, then the EPSG schema will be created without catalog. If the database does not support catalogs in table definitions or in data manipulation, then this property is ignored.
      - `schema`:
        a `String` giving the name of the database schema where to create the EPSG tables. That schema shall not exist prior this method call; the schema will be created by this `install(…)` method. If the schema is an empty string, then the tables will be created without schema. If no schema is specified, then the default schema is `"EPSG"`. If the database does not support schemas in table definitions or in data manipulation, then this property is ignored.
      - `scriptProvider`:
        an `InstallationScriptProvider` giving the SQL scripts to execute for creating the EPSG database. If no provider is specified, then this method will search on the classpath (with `ServiceLoader`) for user-provided implementations of `InstallationScriptProvider`. If no user-specified provider is found, then this method will search for `"EPSG_*Tables​.sql"`, `"EPSG_*Data​.sql"` and `"EPSG_*FKeys​.sql"` files in the `$SIS_DATA/Databases/ExternalSources` directory where `*` stands for any characters provided that there is no ambiguity.

      Legal constraint: the EPSG dataset can not be distributed with Apache SIS at this time for licensing reasons. Users need to either install the dataset manually (for example with the help of this method), or add on the classpath to a separated bundle like `org​.apache​.sis:non-free:sis-epsg​.jar`. See How to use EPSG geodetic dataset for more information.

      Parameters:
        `connection` - connection to the database where to create the EPSG schema.
      Throws:
        `UnavailableFactoryException` - if installation failed. The exception will have a `FileNotFoundException` cause if a SQL script has not been found (typically because a required resource is not on the classpath), an `IOException` if an I/O error occurred while reading a SQL script, or a `SQLException` if an error occurred while writing to the database.
      See Also:
        `InstallationScriptProvider`

    - #### newDataAccess

          protected EPSGDataAccess newDataAccess()
                                          throws FactoryException

      Creates the factory which will perform the actual geodetic object creation work. This method is invoked automatically when a new worker is required, either because the previous one has been disposed after its timeout or because a new one is required for concurrency.

      The default implementation performs the following steps:

      1. Gets a new connection from the `dataSource`.
      2. If this method is invoked for the first time, verifies if the EPSG tables exists. If the tables are not found, invokes `install(Connection)`.
      3. Delegates to `newDataAccess(Connection, SQLTranslator)`, which provides an easier overriding point for subclasses wanting to return a custom `EPSGDataAccess` instance.
      Specified by:
        `newDataAccess` in class `ConcurrentAuthorityFactory<EPSGDataAccess>`
      Returns:
        Data Access Object (DAO) to use in `createFoo(String)` methods.
      Throws:
        `FactoryException` - if the constructor failed to connect to the EPSG database. This exception usually has a `SQLException` as its cause.

    - #### newDataAccess

          protected EPSGDataAccess newDataAccess​(Connection connection,
                                                 SQLTranslator translator)
                                          throws SQLException

      Creates the factory which will perform the actual geodetic object creation from a given connection. This method is a convenience hook easier to override than `newDataAccess()` for subclasses wanting to return instances of their own `EPSGDataAccess` subclass. The default implementation is simply:

      >     return new EPSGDataAccess(this, connection, translator);

      Subclasses can override this method with a similar code but with `new EPSGDataAccess(…)` replaced by `new MyDataAccessSubclass(…)`.
      Parameters:
        `connection` - a connection to the EPSG database.
        `translator` - the translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database.
      Returns:
        Data Access Object (DAO) to use in `createFoo(String)` methods.
      Throws:
        `SQLException` - if a problem with the database has been detected.
      See Also:
        `EPSGDataAccess(EPSGFactory, Connection, SQLTranslator)`

    - #### canClose

          protected boolean canClose​(EPSGDataAccess factory)

      Returns `true` if the given Data Access Object (DAO) can be closed. This method is invoked automatically after the timeout if the given DAO has been idle during all that time. The default implementation always returns `false` if a set returned by `EPSGDataAccess​.getAuthorityCodes(Class)` is still in use.
      Overrides:
        `canClose` in class `ConcurrentAuthorityFactory<EPSGDataAccess>`
      Parameters:
        `factory` - the Data Access Object which is about to be closed.
      Returns:
        `true` if the given Data Access Object can be closed.
      See Also:
        `ConcurrentAuthorityFactory​.close()`

    - #### isCacheable

          protected boolean isCacheable​(String code,
                                        Object object)

      Returns whether the given object can be cached. This method is invoked after `EPSGDataAccess` created a new object not previously in the cache.
      Overrides:
        `isCacheable` in class `ConcurrentAuthorityFactory<EPSGDataAccess>`
      Parameters:
        `code` - the authority code specified by the caller for creating an object.
        `object` - the object created for the given authority code.
      Returns:
        whether the given object should be cached.
      Since:
        0.8
      See Also:
        `ConcurrentAuthorityFactory​.printCacheContent(PrintWriter)`