org.qi4j.api.common
Class QualifiedName

java.lang.Object
  org.qi4j.api.common.QualifiedName

All Implemented Interfaces:

Serializable, Comparable<QualifiedName>

public final class QualifiedName
extends Object
implements Comparable<QualifiedName>, Serializable

QualifiedName is a representation of Property names to their full declaration.

A QualifiedName is created by combining the name of a method and the name of the type that declares the method. This class also contains many static utility methods to manage QualifiedName instances.

NOTE: Unless you do very generic libraries, entity stores and other extensions that is deeply coupled into the Qi4j runtime, it is very unlikely you will need to use this class directly.

It is also important to notice that the QualifiedName needs to be long-term stable, as the names are written to persistent storage. So any changes in the formatting must be made in a backward-compatible manner .

The QualifiedName has two intrinsic parts, one being the type and the other the name. The type comes from the class where the QualifiedName originates from and internally kept as a TypeName instance. The name is the name from the method name. When the QualifiedName instance is converted to an external string representation, via the offical and formal toString() method, the type is normalized, i.e. any dollar characters ($) in the name are replaced by dashes (-), to make them URI friendly.

QualifiedName instances are immutable, implements hashCode() and equals(Object) as a value object and can safely be used as keys in Map.

See Also:

Serialized Form

Constructor Summary

QualifiedName(TypeName typeName, String name)

Method Summary

int	compareTo(QualifiedName other)
boolean	equals(Object o)
static QualifiedName	fromClass(Class type, String name) Creates a QualifiedName instance from the Class and a given name.
static QualifiedName	fromMethod(Method method) Creates a QualifiedName from a method.
static QualifiedName	fromName(String type, String name) Creates a Qualified name from a type as string and a name qualifier.
static QualifiedName	fromQN(String qualifiedName) Creates a QualifiedName from the external string format of QualifiedName.
int	hashCode()
String	name() Returns the name component of the QualifiedName.
String	toNamespace() Return the URI of the TypeName component of the QualifiedName.
String	toString() Return the formal and official, long-term stable, external string representation of a QualifiedName.
String	toURI() Returns the URI of the QualifiedName.
String	type() Returns the normalized string of the type part of the QualifiedName.
TypeName	typeName() Returns the internal TypeName instance of the QualifiedName.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

QualifiedName

public QualifiedName(TypeName typeName,
                     String name)

Method Detail

fromMethod

public static QualifiedName fromMethod(Method method)

Creates a QualifiedName from a method.

This factory method will create a QualifiedName from the Method itself.

Parameters:

method - Type method that returns a Property, for which the QualifiedName will be representing.

Returns:

A QualifiedName representing this method.

Throws:

NullArgumentException - If the method argument passed is null.

fromClass

public static QualifiedName fromClass(Class type,
                                      String name)

Creates a QualifiedName instance from the Class and a given name.

This factory method converts the type to a TypeName and appends the given name.

Parameters:

type - The Class that is the base of the QualifiedName.

name - The qualifier name which will be appended to the base name derived from the type argument.

Returns:

A QualifiedName instance representing the type and name arguments.

Throws:

NullArgumentException - if any of the two arguments are null, or if the name string is empty.

fromName

public static QualifiedName fromName(String type,
                                     String name)

Creates a Qualified name from a type as string and a name qualifier.

Parameters:

type - The type name as a a string, which must be properly formatted. No checks for correctly formatted type name is performed.

name - The qualifier name which will be appended to the base name derived from the type argument.

Returns:

A QualifiedName instance representing the type and name arguments.

Throws:

NullArgumentException - if any of the two arguments are null or either string is empty.

fromQN

public static QualifiedName fromQN(String qualifiedName)

Creates a QualifiedName from the external string format of QualifiedName.

This factory method is the reverse of toString() method, and creates a new QualifiedName instance from the string representation of the QualifiedName.

Parameters:

qualifiedName - The QualifiedName external string representation to be converted back into a QualifiedName instance.

Returns:

The QualifiedName instance represented by the qualifiedName argument.

Throws:

IllegalArgumentException - If the qualifiedName argument has wrong format.

type

public String type()

Returns the normalized string of the type part of the QualifiedName.

The normalized type name means that all dollar ($) characters have been replaced by dashes (-).

Returns:

the normalized string of the type part of the QualifiedName.

typeName

public TypeName typeName()

Returns the internal TypeName instance of the QualifiedName.

The TypeName instance represents the type from which the QualifiedName originates, typically the Class of the Property method.

Returns:

the internal TypeName instance of the QualifiedName.

name

public String name()

Returns the name component of the QualifiedName.

Returns:

the name component of the QualifiedName.

toURI

public String toURI()

Returns the URI of the QualifiedName.

The URI is the toNamespace() followed by the name component.

Returns:

the URI of the QualifiedName.

See Also:

toNamespace()

toNamespace

public String toNamespace()

Return the URI of the TypeName component of the QualifiedName.

The URI of the TypeName component is in the form of;

 "urn:qi4j:type:" normalizedClassName
 

where normalizedClassName is the fully-qualified class name having had any dollar ($) characters replaced by URI friendly dashes (-), with a trailing hash (#). Examples;

 urn:qi4j:type:org.qi4j.api.common.QualifiedName#
 urn:qi4j:type:org.qi4j.samples.MyClass-MyInnerClass#
 

Returns:

the URI of the TypeName component of the QualifiedName.

toString

public String toString()

Return the formal and official, long-term stable, external string representation of a QualifiedName.

This returns the TypeName.toString() followed by the name component.

Overrides:

toString in class Object

Returns:

the formal and official, long-term stable, external string representation of a QualifiedName.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(QualifiedName other)

Specified by:

compareTo in interface Comparable<QualifiedName>