Class WKTDictionary

Object

AbstractFactory

GeodeticAuthorityFactory

WKTDictionary

All Implemented Interfaces:

Authority­Factory, Factory

public class WKTDictionary
extends GeodeticAuthorityFactory

A factory providing CRS objects parsed from WKT definitions associated with authority codes. Each WKT definition is associated with a key according the authority:version:code pattern where code is mandatory and authority:version are optional. Coordinate Reference Systems or other kinds of objects are created from WKT definitions when a create(…) method is invoked for the first time for a given key.

Sub-classing and instantiation

Newly constructed WKTDictionary are initially empty. The dictionary can be populated in the following ways:

• Invoke load(Buffered­Reader) for reading definitions from file(s).
• Invoke add­Definitions(Stream) for providing definitions from an arbitrary source.
• Override fetch­Definition(Default­Identifier) in a subclass for fetching WKT definitions on-the-fly (for example from the "spatial_ref_sys" table of a spatial database.

Sub-classing may be necessary even if fetch­Definition(…) is not overridden because WKTDictionary does not implement any of the CRSAuthority­Factory, CSAuthority­Factory or Datum­Authority­Factory. The choice of interfaces to implement is left to subclasses.

Example

Extend the set of Coordinate Reference Systems recognized by CRS.for­Code(String). The additional CRS are defined by Well-Known Text strings in a "My­CRS.txt" file. First step is to create a CRS factory with those definitions:

public final class MyCRS extends WKTDictionary implements CRSAuthorityFactory {
    MyCRS() throws IOException, FactoryException {
        super(new DefaultCitation("MyAuthority"));
        try (BufferedReader source = Files.newBufferedReader(Path.of("MyCRS.txt"))) {
            load(source);
        }
    }
}

The second step is to declare this factory in the module-info.java file as a provider of the org.opengis.referencing.crs.CRSAuthority­Factory service. That file shall contain the class name of above My­CRS class.

Errors management

Well-Known Text parsing is performed in two steps, each of them executed at a different time:

Early validation

WKT strings added by load(…) or add­Definitions(…) methods are verified for matching quotes, balanced parenthesis or brackets, and valid number or date formats. If a syntax error is detected, the loading process is interrupted at the point the error occurred; CRS definitions after the error location are not loaded. However, WKT keywords and geodetic parameters (e.g. map projections) are not validated at this stage.

Late validation

WKT keywords and geodetic parameters inside WKT elements are validated only when create­Object(String) is invoked. If an error occurs at this stage, only the CRS (or other geodetic object) for the code given to the create­Foo(…) method become invalid. Objects associated with other codes are not impacted.

Multi-threading

This class is thread-safe but not necessarily concurrent. This class is designed for a relatively small number of WKT; it is not a replacement for database-backed factory such as EPSGFactory.

Since:

1.1

Field Summary

Fields

Modifier and Type	Field	Description
protected final WKTFormat	parser	The parser to use for creating geodetic objects from WKT definitions.

Constructor Summary

Constructors

Constructor	Description
WKTDictionary(Citation authority)	Creates an initially empty factory.

Method Summary

Modifier and Type	Method	Description
void	add­Definitions(Stream<String> objects)	Adds definitions of CRS (or other geodetic objects) from Well-Known Texts.
Identified­Object	create­Object(String code)	Returns an arbitrary object from a code.
protected String	fetch­Definition(Default­Identifier identifier)	Fetches the Well-Known Text for a user-specified identifier not found in this WKTDictionary.
Citation	get­Authority()	Returns the authority or specification that defines the codes recognized by this factory.
Set<String>	get­Authority­Codes(Class<? extends Identified­Object> type)	Returns the set of authority codes for objects of the given type.
Set<String>	get­Code­Spaces()	Returns all namespaces recognized by this factory.
Optional<International­String>	get­Description­Text(Class<? extends Identified­Object> type, String code)	Gets a description of the object corresponding to a code.
void	load(Buffered­Reader source)	Adds to this factory all definitions read from the given source.

Methods inherited from class GeodeticAuthorityFactory

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­Datum­Ensemble, 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­Parametric­CRS, create­Parametric­CS, create­Parametric­Datum, 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­Description­Text, new­Identified­Object­Finder, to­String, trim­Namespace

Modifier and Type	Method	Description
Cartesian­CS	create­Cartesian­CS(String code)	Creates a 2- or 3-dimensional Cartesian coordinate system made of straight orthogonal axes.
Compound­CRS	create­Compound­CRS(String code)	Creates a CRS describing the position of points through two or more independent coordinate reference systems.
Coordinate­Operation	create­Coordinate­Operation(String code)	Creates an operation for transforming coordinates in the source CRS to coordinates in the target CRS.
Coordinate­Reference­System	create­Coordinate­Reference­System(String code)	Creates an arbitrary coordinate reference system from a code.
Coordinate­System	create­Coordinate­System(String code)	Creates an arbitrary coordinate system from a code.
Coordinate­System­Axis	create­Coordinate­System­Axis(String code)	Creates a coordinate system axis with name, direction, unit and range of values.
Cylindrical­CS	create­Cylindrical­CS(String code)	Creates a 3-dimensional coordinate system made of a polar coordinate system extended by a straight perpendicular axis.
Datum	create­Datum(String code)	Creates an arbitrary datum from a code.
Default­Datum­Ensemble<?>	create­Datum­Ensemble(String code)	Creates an arbitrary datum ensemble from a code.
Derived­CRS	create­Derived­CRS(String code)	Creates a CRS that is defined by its coordinate conversion from another CRS (not by a datum).
Ellipsoid	create­Ellipsoid(String code)	Creates a geometric figure that can be used to describe the approximate shape of the earth.
Ellipsoidal­CS	create­Ellipsoidal­CS(String code)	Creates a 2- or 3-dimensional coordinate system for geodetic latitude and longitude, sometimes with ellipsoidal height.
Engineering­CRS	create­Engineering­CRS(String code)	Creates a 1-, 2- or 3-dimensional contextually local coordinate reference system.
Engineering­Datum	create­Engineering­Datum(String code)	Creates a datum defining the origin of an engineering coordinate reference system.
Extent	create­Extent(String code)	Creates information about spatial, vertical, and temporal extent (usually a domain of validity) from a code.
Set<Coordinate­Operation>	create­From­Coordinate­Reference­System­Codes(String source­CRS, String target­CRS)	Creates operations from source and target coordinate reference system codes.
Geocentric­CRS	create­Geocentric­CRS(String code)	Creates a 3-dimensional coordinate reference system with the origin at the approximate centre of mass of the earth.
Geodetic­Datum	create­Geodetic­Datum(String code)	Creates a datum defining the location and orientation of an ellipsoid that approximates the shape of the earth.
Geographic­CRS	create­Geographic­CRS(String code)	Creates a 2- or 3-dimensional coordinate reference system based on an ellipsoidal approximation of the geoid.
Image­CRS	create­Image­CRS(String code)	Deprecated. The Image­CRS class has been removed in ISO 19111:2019.
Image­Datum	create­Image­Datum(String code)	Deprecated. The Image­Datum class has been removed in ISO 19111:2019.
final <T extends Identified­Object> T	create­Object(Class<T> type, String code)	Returns an object of the specified type from a code.
Operation­Method	create­Operation­Method(String code)	Creates a description of the algorithm and parameters used to perform a coordinate operation.
Parameter­Descriptor<?>	create­Parameter­Descriptor(String code)	Creates a definition of a single parameter used by an operation method.
Default­Parametric­CRS	create­Parametric­CRS(String code)	Creates a 1-dimensional parametric coordinate reference system.
Default­Parametric­CS	create­Parametric­CS(String code)	Creates a 1-dimensional parametric coordinate system.
Default­Parametric­Datum	create­Parametric­Datum(String code)	Creates a datum defining the origin of a parametric coordinate reference system.
Polar­CS	create­Polar­CS(String code)	Creates a 2-dimensional coordinate system for coordinates represented by a distance from the origin and an angle from a fixed direction.
Prime­Meridian	create­Prime­Meridian(String code)	Creates a prime meridian defining the origin from which longitude values are determined.
Projected­CRS	create­Projected­CRS(String code)	Creates a 2-dimensional coordinate reference system used to approximate the shape of the earth on a planar surface.
Spherical­CS	create­Spherical­CS(String code)	Creates a 3-dimensional coordinate system with one distance measured from the origin and two angular coordinates.
Temporal­CRS	create­Temporal­CRS(String code)	Creates a 1-dimensional coordinate reference system used for the recording of time.
Temporal­Datum	create­Temporal­Datum(String code)	Creates a datum defining the origin of a temporal coordinate reference system.
Time­CS	create­Time­CS(String code)	Creates a 1-dimensional coordinate system for time elapsed in the specified time units from a specified time origin.
Unit<?>	create­Unit(String code)	Creates an unit of measurement from a code.
Vertical­CRS	create­Vertical­CRS(String code)	Creates a 1-dimensional coordinate reference system used for recording heights or depths.
Vertical­CS	create­Vertical­CS(String code)	Creates a 1-dimensional coordinate system for heights or depths of points.
Vertical­Datum	create­Vertical­Datum(String code)	Creates a datum identifying a particular reference level surface used as a zero-height surface.
International­String	get­Description­Text(String code)	Deprecated. This method is ambiguous because the EPSG geodetic registry may allocate the same code to different kinds of object.
Identified­Object­Finder	new­Identified­Object­Finder()	Creates a finder which can be used for looking up unidentified objects.
String	to­String()	Returns a string representation of this factory for debugging purpose only.
protected final String	trim­Namespace(String code)	Trims the namespace, if present.

Methods inherited from class AbstractFactory

get­Vendor

Modifier and Type	Method	Description
Citation	get­Vendor()	Returns the implementer of this factory, or null if unknown.

Methods inherited from class Object

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

Field Details

parser

protected final WKTFormat parser

The parser to use for creating geodetic objects from WKT definitions. Subclasses can modify the WKTFormat configuration in their constructor, but should not use it directly after construction (for thread safety reasons).

Constructor Details

WKTDictionary

public WKTDictionary(Citation authority)

Creates an initially empty factory. The authority can specified explicitly or inferred from the WKTs. In the latter case (when the given authority is null), an authority will be inferred from all ID[…] or AUTHORITY[…] elements found in WKT strings as below, in preference order:

1. Most frequent CITATION[…] value.
2. If there is no citation, then most frequent code space in ID[…] or AUTHORITY[…] elements.

The WKT strings are specified by calls to load(Buffered­Reader) or add­Definitions(Stream) after construction.

Parameters:

authority - organization that defines the codes recognized by this factory, or null.

Method Details

load

public void load(BufferedReader source)
          throws FactoryException

Adds to this factory all definitions read from the given source. Each Coordinate Reference System (or other geodetic object) is defined by a string in WKT format. The key associated with each object is given by the ID[…] or AUTHORITY[…] element, which is typically the last element of a WKT string and is mandatory for definitions in this file.

WKT strings can span many lines. All lines after the first line shall be indented with at least one white space. Non-indented lines start new definitions.

Blank lines and lines starting with the # character (ignoring white spaces) are ignored.

Aliases for WKT fragments

Files with more than one WKT definition tend to repeat the same WKT fragments many times. For example, the same Base­Geog­CRS[…] element may be repeated in every Projected­CRS definitions. Redundant fragments can be replaced by aliases for making the file more compact, easier to read, faster to parse and with smaller memory footprint.

Each line starting with "SET <identifier>=<WKT>" defines an alias for a fragment of WKT string. The WKT can span many lines as described above. Aliases are local to the file where they are defined. Aliases can be expanded in other WKT strings by "$<identifier>".

Validation

This method verifies that definitions have matching quotes, balanced parenthesis or brackets, and valid number or date formats. It does not verify WKT keywords or geodetic parameters. See class javadoc for more details.

Example

An example is available here.

Parameters:

source - the source of WKT definitions.

Throws:

Factory­Exception - if the definition file cannot be read.

addDefinitions

public void addDefinitions(Stream<String> objects)
                    throws FactoryException

Adds definitions of CRS (or other geodetic objects) from Well-Known Texts. Blank strings are ignored. Each non-blank String shall contain the complete definition of exactly one geodetic object. A geodetic object cannot have its definition split in two or more Strings.

The key associated with each object is given by the ID[…] or AUTHORITY[…] element, which is typically the last element of a WKT string and is mandatory. WKT strings can contain line separators for human readability.

Parameters:

objects - CRS (or other geodetic objects) definitions as WKT strings.

Throws:

Factory­Exception - if a WKT cannot be parsed, or does not contain an ID[…] or AUTHORITY[…] element, or if the same codespace:version:code tuple is used for two objects.

fetchDefinition

protected String fetchDefinition(DefaultIdentifier identifier)
                          throws FactoryException

Fetches the Well-Known Text for a user-specified identifier not found in this WKTDictionary. Subclasses can override this method if WKT strings are not loaded or specified in advance, but instead fetched when first needed. An example of such scenario is WKTs provided by the "spatial_ref_sys" table of a spatial database. If no WKT is found for the given identifier, then this method returns null.

On input, identifier contains only the pieces of information provided by user. For example if user invoked create­Geographic­CRS("Foo"), then the identifier code will be "Foo" but the codespace and version will be undefined (null). On output, identifier should be completed with missing code space and version (if available).

Overriding

The default implementation returns null. If a subclass overrides this method, then it should also override get­Authority­Codes(Class) because WKTDictionary does not know the codes that this method can recognize.

Parameters:

identifier - the code specified by user, possible with code space and version.

Returns:

Well-Known Text (WKT) for the given identifier, or null if none.

Throws:

Factory­Exception - if an error occurred while fetching the WKT.

getAuthority

public Citation getAuthority()

Returns the authority or specification that defines the codes recognized by this factory. This is the first of the following values, in preference order:

1. The authority explicitly specified at construction time.
2. A citation built from the most frequent value found in CITATION elements.
3. A citation built from the most frequent value found in ID or AUTHORITY elements.

Specified by:

get­Authority in interface Authority­Factory

Specified by:

get­Authority in class Geodetic­Authority­Factory

Returns:

the organization responsible for CRS definitions, or null if unknown.

See Also:

• Abstract­Factory.get­Vendor()

getCodeSpaces

public Set<String> getCodeSpaces()

Returns all namespaces recognized by this factory. Those namespaces can appear before codes in calls to create­Foo(String) methods, for example "ESRI" in "ESRI:102018". Namespaces are case-insensitive.

Overrides:

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

Returns:

the namespaces recognized by this factory.

getAuthorityCodes

public Set<String> getAuthorityCodes(Class<? extends IdentifiedObject> type)
                              throws FactoryException

Returns the set of authority codes for objects of the given type. The type argument specifies the base type of identified objects.

Parameters:

type - the spatial reference objects type.

Returns:

the set of authority codes for spatial reference objects of the given type.

Throws:

Factory­Exception - if an error occurred while fetching the codes.

getDescriptionText

public Optional<InternationalString> getDescriptionText(Class<? extends IdentifiedObject> type,
 String code)
                                                 throws FactoryException

Gets a description of the object corresponding to a code.

Overrides:

get­Description­Text in class Geodetic­Authority­Factory

Parameters:

type - the type of object for which to get a description.

code - value allocated by authority.

Returns:

a description of the object, or null if null if none.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the query failed for some other reason.

Since:

1.5

createObject

public IdentifiedObject createObject(String code)
                              throws FactoryException

Returns an arbitrary object from a code.

Specified by:

create­Object in interface Authority­Factory

Specified by:

create­Object in class Geodetic­Authority­Factory

Parameters:

code - value allocated by authority.

Returns:

the object for the given code.

Throws:

No­Such­Authority­Code­Exception - if the specified code was not found.

Factory­Exception - if the object creation failed for some other reason.

See Also:

• Abstract­Identified­Object