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 Generic­Name instances and their shortened names to features. The features are typically represented by instances of Feature­Type or Coverage (sometime seen as a kind of features), but this class actually puts no restriction on the kind of object associated to Generic­Names; Data­Store 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 Generic­Name.to­String(), or a shortened name when there is no ambiguity.

Example: a data store may contain a Feature­Type 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 Feature­Naming 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 Generic­Name instances. Instead this class memorizes only their string representations, thus protecting the binding from any change in the original Generic­Name instances. The list of feature names should instead be included in the ISO 19115 metadata returned by Data­Store.get­Metadata(). The path to feature names is:

metadata / content­Info / feature­Types / feature­Type­Name

Note that above metadata information are not necessarily structured as a flat list; a Data­Store may group some feature information in different Feature­Catalogue­Description instances. This is one reason why we let the data store manages Generic­Name lists itself.

Thread safety

A Feature­Naming instance is thread-safe only if constructed once and never modified after publication. For example it is safe to initialize a Feature­Naming in a Data­Store or Data­Store­Provider 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 Data­Store implementation which contains this Feature­Naming instance.

Since:

0.8

See Also:

Abstract­Name, Default­Feature­Type, Default­Feature­Type­Info

Defined in the sis-storage module

Constructor Summary

Constructors

Constructor and Description
FeatureNaming() Creates a new "Generic­Name to object" mapping.

Method Summary

Modifier and Type	Method and 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, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Detail

FeatureNaming

public FeatureNaming()

Creates a new "Generic­Name 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:

Illegal­Name­Exception - 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:

Illegal­Name­Exception - 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:

Illegal­Name­Exception - 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 Scoped­Name.tail() returns different values.