Package org.apache.sis.referencing.gazetteer

# Class ModifiableLocationType

Object
ModifiableLocationType

All Implemented Interfaces:
  `LenientComparable`

public class ModifiableLocationType extends Object
Helper class for building the description of a location. Temporary instances of this class can be used during the construction of spatial reference systems using geographic identifiers. Since `ModifiableLocationType` instances are modifiable, they should not be published directly. Instead, unmodifiable snapshots should be published. The same `ModifiableLocationType` instance can be used for many snapshots.
Example: the following code creates 3 levels of location types: administrative areas, which contain towns, which themselves contain streets. Note that the `street` location type has two parents, `town` and `area`, because a street can be outside any town and directly under the authority of an administrative area instead.

>     ModifiableLocationType area   = new ModifiableLocationType("administrative area");
>     ModifiableLocationType town   = new ModifiableLocationType("town");
>     ModifiableLocationType street = new ModifiableLocationType("street");

>     area  .setTheme("local administration");
>     town  .setTheme("built environment");
>     street.setTheme("access");

>     area  .setDefinition("area of responsibility of highest level local authority");
>     town  .setDefinition("city or town");
>     street.setDefinition("thoroughfare providing access to properties");

>     town  .addParent(area);
>     street.addParent(area);
>     street.addParent(town);

A string representation of the `area` location type is as below:

>     administrative area………………… area of responsibility of highest level local authority
>       ├─town……………………………………………… city or town
>       │   └─street……………………………… thoroughfare providing access to properties
>       └─street………………………………………… thoroughfare providing access to properties

## Inheritance of property values

According ISO 19112:2003, all properties except the collection of parents and children are mandatory. Those mandatory properties are the name, theme, identifications, definition, territory of use and owner. However in Apache SIS implementation, only the name is truly mandatory; SIS is tolerant to missing value for all other properties. But in the hope to improve ISO compliance, values of undefined properties are inherited from the parents (if any) provided that all parents define the same values.
Example: if an administrative area is in some territory of use, then all children of the administrative area (namely towns and streets) can reasonably presumed to be in the same territory of use. That territory can be specified only once as below:

>     area.setTerritoryOfUse("Japan");

Then, the towns and streets automatically inherit the same value for that property, unless they are explicitly given another value.

## Limitation

This class is not serializable and is not thread-safe. For thread safety or for serialization, a snapshots of this location type should be taken.

Since:
  0.8
See Also:
  - `AbstractLocation`
  - `ReferencingByIdentifiers`

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ModifiableLocationType(CharSequence name)`
  Creates a new location type of the given name.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addIdentification(CharSequence value)`
  Adds a method of uniquely identifying location instances.
  `void`
  `addParent(ModifiableLocationType parent)`
  Adds the given element to the list of parents.
  `final boolean`
  `equals(Object object)`
  Compares this location type with the specified object for strict equality.
  `boolean`
  `equals(Object object, ComparisonMode mode)`
  Compares this location type with the specified object for equality.
  `final Collection<ModifiableLocationType>`
  `getChildren()`
  Returns the child location types (location types which sub-divides this location type).
  `InternationalString`
  `getDefinition()`
  Returns the way in which location instances are defined.
  `Collection<InternationalString>`
  `getIdentifications()`
  Returns the method(s) of uniquely identifying location instances.
  `InternationalString`
  `getName()`
  Returns the name of the location type.
  `AbstractParty`
  `getOwner()`
  Returns the name of organization or class of organization able to create and destroy location instances.
  `final Collection<ModifiableLocationType>`
  `getParents()`
  Returns the parent location types (location types of which this location type is a sub-division).
  `ReferencingByIdentifiers`
  `getReferenceSystem()`
  Returns the reference system that comprises this location type.
  `GeographicExtent`
  `getTerritoryOfUse()`
  Returns the geographic area within which the location type occurs.
  `InternationalString`
  `getTheme()`
  Returns the property used as the defining characteristic of the location type.
  `int`
  `hashCode()`
  Returns a hash code value for this location type.
  `void`
  `removeIdentification(CharSequence value)`
  Removes a method of uniquely identifying location instances.
  `void`
  `removeParent(ModifiableLocationType parent)`
  Removes the given element from the list of parent.
  `void`
  `setDefinition(CharSequence value)`
  Sets the way in which location instances are defined.
  `void`
  `setOwner(CharSequence name)`
  Sets the name of the organization or class of organization able to create and destroy location instances.
  `void`
  `setOwner(AbstractParty value)`
  Sets the organization or class of organization able to create and destroy location instances.
  `void`
  `setTerritoryOfUse(String identifier)`
  Sets the name of the geographic area within which the location type occurs.
  `void`
  `setTerritoryOfUse(GeographicExtent value)`
  Sets the geographic area within which the location type occurs.
  `void`
  `setTheme(CharSequence value)`
  Sets the property used as the defining characteristic of the location type.
  `static List<AbstractLocationType>`
  `snapshot(ReferencingByIdentifiers rs, AbstractLocationType... types)`
  Creates unmodifiable snapshots of the given location types.
  `String`
  `toString()`
  Returns a string representation of this location type and all its children.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### ModifiableLocationType

    public ModifiableLocationType(CharSequence name)
    Creates a new location type of the given name.
    Parameters:
      `name` - the location type name.

