Package tigase.xmpp.jid

## Class JID

- java.lang.Object
- - tigase.xmpp.jid.JID

- All Implemented Interfaces:
    `java.lang.Comparable<JID>`

      public final class JID
      extends java.lang.Object
      implements java.lang.Comparable<JID>

  The class defines an instance of a single XMPP JID identifier. When the object is created all parameters are checked and processed through the stringprep. An exception is thrown in case of a stringprep processing error.
  Created: Dec 28, 2009 10:48:04 PM
  Version:
    $Rev$
  Author:
    Artur Hefczyc

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `compareTo​(JID o)` | Method compares the `JID` instance with a given object.
    `JID` | `copyWithoutResource()` | The method returns a copy of the `JID` instance with removed resource part.
    `JID` | `copyWithResource​(java.lang.String resource)` | The method returns a copy of the `JID` instance with a different resource part given as a parameter.
    `JID` | `copyWithResourceNS​(java.lang.String resource)` | The method returns a copy of the `JID` instance with a different resource part given as a parameter.
    `boolean` | `equals​(java.lang.Object b)` | Method compares whether this `JID` instance represents the same user JID as the one given in parameter.
    `BareJID` | `getBareJID()` | Method returns `BareJID` instance for this JID.
    `java.lang.String` | `getDomain()` | Method returns a domain part of the `JID` instance.
    `java.lang.String` | `getLocalpart()` | Method a localpart (nickname) of the `JID` instance.
    `java.lang.String` | `getResource()` | Method a resource part of the `JID` instance.
    `int` | `hashCode()` | Method returns a hash code calculated for the `JID` instance.
    `boolean` | `hasResource()` |
    `static JID` | `jidInstance​(java.lang.String jid)` | Constructs a new `JID` instance using a JID parameter given as a `String` instance.
    `static JID` | `jidInstance​(java.lang.String localpart, java.lang.String domain)` | Constructs a new `JID` instance using given `String` parameters.
    `static JID` | `jidInstance​(java.lang.String localpart, java.lang.String domain, java.lang.String resource)` | Constructs a new `JID` instance using given `String` parameters.
    `static JID` | `jidInstance​(BareJID bareJid)` | Creates a new `JID` instance using given `BareJID` instance as a parameter.
    `static JID` | `jidInstance​(BareJID bareJid, java.lang.String p_resource)` | Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part.
    `static JID` | `jidInstanceNS​(java.lang.String jid)` | Constructs a new `JID` instance using a JID parameter given as a `String` instance.
    `static JID` | `jidInstanceNS​(java.lang.String localpart, java.lang.String domain)` | Constructs a new `JID` instance using given `String` parameters.
    `static JID` | `jidInstanceNS​(java.lang.String localpart, java.lang.String domain, java.lang.String resource)` | Constructs a new `JID` instance using given `String` parameters.
    `static JID` | `jidInstanceNS​(BareJID bareJid)` | Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part.
    `static JID` | `jidInstanceNS​(BareJID bareJid, java.lang.String p_resource)` | Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part.
    `java.lang.String` | `toString()` | Method returns a `String` representation of the `JID` instance.

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

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

