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:

Default­Name­Factory, Default­Name­Space, Default­Scoped­Name, Default­Local­Name, Default­Type­Name, Default­Member­Name

Defined in the sis-utility module

Method Summary

Modifier and Type	Method and Description
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, CharSequence localPart, Class<?> valueClass) Creates a member name for values of the given class.
static ScopedName	createScopedName(GenericName scope, String separator, CharSequence name) Constructs 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, get­Class, hash­Code, notify, notify­All, to­String, 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 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 scoped 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:

Default­Name­Factory.parse­Generic­Name(Name­Space, Char­Sequence)

createScopedName

public static ScopedName createScopedName(GenericName scope,
                                          String separator,
                                          CharSequence name)

Constructs 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:

Default­Name­Factory.create­Local­Name(Name­Space, Char­Sequence)

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

Default­Name­Factory.create­Type­Name(Name­Space, Char­Sequence)

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.

See Also:

Default­Name­Factory.create­Member­Name(Name­Space, Char­Sequence, Type­Name)

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 Default­Type­Name, then this method delegates to Default­Type­Name.to­Class().
• Else if the type name scope is "OGC", then:
  • If the name is "Character­String", "Integer", "Real" or other recognized names (see Default­Type­Name javadoc), then the corresponding class is returned.
  • Otherwise Unknown­Name­Exception is thrown.
• Else if the scope is "class", then:
  • If the name is accepted by Class.for­Name(String), then that class is returned.
  • Otherwise Unknown­Name­Exception 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 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 operation failed.

Since:

0.5

See Also:

Default­Type­Name.to­Class(), Default­Name­Factory.to­Type­Name(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:

Default­Name­Space.to­String()