Module org.apache.sis.referencing.gazetteer
Package org.apache.sis.referencing.gazetteer

# Class ReferencingByIdentifiers

Object
FormattableObject
AbstractIdentifiedObject
AbstractReferenceSystem
ReferencingByIdentifiers

All Implemented Interfaces:
  `Serializable`, `Formattable`, `Deprecable`, `LenientComparable`, `IdentifiedObject`, `ReferenceSystem`

Direct Known Subclasses:
  `GeohashReferenceSystem`, `MilitaryGridReferenceSystem`

public abstract class ReferencingByIdentifiers extends AbstractReferenceSystem
Base class of reference systems that describe locations using geographic identifiers instead of coordinates.

## Immutability and thread safety

This base class is immutable and thus thread-safe 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, `ReferencingByIdentifiers` instances created using only SIS factories and static constants can be shared by many objects and passed between threads without synchronization.

Since:
  0.8
See Also:
  - `ModifiableLocationType`
  - `AbstractLocation`
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ReferencingByIdentifiers​.Coder`
  Conversions between direct positions and identifiers.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `OVERALL_OWNER_KEY`
  Key for the `"overallOwner"` property to be given to the object factory `createFoo(…)` methods.
  `static final String`
  `THEME_KEY`
  Key for the `"theme"` property to be given to the object factory `createFoo(…)` methods.

  ### Fields inherited from class AbstractIdentifiedObject

  `DEPRECATED_KEY, LOCALE_KEY`

  ### Fields inherited from interface IdentifiedObject

  `ALIAS_KEY, IDENTIFIERS_KEY, NAME_KEY, REMARKS_KEY`

  ### Fields inherited from interface ReferenceSystem

  `DOMAIN_OF_VALIDITY_KEY, SCOPE_KEY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ReferencingByIdentifiers(Map<String,?> properties, ModifiableLocationType... types)`
  Creates a reference system from the given properties.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected long`
  `computeHashCode()`
  Invoked by `hashCode()` for computing the hash code when first needed.
  `abstract ReferencingByIdentifiers​.Coder`
  `createCoder()`
  Returns a new object performing conversions between `DirectPosition` and identifiers.
  `boolean`
  `equals(Object object, ComparisonMode mode)`
  Compares this reference system with the specified object for equality.
  `protected String`
  `formatTo(Formatter formatter)`
  Formats a pseudo-Well Known Text (WKT) representation for this object.
  `List<? extends ModifiableLocationType>`
  `getLocationTypes()`
  Description of location type(s) in the spatial reference system.
  `AbstractParty`
  `getOverallOwner()`
  Authority with overall responsibility for the spatial reference system.
  `InternationalString`
  `getTheme()`
  Property used to characterize the spatial reference system.

  ### Methods inherited from class AbstractReferenceSystem

  `getDomainOfValidity, getInterface, getScope`

  ### Methods inherited from class AbstractIdentifiedObject

  `castOrCopy, equals, formatTo, getAlias, getDescription, getDomains, getIdentifiers, getName, getRemarks, hashCode, isDeprecated, isHeuristicMatchForName`

  ### Methods inherited from class FormattableObject

  `print, toString, toString, toWKT`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface IdentifiedObject

  `getAlias, getIdentifiers, getName, getRemarks, toWKT`

- ## Field Details

  - ### THEME_KEY

    public static final String THEME_KEY
    Key for the `"theme"` property to be given to the object factory `createFoo(…)` methods. This is used for setting the value to be returned by `getTheme()`.
    See Also:
      - `getTheme()`
      - Constant Field Values

  - ### OVERALL_OWNER_KEY

    public static final String OVERALL_OWNER_KEY
    Key for the `"overallOwner"` property to be given to the object factory `createFoo(…)` methods. This is used for setting the value to be returned by `getOverallOwner()`.
    See Also:
      - `getOverallOwner()`
      - Constant Field Values

