Package org.apache.sis.util.iso

Class AbstractName

java.lang.Object
org.apache.sis.util.iso.AbstractName
All Implemented Interfaces:
Serializable, Comparable<org.opengis.util.GenericName>, org.opengis.util.GenericName
Direct Known Subclasses:
DefaultLocalName, DefaultScopedName
public abstract class AbstractName extends Object implements org.opengis.util.GenericName, Serializable
Base class for sequence of identifiers rooted within the context of a namespace. Names shall be immutable and thread-safe. A name can be local to a namespace. See the package javadoc for an illustration of name anatomy.

The easiest way to create a name is to use the Names.createLocalName(CharSequence, String, CharSequence) convenience static method. That method supports the common case where the name is made only of a (namespace, local part) pair of strings. However, generic names allows finer grain. For example, the above-cited strings can both be split into smaller name components. If such finer grain control is desired, DefaultNameFactory can be used instead of Names.

Natural ordering

This class has a natural ordering that is inconsistent with equals(Object). See compareTo(GenericName) for more information.

Note for implementers

Subclasses need only to implement the following methods: Subclasses shall make sure that any overridden methods remain safe to call from multiple threads and do not change any public GenericName state.
Since:
0.3
Version:
0.5
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    AbstractName.International
    An international string built from a snapshot of GenericName.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) CharSequence
    asString
    The string representation of this name, to be returned by toString() or toInternationalString().
    (package private) org.opengis.util.GenericName
    fullyQualified
    A view of this name as a fully-qualified one.
    private int
    hash
    The cached hash code, or 0 if not yet computed.
    private static final long
    serialVersionUID
    Serial number for inter-operability with different versions.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractName()
    Creates a new instance of generic name.

  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) int
    arraySize()
    Returns the size of the backing array.
    static AbstractName
    castOrCopy(org.opengis.util.GenericName object)
    Returns a SIS name implementation with the values of the given arbitrary implementation.
    int
    compareTo(org.opengis.util.GenericName name)
    Compares this name with the specified name for order.
    (package private) int
    computeHashCode()
    Invoked by hashCode() for computing the hash code value when first needed.
    int
    depth()
    Indicates the number of levels specified by this name.
    boolean
    equals(Object object)
    Compares this generic name with the specified object for equality.
    abstract List<? extends org.opengis.util.LocalName>
    getParsedNames()
    Returns the sequence of local names making this generic name.
    int
    hashCode()
    Returns a hash code value for this generic name.
    org.opengis.util.LocalName
    head()
    Returns the first element in the sequence of parsed names.
    private static String
    headSeparator(org.opengis.util.GenericName name)
    Returns the separator to write before the given name.
    org.opengis.util.ScopedName
    push(org.opengis.util.GenericName scope)
    Returns this name expanded with the specified scope.
    abstract org.opengis.util.NameSpace
    scope()
    Returns the scope (name space) in which this name is local.
    org.opengis.util.LocalName
    tip()
    Returns the last element in the sequence of parsed names.
    org.opengis.util.GenericName
    toFullyQualifiedName()
    Returns a view of this name as a fully-qualified name.
    org.opengis.util.InternationalString
    toInternationalString()
    Returns a local-dependent string representation of this generic name.
    String
    toString()
    Returns a string representation of this generic name.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:

    • fullyQualified

      transient org.opengis.util.GenericName fullyQualified
      A view of this name as a fully-qualified one. Will be created only when first needed.

    • asString

      transient CharSequence asString
      The string representation of this name, to be returned by toString() or toInternationalString(). This field will initially references a String object when first needed, and may be replaced by a InternationalString object later if such object is asked for.

    • hash

      private transient int hash
      The cached hash code, or 0 if not yet computed.

  • Constructor Details

    • AbstractName

      protected AbstractName()
      Creates a new instance of generic name.

  • Method Details

    • castOrCopy

      public static AbstractName castOrCopy(org.opengis.util.GenericName object)
      Returns a SIS name implementation with the values of the given arbitrary implementation. This method performs the first applicable action in the following choices:
      Parameters:
      object - the object to get as a SIS implementation, or null if none.
      Returns:
      a SIS implementation containing the values of the given object (may be the given object itself), or null if the argument was null.

    • scope

      public abstract org.opengis.util.NameSpace scope()
      Returns the scope (name space) in which this name is local. For example if a fully qualified name is "org.opengis.util.Record" and if this instance is the "util.Record" part, then its scope is named "org.opengis".

      Continuing with the above example, the full "org.opengis.util.Record" name has no scope. If this method is invoked on such name, then the SIS implementation returns a global scope instance (i.e. an instance for which DefaultNameSpace.isGlobal() returns true) which is unique and named "global".

      Specified by:
      scope in interface org.opengis.util.GenericName
      Returns:
      the scope of this name.

    • depth

      public int depth()
      Indicates the number of levels specified by this name. The default implementation returns the size of the list returned by the getParsedNames() method.
      Specified by:
      depth in interface org.opengis.util.GenericName
      Returns:
      the depth of this name.

    • arraySize

      int arraySize()
      Returns the size of the backing array. This is used only has a hint for optimizations in attempts to share internal arrays. The DefaultScopedName class is the only one to override this method. For other classes, the depth() can be assumed.

    • getParsedNames

      public abstract List<? extends org.opengis.util.LocalName> getParsedNames()
      Returns the sequence of local names making this generic name. The length of this sequence is the depth. It does not include the scope.
      Specified by:
      getParsedNames in interface org.opengis.util.GenericName
      Returns:
      the local names making this generic name, without the scope. Shall never be null neither empty.

    • head

      public org.opengis.util.LocalName head()
      Returns the first element in the sequence of parsed names. For any LocalName, this is always this.
      Example: If this name is "org.opengis.util.Record" (no matter its scope, then this method returns "org".
      Specified by:
      head in interface org.opengis.util.GenericName
      Returns:
      the first element in the list of parsed names.

    • tip

      public org.opengis.util.LocalName tip()
      Returns the last element in the sequence of parsed names. For any LocalName, this is always this.
      Example: If this name is "org.opengis.util.Record" (no matter its scope, then this method returns "Record".
      Specified by:
      tip in interface org.opengis.util.GenericName
      Returns:
      the last element in the list of parsed names.

    • toFullyQualifiedName

      public org.opengis.util.GenericName toFullyQualifiedName()
      Returns a view of this name as a fully-qualified name. The scope of a fully qualified name is global. If the scope of this name is already global, then this method returns this.
      Specified by:
      toFullyQualifiedName in interface org.opengis.util.GenericName
      Returns:
      the fully-qualified name (never null).

    • push

      public org.opengis.util.ScopedName push(org.opengis.util.GenericName scope)
      Returns this name expanded with the specified scope. One may represent this operation as a concatenation of the specified scope with this. For example, if this name is "util.Record" and the given scope argument is "org.opengis", then this.push(scope) shall return "org.opengis.util.Record".
      Specified by:
      push in interface org.opengis.util.GenericName
      Parameters:
      scope - the name to use as prefix.
      Returns:
      a concatenation of the given scope with this name.

    • headSeparator

      private static String headSeparator(org.opengis.util.GenericName name)
      Returns the separator to write before the given name. If the scope of the given name is a DefaultNameSpace instance, then this method returns its head separator. We really want DefaultNameSpace.headSeparator, not DefaultNameSpace.separator. See DefaultNameSpace.child(CharSequence, String) for details.
      Parameters:
      name - the name after which to write a separator.
      Returns:
      the separator to write after the given name.

    • toString

      public String toString()
      Returns a string representation of this generic name. This string representation is local-independent. It contains all elements listed by getParsedNames() separated by a namespace-dependent character (usually ':' or '/'). This rule implies that the result may or may not be fully qualified. Special cases:
      Specified by:
      toString in interface org.opengis.util.GenericName
      Overrides:
      toString in class Object
      Returns:
      a local-independent string representation of this name.

    • toInternationalString

      public org.opengis.util.InternationalString toInternationalString()
      Returns a local-dependent string representation of this generic name. This string is similar to the one returned by toString() except that each element has been localized in the specified locale. If no international string is available, then this method returns an implementation mapping to toString() for all locales.
      Specified by:
      toInternationalString in interface org.opengis.util.GenericName
      Returns:
      a localizable string representation of this name.

    • compareTo

      public int compareTo(org.opengis.util.GenericName name)
      Compares this name with the specified name for order. Returns a negative integer, zero, or a positive integer as this name lexicographically precedes, is equal to, or follows the specified name. The comparison is performed in the following way:
      • For each element of the list of parsed names taken in iteration order, compare the LocalName. If a name lexicographically precedes or follows the corresponding element of the specified name, returns a negative or a positive integer respectively.
      • If all elements in both names are lexicographically equal, then if this name has less or more elements than the specified name, returns a negative or a positive integer respectively.
      • Otherwise, returns 0.
      Specified by:
      compareTo in interface Comparable<org.opengis.util.GenericName>
      Parameters:
      name - the other name to compare with this name.
      Returns:
      -1 if this name precedes the given one, +1 if it follows, 0 if equals.

    • equals

      public boolean equals(Object object)
      Compares this generic name with the specified object for equality. The default implementation returns true if the scopes and the lists of parsed names are equal.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compare with this name for equality.
      Returns:
      true if the given object is equal to this name.

    • hashCode

      public int hashCode()
      Returns a hash code value for this generic name.
      Overrides:
      hashCode in class Object

    • computeHashCode

      int computeHashCode()
      Invoked by hashCode() for computing the hash code value when first needed.