Package org.apache.sis.referencing.gazetteer

## Class AbstractLocation

- Object
- - AbstractLocation

-     public abstract class AbstractLocation
      extends Object

  Identifiable geographic place. A geographic place may be identified by a name (for example “Eiffel Tower”), by a postcode, or any other method specified by the location type identifications.

  ISO 19112 describes the following properties as mandatory, but Apache SIS relaxes this restriction by providing default values (possibly `null`) in most cases:

  - geographic identifier (the value, for example a name or code)
  - geographic extent (the position of the identified thing)
  - administrator (who is responsible for this identifier)
  - location type (which specifies the nature of the identifier and its associated geographic location)
  The following properties are optional:
  - temporal extent
  - alternative geographic identifier
  - envelope (an Apache SIS extension not in ISO 19112 standard)
  - position (mandatory if the geographic identifier contains insufficient information to identify location)
  - parent location instance
  - child location instance
  Since:
    0.8
  See Also:
    `ModifiableLocationType`, `ReferencingByIdentifiers`, `LocationFormat`

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

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `AbstractLocation​(ModifiableLocationType type, CharSequence identifier)` | Creates a new location for the given geographic identifier.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `AbstractParty` | `getAdministrator()` | Returns the organization responsible for defining the characteristics of the location instance.
    `Collection<? extends InternationalString>` | `getAlternativeGeographicIdentifiers()` | Returns other identifier(s) for the location instance.
    `Collection<? extends AbstractLocation>` | `getChildren()` | Returns location instances of a different location type which subdivides this location instance.
    `Envelope` | `getEnvelope()` | Returns an envelope that encompass the location.
    `GeographicExtent` | `getGeographicExtent()` | Returns a description of the location instance.
    `InternationalString` | `getGeographicIdentifier()` | Returns a unique identifier for the location instance.
    `ModifiableLocationType` | `getLocationType()` | Returns a description of the nature of this geographic identifier.
    `Collection<? extends AbstractLocation>` | `getParents()` | Returns location instances of a different location type, for which this location instance is a sub-division.
    `Position` | `getPosition()` | Returns coordinates of a representative point for the location instance.
    `TemporalExtent` | `getTemporalExtent()` | Returns the date of creation of this version of the location instance.
    `String` | `toString()` | Returns a string representation of this location.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### AbstractLocation

          protected AbstractLocation​(ModifiableLocationType type,
                                     CharSequence identifier)

      Creates a new location for the given geographic identifier. This constructor accepts `null` arguments, but this is not recommended.
      Upcoming API change — generalization
      in a future SIS version, the type of `type` argument may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
      Parameters:
        `type` - the description of the nature of this geographic identifier.
        `identifier` - the geographic identifier to be returned by `getGeographicIdentifier()`.

  - ### Method Detail

    - #### getGeographicIdentifier

          public InternationalString getGeographicIdentifier()

      Returns a unique identifier for the location instance. The methods of identifying locations is specified by the location type identifications.
      Examples: if `LocationType​.getIdentifications()` contain “name”, then geographic identifiers may be country names like “Japan” or “France”, or places like “Eiffel Tower”. If location type identifications contain “code”, then geographic identifiers may be “SW1P 3AD” postcode.
      In order to ensure that a geographic identifier is unique within a wider geographic domain, the geographic identifier may need to include an identifier of an instance of a parent location type, for example “Paris, Texas”.
      Returns:
        unique identifier for the location instance.
      See Also:
        `ModifiableLocationType​.getIdentifications()`

    - #### getAlternativeGeographicIdentifiers

          public Collection<? extends InternationalString> getAlternativeGeographicIdentifiers()

      Returns other identifier(s) for the location instance. The default implementation returns an empty set.
      Returns:
        other identifier(s) for the location instance, or an empty collection if none.

    - #### getTemporalExtent

          public TemporalExtent getTemporalExtent()

      Returns the date of creation of this version of the location instance. The default implementation returns `null`.
      Returns:
        date of creation of this version of the location instance, or `null` if none.

    - #### getGeographicExtent

          public GeographicExtent getGeographicExtent()

      Returns a description of the location instance. This properties is mandatory according ISO 19112, but Apache SIS nevertheless allows `null` value. If non-null, SIS implementations typically provide instances of geographic bounding boxes.
      Returns:
        description of the location instance, or `null` if none.
      See Also:
        `DefaultGeographicBoundingBox`, `DefaultBoundingPolygon`

    - #### getEnvelope

          public Envelope getEnvelope()

      Returns an envelope that encompass the location. This property is partially redundant with `getGeographicExtent()`, except that this method allows envelopes in non-geographic CRS.

      The default implementation copies the `getGeographicExtent()` in a new envelope associated to the default geographic CRS.

      Returns:
        envelope that encompass the location, or `null` if none.

    - #### getPosition

          public Position getPosition()

      Returns coordinates of a representative point for the location instance. This is typically (but not necessarily) the centroid of the location instance.

      The default implementation returns the getEnvelope() median position.

      Returns:
        coordinates of a representative point for the location instance, or `null` if none.

    - #### getLocationType

          public final ModifiableLocationType getLocationType()

      Returns a description of the nature of this geographic identifier.
      Upcoming API change — generalization
      in a future SIS version, the type of returned element may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision. If applied, this method will be made non-final.
      Returns:
        the nature of the identifier and its associated geographic location.

    - #### getAdministrator

          public AbstractParty getAdministrator()

      Returns the organization responsible for defining the characteristics of the location instance. The default implementation returns the owner.
      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:
        organization responsible for defining the characteristics of the location instance, or `null`.
      See Also:
        `ModifiableLocationType​.getOwner()`, `ReferencingByIdentifiers​.getOverallOwner()`

    - #### getParents

          public Collection<? extends AbstractLocation> getParents()

      Returns location instances of a different location type, for which this location instance is a sub-division. The default implementation returns an empty list.
      Upcoming API change — generalization
      in a future SIS version, the type of collection elements may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
      Returns:
        parent locations, or an empty collection if none.
      See Also:
        `ModifiableLocationType​.getParents()`

    - #### getChildren

          public Collection<? extends AbstractLocation> getChildren()

      Returns location instances of a different location type which subdivides this location instance. The default implementation returns an empty list.
      Upcoming API change — generalization
      in a future SIS version, the type of collection elements may be generalized to the `org​.opengis​.referencing​.gazetteer​.Location` interface. This change is pending GeoAPI revision.
      Returns:
        child locations, or an empty collection if none.
      See Also:
        `ModifiableLocationType​.getChildren()`

    - #### toString

          public String toString()

      Returns a string representation of this location. This representation is mostly for debugging purpose and may change in any future Apache SIS version.
      Overrides:
        `toString` in class `Object`
      Returns:
        a string representation of this location for debugging purpose.