Package org.apache.sis.util.iso

Class Names

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.util.iso.Names
public final class Names extends Static
Static methods for creating, parsing and formatting generic names. This convenience class does not add new functionality compared to DefaultNameFactory, but makes some tasks easier by avoiding the need to find a factory, and by creating name and their namespace in a single step.

Relationship with Java Content Repository (JCR) names

In the Java standard QName class and in the Java Content Repository (JCR) specification, a name is an ordered pair of (namespace, localPart) strings. A JCR name can take two lexical forms: expanded form and qualified form. Those names are mapped to generic names as below:
Equivalence between JCR name and GenericName
JCR name GeoAPI equivalence
ExpandedName ::= '{' Namespace '}' LocalPart GenericName.scope().name().toString() = JCR Namespace
GenericName.toString() = JCR LocalPart
QualifiedName ::= [Prefix ':'] LocalPart ScopedName.scope() = global namespace
ScopedName.head().toString() = JCR Prefix
ScopedName.tail().toString() = JCR LocalPart
Since:
0.5
Version:
1.3
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final org.opengis.util.MemberName[]
    SEQUENCE_NUMBERS
    Sequence numbers, created when first needed.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Names()
    Do not allow instantiation of this class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static org.opengis.util.GenericName
    createGenericName(CharSequence namespace, String separator, CharSequence... parsedNames)
    Creates a local or scoped name from an array of parsed names.
    static org.opengis.util.LocalName
    createLocalName(CharSequence namespace, String separator, CharSequence localPart)
    Creates a name which is local in the given namespace.
    static org.opengis.util.MemberName
    createMemberName(CharSequence namespace, String separator, int localPart)
    Creates a member name for the given sequence number.
    static org.opengis.util.MemberName
    createMemberName(CharSequence namespace, String separator, CharSequence localPart, Class<?> valueClass)
    Creates a member name for values of the given class.
    static org.opengis.util.MemberName
    createMemberName(CharSequence namespace, String separator, CharSequence localPart, org.opengis.util.TypeName attributeType)
    Creates a member name for attribute values of the given type.
    (package private) static org.opengis.util.MemberName
    createMemberName(org.opengis.util.GenericName namespace, CharSequence localPart, Class<?> valueClass)
    Creates a member name for a record of the given name.
    private static org.opengis.util.NameSpace
    createNameSpace(org.opengis.util.NameFactory factory, CharSequence namespace, String separator)
    Creates a namespace for the given name.
    static org.opengis.util.ScopedName
    createScopedName(org.opengis.util.GenericName scope, String separator, CharSequence name)
    Creates a scoped name as the concatenation of the given generic name with a single character sequence.
    static org.opengis.util.TypeName
    createTypeName(CharSequence namespace, String separator, CharSequence localPart)
    Creates a type name from the given character sequence and automatically inferred Java type.
    static org.opengis.util.TypeName
    createTypeName(Class<?> valueClass)
    Creates a type name for the given class using naming convention documented in DefaultTypeName.
    static org.opengis.util.GenericName
    parseGenericName(CharSequence namespace, String separator, CharSequence scopedName)
    Creates a local or scoped name in the given namespace.
    static Class<?>
    toClass(org.opengis.util.TypeName type)
    Returns the Java class associated to the given type name.
    static String
    toExpandedString(org.opengis.util.GenericName name)
    Formats the given name in expanded form close to the Java Content Repository (JCR) definition.

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • Names

      private Names()
      Do not allow instantiation of this class.

  • Method Details

    • createNameSpace

      private static org.opengis.util.NameSpace createNameSpace(org.opengis.util.NameFactory factory, CharSequence namespace, String separator)
      Creates a namespace for the given name.
      Parameters:
      factory - the factory to use for creating the namespace.
      namespace - the namespace string, taken as a whole (not parsed).
      separator - the separator between the namespace and the local part, or null for the default.
      Returns:
      the namespace object, or null if the given namespace was null or empty.

    • parseGenericName

      public static org.opengis.util.GenericName parseGenericName(CharSequence namespace, String separator, CharSequence scopedName)
      Creates a local or scoped name in the given namespace. The character sequences can be either String or InternationalString instances. The namespace character sequences is taken verbatim, while scopedName is splitted around the default separator, which is ":".
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the generic name, or null for the default separator.
      scopedName - the name to parse using ':' as the separator between components.
      Returns:
      a local or scoped name in the given namespace.
      See Also:

    • createGenericName

      public static org.opengis.util.GenericName createGenericName(CharSequence namespace, String separator, CharSequence... parsedNames)
      Creates a local or scoped name from an array of parsed names. This method returns a local name if the length of the parsedNames array is 1, or a scoped named if the length of the array is 2 or more. The first parsedNames element will be the head and the last parsedNames element will be the tip.
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the generic name, or null for the default separator.
      parsedNames - the local names as an array of String or InternationalString instances. This array shall contain at least one element.
      Returns:
      the generic name for the given parsed names.
      Since:
      1.0

    • createScopedName

      public static org.opengis.util.ScopedName createScopedName(org.opengis.util.GenericName scope, String separator, CharSequence name)
      Creates a scoped name as the concatenation of the given generic name with a single character sequence. The scope of the new name will be the scope of the path argument. The tail is a local name created from the given character sequence.
      Parameters:
      scope - the first part to concatenate.
      separator - the separator between the head and the tail, or null for inheriting the same separator than the given scope.
      name - the second part to concatenate.
      Returns:
      a scoped name in the given namespace.
      Since:
      0.8

    • createLocalName

      public static org.opengis.util.LocalName createLocalName(CharSequence namespace, String separator, CharSequence localPart)
      Creates a name which is local in the given namespace. The character sequences can be either String or InternationalString instances. Those character sequences are taken verbatim; they are not parsed into their components.
      Note: it is possible to split the namespace and localPart strings into smaller name components (e.g. namespaces contained in other namespaces). If such finer grain control is desired, one can use DefaultNameFactory instead of this Names class.
      The following table shows where the strings given in argument will go:
      Mapping from arguments to name components
      Argument Mapped to
      namespace name.scope().name().toString()
      localPart name.toString()
      Example: for a name created by createLocalName("http://www.opengis.net/gml/srs/epsg.xml", "#", "4326"):
      • name.toString() returns the "4326" string.
      • name.scope() returns the "http://www.opengis.net/gml/srs/epsg.xml" namespace.
      • name.toFullyQualifiedName() returns the "http://www.opengis.net/gml/srs/epsg.xml#4326" name.
      • toExpandedString(name) returns the "{http://www.opengis.net/gml/srs/epsg.xml}4326" string.
      Performance note: this method is okay for casual use. If many names need to be created in the same namespace, then DefaultNameFactory.createLocalName(NameSpace, CharSequence) is more efficient since it allows to create the NameSpace object only once.
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the local part, or null for the default separator.
      localPart - the name which is locale in the given namespace.
      Returns:
      a local name in the given namespace.
      See Also:

    • createTypeName

      public static org.opengis.util.TypeName createTypeName(CharSequence namespace, String separator, CharSequence localPart)
      Creates a type name from the given character sequence and automatically inferred Java type. The character sequences can be either String or InternationalString instances. Those character sequences are taken verbatim; they are not parsed into their components.
      Example: createTypeName("gco", ":", "Integer") returns a name which can be used for representing the type of <gco:Integer> elements in XML files.
      Performance note: this method is okay for casual use. If many names need to be created in the same namespace, then DefaultNameFactory.createTypeName(NameSpace, CharSequence) is more efficient since it allows to create the NameSpace object only once.
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the local part, or null for the default separator.
      localPart - the name which is locale in the given namespace.
      Returns:
      a type name in the given namespace.
      See Also:

    • createTypeName

      public static org.opengis.util.TypeName createTypeName(Class<?> valueClass)
      Creates a type name for the given class using naming convention documented in DefaultTypeName. This method is a shortcut for DefaultNameFactory.toTypeName(Class) and is the converse of toClass(TypeName).
      Parameters:
      valueClass - the type of values for which to infer a TypeName instance.
      Returns:
      a type name for values of the given type.
      Since:
      1.3
      See Also:

    • createMemberName

      static org.opengis.util.MemberName createMemberName(org.opengis.util.GenericName namespace, CharSequence localPart, Class<?> valueClass)
      Creates a member name for a record of the given name. The given namespace is usually an instance of TypeName.
      Parameters:
      namespace - the name of the record which will contain this member name.
      localPart - the name which is locale in the given namespace.
      valueClass - the type of values, used for inferring a TypeName instance.
      Returns:
      a member name in the given namespace for values of the given type.

    • createMemberName

      public static org.opengis.util.MemberName createMemberName(CharSequence namespace, String separator, CharSequence localPart, Class<?> valueClass)
      Creates a member name for values of the given class. A TypeName will be inferred from the given valueClass as documented in the DefaultTypeName javadoc.
      Performance note: this method is okay for casual use. If many names need to be created, then DefaultNameFactory.createMemberName(NameSpace, CharSequence, TypeName) is more efficient since it allows to create the NameSpace and TypeName objects only once.
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the local part, or null for the default separator.
      localPart - the name which is locale in the given namespace.
      valueClass - the type of values, used for inferring a TypeName instance.
      Returns:
      a member name in the given namespace for values of the given type.

    • createMemberName

      public static org.opengis.util.MemberName createMemberName(CharSequence namespace, String separator, CharSequence localPart, org.opengis.util.TypeName attributeType)
      Creates a member name for attribute values of the given type. This is a shortcut for DefaultNameFactory.createMemberName(NameSpace, CharSequence, TypeName). See performance note.
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the local part, or null for the default separator.
      localPart - the name which is locale in the given namespace.
      attributeType - the type of the data associated with the member.
      Returns:
      a member name in the given namespace for values of the given type.
      Since:
      1.3

    • createMemberName

      public static org.opengis.util.MemberName createMemberName(CharSequence namespace, String separator, int localPart)
      Creates a member name for the given sequence number. The member type will be "OGC:Integer". This method can be used for setting band identifier in metadata in the common case where band identifier are just numbers.
      Parameters:
      namespace - the namespace, or null for the global namespace.
      separator - the separator between the namespace and the local part, or null for the default separator.
      localPart - the sequence number to use as local part.
      Returns:
      a member name in the given namespace with the given sequence number.
      Since:
      1.0
      See Also:
      • RangeDimension.getSequenceIdentifier()

    • toClass

      public static Class<?> toClass(org.opengis.util.TypeName type) throws UnknownNameException
      Returns the Java class associated to the given type name. The method performs the following choices:
      • If the given type name is null, then this method returns null.
      • Else if the value returned by DefaultTypeName.toJavaType() is a Class, returns that class.
      • Else if the type name scope is "OGC", then:
        • If the name is "CharacterString", "Integer", "Real" or other recognized names (see DefaultTypeName javadoc), then the corresponding class is returned.
        • Otherwise UnknownNameException is thrown.
      • Else if the scope is "class", then:
      • Else if the scope is global, then:
        • If the name is one of the names recognized in "OGC" scope (see above), then the corresponding class is returned.
        • Otherwise null is returned. No exception is thrown because names in the global namespace could be anything; this method cannot be sure that the given name was wrong.
      • Otherwise null is returned, because this method cannot check the validity of names in other namespaces.
      Parameters:
      type - the type name from which to infer a Java class.
      Returns:
      the Java class associated to the given TypeName, or null if there is no mapping from the given name to a Java class.
      Throws:
      UnknownNameException - if a mapping from the given name to a Java class was expected to exist (typically because of the scope) but the lookup failed.
      Since:
      0.5
      See Also:

    • toExpandedString

      public static String toExpandedString(org.opengis.util.GenericName name)
      Formats the given name in expanded form close to the Java Content Repository (JCR) definition. The expanded form is defined as below: 
       ExpandedName ::= '{' NameSpace '}' LocalPart
 NameSpace    ::= name.scope().name().toString()
 LocalPart    ::= name.toString()
      Parameters:
      name - the generic name to format in expanded form, or null.
      Returns:
      expanded form of the given generic name, or null if the given name was null.
      See Also: