Module org.apache.sis.referencing

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

Class EPSGFactory

Object

AbstractFactory

GeodeticAuthorityFactory

ConcurrentAuthorityFactory<EPSGDataAccess>

EPSGFactory

All Implemented Interfaces:

Auto­Closeable, Localized, Authority­Factory, CRSAuthority­Factory, CSAuthority­Factory, Datum­Authority­Factory, Coordinate­Operation­Authority­Factory, 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 Data­Source 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 module path, 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 EPSGData­Access instance for performing the actual creation work. Developers who need to customize the geodetic object creation can override the new­Data­Access(Connection, SQLTranslator) method in order to return their own EPSGData­Access subclass.

Since:

0.7

See Also:

• EPSGData­Access
• SQLTranslator
• List of authority codes

Field Summary

Fields

Modifier and Type	Field	Description
protected final Coordinate­Operation­Factory	cop­Factory	The factory to use for creating Coordinate­Operation instances from the properties read in the database.
protected final CRSFactory	crs­Factory	The factory to use for creating Coordinate­Reference­System instances from the properties read in the database.
protected final CSFactory	cs­Factory	The factory to use for creating Coordinate­System instances from the properties read in the database.
protected final Data­Source	data­Source	The factory to use for creating Connections to the EPSG database.
protected final Datum­Factory	datum­Factory	The factory to use for creating Datum instances from the properties read in the database.
protected final Math­Transform­Factory	mt­Factory	The factory to use for creating Math­Transform instances.
protected final Name­Factory	name­Factory	The factory to use for creating Generic­Name instances.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
protected boolean	can­Close(EPSGData­Access factory)	Returns true if the given Data Access Object (DAO) can be closed.
Set<String>	get­Code­Spaces()	Returns the namespace of EPSG codes.
Locale	get­Locale()	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	is­Cacheable(String code, Object object)	Returns whether the given object can be cached.
protected EPSGData­Access	new­Data­Access()	Creates the factory which will perform the actual geodetic object creation work.
protected EPSGData­Access	new­Data­Access(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, create­Cartesian­CS, create­Compound­CRS, create­Coordinate­Operation, create­Coordinate­Reference­System, create­Coordinate­System, create­Coordinate­System­Axis, create­Cylindrical­CS, create­Datum, create­Derived­CRS, create­Ellipsoid, create­Ellipsoidal­CS, create­Engineering­CRS, create­Engineering­Datum, create­Extent, create­From­Coordinate­Reference­System­Codes, create­Geocentric­CRS, create­Geodetic­Datum, create­Geographic­CRS, create­Image­CRS, create­Image­Datum, create­Object, create­Operation­Method, create­Parameter­Descriptor, create­Polar­CS, create­Prime­Meridian, create­Projected­CRS, create­Spherical­CS, create­Temporal­CRS, create­Temporal­Datum, create­Time­CS, create­Unit, create­Vertical­CRS, create­Vertical­CS, create­Vertical­Datum, get­Authority, get­Authority­Codes, get­Description­Text, get­Timeout, new­Identified­Object­Finder, normalize­Code, print­Cache­Content, set­Timeout, to­String

Methods inherited from class GeodeticAuthorityFactory

create­Parametric­CRS, create­Parametric­CS, create­Parametric­Datum, trim­Namespace

Methods inherited from class AbstractFactory

get­Vendor

Methods inherited from class Object

clone, equals, finalize, get­Class, hash­Code, notify, notify­All, wait, wait, wait

Methods inherited from interface AuthorityFactory

create­Object, get­Authority, get­Authority­Codes, get­Description­Text

Methods inherited from interface CoordinateOperationAuthorityFactory

create­Coordinate­Operation, create­From­Coordinate­Reference­System­Codes, create­Operation­Method

Methods inherited from interface CRSAuthorityFactory

create­Compound­CRS, create­Coordinate­Reference­System, create­Derived­CRS, create­Engineering­CRS, create­Geocentric­CRS, create­Geographic­CRS, create­Image­CRS, create­Projected­CRS, create­Temporal­CRS, create­Vertical­CRS

Methods inherited from interface CSAuthorityFactory

create­Cartesian­CS, create­Coordinate­System, create­Coordinate­System­Axis, create­Cylindrical­CS, create­Ellipsoidal­CS, create­Polar­CS, create­Spherical­CS, create­Time­CS, create­Unit, create­Vertical­CS

Methods inherited from interface DatumAuthorityFactory

create­Datum, create­Ellipsoid, create­Engineering­Datum, create­Geodetic­Datum, create­Image­Datum, create­Prime­Meridian, create­Temporal­Datum, create­Vertical­Datum

Methods inherited from interface Factory

get­Vendor

Field Details

dataSource

protected final DataSource dataSource

The factory to use for creating Connections to the EPSG database.

nameFactory

protected final NameFactory nameFactory

The factory to use for creating Generic­Name 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 Coordinate­System instances from the properties read in the database.

crsFactory

protected final CRSFactory crsFactory

The factory to use for creating Coordinate­Reference­System instances from the properties read in the database.

copFactory

protected final CoordinateOperationFactory copFactory

The factory to use for creating Coordinate­Operation instances from the properties read in the database.

mtFactory

protected final MathTransformFactory mtFactory

The factory to use for creating Math­Transform instances. The math transforms are created as part of Coordinate­Operation creation process.

Constructor Details

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 Connections to the EPSG database.
nameFactory	NameFactory	The factory to use for creating Generic­Name instances.
datumFactory	DatumAuthorityFactory	The factory to use for creating Datum instances.
csFactory	CSAuthorityFactory	The factory to use for creating Coordinate­System instances.
crsFactory	CRSAuthorityFactory	The factory to use for creating Coordinate­Reference­System instances.
copFactory	CoordinateOperationAuthorityFactory	The factory to use for creating Coordinate­Operation instances.
mtFactory	MathTransformFactory	The factory to use for creating Math­Transform 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 data­Source 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:

Class­Cast­Exception - if a property value is not of the expected class.

Illegal­Argument­Exception - if a property value is invalid.

Factory­Exception - if an error occurred while creating the EPSG factory.

Method Details

getCodeSpaces

public Set<String> getCodeSpaces()

Returns the namespace of EPSG codes.

Overrides:

get­Code­Spaces in class Geodetic­Authority­Factory

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:

get­Locale 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 new­Data­Access() 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.
• script­Provider:
  an Installation­Script­Provider giving the SQL scripts to execute for creating the EPSG database. If no provider is specified, then this method searches on the module path (with Service­Loader) for user-provided implementations of Installation­Script­Provider. 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/External­Sources directory where * stands for any characters provided that there is no ambiguity.

Legal constraint

The EPSG dataset cannot be distributed with Apache SIS for licensing reasons. Users need to either install the dataset manually (for example with the help of this method), or add on the module path a separated bundle such as the org.apache.sis.referencing.epsg module. See How to use EPSG geodetic dataset for more information.

Parameters:

connection - connection to the database where to create the EPSG schema.

Throws:

Unavailable­Factory­Exception - if installation failed. The exception will have a File­Not­Found­Exception cause if a SQL script has not been found (typically because a required resource is not on the module path), 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:

• Installation­Script­Provider

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 data­Source.
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 new­Data­Access(Connection, SQLTranslator), which provides an easier overriding point for subclasses wanting to return a custom EPSGData­Access instance.

Specified by:

new­Data­Access in class Concurrent­Authority­Factory<EPSGData­Access>

Returns:

Data Access Object (DAO) to use in create­Foo(String) methods.

Throws:

Factory­Exception - 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 new­Data­Access() for subclasses wanting to return instances of their own EPSGData­Access subclass. The default implementation is simply:

return new EPSGDataAccess(this, connection, translator);

Subclasses can override this method with a similar code but with new EPSGData­Access(…) replaced by new My­Data­Access­Subclass(…).

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 create­Foo(String) methods.

Throws:

SQLException - if a problem with the database has been detected.

See Also:

• EPSGData­Access(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 EPSGData­Access.get­Authority­Codes(Class) is still in use.

Overrides:

can­Close in class Concurrent­Authority­Factory<EPSGData­Access>

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:

• Concurrent­Authority­Factory.close()

isCacheable

protected boolean isCacheable(String code,
 Object object)

Returns whether the given object can be cached. This method is invoked after EPSGData­Access created a new object not previously in the cache.

Overrides:

is­Cacheable in class Concurrent­Authority­Factory<EPSGData­Access>

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:

• Concurrent­Authority­Factory.print­Cache­Content(Print­Writer)