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 `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
See Also:
  - `DefaultNameFactory`
  - `DefaultNameSpace`
  - `DefaultScopedName`
  - `DefaultLocalName`
  - `DefaultTypeName`
  - `DefaultMemberName`

Defined in the `sis-metadata` module

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static GenericName`
  `createGenericName(CharSequence namespace, String separator, CharSequence... parsedNames)`
  Creates a local or scoped name from an array of parsed names.
  `static LocalName`
  `createLocalName(CharSequence namespace, String separator, CharSequence localPart)`
  Creates a name which is local in the given namespace.
  `static MemberName`
  `createMemberName(CharSequence namespace, String separator, int localPart)`
  Creates a member name for the given sequence number.
  `static MemberName`
  `createMemberName(CharSequence namespace, String separator, CharSequence localPart, Class<?> valueClass)`
  Creates a member name for values of the given class.
  `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.
  `static TypeName`
  `createTypeName(CharSequence namespace, String separator, CharSequence localPart)`
  Creates a type name which is local in the given namespace.
  `static GenericName`
  `parseGenericName(CharSequence namespace, String separator, CharSequence scopedName)`
  Creates a local or scoped name in the given namespace.
  `static Class<?>`
  `toClass(TypeName type)`
  Returns the Java class associated to the given type name.
  `static String`
  `toExpandedString(GenericName name)`
  Formats the given name in expanded form close to the Java Content Repository (JCR) definition.

  ### Methods inherited from class Object

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

- ## 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 `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:
      - `DefaultNameFactory​.parseGenericName(NameSpace, CharSequence)`
    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 `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 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 `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:
      - `DefaultNameFactory​.createLocalName(NameSpace, CharSequence)`

  - ### createTypeName

    public static TypeName createTypeName(CharSequence namespace, String separator, CharSequence localPart)
    Creates a type 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.
    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:
      - `DefaultNameFactory​.createTypeName(NameSpace, CharSequence)`

  - ### createMemberName

    public static 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.
    See Also:
      - `DefaultNameFactory​.createMemberName(NameSpace, CharSequence, TypeName)`

  - ### 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.
      `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(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 given type name is an instance of `DefaultTypeName`, then this method delegates to `DefaultTypeName​.toClass()`.
    - 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:
      - If the name is accepted by `Class​.forName(String)`, then that class is returned.
      - Otherwise `UnknownNameException` is thrown.
    - 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, so we can not be sure that the given name was wrong.
    - Otherwise `null` is returned, since this method can not 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 operation failed.
    Since:
      0.5
    See Also:
      - `DefaultTypeName​.toClass()`
      - `DefaultNameFactory​.toTypeName(Class)`

  - ### 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:
      - `DefaultNameSpace​.toString()`