org.qi4j.api.common
Class QualifiedName

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

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<QualifiedName>

public final class QualifiedName
extends java.lang.Object
implements java.lang.Comparable<QualifiedName>, java.io.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

Method Summary

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

Methods inherited from class java.lang.Object

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

Method Detail

fromAccessor

public static QualifiedName fromAccessor(java.lang.reflect.AccessibleObject 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(java.lang.Class type,
                                      java.lang.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(java.lang.String type,
                                     java.lang.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.

fromFQN

public static QualifiedName fromFQN(java.lang.String fullQualifiedName)

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:

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

Returns:

The QualifiedName instance represented by the qualifiedName argument.

Throws:

java.lang.IllegalArgumentException - If the qualifiedName argument has wrong format.

type

public java.lang.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.

name

public java.lang.String name()

Returns the name component of the QualifiedName.

Returns:

the name component of the QualifiedName.

toURI

public java.lang.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 java.lang.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 java.lang.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 java.lang.Object

Returns:

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

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(QualifiedName other)

Specified by:

compareTo in interface java.lang.Comparable<QualifiedName>