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

    All Methods Static Methods Concrete Methods
    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 Detail

    - #### 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)`

    - #### 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()`