org.xmpp.packet
Class JID

java.lang.Object
  extended by org.xmpp.packet.JID
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<JID>

@Immutable
public class JID
extends java.lang.Object
implements java.lang.Comparable<JID>, java.io.Serializable

An XMPP address (JID). A JID is made up of a node (generally a username), a domain, and a resource. The node and resource are optional; domain is required. In simple ABNF form:

Some sample JID's: Each allowable portion of a JID (node, domain, and resource) must not be more than 1023 bytes in length, resulting in a maximum total size (including the '@' and '/' separators) of 3071 bytes.

Author:
Matt Tucker
See Also:
Serialized Form

Constructor Summary
JID(java.lang.String jid)
          Constructs a JID from it's String representation.
JID(java.lang.String jid, boolean skipStringPrep)
          Constructs a JID from it's String representation.
JID(java.lang.String node, java.lang.String domain, java.lang.String resource)
          Constructs a JID given a node, domain, and resource.
JID(java.lang.String node, java.lang.String domain, java.lang.String resource, boolean skipStringprep)
          Constructs a JID given a node, domain, and resource being able to specify if stringprep should be applied or not.
 
Method Summary
 int compareTo(JID jid)
           
 boolean equals(java.lang.Object object)
           
static boolean equals(java.lang.String jid1, java.lang.String jid2)
          Returns true if two JID's are equivalent.
static java.lang.String escapeNode(java.lang.String node)
          Escapes the node portion of a JID according to "JID Escaping" (JEP-0106).
 java.lang.String getDomain()
          Returns the domain.
 java.lang.String getNode()
          Returns the node, or null if this JID does not contain node information.
 java.lang.String getResource()
          Returns the resource, or null if this JID does not contain resource information.
 int hashCode()
           
static java.lang.String resourceprep(java.lang.String resource)
           
 java.lang.String toBareJID()
          Returns the String representation of the bare JID, which is the JID with resource information removed.
 java.lang.String toString()
          Returns a String representation of the JID.
static java.lang.String unescapeNode(java.lang.String node)
          Un-escapes the node portion of a JID according to "JID Escaping" (JEP-0106).
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

JID

public JID(java.lang.String jid)
Constructs a JID from it's String representation.

Parameters:
jid - a valid JID.
Throws:
java.lang.IllegalArgumentException - if the JID is not valid.

JID

public JID(java.lang.String jid,
           boolean skipStringPrep)
Constructs a JID from it's String representation. This construction allows the caller to specify if stringprep should be applied or not.

Parameters:
jid - a valid JID.
skipStringprep - true if stringprep should not be applied.
Throws:
java.lang.IllegalArgumentException - if the JID is not valid.

JID

public JID(java.lang.String node,
           java.lang.String domain,
           java.lang.String resource)
Constructs a JID given a node, domain, and resource.

Parameters:
node - the node.
domain - the domain, which must not be null.
resource - the resource.
Throws:
java.lang.IllegalArgumentException - if the JID is not valid.

JID

public JID(java.lang.String node,
           java.lang.String domain,
           java.lang.String resource,
           boolean skipStringprep)
Constructs a JID given a node, domain, and resource being able to specify if stringprep should be applied or not.

Parameters:
node - the node.
domain - the domain, which must not be null.
resource - the resource.
skipStringprep - true if stringprep should not be applied.
Throws:
java.lang.IllegalArgumentException - if the JID is not valid.
Method Detail

escapeNode

public static java.lang.String escapeNode(java.lang.String node)
Escapes the node portion of a JID according to "JID Escaping" (JEP-0106). Escaping replaces characters prohibited by node-prep with escape sequences, as follows:

Unescaped CharacterEncoded Sequence
<space>\20
"\22
&\26
'\27
/\2f
:\3a
<\3c
>\3e
@\40
\\5c

This process is useful when the node comes from an external source that doesn't conform to nodeprep. For example, a username in LDAP may be "Joe Smith". Because the <space> character isn't a valid part of a node, the username should be escaped to "Joe\20Smith" before being made into a JID (e.g. "joe\20smith@example.com" after case-folding, etc. has been applied).

All node escaping and un-escaping must be performed manually at the appropriate time; the JID class will not escape or un-escape automatically.

Parameters:
node - the node.
Returns:
the escaped version of the node.

unescapeNode

public static java.lang.String unescapeNode(java.lang.String node)
Un-escapes the node portion of a JID according to "JID Escaping" (JEP-0106).

Escaping replaces characters prohibited by node-prep with escape sequences, as follows:

Unescaped CharacterEncoded Sequence
<space>\20
"\22
&\26
'\27
/\2f
:\3a
<\3c
>\3e
@\40
\\5c

This process is useful when the node comes from an external source that doesn't conform to nodeprep. For example, a username in LDAP may be "Joe Smith". Because the <space> character isn't a valid part of a node, the username should be escaped to "Joe\20Smith" before being made into a JID (e.g. "joe\20smith@example.com" after case-folding, etc. has been applied).

All node escaping and un-escaping must be performed manually at the appropriate time; the JID class will not escape or un-escape automatically.

Parameters:
node - the escaped version of the node.
Returns:
the un-escaped version of the node.

resourceprep

public static java.lang.String resourceprep(java.lang.String resource)
                                     throws org.jivesoftware.stringprep.StringprepException
Throws:
org.jivesoftware.stringprep.StringprepException

getNode

public java.lang.String getNode()
Returns the node, or null if this JID does not contain node information.

Returns:
the node.

getDomain

public java.lang.String getDomain()
Returns the domain.

Returns:
the domain.

getResource

public java.lang.String getResource()
Returns the resource, or null if this JID does not contain resource information.

Returns:
the resource.

toBareJID

public java.lang.String toBareJID()
Returns the String representation of the bare JID, which is the JID with resource information removed.

Returns:
the bare JID.

toString

public java.lang.String toString()
Returns a String representation of the JID.

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

hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object object)
Overrides:
equals in class java.lang.Object

compareTo

public int compareTo(JID jid)
Specified by:
compareTo in interface java.lang.Comparable<JID>

equals

public static boolean equals(java.lang.String jid1,
                             java.lang.String jid2)
Returns true if two JID's are equivalent. The JID components are compared using the following rules: These normalization rules ensure, for example, that User@EXAMPLE.com/home is considered equal to user@example.com/home.

Parameters:
jid1 - a JID.
jid2 - a JID.
Returns:
true if the JIDs are equivalent; false otherwise.
Throws:
java.lang.IllegalArgumentException - if either JID is not valid.