Class DefaultNameSpace

java.lang.Object
org.apache.sis.util.iso.DefaultNameSpace
All Implemented Interfaces:
Serializable, org.opengis.util.NameSpace
Direct Known Subclasses:
GlobalNameSpace

public class DefaultNameSpace extends Object implements org.opengis.util.NameSpace, Serializable
A domain in which names given by character strings are defined. This implementation does not support localization in order to avoid ambiguity when testing two namespaces for equality.

DefaultNameSpace can be instantiated by any of the following methods:

Immutability and thread safety

This class is immutable and thus inherently thread-safe if the NameSpace and CharSequence arguments given to the constructor are also immutable. Subclasses shall make sure that any overridden methods remain safe to call from multiple threads and do not change any public NameSpace state.
Since:
0.3
Version:
1.3
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • DEFAULT_SEPARATOR

      public static final char DEFAULT_SEPARATOR
      The default separator, which is ':'. The separator is inserted between the namespace and any generic name in that namespace.
      See Also:
    • DEFAULT_SEPARATOR_STRING

      static final String DEFAULT_SEPARATOR_STRING
      See Also:
    • parent

      private final DefaultNameSpace parent
      The parent namespace, or null if the parent is the unique GLOBAL instance. We don't use direct reference to GLOBAL because null is used as a sentinel value for stopping iterative searches (using GLOBAL would have higher risk of never-ending loops in case of bug), and in order to reduce the stream size during serialization.
      See Also:
    • name

      private final CharSequence name
      The name of this namespace, usually as a String or an InternationalString.
    • headSeparator

      private final String headSeparator
      The separator to insert between the namespace and the head of any name in that namespace.
      See Also:
    • separator

      final String separator
      The separator to insert between the parsed names of any name in that namespace.
      See Also:
    • path

      private transient AbstractName path
      The fully qualified name for this namespace. Will be created when first needed.
    • childs

      private transient WeakValueHashMap<String,Object> childs
      The children created in this namespace. The values are restricted to the following types: No other type should be allowed. The main purpose of this map is to hold child namespaces. However, we can (in an opportunist way) handles local names as well. In case of conflict, the namespace will have precedence.

      This field is initialized by init() soon after DefaultNameSpace creation and shall be treated like a final field from that point.

  • Constructor Details

    • DefaultNameSpace

      DefaultNameSpace()
      Creates the global namespace. This constructor can be invoked by GlobalNameSpace only.
    • DefaultNameSpace

      protected DefaultNameSpace(DefaultNameSpace parent, CharSequence name, String headSeparator, String separator)
      Creates a new namespace with the given separator.
      Parameters:
      parent - the parent namespace, or null if none.
      name - the name of the new namespace, usually as a String or an InternationalString.
      headSeparator - the separator to insert between the namespace and the head of any name in that namespace.
      separator - the separator to insert between the parsed names of any name in that namespace.
  • Method Details

    • simplify

      private static CharSequence simplify(CharSequence name)
      Converts the given name to its String representation if that name is not an InternationalString instance from which this DefaultNameSpace implementation can extract useful information. For example, if the given name is a SimpleInternationalString, that international string does not give more information than the String that it wraps. Using the String as the canonical value increase the chances that equals(Object) detect that two GenericName instances are equal.
    • init

      private void init()
      Initializes the transient fields.
    • castOrCopy

      static DefaultNameSpace castOrCopy(org.opengis.util.NameSpace ns)
      Wraps the given namespace in a DefaultNameSpace implementation. This method returns an existing instance when possible.
      Parameters:
      ns - the namespace to wrap, or null for the global one.
      Returns:
      the given namespace as a DefaultNameSpace implementation.
    • forName

      static DefaultNameSpace forName(org.opengis.util.GenericName name, String headSeparator, String separator)
      Returns a namespace having the given name and separators. This method returns an existing instance when possible.
      Parameters:
      name - the name for the namespace to obtain, or null.
      headSeparator - the separator to insert between the namespace and the head of any name in that namespace.
      separator - the separator to insert between the parsed names of any name in that namespace.
      Returns:
      a namespace having the given name, or null if name was null.
    • getSeparator

      public static String getSeparator(org.opengis.util.NameSpace ns, boolean head)
      Returns the separator between name components in the given namespace. If the given namespace is an instance of DefaultNameSpace, then this method returns the headSeparator or separator argument given to the constructor. Otherwise this method returns the default separator.
      API note: this method is static because the getSeparator(…) method is not part of GeoAPI interfaces. A static method makes easier to use without (if (x instanceof DefaultNameSpace) checks.
      Parameters:
      ns - the namespace for which to get the separator. May be null.
      head - true for the separator between namespace and head, or false for the separator between parsed names.
      Returns:
      separator between name components.
      Since:
      1.3
    • isGlobal

      public boolean isGlobal()
      Indicates whether this namespace is a "top level" namespace. Global, or top-level namespaces are not contained within another namespace. The global namespace has no parent.
      Specified by:
      isGlobal in interface org.opengis.util.NameSpace
      Returns:
      true if this namespace is the global namespace.
    • parent

      final DefaultNameSpace parent()
      Returns the parent namespace, replacing null parent by GlobalNameSpace.GLOBAL.
    • depth

      private static int depth(DefaultNameSpace ns)
      Returns the depth of the given namespace.
      Parameters:
      ns - the namespace for which to get the depth, or null.
      Returns:
      the depth of the given namespace.
    • name

      public org.opengis.util.GenericName name()
      Represents the identifier of this namespace. Namespace identifiers shall be fully-qualified names where the following condition holds:
      Specified by:
      name in interface org.opengis.util.NameSpace
      Returns:
      the identifier of this namespace.
    • child

      final DefaultNameSpace child(CharSequence name, String sep)
      Returns a child namespace of the given name. The returned namespace will have this namespace as its parent, and will use the same separator.

      The headSeparator is not inherited by the children on intent, because this method is used only by DefaultScopedName constructors in order to create a sequence of parsed local names. For example, in "http://www.opengeospatial.org" the head separator is "://" for "www" (which is having this namespace), but it is "." for all children ("opengeospatial" and "org").

      Parameters:
      name - the name of the child namespace.
      sep - the separator to use (typically separator).
      Returns:
      the child namespace. It may be an existing instance.
    • key

      private static String key(CharSequence name)
      Returns a key to be used in the childs pool from the given name. The key must be the unlocalized version of the given string.
      Parameters:
      name - the name.
      Returns:
      a key from the given name.
    • child

      private DefaultNameSpace child(String key, CharSequence name, String headSeparator, String separator)
      Returns a child namespace of the given name and separator. The returned namespace will have this namespace as its parent.
      Parameters:
      key - the unlocalized name of the child namespace, to be used as a key in the cache.
      name - the name of the child namespace, or null if same than key.
      headSeparator - the separator to insert between the namespace and the head of any name in that namespace.
      separator - the separator to insert between the parsed names of any name in that namespace.
      Returns:
      the child namespace. It may be an existing instance.
    • local

      final DefaultLocalName local(CharSequence name, DefaultLocalName candidate)
      Returns a name which is local in this namespace. The returned name will have this namespace as its scope. This method may returns an existing instance on a "best effort" basis, but this is not guaranteed.
      Parameters:
      name - the name of the instance to create.
      candidate - the instance to cache if no instance was found for the given name, or null if none.
      Returns:
      a name which is local in this namespace.
    • toString

      public String toString()
      Returns a JCR-like lexical form representation of this namespace. Following the Java Content Repository (JCR) convention, this method returns the string representation of name() between curly brackets.
      Example: if the name of this namespace is “org.apache.sis”, then this method returns “{org.apache.sis}”.

      Usage

      With this convention, it would be possible to create an expanded form of a generic name (except for escaping of illegal characters) with a simple concatenation as in the following code example: However, the convention followed by this DefaultNameSpace implementation is not specified in the NameSpace contract. This implementation follows the JCR convention for debugging convenience, but applications needing better guarantees should use Names.toExpandedString(GenericName) instead.
      Overrides:
      toString in class Object
      Returns:
      a JCR-like lexical form of this namespace.
      See Also:
    • equals

      public boolean equals(Object object)
      Returns true if this namespace is equal to the given object.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with this namespace.
      Returns:
      true if the given object is equal to this namespace.
    • equalsIgnoreParent

      private boolean equalsIgnoreParent(DefaultNameSpace that)
      Returns true if the namespace is equal to the given one, ignoring the parent.
      Parameters:
      that - the namespace to compare with this one.
      Returns:
      true if both namespaces are equal, ignoring the parent.
    • hashCode

      public int hashCode()
      Returns a hash code value for this namespace.
      Overrides:
      hashCode in class Object
    • readResolve

      Object readResolve() throws ObjectStreamException
      If an instance already exists for the deserialized namespace, returns that instance. Otherwise completes the initialization of the deserialized instance.

      Because of its package-private access, this method is not invoked if the deserialized class is a subclass defined in another package. This is the intended behavior since we don't want to replace an instance of a user-defined class.

      Returns:
      the unique instance.
      Throws:
      ObjectStreamException - required by specification but should never be thrown.