rocks.xmpp.addr

Interface Jid

All Superinterfaces:

java.lang.CharSequence, java.lang.Comparable<Jid>, java.io.Serializable

All Known Implementing Classes:

MalformedJid

public interface Jid
extends java.lang.Comparable<Jid>, java.io.Serializable, java.lang.CharSequence

Represents the JID as described in Extensible Messaging and Presence Protocol (XMPP): Address Format.

A JID consists of three parts:

[ localpart “@” ] domainpart [ “/” resourcepart ]

The easiest way to create a JID is to use the of(CharSequence) method:

Jid jid = Jid.of("juliet@capulet.lit/balcony");

You can then get the parts from it via the respective methods:

String local = jid.getLocal(); // juliet
String domain = jid.getDomain(); // capulet.lit
String resource = jid.getResource(); // balcony

Implementations of this interface should override equals() and hashCode(), so that different instances with the same value are equal:

Jid.of("romeo@capulet.lit/balcony").equals(Jid.of("romeo@capulet.lit/balcony")); // true

The default implementation of this class also supports XEP-0106: JID Escaping, i.e.

Jid.of("d'artagnan@musketeers.lit")

is escaped as d\27artagnan@musketeers.lit.

Implementations of this interface should be thread-safe and immutable.

See Also:

RFC 7622 - Extensible Messaging and Presence Protocol (XMPP): Address Format

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ESCAPING_FEATURE The service discovery feature used for determining support of JID escaping (jid\20escaping).
static int	MAX_BARE_JID_LENGTH The maximal length of a bare JID, which is 2047 (1023 + 1 + 1023).
static int	MAX_FULL_JID_LENGTH The maximal length of a full JID, which is 3071.

Method Summary

Modifier and Type	Method and Description
Jid	asBareJid() Gets the bare JID representation of this JID, i.e. removes the resource part.
Jid	atSubdomain(java.lang.CharSequence subdomain) Creates a new JID at a subdomain and at the same domain as this JID.
java.lang.String	getDomain() Gets the domain part.
java.lang.String	getEscapedLocal() Gets the escaped local part of the JID.
java.lang.String	getLocal() Gets the local part of the JID, also known as the name or node.
java.lang.String	getResource() Gets the resource part.
boolean	isBareJid() Checks if the JID is a bare JID.
boolean	isDomainJid() Checks if the JID is a domain JID, i.e. if it has no local part.
boolean	isFullJid() Checks if the JID is a full JID.
static Jid	of(java.lang.CharSequence jid) Creates a JID from an unescaped string.
static Jid	of(java.lang.CharSequence local, java.lang.CharSequence domain, java.lang.CharSequence resource) Returns a full JID with a domain and resource part, e.g.
static Jid	ofDomain(java.lang.CharSequence domain) Creates a bare JID with only the domain part, e.g.
static Jid	ofDomainAndResource(java.lang.CharSequence domain, java.lang.CharSequence resource) Creates a full JID with a domain and resource part, e.g.
static Jid	ofEscaped(java.lang.CharSequence jid) Creates a JID from a escaped JID string.
static Jid	ofLocalAndDomain(java.lang.CharSequence local, java.lang.CharSequence domain) Creates a bare JID with a local and domain part, e.g.
java.lang.String	toEscapedString() Returns the JID in escaped form as described in XEP-0106: JID Escaping.
Jid	withLocal(java.lang.CharSequence local) Creates a new JID with a new local part and the same domain and resource part of the current JID.
Jid	withResource(java.lang.CharSequence resource) Creates a new full JID with a resource and the same local and domain part of the current JID.

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface java.lang.CharSequence

charAt, chars, codePoints, length, subSequence, toString

Field Detail

MAX_FULL_JID_LENGTH

static final int MAX_FULL_JID_LENGTH

The maximal length of a full JID, which is 3071.

3.1. Fundamentals

Each allowable portion of a JID (localpart, domainpart, and resourcepart) is 1 to 1023 octets in length, resulting in a maximum total size (including the ‘@’ and ‘/’ separators) of 3071 octets.

Note that the length is based on bytes, not characters.

See Also:

MAX_BARE_JID_LENGTH, Constant Field Values

MAX_BARE_JID_LENGTH

static final int MAX_BARE_JID_LENGTH

The maximal length of a bare JID, which is 2047 (1023 + 1 + 1023). Note that the length is based on bytes, not characters.

See Also:

MAX_FULL_JID_LENGTH, Constant Field Values

ESCAPING_FEATURE

static final java.lang.String ESCAPING_FEATURE

The service discovery feature used for determining support of JID escaping (jid\20escaping).

See Also:

Constant Field Values

Method Detail

of

static Jid of(java.lang.CharSequence local,
              java.lang.CharSequence domain,
              java.lang.CharSequence resource)

Returns a full JID with a domain and resource part, e.g. capulet.com/balcony

Parameters:

local - The local part.

domain - The domain.

resource - The resource part.

Returns:

The JID.

Throws:

java.lang.NullPointerException - If the domain is null.

java.lang.IllegalArgumentException - If the domain, local or resource part are not valid.

ofDomain

static Jid ofDomain(java.lang.CharSequence domain)

Creates a bare JID with only the domain part, e.g. capulet.com

Parameters:

domain - The domain.

Returns:

The JID.

Throws:

java.lang.NullPointerException - If the domain is null.

java.lang.IllegalArgumentException - If the domain or local part are not valid.

ofLocalAndDomain

static Jid ofLocalAndDomain(java.lang.CharSequence local,
                            java.lang.CharSequence domain)

Creates a bare JID with a local and domain part, e.g. juliet@capulet.com

Parameters:

local - The local part.

domain - The domain.

Returns:

The JID.

Throws:

java.lang.NullPointerException - If the domain is null.

java.lang.IllegalArgumentException - If the domain or local part are not valid.

ofDomainAndResource

static Jid ofDomainAndResource(java.lang.CharSequence domain,
                               java.lang.CharSequence resource)

Creates a full JID with a domain and resource part, e.g. capulet.com/balcony

Parameters:

domain - The domain.

resource - The resource part.

Returns:

The JID.

Throws:

java.lang.NullPointerException - If the domain is null.

java.lang.IllegalArgumentException - If the domain or resource are not valid.

of

static Jid of(java.lang.CharSequence jid)

Creates a JID from an unescaped string. The format must be

[ localpart “@” ] domainpart [ “/” resourcepart ]

The input string will be escaped.

Parameters:

jid - The JID.

Returns:

The JID.

Throws:

java.lang.NullPointerException - If the jid is null.

java.lang.IllegalArgumentException - If the jid could not be parsed or is not valid.

See Also:

XEP-0106: JID Escaping

ofEscaped

static Jid ofEscaped(java.lang.CharSequence jid)

Creates a JID from a escaped JID string. The format must be

[ localpart “@” ] domainpart [ “/” resourcepart ]

This method should be used, when parsing JIDs from the XMPP stream.

Parameters:

jid - The JID.

Returns:

The JID.

Throws:

java.lang.NullPointerException - If the jid is null.

java.lang.IllegalArgumentException - If the jid could not be parsed or is not valid.

See Also:

XEP-0106: JID Escaping

isFullJid

boolean isFullJid()

Checks if the JID is a full JID.

The term “full JID” refers to an XMPP address of the form <localpart@domainpart/resourcepart> (for a particular authorized client or device associated with an account) or of the form <domainpart/resourcepart> (for a particular resource or script associated with a server).

Returns:

True, if the JID is a full JID; otherwise false.

isBareJid

boolean isBareJid()

Checks if the JID is a bare JID.

The term “bare JID” refers to an XMPP address of the form <localpart@domainpart> (for an account at a server) or of the form <domainpart> (for a server).

Returns:

True, if the JID is a bare JID; otherwise false.

isDomainJid

boolean isDomainJid()

Checks if the JID is a domain JID, i.e. if it has no local part.

Returns:

True, if the JID is a domain JID, i.e. if it has no local part.

asBareJid

Jid asBareJid()

Gets the bare JID representation of this JID, i.e. removes the resource part.

The term “bare JID” refers to an XMPP address of the form <localpart@domainpart> (for an account at a server) or of the form <domainpart> (for a server).

Returns:

The bare JID.

See Also:

withResource(CharSequence)

withLocal

Jid withLocal(java.lang.CharSequence local)

Creates a new JID with a new local part and the same domain and resource part of the current JID.

Parameters:

local - The local part.

Returns:

The JID with a new local part.

Throws:

java.lang.IllegalArgumentException - If the local is not a valid local part.

See Also:

withResource(CharSequence)

withResource

Jid withResource(java.lang.CharSequence resource)

Creates a new full JID with a resource and the same local and domain part of the current JID.

Parameters:

resource - The resource.

Returns:

The full JID with a resource.

Throws:

java.lang.IllegalArgumentException - If the resource is not a valid resource part.

See Also:

asBareJid(), withLocal(CharSequence)

atSubdomain

Jid atSubdomain(java.lang.CharSequence subdomain)

Creates a new JID at a subdomain and at the same domain as this JID.

Parameters:

subdomain - The subdomain.

Returns:

The JID at a subdomain.

Throws:

java.lang.NullPointerException - If subdomain is null.

java.lang.IllegalArgumentException - If subdomain is not a valid subdomain name.

getLocal

java.lang.String getLocal()

Gets the local part of the JID, also known as the name or node.

3.3. Localpart

The localpart of a JID is an optional identifier placed before the domainpart and separated from the latter by the ‘@’ character. Typically, a localpart uniquely identifies the entity requesting and using network access provided by a server (i.e., a local account), although it can also represent other kinds of entities (e.g., a chatroom associated with a multi-user chat service [XEP-0045]). The entity represented by an XMPP localpart is addressed within the context of a specific domain (i.e., <localpart@domainpart>).

Returns:

The local part or null.

See Also:

getEscapedLocal()

getEscapedLocal

java.lang.String getEscapedLocal()

Gets the escaped local part of the JID.

Returns:

The escaped local part or null.

Since:

0.8.0

See Also:

getLocal()

getDomain

java.lang.String getDomain()

Gets the domain part.

3.2. Domainpart

The domainpart is the primary identifier and is the only REQUIRED element of a JID (a mere domainpart is a valid JID). Typically, a domainpart identifies the “home” server to which clients connect for XML routing and data management functionality.

Returns:

The domain part.

getResource

java.lang.String getResource()

Gets the resource part.

3.4. Resourcepart

The resourcepart of a JID is an optional identifier placed after the domainpart and separated from the latter by the ‘/’ character. A resourcepart can modify either a <localpart@domainpart> address or a mere <domainpart> address. Typically, a resourcepart uniquely identifies a specific connection (e.g., a device or location) or object (e.g., an occupant in a multi-user chatroom [XEP-0045]) belonging to the entity associated with an XMPP localpart at a domain (i.e., <localpart@domainpart/resourcepart>).

Returns:

The resource part or null.

toEscapedString

java.lang.String toEscapedString()

Returns the JID in escaped form as described in XEP-0106: JID Escaping.

Returns:

The escaped JID.

See Also:

CharSequence.toString()