- ## Method Details

  - ### getName

    public InternationalString getName()
    Returns the name of the location type. This name is specified at construction time and can not be changed.
    Examples: “administrative area”, “town”, “locality”, “street”, “property”.
    Returns:
      name of the location type.

  - ### getTheme

    public InternationalString getTheme()
    Returns the property used as the defining characteristic of the location type. If no theme has been explicitly set, then this method inherits the value from the parents providing that all parents specify the same theme.
    Returns:
      property used as the defining characteristic of the location type, or `null` if no value has been defined or can be inherited.
    See Also:
      - `ReferencingByIdentifiers​.getTheme()`

  - ### setTheme

    public void setTheme(CharSequence value)
    Sets the property used as the defining characteristic of the location type.
    Examples: “local administration” for administrative areas, “built environment” for towns or properties, “access” for streets, “electoral”, “postal”.
    Parameters:
      `value` - the new theme, or `null` for inheriting a value from the parents.

  - ### getIdentifications

    public Collection<InternationalString> getIdentifications()
    Returns the method(s) of uniquely identifying location instances. If no methods have been explicitly set, then this method inherits the values from the parents providing that all parents specify the same methods.
    Examples: some identification methods are “name”, “code”, “unique street reference number” and “geographic address”. A location using “name” identifications may have the “Spain” geographic identifier, and a location using “postcode” identifications may have the “SW1P 3AD” geographic identifier.
    The collection returned by this method is unmodifiable. For adding or removing an identification, use `addIdentification(CharSequence)` or `removeIdentification(CharSequence)`.
    Returns:
      method(s) of uniquely identifying location instances, or an empty list if no value has been defined or can be inherited.
    See Also:
      - `AbstractLocation​.getGeographicIdentifier()`

  - ### addIdentification

    public void addIdentification(CharSequence value)
    Adds a method of uniquely identifying location instances.
    Examples: “name”, “code”, “unique street reference number”, “geographic address”.
    Parameters:
      `value` - the method to add.
    Throws:
      `IllegalArgumentException` - if the given value is already defined.

  - ### removeIdentification

    public void removeIdentification(CharSequence value)
    Removes a method of uniquely identifying location instances.
    Parameters:
      `value` - the method to remove.
    Throws:
      `IllegalArgumentException` - if the given value is not found.

  - ### getDefinition

    public InternationalString getDefinition()
    Returns the way in which location instances are defined. If no definition has been explicitly set, then this method inherits the value from the parents providing that all parents specify the same definition.
    Returns:
      the way in which location instances are defined, or `null` if no value has been defined or can be inherited.

  - ### setDefinition

    public void setDefinition(CharSequence value)
    Sets the way in which location instances are defined.
    Parameters:
      `value` - the new identification.

  - ### getTerritoryOfUse

    public GeographicExtent getTerritoryOfUse()
    Returns the geographic area within which the location type occurs. If no geographic area has been explicitly set, then this method inherits the value from the parents providing that all parents specify the same geographic area.
    Returns:
      geographic area within which the location type occurs, or `null` if no value has been defined or can be inherited.
    See Also:
      - `AbstractReferenceSystem​.getDomainOfValidity()`

  - ### setTerritoryOfUse

    public void setTerritoryOfUse(GeographicExtent value)
    Sets the geographic area within which the location type occurs. The given value is typically an instance of `DefaultGeographicBoundingBox`. For an alternative where only the territory name is specified, see `setTerritoryOfUse(String)`.
    Parameters:
      `value` - the new geographic extent.

  - ### setTerritoryOfUse

    public void setTerritoryOfUse(String identifier)
    Sets the name of the geographic area within which the location type occurs.
    Examples: the geographic domain for a location type “rivers” might be “North America”.
    Parameters:
      `identifier` - the identifier of the geographic extent.

  - ### getOwner

    public AbstractParty getOwner()
    Returns the name of organization or class of organization able to create and destroy location instances. If no organization has been explicitly set, then this method inherits the value from the parents providing that all parents specify the same organization.
    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 or class of organization able to create and destroy location instances, or `null` if no value has been defined or can be inherited.
    See Also:
      - `AbstractLocation​.getAdministrator()`
      - `ReferencingByIdentifiers​.getOverallOwner()`

  - ### setOwner

    public void setOwner(AbstractParty value)
    Sets the organization or class of organization able to create and destroy location instances. The given value is typically an instance of `DefaultOrganisation`. For an alternative where only the organization name is specified, see `setOwner(CharSequence)`.
    Upcoming API change — generalization
    in a future SIS version, the argument type 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.
    Parameters:
      `value` - the new owner.

  - ### setOwner

    public void setOwner(CharSequence name)
    Sets the name of the organization or class of organization able to create and destroy location instances.
    Parameters:
      `name` - the organization name.

  - ### getParents

    public final Collection<ModifiableLocationType> getParents()
    Returns the parent location types (location types of which this location type is a sub-division). A location type can have more than one possible parent. For example the parent of a location type named “street” could be “locality”, “town” or “administrative area”.

    The collection returned by this method is unmodifiable. For adding or removing a parent, use `addParent(ModifiableLocationType)` or `removeParent(ModifiableLocationType)`.

    Returns:
      parent location types, or an empty collection if none.
    See Also:
      - `AbstractLocation​.getParents()`

  - ### getChildren

    public final Collection<ModifiableLocationType> getChildren()
    Returns the child location types (location types which sub-divides this location type). The collection returned by this method is unmodifiable. For adding or removing a child, use `child.addParent(this)` or `child.removeParent(this)`.
    Returns:
      child location types, or an empty collection if none.
    See Also:
      - `AbstractLocation​.getChildren()`

  - ### addParent

    public void addParent(ModifiableLocationType parent)
    Adds the given element to the list of parents.
    Parameters:
      `parent` - the parent to add.
    Throws:
      `IllegalStateException` - if this location type already have a parent of the same name.
      `IllegalArgumentException` - if the given parent already have a child of the same name than this location type.

  - ### removeParent

    public void removeParent(ModifiableLocationType parent)
    Removes the given element from the list of parent.
    Parameters:
      `parent` - the parent to remove.
    Throws:
      `IllegalArgumentException` - if the given parent has not been found.

  - ### getReferenceSystem

    public ReferencingByIdentifiers getReferenceSystem()
    Returns the reference system that comprises this location type. For `ModifiableLocationType`s, the reference system is always null. The reference system is defined when the location types are given to the `ReferencingByIdentifiers` constructor for example.
    Upcoming API change — generalization
    in a future SIS version, the type of returned element may be generalized to the `org​.opengis​.referencing​.gazetteer​.ReferenceSystemUsingIdentifiers` interface. This change is pending GeoAPI revision.
    Returns:
      `null`.
    See Also:
      - `ReferencingByIdentifiers​.getLocationTypes()`

  - ### snapshot

    public static List<AbstractLocationType> snapshot(ReferencingByIdentifiers rs, AbstractLocationType... types)
    Creates unmodifiable snapshots of the given location types. This method returns a new collection within which all elements are snapshots of the given location types (in iteration order), except the reference system which is set to the given value.

    The location types returned by this method are serializable if all properties (name, territory of use, etc. are also serializable).

    Parameters:
      `rs` - the reference system to assign to the new location types, or `null` if none.
      `types` - the location types for which to take a snapshot.
    Returns:
      unmodifiable copies of the given location types.

  - ### equals

    public boolean equals(Object object, ComparisonMode mode)
    Compares this location type with the specified object for equality. This method compares the value of `getName()` and `getChildren()` in all modes. At the opposite, values of `getParents()` and `getReferenceSystem()` are never compared, no matter the mode, for avoiding never-ending loops. Other properties may or may not be compared depending on the `mode` argument.

    If the `mode` argument value is `STRICT` or `BY_CONTRACT`, then almost all properties are compared including the theme and the owner.

    Specified by:
      `equals` in interface `LenientComparable`
    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:
      - `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  - ### equals

    public final boolean equals(Object object)
    Compares this location type with the specified object for strict equality. This method compares all properties except the value returned by `getParents()` and `getReferenceSystem()`, for avoiding never-ending loops.

    This method is implemented as below:

    >     return equals(object, ComparisonMode.STRICT);

    Specified by:
      `equals` in interface `LenientComparable`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare to `this`.
    Returns:
      `true` if both objects are equal.
    See Also:
      - `ComparisonMode​.STRICT`

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this location type.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value for this location type.

  - ### toString

    public String toString()
    Returns a string representation of this location type and all its children. Current implementation formats a tree with the name and definition of each type, like below:

    >     administrative area………………… area of responsibility of highest level local authority
    >       ├─town……………………………………………… city or town
    >       │   └─street……………………………… thoroughfare providing access to properties
    >       └─street………………………………………… thoroughfare providing access to properties

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