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

# Class DefaultNameFactory

Object
AbstractFactory
DefaultNameFactory

All Implemented Interfaces:
  `Factory`, `NameFactory`

public class DefaultNameFactory extends AbstractFactory implements NameFactory
A factory for creating `AbstractName` objects. This factory provides the following methods for creating name instances:

- `createTypeName(NameSpace, CharSequence)`
- `createMemberName(NameSpace, CharSequence, TypeName)`
- `createLocalName(NameSpace, CharSequence)`
- `createGenericName(NameSpace, CharSequence[])` – for local or scoped names

The following methods for creating miscellaneous name-related objects:

- `createNameSpace(GenericName, Map)`
- `createInternationalString(Map)`

And the following methods for performing some analysis:

- `parseGenericName(NameSpace, CharSequence)`
- `toGenericNames(Object)`
- `toTypeName(Class)`

## Thread safety

The same `DefaultNameFactory` instance can be safely used by many threads without synchronization on the part of the caller. Subclasses should make sure that any overridden methods remain safe to call from multiple threads.

Since:
  0.3
See Also:
  - `Names`
  - `DefaultNameSpace`
  - `DefaultScopedName`
  - `DefaultLocalName`
  - `DefaultTypeName`
  - `DefaultMemberName`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultNameFactory()`
  Creates a new factory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GenericName`
  `createGenericName(NameSpace scope, CharSequence... parsedNames)`
  Creates a local or scoped name from an array of parsed names.
  `InternationalString`
  `createInternationalString(Map<Locale,String> strings)`
  Creates an international string from a set of strings in different locales.
  `LocalName`
  `createLocalName(NameSpace scope, CharSequence name)`
  Creates a local name from the given character sequence.
  `MemberName`
  `createMemberName(NameSpace scope, CharSequence name, TypeName attributeType)`
  Creates a member name from the given character sequence and attribute type.
  `NameSpace`
  `createNameSpace(GenericName name, Map<String,?> properties)`
  Returns a namespace having the given name.
  `TypeName`
  `createTypeName(NameSpace scope, CharSequence name)`
  Creates a type name from the given character sequence and automatically inferred Java type.
  `TypeName`
  `createTypeName(NameSpace scope, CharSequence name, Type javaType)`
  Creates a type name from the given character sequence and explicit Java type.
  `GenericName`
  `parseGenericName(NameSpace scope, CharSequence name)`
  Constructs a generic name from a qualified name.
  `static DefaultNameFactory`
  `provider()`
  Returns the default provider of `GenericName` instances.
  `GenericName[]`
  `toGenericNames(Object value)`
  Converts the given value to an array of generic names.
  `TypeName`
  `toTypeName(Class<?> valueClass)`
  Suggests a type name for the given class.

  ### Methods inherited from class AbstractFactory

  `getVendor`

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### DefaultNameFactory

    public DefaultNameFactory()
    Creates a new factory.
    See Also:
      - `provider()`

