Package org.apache.sis.referencing.gazetteer

## Class ReferencingByIdentifiers

- Object
- - FormattableObject
  - - AbstractIdentifiedObject
    - - AbstractReferenceSystem
      - - ReferencingByIdentifiers

- All Implemented Interfaces:
    `Serializable`, `Deprecable`, `LenientComparable`, `IdentifiedObject`, `ReferenceSystem`
  Direct Known Subclasses:
    `GeohashReferenceSystem`, `MilitaryGridReferenceSystem`

      public class ReferencingByIdentifiers
      extends AbstractReferenceSystem

  Base class of reference systems that describe locations using geographic identifiers instead than 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

  Defined in the `sis-referencing-by-identifiers` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static String` | `OVERALL_OWNER_KEY` | Key for the `"overallOwner"` property to be given to the object factory `createFoo(…)` methods.
    `static 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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected long` | `computeHashCode()` | Invoked by `hashCode()` for computing the hash code when first needed.
    `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, getAlias, getDescription, 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 Detail

    - #### 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 Detail

    - #### 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 Detail

    - #### 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()`

    - #### 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 `AbstractReferenceSystem`
      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 `AbstractReferenceSystem`
      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