Class AbstractDatum

Object

FormattableObject

AbstractIdentifiedObject

AbstractDatum

All Implemented Interfaces:

Serializable, Formattable, Deprecable, Lenient­Comparable, Printable, Datum, Identified­Object

Direct Known Subclasses:

Default­Engineering­Datum, Default­Geodetic­Datum, Default­Image­Datum, Default­Parametric­Datum, Default­Temporal­Datum, Default­Vertical­Datum

public class AbstractDatum
extends AbstractIdentifiedObject
implements Datum

Specifies the relationship of a Coordinate System to the earth. A datum can be defined as a set of real points on the earth that have coordinates. Each datum subtype can be associated with only specific types of coordinate systems, thus creating specific types of coordinate reference system.

Instantiation

This class is conceptually abstract, even if it is technically possible to instantiate it. Typical applications should create instances of the most specific subclass prefixed by Default instead.

Immutability and thread safety

This base class is immutable if the property values (not necessarily the map itself) given to the constructor are also immutable. Most SIS subclasses and related classes are immutable under similar conditions. This means that unless otherwise noted in the javadoc, Datum instances created using only SIS factories and static constants can be shared by many objects and passed between threads without synchronization.

Since:

0.4

See Also:

• Abstract­CS
• Abstract­CRS
• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ANCHOR_DEFINITION_KEY	Key for the "anchor­Definition" property to be given to the Datum­Factory.create­Foo(Map, ...) methods.
static final String	ANCHOR_EPOCH_KEY	Key for the "anchor­Epoch" property to be given to the Datum­Factory.create­Foo(Map, ...) methods.
static final String	CONVENTIONAL_RS_KEY	Key for the "conventional­RS" property to be given to the Datum­Factory.create­Foo(Map, ...) methods.
static final String	PUBLICATION_DATE_KEY	Key for the "publication­Date" property to be given to the Datum­Factory.create­Foo(Map, ...) methods.

Fields inherited from class AbstractIdentifiedObject

DEPRECATED_KEY, DOMAINS_KEY, LOCALE_KEY

Fields inherited from interface Datum

ANCHOR_POINT_KEY, DOMAIN_OF_VALIDITY_KEY, REALIZATION_EPOCH_KEY, SCOPE_KEY

Fields inherited from interface IdentifiedObject

ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY

Constructor Summary

Constructors

Modifier	Constructor	Description
	Abstract­Datum(Map<String,?> properties)	Creates a datum from the given properties.
protected	Abstract­Datum(Datum datum)	Creates a new datum with the same values as the specified one.

Method Summary

Modifier and Type	Method	Description
static Abstract­Datum	cast­Or­Copy(Datum object)	Returns a SIS datum implementation with the values of the given arbitrary implementation.
boolean	equals(Object object, Comparison­Mode mode)	Compares the specified object with this datum for equality.
protected String	format­To(Formatter formatter)	Formats the inner part of the Well Known Text (WKT) representation for this datum.
Optional<International­String>	get­Anchor­Definition()	Returns a description of the relationship used to anchor the coordinate system to the Earth or alternate object.
Optional<Temporal>	get­Anchor­Epoch()	Returns the epoch at which a static datum matches a dynamic datum from which it has been derived.
International­String	get­Anchor­Point()	Deprecated. Renamed get­Anchor­Definition() as of ISO 19111:2019.
Optional<Identified­Object>	get­Conventional­RS()	Returns the name, identifier, alias and remarks for the reference system realized by this reference frame.
Extent	get­Domain­Of­Validity()	Deprecated. Replaced by Abstract­Identified­Object.get­Domains() as of ISO 19111:2019.
Class<? extends Datum>	get­Interface()	Returns the GeoAPI interface implemented by this class.
Optional<Temporal>	get­Publication­Date()	Returns the date on which the datum definition was published.
Date	get­Realization­Epoch()	Deprecated. Since ISO 19111:2019, replaced by get­Anchor­Epoch().
International­String	get­Scope()	Deprecated. Replaced by Abstract­Identified­Object.get­Domains() as of ISO 19111:2019.
boolean	is­Heuristic­Match­For­Name(String name)	Returns true if either the primary name or at least one alias matches the given string according heuristic rules.

Methods inherited from class AbstractIdentifiedObject

cast­Or­Copy, equals, format­To, get­Alias, get­Description, get­Domains, get­Identifiers, get­Name, get­Remarks, hash­Code, is­Deprecated

Methods inherited from class FormattableObject

print, to­String, to­String, to­WKT

Methods inherited from class Object

clone, finalize, get­Class, notify, notify­All, wait, wait, wait

Methods inherited from interface IdentifiedObject

get­Alias, get­Identifiers, get­Name, get­Remarks, to­WKT

Field Details

ANCHOR_DEFINITION_KEY

public static final String ANCHOR_DEFINITION_KEY

Key for the "anchor­Definition" property to be given to the Datum­Factory.create­Foo(Map, ...) methods. This is used for setting the value to be returned by get­Anchor­Definition().

Since:

1.5

See Also:

• invalid reference

  Datum­Factory

• get­Anchor­Definition()
• Constant Field Values

ANCHOR_EPOCH_KEY

public static final String ANCHOR_EPOCH_KEY

Key for the "anchor­Epoch" property to be given to the Datum­Factory.create­Foo(Map, ...) methods. This is used for setting the value to be returned by get­Anchor­Epoch().

Since:

1.5

See Also:

• invalid reference

  Datum­Factory

• get­Anchor­Epoch()
• Constant Field Values

PUBLICATION_DATE_KEY

public static final String PUBLICATION_DATE_KEY

Key for the "publication­Date" property to be given to the Datum­Factory.create­Foo(Map, ...) methods. This is used for setting the value to be returned by get­Publication­Date().

Since:

1.5

See Also:

• Constant Field Values

CONVENTIONAL_RS_KEY

public static final String CONVENTIONAL_RS_KEY

Key for the "conventional­RS" property to be given to the Datum­Factory.create­Foo(Map, ...) methods. This is used for setting the value to be returned by get­Conventional­RS().

Since:

1.5

See Also:

• Constant Field Values

Constructor Details

AbstractDatum

public AbstractDatum(Map<String,?> properties)

Creates a datum from the given properties. The properties given in argument follow the same rules as for the super-class constructor. Additionally, the following properties are understood by this constructor:

Recognized properties (non exhaustive list)

Property name	Value type	Returned by
"anchorPoint"	InternationalString or String	getAnchorDefinition()
"anchorEpoch"	Temporal	getAnchorEpoch()
"publicationDate"	Temporal	getPublicationDate()
"conventionalRS"	IdentifiedObject	getConventionalRS()
Defined in parent class (reminder)
"name"	ReferenceIdentifier or String	AbstractIdentifiedObject.getName()
"alias"	GenericName or Char­Sequence (optionally as array)	AbstractIdentifiedObject.getAlias()
"identifiers"	ReferenceIdentifier (optionally as array)	AbstractIdentifiedObject.getIdentifiers()
"domains"	DefaultObjectDomain (optionally as array)	AbstractIdentifiedObject.getDomains()
"remarks"	InternationalString or String	AbstractIdentifiedObject.getRemarks()

Parameters:

properties - the properties to be given to the identified object.

AbstractDatum

protected AbstractDatum(Datum datum)

Creates a new datum with the same values as the specified one. This copy constructor provides a way to convert an arbitrary implementation into a SIS one or a user-defined one (as a subclass), usually in order to leverage some implementation-specific API.

This constructor performs a shallow copy, i.e. the properties are not cloned.

Parameters:

datum - the datum to copy.

Method Details

castOrCopy

public static AbstractDatum castOrCopy(Datum object)

Returns a SIS datum implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:

• If the given object is null, then this method returns null.
• Otherwise if the given object is an instance of Geodetic­Datum, Vertical­Datum, Temporal­Datum, Engineering­Datum or Image­Datum, then this method delegates to the cast­Or­Copy(…) method of the corresponding SIS subclass. Note that if the given object implements more than one of the above-cited interfaces, then the cast­Or­Copy(…) method to be used is unspecified.
• Otherwise if the given object is already an instance of Abstract­Datum, then it is returned unchanged.
• Otherwise a new Abstract­Datum instance is created using the copy constructor and returned. Note that this is a shallow copy operation, because the other properties contained in the given object are not recursively copied.

Parameters:

object - the object to get as a SIS implementation, or null if none.

Returns:

a SIS implementation containing the values of the given object (may be the given object itself), or null if the argument was null.

getInterface

public Class<? extends Datum> getInterface()

Returns the GeoAPI interface implemented by this class. The default implementation returns Datum.class. Subclasses implementing a more specific GeoAPI interface shall override this method.

Overrides:

get­Interface in class Abstract­Identified­Object

Returns:

the datum interface implemented by this class.

getAnchorDefinition

public Optional<InternationalString> getAnchorDefinition()

Returns a description of the relationship used to anchor the coordinate system to the Earth or alternate object. Also known as the "origin", especially for Engineering and Image Datums.

• For a geodetic reference frame, the anchor may be the point(s) where the relationship between geoid and ellipsoid is defined.
• For an engineering datum, the anchor may be an identified physical point with the orientation defined relative to the object.
• For a temporal datum, see their origin instead.

Returns:

description, possibly including coordinates, of the point or points used to anchor the datum to the Earth.

Since:

1.5

getAnchorPoint

@Deprecated(since="1.5")
public InternationalString getAnchorPoint()

Deprecated.

Renamed get­Anchor­Definition() as of ISO 19111:2019.

Returns a description of the point(s) used to anchor the datum to the Earth.

Specified by:

get­Anchor­Point in interface Datum

Returns:

a description of the point(s) used to anchor the datum to the Earth.

getAnchorEpoch

public Optional<Temporal> getAnchorEpoch()

Returns the epoch at which a static datum matches a dynamic datum from which it has been derived. This time may be precise or merely a year (e.g. 1983 for NAD83).

Returns:

epoch at which a static datum matches a dynamic datum from which it has been derived.

Since:

1.5

See Also:

• Year
• Year­Month
• Local­Date

getRealizationEpoch

@Deprecated(since="1.5")
public Date getRealizationEpoch()

Deprecated.

Since ISO 19111:2019, replaced by get­Anchor­Epoch().

The time after which this datum definition is valid.

Specified by:

get­Realization­Epoch in interface Datum

Returns:

the time after which this datum definition is valid, or null if none.

getDomainOfValidity

@Deprecated(since="1.4")
public Extent getDomainOfValidity()

Deprecated.

Replaced by Abstract­Identified­Object.get­Domains() as of ISO 19111:2019.

Returns the region or timeframe in which this datum is valid, or null if unspecified.

Specified by:

get­Domain­Of­Validity in interface Datum

Returns:

area or region or timeframe in which this datum is valid, or null.

getScope

@Deprecated(since="1.4")
public InternationalString getScope()

Deprecated.

Replaced by Abstract­Identified­Object.get­Domains() as of ISO 19111:2019.

Returns the domain or limitations of usage, or null if unspecified.

Specified by:

get­Scope in interface Datum

Returns:

description of domain of usage, or limitations of usage, for which this datum object is valid.

getPublicationDate

public Optional<Temporal> getPublicationDate()

Returns the date on which the datum definition was published.

Returns:

date on which the datum definition was published.

Since:

1.5

getConventionalRS

public Optional<IdentifiedObject> getConventionalRS()

Returns the name, identifier, alias and remarks for the reference system realized by this reference frame. All datums that are members of a datum ensemble shall have the same conventional reference system.

Returns:

reference system realized by this reference frame.

Since:

1.5

isHeuristicMatchForName

public boolean isHeuristicMatchForName(String name)

Returns true if either the primary name or at least one alias matches the given string according heuristic rules. This method performs the comparison documented in the super-class, with the following additional flexibility:

• The "D_" prefix (used in ESRI datum names), if presents in the given name or in this datum name, is ignored.
• If this datum is an instance of Default­Geodetic­Datum, then the prime meridian name may also be ignored.

Future evolutions

This method implements heuristic rules learned from experience while trying to provide inter-operability with different data producers. Those rules may be adjusted in any future SIS version according experience gained while working with more data producers.

Overrides:

is­Heuristic­Match­For­Name in class Abstract­Identified­Object

Parameters:

name - the name to compare.

Returns:

true if the primary name or at least one alias matches the specified name.

See Also:

• Identified­Objects.is­Heuristic­Match­For­Name(Identified­Object, String)
• Characters.Filter.LETTERS_AND_DIGITS

equals

public boolean equals(Object object,
 ComparisonMode mode)

Compares the specified object with this datum for equality. If the mode argument value is STRICT or BY_CONTRACT, then all available properties are compared including the anchor definition, anchor epoch, and the domains.

Static versus dynamic datum

If this datum implements the Dynamic­Reference­Frame interface, then the given object needs to also implement that interface and provide the same reference epoch for being considered equal. Conversely, if this datum does not implement Dynamic­Reference­Frame, then the given object also need to not implement that interface for being considered equal. This condition is relaxed with Comparison­Mode.COMPATIBILITY if the two reference frames have a common identifier or an equivalent name.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Identified­Object

Parameters:

object - the object to compare to this.

mode - the strictness level of the comparison.

Returns:

true if both objects are equal.

See Also:

• Abstract­Identified­Object.compute­Hash­Code()
• Utilities.deep­Equals(Object, Object, Comparison­Mode)

formatTo

protected String formatTo(Formatter formatter)

Formats the inner part of the Well Known Text (WKT) representation for this datum. See Abstract­Identified­Object.format­To(Formatter) for more information.

Default implementation

The default implementation appends the datum name and returns "Member" if this datum is formatted inside a ENSEMBLE WKT element, or null otherwise.

Overrides:

format­To in class Abstract­Identified­Object

Parameters:

formatter - the formatter where to format the inner content of this WKT element.

Returns:

the CamelCase keyword for the WKT element, or null if unknown.

See Also:

• Formattable­Object.to­WKT()
• Formattable­Object.to­String()