- ## Method Details

  - ### provider

    public static DefaultNameFactory provider()
    Returns the default provider of `GenericName` instances. This is the factory used by the Apache SIS library when no non-null `NameFactory` has been explicitly specified. This method can be invoked directly, or indirectly through `ServiceLoader​.load(NameFactory​.class)`.
    Returns:
      the default provider of generic names.
    Since:
      1.4
    See Also:
      - `ServiceLoader`

  - ### createInternationalString

    public InternationalString createInternationalString(Map<Locale,String> strings)
    Creates an international string from a set of strings in different locales.
    Specified by:
      `createInternationalString` in interface `NameFactory`
    Parameters:
      `strings` - string value for each locale key.
    Returns:
      the international string.
    See Also:
      - `Types​.toInternationalString(CharSequence)`

  - ### createNameSpace

    public NameSpace createNameSpace(GenericName name, Map<String,?> properties)
    Returns a namespace having the given name. Despite the "create" name, this method tries to return an existing instance when possible. The namespace is characterized by the given name, and optionally by the following properties:

    Recognized properties
    Property name | Purpose
    --- | ---
    `"separator"` | The separator to insert between parsed names in that namespace.
    `"separator.head"` | The separator to insert between the namespace and the head. If omitted, then the default is the same value than `"separator"`.

    #### Examples

    - For URN namespace, `separator` = `":"` is typically sufficient.
    - For HTTP namespace, `separator​.head` = `"://"` and `separator` = `"."`.
    Specified by:
      `createNameSpace` in interface `NameFactory`
    Parameters:
      `name` - the name of the namespace to be returned. This argument can be created using `createGenericName(null, namespace)`.
      `properties` - an optional map of properties to be assigned to the namespace, or `null` if none.
    Returns:
      a namespace having the given name and separator.
    See Also:
      - `Names​.createLocalName(CharSequence, String, CharSequence)`

  - ### createTypeName

    public TypeName createTypeName(NameSpace scope, CharSequence name) throws UnknownNameException
    Creates a type name from the given character sequence and automatically inferred Java type. The default implementation returns a new or an existing `DefaultTypeName` instance. See `DefaultTypeName` javadoc for the list of recognized type names.
    Specified by:
      `createTypeName` in interface `NameFactory`
    Parameters:
      `scope` - the scope of the type name create, or `null` for a global namespace.
      `name` - the type name as a string or an international string.
    Returns:
      the type name for the given scope and character sequence.
    Throws:
      `UnknownNameException` - if a mapping from the name to a Java class was expected to exist (because the specified scope is "OGC" or "class") but the associated Java class cannot be found.
    See Also:
      - `toTypeName(Class)`
      - `DefaultTypeName(NameSpace, CharSequence)`
      - `Names​.createTypeName(CharSequence, String, CharSequence)`

  - ### createTypeName

    public TypeName createTypeName(NameSpace scope, CharSequence name, Type javaType)
    Creates a type name from the given character sequence and explicit Java type. The default implementation returns a new or an existing `DefaultTypeName` instance.
    Parameters:
      `scope` - the scope of the type name to create, or `null` for a global namespace.
      `name` - the type name as a string or an international string.
      `javaType` - the Java type represented by the name, or `null` if none.
    Returns:
      the type name for the given scope, character sequence and Java type.
    Since:
      1.3
    See Also:
      - `toTypeName(Class)`
      - `DefaultTypeName(NameSpace, CharSequence, Type)`

  - ### createMemberName

    public MemberName createMemberName(NameSpace scope, CharSequence name, TypeName attributeType)
    Creates a member name from the given character sequence and attribute type. The default implementation returns a new or an existing `DefaultMemberName` instance.
    Parameters:
      `scope` - the scope of the member name to create, or `null` for a global namespace.
      `name` - the member name as a string or an international string.
      `attributeType` - the type of the data associated with the member.
    Returns:
      the member name for the given character sequence.
    See Also:
      - `Names​.createMemberName(CharSequence, String, CharSequence, TypeName)`
      - `Names​.createMemberName(CharSequence, String, CharSequence, Class)`

  - ### createLocalName

    public LocalName createLocalName(NameSpace scope, CharSequence name)
    Creates a local name from the given character sequence. The default implementation returns a new or an existing `DefaultLocalName` instance.
    Specified by:
      `createLocalName` in interface `NameFactory`
    Parameters:
      `scope` - the scope of the local name to create, or `null` for a global namespace.
      `name` - the local name as a string or an international string.
    Returns:
      the local name for the given character sequence.
    See Also:
      - `Names​.createLocalName(CharSequence, String, CharSequence)`

  - ### createGenericName

    public GenericName createGenericName(NameSpace scope, CharSequence... parsedNames)
    Creates a local or scoped name from an array of parsed names. The default implementation returns an instance of `DefaultLocalName` if the length of the `parsedNames` array is 1, or an instance of `DefaultScopedName` if the length of the array is 2 or more.
    Specified by:
      `createGenericName` in interface `NameFactory`
    Parameters:
      `scope` - the scope of the generic name to create, or `null` for a global namespace.
      `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.
    See Also:
      - `parseGenericName(NameSpace, CharSequence)`

  - ### parseGenericName

    public GenericName parseGenericName(NameSpace scope, CharSequence name)
    Constructs a generic name from a qualified name. This method splits the given name around a separator inferred from the given scope, or the `':'` separator if the given scope is null.
    Specified by:
      `parseGenericName` in interface `NameFactory`
    Parameters:
      `scope` - the scope of the generic name to create, or `null` for a global namespace.
      `name` - the qualified name, as a sequence of names separated by a scope-dependent separator.
    Returns:
      a name parsed from the given string.
    See Also:
      - `Names​.parseGenericName(CharSequence, String, CharSequence)`

  - ### toGenericNames

    public GenericName[] toGenericNames(Object value) throws ClassCastException
    Converts the given value to an array of generic names. If the given value is an instance of `GenericName`, `String` or any other type enumerated below, then it is converted and returned in an array of length 1. If the given value is an array or a collection, then an array of same length is returned where each element has been converted.

    Allowed types or element types are:

    - `GenericName`, to be casted and returned as-is.
    - `CharSequence` (usually a `String` or an `InternationalString`), to be parsed as a generic name using the `':'` separator.
    - `Identifier`, its code to be parsed as a generic name using the `':'` separator.
    If `value` is an array or a collection containing `null` elements, then the corresponding element in the returned array will also be `null`.
    Parameters:
      `value` - the object to cast into an array of generic names, or `null`.
    Returns:
      the generic names, or `null` if the given `value` was null. Note that it may be the `value` reference itself casted to `GenericName[]`.
    Throws:
      `ClassCastException` - if `value` cannot be casted.
    Since:
      0.5

  - ### toTypeName

    public TypeName toTypeName(Class<?> valueClass)
    Suggests a type name for the given class. Apache SIS provides a mapping between `Class` and `TypeName` objects as documented in the `DefaultTypeName` javadoc. The given `valueClass` can be fetched back by `DefaultTypeName​.toJavaType()`.
    Parameters:
      `valueClass` - the Java class for which to get a type name, or `null`.
    Returns:
      a suggested type name, or `null` if the given class was null.
    Since:
      0.5
    See Also:
      - `DefaultTypeName​.toJavaType()`
      - `Names​.toClass(TypeName)`
      - `Names​.createTypeName(Class)`