Module org.apache.sis.storage
Package org.apache.sis.storage

# Class FeatureNaming<E>

Object
FeatureNaming<E>

Type Parameters:
  `E` - the type of elements associated with the names.

public class FeatureNaming<E> extends Object
Helper class for mapping `GenericName` instances and their shortened names to features. The features are typically represented by instances of `FeatureType` or `Coverage` (sometimes seen as a kind of features), but this class actually puts no restriction on the kind of object associated to `GenericName`s; `DataStore` implementations are free to choose their internal object. Those objects can be stored and fetched using the `String` representation of their name as given by `GenericName​.toString()`, or a shortened name when there is no ambiguity. Note that search is case sensitive.

## Example

a data store may contain a `FeatureType` named `"foo:bar"`. If that feature type has been binded like below:

    FeatureNaming<FeatureType> binding = new FeatureNaming<>();
    FeatureType myFooBar = ...;                                  // Some type named "foo:bar" for this example.
    binding.add(null, myFooBar.getName(), myFooBar);

Then the two following lines return the same instance:

    assert binding.get(null, "foo:bar") == myFooBar;
    assert binding.get(null,     "bar") == myFooBar;    // Allowed only if there is no ambiguity.

Note that contrarily to the standard `Map​.get(Object)` method contract, the `get(…)` method defined in this class throws an exception instead of returning `null` if no unambiguous mapping can be established for the given name. This behavior allows `FeatureNaming` to produce an error message telling why the operation cannot succeed.

## Managing the list of generic names

This class does not memorize the list of added `GenericName` instances. Instead, this class memorizes only their string representations, thus protecting the binding from any change in the original `GenericName` instances. The list of feature names should instead be included in the ISO 19115 metadata returned by `DataStore​.getMetadata()`. The path to feature names is:

> `metadata` / `contentInfo` / `featureTypes` / `featureTypeName`

Note that above metadata information are not necessarily structured as a flat list; a `DataStore` may group some feature information in different `FeatureCatalogueDescription` instances. This is one reason why we let the data store manages `GenericName` lists itself.

## Thread safety

A `FeatureNaming` instance is thread-safe only if constructed once and never modified after publication. For example, it is safe to initialize a `FeatureNaming` in a `DataStore` or `DataStoreProvider` constructor if the result is stored in a private final field with no public accessor and no call to `add(…)` or `remove(…)` methods after construction. If this condition does not hold, then synchronization (if desired) is caller's responsibility. The caller is typically the `DataStore` implementation which contains this `FeatureNaming` instance.

Since:
  0.8
See Also:
  - `AbstractName`
  - `DefaultFeatureType`
  - `DefaultFeatureTypeInfo`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FeatureNaming()`
  Creates a new "`GenericName` to object" mapping.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(DataStore store, GenericName name, E value)`
  Adds a value for the given name if none exist.
  `E`
  `get(DataStore store, String name)`
  Returns the value associated to the given name (case sensitive).
  `boolean`
  `remove(DataStore store, GenericName name)`
  Removes the value associated to the given name.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### FeatureNaming

    public FeatureNaming()
    Creates a new "`GenericName` to object" mapping.

- ## Method Details

  - ### get

    public E get(DataStore store, String name) throws IllegalNameException
    Returns the value associated to the given name (case sensitive).
    Parameters:
      `store` - the data store for which to get a value, or `null` if unknown.
      `name` - the name for which to get a value.
    Returns:
      value associated to the given object.
    Throws:
      `IllegalNameException` - if the given name was not found or is ambiguous.

  - ### add

    public void add(DataStore store, GenericName name, E value) throws IllegalNameException
    Adds a value for the given name if none exist. If a previous value already exists for the given name, then an exception is thrown.
    Parameters:
      `store` - the data store for which to add a value, or `null` if unknown.
      `name` - the name for which to add a value.
      `value` - the value to add (cannot be null).
    Throws:
      `IllegalNameException` - if another element is already registered for the given name.

  - ### remove

    public boolean remove(DataStore store, GenericName name) throws IllegalNameException
    Removes the value associated to the given name. If no value is associated to the given name, then this method does nothing.
    Parameters:
      `store` - the data store for which to remove a value, or `null` if unknown.
      `name` - the name for which to remove value.
    Returns:
      `true` if the value was removed, or `false` if no value was defined for the given name.
    Throws:
      `IllegalNameException` - if inconsistency are found between the given name and the one which was given to the `add(…)` method. An example of inconsistency is a name having the same string representation, but for which `ScopedName​.tail()` returns different values.