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 standardQName 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 GenericNameJCR name GeoAPI equivalence ExpandedName ::= '{' Namespace '}' LocalPartGenericName.scope().name().toString()= JCR NamespaceGenericName.toString()= JCR LocalPartQualifiedName ::= [Prefix ':'] LocalPartScopedName.scope()= global namespace ScopedName.head().toString()= JCR PrefixScopedName.tail().toString()= JCR LocalPart
- Since:
- 0.5
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionstatic GenericNamecreateGenericName(CharSequence namespace, String separator, CharSequence... parsedNames) Creates a local or scoped name from an array of parsed names.static LocalNamecreateLocalName(CharSequence namespace, String separator, CharSequence localPart) Creates a name which is local in the given namespace.static MemberNamecreateMemberName(CharSequence namespace, String separator, int localPart) Creates a member name for the given sequence number.static MemberNamecreateMemberName(CharSequence namespace, String separator, CharSequence localPart, Class<?> valueClass) Creates a member name for values of the given class.static MemberNamecreateMemberName(CharSequence namespace, String separator, CharSequence localPart, TypeName attributeType) Creates a member name for attribute values of the given type.static ScopedNamecreateScopedName(GenericName scope, String separator, CharSequence name) Creates a scoped name as the concatenation of the given generic name with a single character sequence.static TypeNamecreateTypeName(CharSequence namespace, String separator, CharSequence localPart) Creates a type name from the given character sequence and automatically inferred Java type.static TypeNamecreateTypeName(Class<?> valueClass) Creates a type name for the given class using naming convention documented inDefaultTypeName.static GenericNameparseGenericName(CharSequence namespace, String separator, CharSequence scopedName) Creates a local or scoped name in the given namespace.static Class<?> Returns the Java class associated to the given type name.static StringFormats the given name in expanded form close to the Java Content Repository (JCR) definition.
-
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 eitherStringorInternationalStringinstances. Thenamespacecharacter sequences is taken verbatim, whilescopedNameis splitted around the default separator, which is":".- Parameters:
namespace- the namespace, ornullfor the global namespace.separator- the separator between the namespace and the generic name, ornullfor 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:
- "TODO:"
- Bug in current implementation: the
separatorargument is ignored ifnamespaceis 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 theparsedNamesarray is 1, or a scoped named if the length of the array is 2 or more. The firstparsedNameselement will be the head and the lastparsedNameselement will be thetip.- Parameters:
namespace- the namespace, ornullfor the global namespace.separator- the separator between the namespace and the generic name, ornullfor the default separator.parsedNames- the local names as an array ofStringorInternationalStringinstances. This array shall contain at least one element.- Returns:
- the generic name for the given parsed names.
- Since:
- 1.0
-
createScopedName
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 thepathargument. 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, ornullfor 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 eitherStringorInternationalStringinstances. Those character sequences are taken verbatim; they are not parsed into their components.Note: it is possible to split theThe following table shows where the strings given in argument will go:namespaceandlocalPartstrings into smaller name components (e.g. namespaces contained in other namespaces). If such finer grain control is desired, one can useDefaultNameFactoryinstead of thisNamesclass.Mapping from arguments to name components Argument Mapped to namespacename.scope().name().toString()localPartname.toString()Example
For a name created bycreateLocalName("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, thenDefaultNameFactory.createLocalName(NameSpace, CharSequence)is more efficient since it allows to create theNameSpaceobject only once.- Parameters:
namespace- the namespace, ornullfor the global namespace.separator- the separator between the namespace and the local part, ornullfor the default separator.localPart- 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 eitherStringorInternationalStringinstances. 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, thenDefaultNameFactory.createTypeName(NameSpace, CharSequence)is more efficient since it allows to create theNameSpaceobject only once.- Parameters:
namespace- the namespace, ornullfor the global namespace.separator- the separator between the namespace and the local part, ornullfor the default separator.localPart- the name which is locale in the given namespace.- Returns:
- a type name in the given namespace.
- See Also:
-
createTypeName
Creates a type name for the given class using naming convention documented inDefaultTypeName. This method is a shortcut forDefaultNameFactory.toTypeName(Class)and is the converse oftoClass(TypeName).- Parameters:
valueClass- the type of values for which to infer aTypeNameinstance.- 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. ATypeNamewill be inferred from the givenvalueClassas documented in theDefaultTypeNamejavadoc.Performance note
This method is okay for casual use. If many names need to be created, thenDefaultNameFactory.createMemberName(NameSpace, CharSequence, TypeName)is more efficient since it allows to create theNameSpaceandTypeNameobjects only once.- Parameters:
namespace- the namespace, ornullfor the global namespace.separator- the separator between the namespace and the local part, ornullfor the default separator.localPart- the name which is locale in the given namespace.valueClass- the type of values, used for inferring aTypeNameinstance.- 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 forDefaultNameFactory.createMemberName(NameSpace, CharSequence, TypeName). See performance note.- Parameters:
namespace- the namespace, ornullfor the global namespace.separator- the separator between the namespace and the local part, ornullfor the default separator.localPart- the name which is locale in the given namespace.attributeType- 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
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, ornullfor the global namespace.separator- the separator between the namespace and the local part, ornullfor 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:
-
toClass
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 returnsnull. - Else if the value returned by
DefaultTypeName.toJavaType()is aClass, returns that class. - Else if the type name scope is
"OGC", then:- If the name is
"CharacterString","Integer","Real"or other recognized names (seeDefaultTypeNamejavadoc), then the corresponding class is returned. - Otherwise
UnknownNameExceptionis thrown.
- If the name is
- Else if the scope is
"class", then:- If the name is accepted by
Class.forName(String), then that class is returned. - Otherwise
UnknownNameExceptionis thrown.
- If the name is accepted by
- 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
nullis 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.
- If the name is one of the names recognized in
- Otherwise
nullis 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
TypeName, ornullif 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 lookup failed.- Since:
- 0.5
- See Also:
- If the given type name is
-
toExpandedString
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, ornull.- Returns:
- expanded form of the given generic name, or
nullif the given name was null. - See Also:
-