- - ### Method Detail

    - #### jidInstance

          public static JID jidInstance​(BareJID bareJid,
                                        java.lang.String p_resource)
                                 throws TigaseStringprepException

      Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part.
      As the `BareJID` instances are immutable the constructor doesn't create a copy of the given `BareJID`, instead it saves the reference to a given object.
      The resource parameter is parsed, checked and run through the stringprep processing. In case of stringprep error, an exception is thrown.
      Parameters:
        `bareJid` - is a `BareJID` instance used to create the `JID` instance.
        `p_resource` - is a `String` instance representing JID's resource part.
      Returns:
        `JID` class instance.
      Throws:
        `TigaseStringprepException` - exception if there was an error during stringprep processing or null if passed string/domain was null or effectively empty..

    - #### jidInstance

          public static JID jidInstance​(BareJID bareJid)

      Creates a new `JID` instance using given `BareJID` instance as a parameter. The resource part is set to null.
      As the `BareJID` instances are immutable the constructor doesn't create a copy of the given `BareJID`, instead it saves the reference to a given object.
      Parameters:
        `bareJid` - is a `BareJID` instance used to create the `JID` instance.
      Returns:
        `JID` class instance.

    - #### jidInstance

          public static JID jidInstance​(java.lang.String jid)
                                 throws TigaseStringprepException

      Constructs a new `JID` instance using a JID parameter given as a `String` instance. The parameter is parsed, checked and run through stringprep processing. An exception is thrown if there is an error while the JID is checked.
      Parameters:
        `jid` - a JID parameter given as a `String` instance.
      Returns:
        `JID` class instance.
      Throws:
        `TigaseStringprepException` - exception if there was an error during stringprep processing or null if passed string/domain was null or effectively empty..

    - #### jidInstance

          public static JID jidInstance​(java.lang.String localpart,
                                        java.lang.String domain)
                                 throws TigaseStringprepException

      Constructs a new `JID` instance using given `String` parameters.
      All the `String` parameters are parsed, checked and run through the stringprep processing. In case of stringprep error, an exception is thrown.
      Parameters:
        `localpart` - is a `String` instance representing JID's localpart (nickname) part.
        `domain` - is a `String` instance representing JID's domain part.
      Returns:
        `JID` class instance.
      Throws:
        `TigaseStringprepException` - exception if there was an error during stringprep processing or null if passed string/domain was null or effectively empty..

    - #### jidInstance

          public static JID jidInstance​(java.lang.String localpart,
                                        java.lang.String domain,
                                        java.lang.String resource)
                                 throws TigaseStringprepException

      Constructs a new `JID` instance using given `String` parameters.
      All the `String` parameters are parsed, checked and run through the stringprep processing. In case of stringprep error, an exception is thrown.
      Parameters:
        `localpart` - is a `String` instance representing JID's localpart (nickname) part.
        `domain` - is a `String` instance representing JID's domain part.
        `resource` - is a `String` instance representing JID's resource part.
      Returns:
        `JID` class instance.
      Throws:
        `TigaseStringprepException` - exception if there was an error during stringprep processing or if passed string/domain was null or effectively empty..

    - #### jidInstanceNS

          public static JID jidInstanceNS​(BareJID bareJid)

      Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part. Note, this method does not perform stringprep processing on input parameters.
      As the `BareJID` instances are immutable the constructor doesn't create a copy of the given `BareJID`, instead it saves the reference to a given object.
      Parameters:
        `bareJid` - is a `BareJID` instance used to create the `JID` instance.
      Returns:
        `JID` class instance or null if passed string/domain was null or effectively empty.

    - #### jidInstanceNS

          public static JID jidInstanceNS​(BareJID bareJid,
                                          java.lang.String p_resource)

      Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part. Note, this method does not perform stringprep processing on input parameters.
      As the `BareJID` instances are immutable the constructor doesn't create a copy of the given `BareJID`, instead it saves the reference to a given object.
      Parameters:
        `bareJid` - is a `BareJID` instance used to create the `JID` instance.
        `p_resource` - is a `String` instance representing JID's resource part.
      Returns:
        `JID` class instance or null if passed string/domain was null or effectively empty.

    - #### jidInstanceNS

          public static JID jidInstanceNS​(java.lang.String jid)

      Constructs a new `JID` instance using a JID parameter given as a `String` instance. Note, this method does not perform stringprep processing on input parameters and it returns `null` if null is passed as parameter. The method does not throw `NullPointerException` if the `String` passed is null.
      Parameters:
        `jid` - a JID parameter given as a `String` instance.
      Returns:
        `JID` class instance or null.

    - #### jidInstanceNS

          public static JID jidInstanceNS​(java.lang.String localpart,
                                          java.lang.String domain,
                                          java.lang.String resource)

      Constructs a new `JID` instance using given `String` parameters. Note, this method does not perform stringprep processing on input parameters.
      Parameters:
        `localpart` - is a `String` instance representing JID's localpart (nickname) part.
        `domain` - is a `String` instance representing JID's domain part.
        `resource` - is a `String` instance representing JID's resource part.
      Returns:
        `JID` class instance.

    - #### jidInstanceNS

          public static JID jidInstanceNS​(java.lang.String localpart,
                                          java.lang.String domain)

      Constructs a new `JID` instance using given `String` parameters. Note, this method does not perform stringprep processing on input parameters.
      Parameters:
        `localpart` - is a `String` instance representing JID's localpart (nickname) part.
        `domain` - is a `String` instance representing JID's domain part.
      Returns:
        `JID` class instance.

    - #### hasResource

          public boolean hasResource()

    - #### compareTo

          public int compareTo​(JID o)

      Method compares the `JID` instance with a given object. The implementation fulfills the specification contract and returns a value as you would expect from the call:

           jid_1.toString().compareTo(jid_2.toString())

      Specified by:
        `compareTo` in interface `java.lang.Comparable<JID>`
      Parameters:
        `o` - is a `JID` instance to compare to.
      Returns:
        an integer value which is a result of comparing the two objects.

    - #### copyWithResource

          public JID copyWithResource​(java.lang.String resource)
                               throws TigaseStringprepException

      The method returns a copy of the `JID` instance with a different resource part given as a parameter.
      Parameters:
        `resource` - is a `String` instance representing JID's new resource part.
      Returns:
        a new instance of the `JID` class with a new resource part.
      Throws:
        `TigaseStringprepException` - if resource stringprep processing fails.

    - #### copyWithResourceNS

          public JID copyWithResourceNS​(java.lang.String resource)

      The method returns a copy of the `JID` instance with a different resource part given as a parameter.
      Parameters:
        `resource` - is a `String` instance representing JID's new resource part.
      Returns:
        a new instance of the `JID` class with a new resource part.

    - #### copyWithoutResource

          public JID copyWithoutResource()

      The method returns a copy of the `JID` instance with removed resource part. The result is similar to the `BareJID` instance, however there are APIs which require `JID` object to use.
      Returns:
        a new instance of the `JID` class with removed resource part.

    - #### equals

          public boolean equals​(java.lang.Object b)

      Method compares whether this `JID` instance represents the same user JID as the one given in parameter. It returns `true` of all: the localpart (nickname), domain part, and the resource part are the same for both objects.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `b` - is a `JID` object to which the instance is compared.
      Returns:
        a `boolean` value of `true` if both instances represent the same JID and `false` otherwise.

    - #### getBareJID

          public BareJID getBareJID()

      Method returns `BareJID` instance for this JID.
      Returns:
        a `BareJID` instance.

    - #### getDomain

          public java.lang.String getDomain()

      Method returns a domain part of the `JID` instance.
      Returns:
        a domain part of the `JID` instance.

    - #### getLocalpart

          public java.lang.String getLocalpart()

      Method a localpart (nickname) of the `JID` instance.
      Returns:
        a localpart (nickname) of the `JID` instance.

    - #### getResource

          public java.lang.String getResource()

      Method a resource part of the `JID` instance.
      Returns:
        a resource part of the `JID` instance.

    - #### hashCode

          public int hashCode()

      Method returns a hash code calculated for the `JID` instance.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        an object hash code.

    - #### toString

          public java.lang.String toString()

      Method returns a `String` representation of the `JID` instance.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a `String` representation of the `JID` instance.