- ## Constructor Details

  - ### ReferencingByIdentifiers

    public ReferencingByIdentifiers(Map<String,?> properties, ModifiableLocationType... types)
    Creates a reference system from the given properties. The properties given in argument follow the same rules than for the super-class constructor. The following table is a reminder of main (not all) properties:

    Recognized properties (non exhaustive list)
    Property name | Value type | Returned by
    --- | --- | ---
    "theme" | `String` or `InternationalString` | `getTheme()`
    "overallOwner" | `Party` | `getOverallOwner()`
    Defined in parent class (reminder)
    "name" | `Identifier` or `String` | `AbstractIdentifiedObject.getName()`
    "alias" | `GenericName` or `CharSequence` (optionally as array) | `AbstractIdentifiedObject.getAlias()`
    "identifiers" | `Identifier` (optionally as array) | `AbstractIdentifiedObject.getIdentifiers()`
    "remarks" | `InternationalString` or `String` | `AbstractIdentifiedObject.getRemarks()`
    "domainOfValidity" | `Extent` | `AbstractReferenceSystem.getDomainOfValidity()`
    "scope" | `InternationalString` or `String` | `AbstractReferenceSystem.getScope()`

    This constructor copies the given `LocationType` instances as per `ModifiableLocationType​.snapshot(ReferenceSystemUsingIdentifiers, LocationType...)`. Changes in the given location types after construction will not affect this `ReferencingByIdentifiers`.
    Upcoming API change — generalization
    In a future SIS version, the type of array elements may be generalized to the `org​.opengis​.referencing​.gazetteer​.LocationType` interface. This change is pending GeoAPI revision.
    Parameters:
      `properties` - the properties to be given to the reference system.
      `types` - description of location type(s) in the spatial reference system.

- ## Method Details

  - ### getTheme

    public InternationalString getTheme()
    Property used to characterize the spatial reference system.
    Returns:
      property used to characterize the spatial reference system.
    See Also:
      - `ModifiableLocationType​.getTheme()`

  - ### getOverallOwner

    public AbstractParty getOverallOwner()
    Authority with overall responsibility for the spatial reference system.
    Upcoming API change — generalization
    in a future SIS version, the type of returned element may be generalized to the `org​.opengis​.metadata​.citation​.Party` interface. This change is pending GeoAPI revision for upgrade from ISO 19115:2003 to ISO 19115:2014.
    Returns:
      authority with overall responsibility for the spatial reference system.
    See Also:
      - `ModifiableLocationType​.getOwner()`
      - `AbstractLocation​.getAdministrator()`

  - ### getLocationTypes

    public List<? extends ModifiableLocationType> getLocationTypes()
    Description of location type(s) in the spatial reference system. The collection returned by this method is unmodifiable.
    Upcoming API change — generalization
    in a future SIS version, the type of elements type may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
    Returns:
      description of location type(s) in the spatial reference system.
    See Also:
      - `ModifiableLocationType​.getReferenceSystem()`

  - ### createCoder

    public abstract ReferencingByIdentifiers.Coder createCoder()
    Returns a new object performing conversions between `DirectPosition` and identifiers. The returned object is not thread-safe; a new instance must be created for each thread, or synchronization must be applied by the caller.
    Returns:
      a new object performing conversions between `DirectPosition` and identifiers.
    Since:
      1.3

  - ### equals

    public boolean equals(Object object, ComparisonMode mode)
    Compares this reference system with the specified object for equality. If the `mode` argument value is `STRICT` or `BY_CONTRACT`, then all available properties are compared including the theme and the overall owner.
    Specified by:
      `equals` in interface `LenientComparable`
    Overrides:
      `equals` in class `AbstractIdentifiedObject`
    Parameters:
      `object` - the object to compare to `this`.
      `mode` - `STRICT` for performing a strict comparison, or `IGNORE_METADATA` for comparing only properties relevant to location identifications.
    Returns:
      `true` if both objects are equal.
    See Also:
      - `AbstractIdentifiedObject​.computeHashCode()`
      - `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  - ### computeHashCode

    protected long computeHashCode()
    Invoked by `hashCode()` for computing the hash code when first needed. See `AbstractIdentifiedObject​.computeHashCode()` for more information.
    Overrides:
      `computeHashCode` in class `AbstractIdentifiedObject`
    Returns:
      the hash code value. This value may change in any future Apache SIS version.

  - ### formatTo

    @Debug protected String formatTo(Formatter formatter)
    Formats a pseudo-Well Known Text (WKT) representation for this object. The format produced by this method is non-standard and may change in any future Apache SIS version.
    Overrides:
      `formatTo` in class `AbstractIdentifiedObject`
    Parameters:
      `formatter` - the formatter where to format the inner content of this pseudo-WKT element.
    Returns:
      an arbitrary keyword for the pseudo-WKT element.
    See Also:
      - WKT 2 specification §7