Module org.apache.sis.referencing
Class EPSGDataAccess
Object
AbstractFactory
GeodeticAuthorityFactory
EPSGDataAccess
- All Implemented Interfaces:
AutoCloseable,Localized,AuthorityFactory,CRSAuthorityFactory,CSAuthorityFactory,DatumAuthorityFactory,CoordinateOperationAuthorityFactory,Factory
public class EPSGDataAccess
extends GeodeticAuthorityFactory
implements CRSAuthorityFactory, CSAuthorityFactory, DatumAuthorityFactory, CoordinateOperationAuthorityFactory, Localized, AutoCloseable
Data Access Object (DAO) creating geodetic objects from a JDBC connection to an EPSG database.
The EPSG database is freely available at https://epsg.org/.
Current version of this class requires EPSG database version 6.6 or above.
Object identifier (code or name)
EPSG codes are numerical identifiers. For example, code 3395 stands for "WGS 84 / World Mercator". Coordinate Reference Objects are normally created from their numerical codes, but this factory accepts also names. For example,createProjectedCRS("3395") and createProjectedCRS("WGS 84 / World Mercator") both fetch
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 instance.
If such an ambiguity is found, an exception will be thrown.
Life cycle and caching
EPSGDataAccess instances should be short-lived since they may hold a significant amount of JDBC resources.
EPSGDataAccess instances are created on the fly by EPSGFactory and closed after a relatively short
timeout.
In addition EPSGFactory caches the most recently created objects, which reduce greatly
the amount of EPSGDataAccess instantiations (and consequently the amount of database accesses)
in the common case where only a few EPSG codes are used by an application.
EPSGDataAccess.createFoo(String) methods do not cache by themselves and query the database on every invocation.
SQL dialects
Because the primary distribution format for the EPSG dataset is MS-Access, this class uses SQL statements formatted for the MS-Access dialect. For usage with other database software products like PostgreSQL or Derby, aSQLTranslator instance is provided to the constructor.- Since:
- 0.7
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final ConnectionThe connection to the EPSG database.protected final EPSGFactoryTheConcurrentAuthorityFactorythat created this Data Access Object (DAO).protected final SQLTranslatorThe translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedEPSGDataAccess(EPSGFactory owner, Connection connection, SQLTranslator translator) Creates a factory using the given connection. -
Method Summary
Modifier and TypeMethodDescriptionvoidclose()Closes the JDBC connection used by this factory.Creates an operation for transforming coordinates in the source CRS to coordinates in the target CRS.Creates an arbitrary coordinate reference system from a code.Creates an arbitrary coordinate system from a code.Creates a coordinate system axis with name, direction, unit and range of values.createDatum(String code) Creates an arbitrary datum from a code.createEllipsoid(String code) Creates a geometric figure that can be used to describe the approximate shape of the earth.createExtent(String code) Creates information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.createFromCoordinateReferenceSystemCodes(String sourceCRS, String targetCRS) Creates operations from source and target coordinate reference system codes.createObject(String code) Returns an arbitrary object from a code.Creates description of the algorithm and parameters used to perform a coordinate operation.Creates a definition of a single parameter used by an operation method.createPrimeMeridian(String code) Creates a prime meridian defining the origin from which longitude values are determined.Unit<?> createUnit(String code) Creates an unit of measurement from a code.Returns the authority for this EPSG dataset.getAuthorityCodes(Class<? extends IdentifiedObject> type) Returns the set of authority codes of the given type.Returns an empty set since this data access class expects no namespace.getDescriptionText(String code) Gets a description of the object corresponding to a code.Returns the locale used by this factory for producing error messages.Returns a finder which can be used for looking up unidentified objects.Methods inherited from class GeodeticAuthorityFactory
createCartesianCS, createCompoundCRS, createCylindricalCS, createDerivedCRS, createEllipsoidalCS, createEngineeringCRS, createEngineeringDatum, createGeocentricCRS, createGeodeticDatum, createGeographicCRS, createImageCRS, createImageDatum, createParametricCRS, createParametricCS, createParametricDatum, createPolarCS, createProjectedCRS, createSphericalCS, createTemporalCRS, createTemporalDatum, createTimeCS, createVerticalCRS, createVerticalCS, createVerticalDatum, toString, trimNamespaceMethods inherited from class AbstractFactory
getVendorMethods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitMethods inherited from interface CRSAuthorityFactory
createCompoundCRS, createDerivedCRS, createEngineeringCRS, createGeocentricCRS, createGeographicCRS, createImageCRS, createProjectedCRS, createTemporalCRS, createVerticalCRSMethods inherited from interface CSAuthorityFactory
createCartesianCS, createCylindricalCS, createEllipsoidalCS, createPolarCS, createSphericalCS, createTimeCS, createVerticalCSMethods inherited from interface DatumAuthorityFactory
createEngineeringDatum, createGeodeticDatum, createImageDatum, createTemporalDatum, createVerticalDatumMethods inherited from interface Factory
getVendor
-
Field Details
-
owner
TheConcurrentAuthorityFactorythat created this Data Access Object (DAO). The owner supplies caching for allcreateFoo(String)methods. -
connection
The connection to the EPSG database. This connection is specified at construction time and closed by theclose()method.- See Also:
-
translator
The translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database.
-
-
Constructor Details
-
EPSGDataAccess
Creates a factory using the given connection. The connection will be closed when this factory will be closed.API design note
This constructor is protected becauseEPSGDataAccessinstances should not be created as standalone factories. This constructor is for allowing definition of customEPSGDataAccesssubclasses, which are then instantiated by theEPSGFactory.newDataAccess(Connection, SQLTranslator)method of a corresponding customEPSGFactorysubclass.- Parameters:
owner- theEPSGFactorywhich is creating this Data Access Object (DAO).connection- the connection to the underlying EPSG database.translator- the translator from the SQL statements using MS-Access dialect to SQL statements using the dialect of the actual database.- See Also:
-
-
Method Details
-
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:
getLocalein interfaceLocalized- Returns:
- the locale for error messages.
-
getAuthority
Returns the authority for this EPSG dataset. The returned citation contains the database version in the edition attribute, together with date of last update in the edition date. Example (the exact content will vary with Apache SIS versions, JDBC driver and EPSG dataset versions):Citation ├─ Title ……………………………………………………… EPSG Geodetic Parameter Dataset ├─ Identifier ………………………………………… EPSG ├─ Online resource (1 of 2) │ ├─ Linkage ………………………………………… https://epsg.org/ │ └─ Function ……………………………………… Browse └─ Online resource (2 of 2) ├─ Linkage ………………………………………… jdbc:derby:/my/path/to/SIS_DATA/Databases/SpatialMetadata ├─ Description ……………………………… EPSG dataset version 9.1 on “Apache Derby Embedded JDBC Driver” version 10.14. └─ Function ……………………………………… Connection- Specified by:
getAuthorityin interfaceAuthorityFactory- Specified by:
getAuthorityin classGeodeticAuthorityFactory- Returns:
- the organization responsible for definition of the database, or
nullif unknown. - See Also:
-
getAuthorityCodes
public Set<String> getAuthorityCodes(Class<? extends IdentifiedObject> type) throws FactoryException Returns the set of authority codes of the given type. This returned set may keep a connection to the EPSG database, so the set can execute efficiently idioms like the following one:The returned set should not be referenced for a long time, as it may prevent this factory to release JDBC resources. If the set of codes is needed for a long time, their values should be copied in another collection object.getAuthorityCodes(type).containsAll(others);Handling of deprecated objects
The collection returned by this method gives an enumeration of EPSG codes for valid objects only. The EPSG codes of deprecated objects are not included in iterations, computation ofSet.size()value,Set.toString()result, etc. with one exception: a call toSet.contains(…)will returntrueif the given identifier exists for a deprecated object, even if that identifier does not show up in iterations. In other words, the returned collection behaves as if deprecated codes were included in the set but invisible.- Specified by:
getAuthorityCodesin interfaceAuthorityFactory- Parameters:
type- the spatial reference objects type (may beObject.class).- Returns:
- the set of authority codes for spatial reference objects of the given type (may be an empty set).
- Throws:
FactoryException- if access to the underlying database failed.
-
getCodeSpaces
Returns an empty set since this data access class expects no namespace. Code shall be given tocreateFoo(String)methods directly, without"EPSG:"prefix.- Overrides:
getCodeSpacesin classGeodeticAuthorityFactory- Returns:
- empty set.
-
getDescriptionText
public InternationalString getDescriptionText(String code) throws NoSuchAuthorityCodeException, FactoryException Gets a description of the object corresponding to a code. This method returns the object name in a lightweight manner, without creating the fullIdentifiedObject.- Specified by:
getDescriptionTextin interfaceAuthorityFactory- Overrides:
getDescriptionTextin classGeodeticAuthorityFactory- Parameters:
code- value allocated by authority.- Returns:
- the object name, or
nullif the object corresponding to the specifiedcodehas no name. - Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the query failed for some other reason.
-
createObject
public IdentifiedObject createObject(String code) throws NoSuchAuthorityCodeException, FactoryException Returns an arbitrary object from a code. The default implementation delegates to more specific methods, for examplecreateCoordinateReferenceSystem(String),createDatum(String), etc. until a successful one is found.Note that this method may be ambiguous since the same EPSG code can be used for different kinds of objects. This method throws an exception if it detects an ambiguity on a best-effort basis. It is recommended to invoke the most specific
createFoo(String)method when the desired type is known, both for performance reason and for avoiding ambiguity.- Specified by:
createObjectin interfaceAuthorityFactory- Specified by:
createObjectin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the object for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createCoordinateReferenceSystem
public CoordinateReferenceSystem createCoordinateReferenceSystem(String code) throws NoSuchAuthorityCodeException, FactoryException Creates an arbitrary coordinate reference system from a code. The returned object will typically be an instance ofGeographicCRS,ProjectedCRS,VerticalCRSorCompoundCRS.Examples
Some EPSG codes for coordinate reference systems are:EPSG codes examples Code Type Description 4326 Geographic World Geodetic System 1984 4979 Geographic 3D World Geodetic System 1984 4978 Geocentric World Geodetic System 1984 3395 Projected WGS 84 / World Mercator 5714 Vertical Mean Sea Level height 6349 Compound NAD83(2011) + NAVD88 height 5800 Engineering Astra Minas Grid - Specified by:
createCoordinateReferenceSystemin interfaceCRSAuthorityFactory- Overrides:
createCoordinateReferenceSystemin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the coordinate reference system for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createDatum
Creates an arbitrary datum from a code. The returned object will typically be an instance ofGeodeticDatum,VerticalDatumorTemporalDatum.Examples
Some EPSG codes for datums are:EPSG codes examples Code Type Description 6326 Geodetic World Geodetic System 1984 6322 Geodetic World Geodetic System 1972 1027 Vertical EGM2008 geoid 5100 Vertical Mean Sea Level 9315 Engineering Seismic bin grid datum - Specified by:
createDatumin interfaceDatumAuthorityFactory- Overrides:
createDatumin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the datum for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createEllipsoid
Creates a geometric figure that can be used to describe the approximate shape of the earth. In mathematical terms, it is a surface formed by the rotation of an ellipse about its minor axis.Examples
Some EPSG codes for ellipsoids are:EPSG codes examples Code Description 7030 WGS 84 7034 Clarke 1880 7048 GRS 1980 Authalic Sphere - Specified by:
createEllipsoidin interfaceDatumAuthorityFactory- Overrides:
createEllipsoidin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the ellipsoid for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createPrimeMeridian
public PrimeMeridian createPrimeMeridian(String code) throws NoSuchAuthorityCodeException, FactoryException Creates a prime meridian defining the origin from which longitude values are determined.Examples
Some EPSG codes for prime meridians are:EPSG codes examples Code Description 8901 Greenwich 8903 Paris 8904 Bogota 8905 Madrid 8906 Rome - Specified by:
createPrimeMeridianin interfaceDatumAuthorityFactory- Overrides:
createPrimeMeridianin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the prime meridian for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createExtent
Creates information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.Examples
Some EPSG codes for extents are:EPSG codes examples Code Description 1262 World 3391 World - between 80°S and 84°N - Overrides:
createExtentin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the extent for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createCoordinateSystem
public CoordinateSystem createCoordinateSystem(String code) throws NoSuchAuthorityCodeException, FactoryException Creates an arbitrary coordinate system from a code. The returned object will typically be an instance ofEllipsoidalCS,CartesianCSorVerticalCS.Examples
Some EPSG codes for coordinate systems are:EPSG codes examples Code Type Axes Orientations Unit 4406 Cartesian 2D CS easting, northing (E,N) east, north kilometre 4496 Cartesian 2D CS easting, northing (E,N) east, north metre 4500 Cartesian 2D CS northing, easting (N,E) north, east metre 4491 Cartesian 2D CS westing, northing (W,N) west, north metre 6422 Ellipsoidal 2D CS latitude, longitude north, east degree 6424 Ellipsoidal 2D CS longitude, latitude east, north degree 6429 Ellipsoidal 2D CS longitude, latitude east, north radian 6423 Ellipsoidal 3D CS latitude, longitude, ellipsoidal height north, east, up degree, degree, metre 6404 Spherical 3D CS latitude, longitude, radius north, east, up degree, degree, metre 6498 Vertical CS depth (D) down metre 6499 Vertical CS height (H) up metre - Specified by:
createCoordinateSystemin interfaceCSAuthorityFactory- Overrides:
createCoordinateSystemin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the coordinate system for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createCoordinateSystemAxis
public CoordinateSystemAxis createCoordinateSystemAxis(String code) throws NoSuchAuthorityCodeException, FactoryException Creates a coordinate system axis with name, direction, unit and range of values.Examples
Some EPSG codes for axes are:EPSG codes examples Code Description Unit 106 Latitude (φ) degree 107 Longitude (λ) degree 1 Easting (E) metre 2 Northing (N) metre - Specified by:
createCoordinateSystemAxisin interfaceCSAuthorityFactory- Overrides:
createCoordinateSystemAxisin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the axis for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createUnit
Creates an unit of measurement from a code. Current implementation first checks ifUnits.valueOfEPSG(int)can provide a hard-coded unit for the given code before to try to parse the information found in the database. This is done that way for better support of non-straightforward units like sexagesimal degrees (EPSG:9110 and 9111).Examples
Some EPSG codes for units are:EPSG codes examples Code Description 9002 decimal degree 9001 metre 9030 kilometre 1040 second 1029 year - Specified by:
createUnitin interfaceCSAuthorityFactory- Overrides:
createUnitin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the unit of measurement for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createParameterDescriptor
public ParameterDescriptor<?> createParameterDescriptor(String code) throws NoSuchAuthorityCodeException, FactoryException Creates a definition of a single parameter used by an operation method.Examples
Some EPSG codes for parameters are:EPSG codes examples Code Description 8801 Latitude of natural origin 8802 Longitude of natural origin 8805 Scale factor at natural origin 8806 False easting 8807 False northing - Overrides:
createParameterDescriptorin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the parameter descriptor for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createOperationMethod
public OperationMethod createOperationMethod(String code) throws NoSuchAuthorityCodeException, FactoryException Creates description of the algorithm and parameters used to perform a coordinate operation. AnOperationMethodis a kind of metadata: it does not perform any coordinate operation (e.g. map projection) by itself, but tells us what is needed in order to perform such operation.Examples
Some EPSG codes for operation methods are:EPSG codes examples Code Description 9804 Mercator (variant A) 9802 Lambert Conic Conformal (2SP) 9810 Polar Stereographic (variant A) 9624 Affine parametric transformation - Specified by:
createOperationMethodin interfaceCoordinateOperationAuthorityFactory- Overrides:
createOperationMethodin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the operation method for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createCoordinateOperation
public CoordinateOperation createCoordinateOperation(String code) throws NoSuchAuthorityCodeException, FactoryException Creates an operation for transforming coordinates in the source CRS to coordinates in the target CRS. The returned object will either be aConversionor aTransformation, depending on the code.Examples
Some EPSG codes for coordinate transformations are:EPSG codes examples Code Description 1133 ED50 to WGS 84 (1) 1241 NAD27 to NAD83 (1) 1173 NAD27 to WGS 84 (4) 6326 NAD83(2011) to NAVD88 height (1) - Specified by:
createCoordinateOperationin interfaceCoordinateOperationAuthorityFactory- Overrides:
createCoordinateOperationin classGeodeticAuthorityFactory- Parameters:
code- value allocated by EPSG.- Returns:
- the operation for the given code.
- Throws:
NoSuchAuthorityCodeException- if the specifiedcodewas not found.FactoryException- if the object creation failed for some other reason.- See Also:
-
createFromCoordinateReferenceSystemCodes
public Set<CoordinateOperation> createFromCoordinateReferenceSystemCodes(String sourceCRS, String targetCRS) throws FactoryException Creates operations from source and target coordinate reference system codes. This method only extract the information explicitly declared in the EPSG database; it does not attempt to infer by itself operations that are not explicitly recorded in the database.The returned set is ordered with the most accurate operations first. Deprecated operations are not included in the set; if a deprecated operation is really wanted, it can be fetched by an explicit call to
createCoordinateOperation(String).- Specified by:
createFromCoordinateReferenceSystemCodesin interfaceCoordinateOperationAuthorityFactory- Overrides:
createFromCoordinateReferenceSystemCodesin classGeodeticAuthorityFactory- Parameters:
sourceCRS- coded value of source coordinate reference system.targetCRS- coded value of target coordinate reference system.- Returns:
- the operations from
sourceCRStotargetCRS. - Throws:
NoSuchAuthorityCodeException- if a specified code was not found.FactoryException- if the object creation failed for some other reason.
-
newIdentifiedObjectFinder
Returns a finder which can be used for looking up unidentified objects. The finder tries to fetch a fully identified object from an incomplete one, for example from an object without "ID[…]" or "AUTHORITY[…]" element in Well Known Text.- Overrides:
newIdentifiedObjectFinderin classGeodeticAuthorityFactory- Returns:
- a finder to use for looking up unidentified objects.
- Throws:
FactoryException- if the finder cannot be created.- See Also:
-
close
Closes the JDBC connection used by this factory. If thisEPSGDataAccessis used by anEPSGFactory, then this method will be automatically invoked after some timeout.- Specified by:
closein interfaceAutoCloseable- Throws:
FactoryException- if an error occurred while closing the connection.- See Also:
-