public class AbstractIdentifiedObject extends FormattableObject implements IdentifiedObject, LenientComparable, Deprecable, Serializable
"EPSG:3395"
), can be used for fetching an object from a database.
However it is not sufficient to know the object name. We also need to know who define that name
(the authority) since the same objects are often named differently
depending on the providers, or conversely the same name is used for different objects depending on the provider.
The main information stored in an IdentifiedObject
are:
Default
.
However exceptions to this rule may occur when it is not possible to identify the exact type.
LOCAL_CS
element.
In such exceptional situation, a plain AbstractCS
object may be instantiated.IdentifiedObject
instances are created in two main ways:
ObjectFactory
, in which case all properties can be explicitely specified.AuthorityFactory
, in which case only a code (typically a primary key) is specified.
The authority
and authority code values are set to the authority name
of the factory object, and the authority code supplied by the client, respectively.
All other information are fetched from the database.Citation
, ReferenceIdentifier
, GenericName
and
InternationalString
instances 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,
IdentifiedObject
instances created using only SIS factories and static constants can be shared by many
objects and passed between threads without synchronization.Defined in the sis-referencing
module
Modifier and Type | Field and Description |
---|---|
static String |
LOCALE_KEY
Optional key which can be given to the constructor for specifying
the locale to use for producing error messages.
|
ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY
Modifier | Constructor and Description |
---|---|
protected |
AbstractIdentifiedObject(IdentifiedObject object)
Constructs a new identified object with the same values than the specified one.
|
|
AbstractIdentifiedObject(Map<String,?> properties)
Constructs an object from the given properties.
|
Modifier and Type | Method and Description |
---|---|
static AbstractIdentifiedObject |
castOrCopy(IdentifiedObject object)
Returns a SIS identified object implementation with the values of the given arbitrary implementation.
|
protected long |
computeHashCode()
Invoked by
hashCode() for computing the hash code when first needed. |
boolean |
equals(Object object)
Compares the specified object with this object for equality.
|
boolean |
equals(Object object,
ComparisonMode mode)
Compares this object with the given object for equality.
|
protected String |
formatTo(Formatter formatter)
Formats the inner part of the Well Known Text (WKT) representation for this object.
|
Collection<GenericName> |
getAlias()
Returns alternative names by which this object is identified.
|
Set<ReferenceIdentifier> |
getIdentifiers()
Returns identifiers which references elsewhere the object's defining information.
|
Class<? extends IdentifiedObject> |
getInterface()
Returns the GeoAPI interface implemented by this class.
|
ReferenceIdentifier |
getName()
Returns the primary name by which this object is identified.
|
InternationalString |
getRemarks()
Returns comments on or information about this object, including data source information.
|
int |
hashCode()
Returns a hash value for this identified object.
|
boolean |
isDeprecated()
Returns
true if this object is deprecated. |
boolean |
isHeuristicMatchForName(String name)
Returns
true if either the primary name or at least
one alias matches the given string according heuristic rules. |
print, toString, toString, toWKT
toWKT
public static final String LOCALE_KEY
AbstractIdentifiedObject
property;
its value is ignored if no error occurred at construction time.public AbstractIdentifiedObject(Map<String,?> properties) throws IllegalArgumentException
"authority"
, "code"
, "codespace"
and "version"
are convenience properties for building a name, and are ignored if the "name"
property
is already a ReferenceIdentifier
object instead than a String
.
Property name | Value type | Returned by |
---|---|---|
"name" | ReferenceIdentifier or String |
getName() |
"authority" | String or Citation |
ImmutableIdentifier.getAuthority() on the name |
"code" | String |
ImmutableIdentifier.getCode() on the name |
"codespace" | String |
ImmutableIdentifier.getCodeSpace() on the name |
"version" | String |
ImmutableIdentifier.getVersion() on the name |
"description" | String |
ImmutableIdentifier.getDescription() on the name |
"alias" | GenericName or CharSequence (optionally as array) |
getAlias() |
"identifiers" | ReferenceIdentifier (optionally as array) |
getIdentifiers() |
"remarks" | InternationalString or String |
getRemarks() |
"locale" | Locale |
(none) |
"remarks"
may have a language and country code suffix.
For example the "remarks_fr"
property stands for remarks in French and
the "remarks_fr_CA"
property stands for remarks in French Canadian.
They are convenience properties for building the InternationalString
value.
The "locale"
property applies only in case of exception for formatting the error message, and
is used only on a best effort basis. The locale is discarded after successful construction
since localizations are applied by the InternationalString.toString(Locale)
method.
properties
map are considered ignorable metadata
while information provided in explicit arguments to the sub-class constructors have an impact on coordinate
transformation results. See equals(Object, ComparisonMode)
for more information.properties
- The properties to be given to this identified object.IllegalArgumentException
- if a property has an invalid value.protected AbstractIdentifiedObject(IdentifiedObject object)
This constructor performs a shallow copy, i.e. the properties are not cloned.
object
- The object to shallow copy.public static AbstractIdentifiedObject castOrCopy(IdentifiedObject object)
null
, then this method returns null
.CoordinateReferenceSystem
,
CoordinateSystem
,
CoordinateSystemAxis
,
Datum
,
Ellipsoid
,
PrimeMeridian
,
ParameterDescriptor
or
ParameterDescriptorGroup
,
then this method delegates to the castOrCopy(…)
method of the corresponding SIS subclass.
Note that if the given object implements more than one of the above-cited interfaces,
then the castOrCopy(…)
method to be used is unspecified.AbstractIdentifiedObject
, then it is returned unchanged.AbstractIdentifiedObject
instance is created using the
copy constructor
and returned. Note that this is a shallow copy operation, since the other
properties contained in the given object are not recursively copied.object
- The object to get as a SIS implementation, or null
if none.null
if the argument was null.public Class<? extends IdentifiedObject> getInterface()
equals(Object, ComparisonMode)
.
The default implementation returns IdentifiedObject.class
.
Subclasses implementing a more specific GeoAPI interface shall override this method.
AbstractIdentifiedObject
instances:
getInterface().isInstance(this)
shall return true
.A.getClass() == B.getClass()
is true
, then
A.getInterface() == B.getInterface()
shall be true
.
Note that the converse does not need to hold.public ReferenceIdentifier getName()
getName
in interface IdentifiedObject
IdentifiedObjects.getName(IdentifiedObject, Citation)
public Collection<GenericName> getAlias()
getAlias
in interface IdentifiedObject
getName()
public Set<ReferenceIdentifier> getIdentifiers()
getIdentifiers
in interface IdentifiedObject
IdentifiedObjects.getIdentifier(IdentifiedObject, Citation)
public InternationalString getRemarks()
getRemarks
in interface Deprecable
getRemarks
in interface IdentifiedObject
null
if none.public boolean isDeprecated()
true
if this object is deprecated. Deprecated objects exist in some
authority factories like the
EPSG database. Deprecated objects are usually obtained from a deprecated authority code.
For this reason, the default implementation applies the following rules:
true
.Deprecable
(because they can not be tested), then returns true
.false
.isDeprecated
in interface Deprecable
true
if this object is deprecated.ImmutableIdentifier.isDeprecated()
public boolean isHeuristicMatchForName(String name)
true
if either the primary name or at least
one alias matches the given string according heuristic rules.
The default implementation returns true
if the given name
is equal,
ignoring aspects documented below, to one of the following names:
The comparison ignores the following aspects:
"Réunion"
and "Reunion"
are considered equal)."Mercator (1SP)"
and "Mercator_1SP"
are considered equal).IdentifiedObject.getName().getCode()
or with the Well Known Text (WKT)
projection or parameter name.IGNORE_METADATA
mode
two objects that can be differentiated only by some identifier (name or alias), like
coordinate system axes,
datum,
parameters and
operation methods.
See equals(Object, ComparisonMode)
for more information.
This method is also invoked when searching a parameter or operation method for a given name.
For example the same projection is known as "Mercator (variant A)"
(the primary name according EPSG)
and "Mercator (1SP)"
(the legacy name prior EPSG 7.6). Since the later is still in frequent use, SIS
accepts it as an alias of the Mercator (variant A) projection.
"Lat"
, "Latitude"
and
"Geodetic latitude"
as synonymous, and likewise for longitude."D_"
prefix, if any.
This prefix appears in ESRI datum name (e.g. "D_WGS_1984"
).name
- The name to compare with the object name or aliases.true
if the primary name of at least one alias matches the specified name
.IdentifiedObjects.isHeuristicMatchForName(IdentifiedObject, String)
public boolean equals(Object object, ComparisonMode mode)
STRICT : |
Verifies if the two objects are of the same class and compares all public properties, including SIS-specific (non standard) properties. |
BY_CONTRACT : |
Verifies if the two objects implement the same GeoAPI interface and compares all properties defined by that interface (name, identifiers, remarks, etc). The two objects do not need to be instances of the same implementation class and SIS-specific properties are ignored. |
IGNORE_METADATA : |
Compares only the properties relevant to coordinate transformations. Generally speaking, the content
of the properties map given at construction time
is considered ignorable metadata while the explicit arguments given to the constructor (if any) are
considered non-ignorable. Note that there is some exceptions to this rule of thumb — see
When object name matter below. |
APPROXIMATIVE : |
Same as IGNORE_METADATA , with some tolerance threshold on numerical values. |
DEBUG : |
Special mode for figuring out why two objects expected to be equal are not. |
sourceCRS.equals(targetCRS, IGNORE_METADATA)
returns true
,
then the transformation from sourceCRS
to targetCRS
should be the identity transform
even if the two CRS do not have the same name.
DefaultCoordinateSystemAxis
,
AbstractDatum
and
DefaultParameterDescriptor
) will compare the
name even in IGNORE_METADATA
mode,
because objects of those types with different names have completely different meaning.
For example nothing differentiate the "semi_major"
and "semi_minor"
parameters except the name.
The name comparison may be lenient however, i.e. the rules may accept a name matching an alias.
See isHeuristicMatchForName(String)
for more information.
equals(Object)
method contractComparisonMode.STRICT
is the only mode compliant with the Object.equals(Object)
contract.
For all other modes, the comparison is not guaranteed to be symmetric neither
transitive. See LenientComparable
for more information.equals
in interface LenientComparable
object
- The object to compare to this
.mode
- The strictness level of the comparison.true
if both objects are equal according the given comparison mode.computeHashCode()
,
Utilities.deepEquals(Object, Object, ComparisonMode)
public final boolean equals(Object object)
Subclasses shall overridereturn equals(other, ComparisonMode.STRICT);
equals(Object, ComparisonMode)
instead than this method.equals
in interface LenientComparable
equals
in class Object
object
- The other object (may be null
).true
if both objects are equal.ComparisonMode.STRICT
public final int hashCode()
AbstractIdentifiedObject
instances
for which equals(Object)
returns true
shall have the same hash code value, if
the hash codes are computed on the same JVM instance for both objects. The hash code value is
not guaranteed to be stable between different versions of the Apache SIS library, or
between libraries running on different JVM.
computeHashCode()
when first needed, then caches the result.
Subclasses shall override computeHashCode()
instead than this method.protected long computeHashCode()
hashCode()
for computing the hash code when first needed.
This method is invoked at most once in normal execution, or an arbitrary amount of times if Java
assertions are enabled. The hash code value shall never change during the whole lifetime of this
object in a JVM. The hash code value does not need to be the same in two different executions of
the JVM.
computeHashCode()
methods shall invoke super.computeHashCode()
,
not hashCode()
. Example:
@Override protected long computeHashCode() { return super.computeHashCode() + 31 * Objects.hash(myProperties); }
protected String formatTo(Formatter formatter)
GeodeticCRS[…]
element,
then subclasses shall write the content starting at the insertion point shown below:
WKT example | Java code example |
---|---|
GeodeticCRS["WGS 84", ID["EPSG", 4326]] ↑ (insertion point) |
super.formatTo(formatter); // ... write the elements at the insertion point ... return "GeodeticCRS"; |
Formatter.setInvalidWKT(…)
methods.
Alternatively, the implementation may also have no WKT keyword for this object.
In such case, this method shall return null
.
formatTo
in class FormattableObject
formatter
- The formatter where to format the inner content of this WKT element.null
if unknown.FormattableObject.toWKT()
,
FormattableObject.toString()
Copyright © 2010–2015 The Apache Software Foundation. All rights reserved.