Module org.apache.sis.metadata
Package org.apache.sis.util.iso

Class Names

Object
Static
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 Default­Name­Factory, 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, local­Part) 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 Generic­Name
JCR name GeoAPI equivalence
ExpandedName ::= '{' Namespace '}' LocalPart GenericName.scope().name().toString() = JCR Namespace
GenericName.toString() = JCR Local­Part
QualifiedName ::= [Prefix ':'] LocalPart ScopedName.scope() = global namespace
ScopedName.head().toString() = JCR Prefix
ScopedName.tail().toString() = JCR Local­Part
Since:
0.5
See Also:

  • Method Details

    • parseGenericName

      public static 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 International­String instances. The namespace character sequences is taken verbatim, while scoped­Name 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.
      scoped­Name - the name to parse using ':' as the separator between components.
      Returns:
      a local or scoped name in the given namespace.
      See Also:
      "TODO:"
      Bug in current implementation: the separator argument is ignored if namespace is null.

    • createGenericName

      public static 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 parsed­Names array is 1, or a scoped named if the length of the array is 2 or more. The first parsed­Names element will be the head and the last parsed­Names 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.
      parsed­Names - the local names as an array of String or International­String instances. This array shall contain at least one element.
      Returns:
      the generic name for the given parsed names.
      Since:
      1.0

    • createScopedName

      public static ScopedName createScopedName(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 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 International­String instances. Those character sequences are taken verbatim; they are not parsed into their components.
      Note: it is possible to split the namespace and local­Part strings into smaller name components (e.g. namespaces contained in other namespaces). If such finer grain control is desired, one can use Default­Name­Factory 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 create­Local­Name("http://www​.opengis​.net/gml/srs/epsg​.xml", "#", "4326"):
      • name.to­String() returns the "4326" string.
      • name.scope() returns the "http://www​.opengis​.net/gml/srs/epsg​.xml" namespace.
      • name.to­Fully­Qualified­Name() returns the "http://www​.opengis​.net/gml/srs/epsg​.xml#4326" name.
      • to­Expanded­String(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 Default­Name­Factory​.create­Local­Name(Name­Space, Char­Sequence) is more efficient since it allows to create the Name­Space 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.
      local­Part - the name which is locale in the given namespace.
      Returns:
      a local name in the given namespace.
      See Also:

    • createTypeName

      public static 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 International­String instances. Those character sequences are taken verbatim; they are not parsed into their components.

      Example

      create­Type­Name("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 Default­Name­Factory​.create­Type­Name(Name­Space, Char­Sequence) is more efficient since it allows to create the Name­Space 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.
      local­Part - the name which is locale in the given namespace.
      Returns:
      a type name in the given namespace.
      See Also:

    • createTypeName

      public static TypeName createTypeName(Class<?> valueClass)
      Creates a type name for the given class using naming convention documented in Default­Type­Name. This method is a shortcut for Default­Name­Factory​.to­Type­Name(Class) and is the converse of to­Class(Type­Name).
      Parameters:
      value­Class - the type of values for which to infer a Type­Name instance.
      Returns:
      a type name for values of the given type.
      Since:
      1.3
      See Also:

    • createMemberName

      public static MemberName createMemberName(CharSequence namespace, String separator, CharSequence localPart, Class<?> valueClass)
      Creates a member name for values of the given class. A Type­Name will be inferred from the given value­Class as documented in the Default­Type­Name javadoc.

      Performance note

      This method is okay for casual use. If many names need to be created, then Default­Name­Factory​.create­Member­Name(Name­Space, Char­Sequence, Type­Name) is more efficient since it allows to create the Name­Space and Type­Name 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.
      local­Part - the name which is locale in the given namespace.
      value­Class - the type of values, used for inferring a Type­Name instance.
      Returns:
      a member name in the given namespace for values of the given type.

    • createMemberName

      public static MemberName createMemberName(CharSequence namespace, String separator, CharSequence localPart, TypeName attributeType)
      Creates a member name for attribute values of the given type. This is a shortcut for Default­Name­Factory​.create­Member­Name(Name­Space, Char­Sequence, Type­Name). 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.
      local­Part - the name which is locale in the given namespace.
      attribute­Type - 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 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.
      local­Part - 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:

    • toClass

      public static Class<?> toClass(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 Default­Type­Name​.to­Java­Type() is a Class, returns that class.
      • Else if the type name scope is "OGC", then:
      • 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 Type­Name, or null if there is no mapping from the given name to a Java class.
      Throws:
      Unknown­Name­Exception - 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(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: