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` (sometime 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.
  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 than 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 can not 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`

  Defined in the `sis-storage` module

- - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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.
    `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 Detail

    - #### FeatureNaming

          public FeatureNaming()

      Creates a new "`GenericName` to object" mapping.

  - ### Method Detail

    - #### get

          public E get​(DataStore store,
                       String name)
                throws IllegalNameException

      Returns the value associated to the given name.
      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 (can not 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.