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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(QualifiedName other)`
    `boolean` | `equals(Object o)`
    `static QualifiedName` | `fromAccessor(AccessibleObject method)` Creates a QualifiedName from a method.
    `static QualifiedName` | `fromClass(Class type, String name)` Creates a QualifiedName instance from the Class and a given name.
    `static QualifiedName` | `fromFQN(String fullQualifiedName)` Creates a QualifiedName from the external string format of QualifiedName.
    `static QualifiedName` | `fromName(String type, String name)` Creates a Qualified name from a type as string and a name qualifier.
    `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.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### fromAccessor

          public static QualifiedName fromAccessor(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(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.

    - #### fromFQN

          public static QualifiedName fromFQN(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:
        `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.

    - #### 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>`