Package org.xmpp.packet

Class JID

  • All Implemented Interfaces:
    Serializable, Comparable<JID>
    @Immutable
public class JID
extends Object
implements Comparable<JID>, 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:
    • jid = [ node "@" ] domain [ "/" resource ]
    Some sample JID's:
    • user@example.com
    • user@example.com/home
    • example.com
    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. JID instances are immutable. Multiple threads can act on data represented by JID objects without concern of the data being changed by other threads.
    Author:
    Matt Tucker, Guus der Kinderen, guus.der.kinderen@gmail.com
    See Also:
    Serialized Form

    • Field Detail

      • NODEPREP_CACHE

        public static final com.github.benmanes.caffeine.cache.Cache<String,​ValueWrapper<String>> NODEPREP_CACHE

      • DOMAINPREP_CACHE

        public static final com.github.benmanes.caffeine.cache.Cache<String,​ValueWrapper<String>> DOMAINPREP_CACHE

      • RESOURCEPREP_CACHE

        public static final com.github.benmanes.caffeine.cache.Cache<String,​ValueWrapper<String>> RESOURCEPREP_CACHE

    • Constructor Detail

      • JID

        public JID​(String jid)
        Constructs a JID from it's String representation.
        Parameters:
        jid - a valid JID.
        Throws:
        IllegalArgumentException - if the JID is not valid.

      • JID

        public JID​(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:
        IllegalArgumentException - if the JID is not valid.

      • JID

        public JID​(String node,
           String domain,
           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:
        NullPointerException - if domain is null.
        IllegalArgumentException - if the JID is not valid.

      • JID

        public JID​(String node,
           String domain,
           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:
        NullPointerException - if domain is null.
        IllegalArgumentException - if the JID is not valid.

    • Method Detail

      • escapeNode

        public static String escapeNode​(String node)
        Escapes the node portion of a JID according to "JID Escaping" (XEP-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
        A backslash is escaped only when it is followed by 20, 22, 26, 27, 2f, 3a, 3c, 3e, 40 or 5c, so that it is not mistaken for the start of an escape sequence. Any other backslash is left unchanged. 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). Only the characters listed above are escaped. Other characters that node-prep prohibits, such as tabs, line breaks or non-ASCII space characters, are left unchanged, as XEP-0106 does not allow them to be escaped. All node escaping and un-escaping must be performed manually at the appropriate time; the JID class will not escape or un-escape automatically. XEP-0106 does not allow an escaped node to start or end with the escaped space (\20), and defines no alternative representation. Therefore, a node that starts or ends with a space cannot be escaped. This restriction applies to escaping only: a node that starts or ends with \20 (for example, one created by other software) remains valid, and can be used in a JID and unescaped.
        Parameters:
        node - the node.
        Returns:
        the escaped version of the node.
        Throws:
        IllegalArgumentException - if node starts or ends with a space.
        See Also:
        XEP-0106: JID Escaping

      • unescapeNode

        public static String unescapeNode​(String node)
        Un-escapes the node portion of a JID according to "JID Escaping" (XEP-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.
        See Also:
        XEP-0106: JID Escaping

      • nodeprep

        public static String nodeprep​(String node)
        Returns a valid representation of a JID node, based on the provided input. This method throws an IllegalArgumentException if the provided argument cannot be represented as a valid JID node (e.g. if StringPrepping fails).
        Parameters:
        node - The raw node value.
        Returns:
        A String based JID node representation
        Throws:
        IllegalArgumentException - if node is not a valid JID node.

      • domainprep

        public static String domainprep​(String domain)
        Returns a valid representation of a JID domain part, based on the provided input. This method throws an IllegalArgumentException if the provided argument cannot be represented as a valid JID domain part (e.g. if Stringprepping fails). As defined in RFC 6122, section 2.2, a single trailing label separator (dot) is stripped before any other processing, and a domain that is empty (after stripping, or after Nameprep) is not valid.
        Parameters:
        domain - The raw domain value.
        Returns:
        A String based JID domain part representation
        Throws:
        IllegalArgumentException - if domain is not a valid JID domain part.

      • resourceprep

        public static String resourceprep​(String resource)
        Returns a valid representation of a JID resource, based on the provided input. This method throws an IllegalArgumentException if the provided argument cannot be represented as a valid JID resource (e.g. if StringPrepping fails).
        Parameters:
        resource - The raw resource value.
        Returns:
        A String based JID resource representation
        Throws:
        IllegalArgumentException - if resource is not a valid JID resource.

      • getNode

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

      • getDomain

        public String getDomain()
        Returns the domain.
        Returns:
        the domain.

      • getResource

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

      • toBareJID

        public String toBareJID()
        Returns the String representation of the bare JID, which is the JID with resource information removed. For example: username@domain.com
        Returns:
        the bare JID.

      • asBareJID

        public JID asBareJID()
        Returns the bare JID representation of this JID, which is the JID with resource information removed. For example: username@domain.com
        Returns:
        the bare JID.
        See Also:
        TINDER-68

      • toFullJID

        public String toFullJID()
        Returns the String representation of the full JID, for example: username@domain.com/mobile. If no resource has been provided in the constructor of this object, an IllegalStateException is thrown.
        Returns:
        the full JID.
        Throws:
        IllegalStateException - If no resource was provided in the constructor used to create this instance.

      • toString

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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • equals

        public static boolean equals​(String jid1,
                             String jid2)
        Returns true if two JID's are equivalent. The JID components are compared using the following rules:
        • Nodes are normalized using nodeprep (case insensitive).
        • Domains are normalized using IDNA and then nameprep (case insensitive).
        • Resources are normalized using resourceprep (case sensitive).
        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:
        IllegalArgumentException - if either JID is not valid.