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

Class EPSGFactory

java.lang.Object
org.apache.sis.util.iso.AbstractFactory
org.apache.sis.referencing.factory.GeodeticAuthorityFactory
org.apache.sis.referencing.factory.ConcurrentAuthorityFactory<EPSGDataAccess>
org.apache.sis.referencing.factory.sql.EPSGFactory
All Implemented Interfaces:
AutoCloseable, Localized, org.opengis.referencing.AuthorityFactory, org.opengis.referencing.crs.CRSAuthorityFactory, org.opengis.referencing.cs.CSAuthorityFactory, org.opengis.referencing.datum.DatumAuthorityFactory, org.opengis.referencing.operation.CoordinateOperationAuthorityFactory, org.opengis.util.Factory
public class EPSGFactory extends ConcurrentAuthorityFactory<EPSGDataAccess> implements org.opengis.referencing.crs.CRSAuthorityFactory, org.opengis.referencing.cs.CSAuthorityFactory, org.opengis.referencing.datum.DatumAuthorityFactory, org.opengis.referencing.operation.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
Version:
0.8
See Also:

  • Field Details

    • CODESPACES

      private static final Set<String> CODESPACES
      The namespace of EPSG codes.
      See Also:

    • dataSource

      protected final DataSource dataSource
      The factory to use for creating Connections to the EPSG database.

    • nameFactory

      protected final org.opengis.util.NameFactory nameFactory
      The factory to use for creating GenericName instances.

    • datumFactory

      protected final org.opengis.referencing.datum.DatumFactory datumFactory
      The factory to use for creating Datum instances from the properties read in the database.

    • csFactory

      protected final org.opengis.referencing.cs.CSFactory csFactory
      The factory to use for creating CoordinateSystem instances from the properties read in the database.

    • crsFactory

      protected final org.opengis.referencing.crs.CRSFactory crsFactory
      The factory to use for creating CoordinateReferenceSystem instances from the properties read in the database.

    • copFactory

      protected final org.opengis.referencing.operation.CoordinateOperationFactory copFactory
      The factory to use for creating CoordinateOperation instances from the properties read in the database.

    • mtFactory

      protected final org.opengis.referencing.operation.MathTransformFactory mtFactory
      The factory to use for creating MathTransform instances. The math transforms are created as part of CoordinateOperation creation process.

    • catalog

      private final String catalog
      The name of the catalog that contains the EPSG tables, or null or an empty string.
      • The "" value retrieves the EPSG schema without a catalog.
      • The null value means that the catalog name should not be used to narrow the search.

    • schema

      private final String schema
      The name of the schema that contains the EPSG tables, or null or an empty string.
      • The "" value retrieves the EPSG tables without a schema. In such case, table names are prefixed by "epsg_".
      • The null value means that the schema name should not be used to narrow the search. In such case, SQLTranslator will tries to automatically detect the schema.

    • scriptProvider

      private final InstallationScriptProvider scriptProvider
      A provider of SQL scripts to use if EPSGFactory needs to create the database, or null for the default mechanism.

    • translator

      private volatile SQLTranslator translator
      The translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database. If null, will be created when first needed.

    • locale

      private final Locale locale
      The locale for producing error messages. This is usually the default locale.
      See Also:

  • Constructor Details

    • EPSGFactory

      public EPSGFactory(Map<String,?> properties) throws org.opengis.util.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 Connections 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.
      org.opengis.util.FactoryException - if an error occurred while creating the EPSG factory.

  • Method Details

    • factory

      private static <F> F factory(Class<F> type, String key, Map<String,?> properties)
      Returns the factory for the given key if it exists, or the default factory instance otherwise.

    • canNotUse

      private String canNotUse(Exception e)
      Returns the message to put in an UnavailableFactoryException having the given exception as its cause.

    • canNotUse

      private String canNotUse(String cause)
      Returns the message to put in an UnavailableFactoryException having the given cause.

    • 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 cannot 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:

    • newDataAccess

      protected EPSGDataAccess newDataAccess() throws org.opengis.util.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:
      org.opengis.util.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: 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:

    • 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:

    • 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: