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
        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.
        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).
        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.