Package tigase.xmpp.jid

# Class JID

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

All Implemented Interfaces:
  `Comparable<JID>`

public final class JID extends Object implements 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

  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(String resource)`
  The method returns a copy of the `JID` instance with a different resource part given as a parameter.
  `JID`
  `copyWithResourceNS(String resource)`
  The method returns a copy of the `JID` instance with a different resource part given as a parameter.
  `boolean`
  `equals(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.
  `String`
  `getDomain()`
  Method returns a domain part of the `JID` instance.
  `String`
  `getLocalpart()`
  Method a localpart (nickname) of the `JID` instance.
  `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(String jid)`
  Constructs a new `JID` instance using a JID parameter given as a `String` instance.
  `static JID`
  `jidInstance(String localpart, String domain)`
  Constructs a new `JID` instance using given `String` parameters.
  `static JID`
  `jidInstance(String localpart, String domain, 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, 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(String jid)`
  Constructs a new `JID` instance using a JID parameter given as a `String` instance.
  `static JID`
  `jidInstanceNS(String localpart, String domain)`
  Constructs a new `JID` instance using given `String` parameters.
  `static JID`
  `jidInstanceNS(String localpart, String domain, 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, String p_resource)`
  Constructs a new `JID` instance using given `BareJID` instance as user bare JID and `String` instance as a resource part.
  `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 Details

  - ### jidInstance

    public static JID jidInstance(BareJID bareJid, 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(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(String localpart, 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(String localpart, String domain, 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, 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(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(String localpart, String domain, 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(String localpart, 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 `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(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(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(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 `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 String getDomain()
    Method returns a domain part of the `JID` instance.
    Returns:
      a domain part of the `JID` instance.

  - ### getLocalpart

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

  - ### getResource

    public 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 `Object`
    Returns:
      an object hash code.

  - ### toString

    public String toString()
    Method returns a `String` representation of the `JID` instance.
    Overrides:
      `toString` in class `Object`
    Returns:
      a `String` representation of the `JID` instance.