Class Names

Object
Names
public final class Names extends Object
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 split 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 as 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

      @OptionalCandidate 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: