Module org.apache.sis.referencing

Package org.apache.sis.referencing.datum

Class AbstractDatum

Object

FormattableObject

AbstractIdentifiedObject

AbstractDatum

All Implemented Interfaces:

Serializable, Formattable, Deprecable, Lenient­Comparable, 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 inherited from class AbstractIdentifiedObject

DEPRECATED_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 than 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.
International­String	get­Anchor­Point()	Returns a description of the point(s) used to anchor the datum to the Earth.
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.
Date	get­Realization­Epoch()	The time after which this datum definition is valid.
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

Constructor Details

AbstractDatum

public AbstractDatum(Map<String,?> properties)

Creates a datum from the given properties. The properties given in argument follow the same rules than 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	getAnchorPoint()
"realizationEpoch"	Date	getRealizationEpoch()
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 than 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.

getAnchorPoint

public InternationalString getAnchorPoint()

Returns a description of the point(s) used to anchor the datum to the Earth. Also known as the "origin", especially for Engineering and Image Datums.

• For a geodetic datum, 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 an image datum, the anchor point may be the centre or the corner of the image.
• For a temporal datum, see their origin instead.

Specified by:

get­Anchor­Point in interface Datum

Returns:

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

getRealizationEpoch

public Date getRealizationEpoch()

The time after which this datum definition is valid. This time may be precise or merely a year.

If an old datum is superseded by a new datum, then the realization epoch for the new datum defines the upper limit for the validity of the old datum.

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.

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 point, realization epoch, and the domains.

Specified by:

equals in interface Lenient­Comparable

Overrides:

equals in class Abstract­Identified­Object

Parameters:

object - the object to compare to this.

mode - STRICT for performing a strict comparison, or IGNORE_METADATA for comparing only properties relevant to coordinate transformations.

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.

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:

• WKT 2 specification §7