Package rocks.xmpp.core.stanza.model

Class Presence

java.lang.Object

rocks.xmpp.core.stanza.model.Stanza

rocks.xmpp.core.stanza.model.ExtensibleStanza

rocks.xmpp.core.stanza.model.Presence

All Implemented Interfaces:

Comparable<Presence>, LanguageElement, StreamElement

Direct Known Subclasses:

ClientPresence, ComponentPresence, ServerPresence

public class Presence
extends ExtensibleStanza
implements Comparable<Presence>

The implementation of the <presence/> element.

4.1. Presence Fundamentals

The concept of presence refers to an entity's availability for communication over a network. At the most basic level, presence is a boolean "on/off" variable that signals whether an entity is available or unavailable for communication (the terms "online" and "offline" are also used). In XMPP, an entity's availability is signaled when its client generates a <presence/> stanza with no 'type' attribute, and an entity's lack of availability is signaled when its client generates a <presence/> stanza whose 'type' attribute has a value of "unavailable".

XMPP presence typically follows a "publish-subscribe" or "observer" pattern, wherein an entity sends presence to its server, and its server then broadcasts that information to all of the entity's contacts who have a subscription to the entity's presence (in the terminology of [IMP-MODEL], an entity that generates presence is a "presentity" and the entities that receive presence are "subscribers"). A client generates presence for broadcast to all subscribed entities by sending a presence stanza to its server with no 'to' address, where the presence stanza has either no 'type' attribute or a 'type' attribute whose value is "unavailable". This kind of presence is called "broadcast presence".

After a client completes the preconditions specified in [XMPP-CORE], it can establish a "presence session" at its server by sending initial presence, where the presence session is terminated by sending unavailable presence. For the duration of its presence session, a connected resource (in the terminology of [XMPP-CORE]) is said to be an "available resource".

In XMPP, applications that combine messaging and presence functionality, the default type of communication for which presence signals availability is messaging; however, it is not necessary for XMPP applications to combine messaging and presence functionality, and they can provide standalone presence features without messaging (in addition, XMPP servers do not require information about network availability in order to successfully route message and IQ stanzas).

This class is thread-safe.

See Also:

4.7. Presence Syntax

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Presence.Show	Represents a <presence/> <show/> element.
static class	Presence.Type	Represents a <presence/> 'type' attribute.

Constructor Summary

Constructors

Constructor	Description
Presence()	Constructs an empty presence to indicate availability.
Presence(byte priority)	Constructs a presence with a priority.
Presence(Jid to)	Constructs a directed presence.
Presence(Jid to, Presence.Show show, String status)	Constructs a directed presence with a specific 'show' attribute and status.
Presence(Jid to, Presence.Type type, String status)	Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.
Presence(Jid to, Presence.Type type, String status, String id)	Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.
Presence(Jid to, Presence.Type type, Presence.Show show, Collection<Text> status, byte priority, String id, Jid from, Locale language, Collection<?> extensions, StanzaError error)	Constructs a presence with all possible values.
Presence(Presence.Show show)	Constructs a presence with a specific 'show' value.
Presence(Presence.Show show, byte priority)	Constructs a presence with a specific 'show' value and priority.
Presence(Presence.Type type)	Constructs a presence of a specific type.
Presence(Presence.Type type, byte priority)	Constructs a presence of a specific type.

Method Summary

Modifier and Type	Method	Description
int	compareTo(Presence o)
Presence	createError(Condition condition)	Creates an error response for this stanza.
Presence	createError(StanzaError error)	Creates an error response for this stanza.
boolean	equals(Object o)
byte	getPriority()	Gets the priority.
Presence.Show	getShow()	Gets the <show/> element.
String	getStatus()	Gets the default body (which has no language attribute).
List<Text>	getStatuses()	Gets the statuses.
Presence.Type	getType()	Gets the type of the presence.
int	hashCode()
boolean	isAvailable()	Indicates, whether an entity is available.
boolean	isSubscription()	Indicates whether this presence is a subscription presence.
void	setPriority(byte priority)	Sets the priority.
void	setShow(Presence.Show show)	Sets the <show/> element.
void	setStatus(String text)	Sets the default status element.
void	setType(Presence.Type type)	Sets the type of the presence.
String	toString()

Methods inherited from class rocks.xmpp.core.stanza.model.ExtensibleStanza

addExtension, addExtensions, addExtensions, getExtensions, getExtensions, putExtension, removeExtension

Methods inherited from class rocks.xmpp.core.stanza.model.Stanza

getError, getExtension, getFrom, getId, getLanguage, getTo, hasExtension, isToItselfOrServer, setError, setFrom, setId, setLanguage, setTo

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Presence

public Presence()

Constructs an empty presence to indicate availability.

Presence

public Presence(byte priority)

Constructs a presence with a priority.

Parameters:

priority - The priority.

Presence

public Presence(Presence.Show show)

Constructs a presence with a specific 'show' value.

Parameters:

show - The 'show' value.

Presence

public Presence(Presence.Show show,
                byte priority)

Constructs a presence with a specific 'show' value and priority.

Parameters:

show - The 'show' value.

priority - The priority.

Presence

public Presence(Presence.Type type)

Constructs a presence of a specific type.

Parameters:

type - The type.

Presence

public Presence(Presence.Type type,
                byte priority)

Constructs a presence of a specific type.

Parameters:

type - The type.

priority - The priority.

Presence

public Presence(Jid to)

Constructs a directed presence.

Parameters:

to - The recipient.

Presence

public Presence(Jid to,
                Presence.Show show,
                String status)

Constructs a directed presence with a specific 'show' attribute and status.

Parameters:

to - The recipient.

show - The 'show' value.

status - The status.

Presence

public Presence(Jid to,
                Presence.Type type,
                String status)

Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.

Parameters:

to - The recipient.

type - The type.

status - The status.

Presence

public Presence(Jid to,
                Presence.Type type,
                String status,
                String id)

Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.

Parameters:

to - The recipient.

type - The type.

status - The status.

id - The id.

Presence

public Presence(Jid to,
                Presence.Type type,
                Presence.Show show,
                Collection<Text> status,
                byte priority,
                String id,
                Jid from,
                Locale language,
                Collection<?> extensions,
                StanzaError error)

Constructs a presence with all possible values.

Parameters:

to - The recipient.

type - The type.

show - The 'show' value.

status - The status.

priority - The priority.

id - The id.

from - The 'from' attribute.

language - The language.

extensions - The extensions.

error - The stanza error.

Method Detail

isAvailable

public final boolean isAvailable()

Indicates, whether an entity is available.

4.1. Presence Fundamentals

In XMPP, an entity's availability is signaled when its client generates a <presence/> stanza with no 'type' attribute, and an entity's lack of availability is signaled when its client generates a <presence/> stanza whose 'type' attribute has a value of "unavailable".

Returns:

True, if the presence is available.

getShow

public final Presence.Show getShow()

Gets the <show/> element.

Returns:

The <show/> element.

See Also:

Presence.Show

setShow

public final void setShow(Presence.Show show)

Sets the <show/> element.

Parameters:

show - The <show/> element.

See Also:

getShow()

getPriority

public final byte getPriority()

Gets the priority.

4.7.2.3. Priority Element

The OPTIONAL <priority/> element contains non-human-readable XML character data that specifies the priority level of the resource. The value MUST be an integer between -128 and +127.

Returns:

The priority.

setPriority

public final void setPriority(byte priority)

Sets the priority.

Parameters:

priority - The priority.

See Also:

getPriority()

getType

public final Presence.Type getType()

Gets the type of the presence.

Returns:

The type.

See Also:

Presence.Type

setType

public final void setType(Presence.Type type)

Sets the type of the presence.

Parameters:

type - The type.

See Also:

getType()

getStatuses

public final List<Text> getStatuses()

Gets the statuses.

4.7.2.2. Status Element

The OPTIONAL <status/> element contains human-readable XML character data specifying a natural-language description of an entity's availability. It is normally used in conjunction with the show element to provide a detailed description of an availability state (e.g., "In a meeting") when the presence stanza has no 'type' attribute.

Multiple instances of the <status/> element MAY be included, but only if each instance possesses an 'xml:lang' attribute with a distinct language value.

Returns:

The statuses.

See Also:

getStatus()

getStatus

public final String getStatus()

Gets the default body (which has no language attribute).

4.7.2.2. Status Element

The OPTIONAL <status/> element contains human-readable XML character data specifying a natural-language description of an entity's availability. It is normally used in conjunction with the show element to provide a detailed description of an availability state (e.g., "In a meeting") when the presence stanza has no 'type' attribute.

If there's no default status, but only statuses with a language attribute, the first status is returned.

If there are no statuses at all, null is returned.

Returns:

The status or null.

See Also:

getStatuses()

setStatus

public final void setStatus(String text)

Sets the default status element.

Parameters:

text - The status text.

See Also:

()

isSubscription

public final boolean isSubscription()

Indicates whether this presence is a subscription presence. This is the case if it has as type of Presence.Type.SUBSCRIBE, Presence.Type.SUBSCRIBED, Presence.Type.UNSUBSCRIBE or Presence.Type.UNSUBSCRIBED.

Returns:

True, if this presence is a subscription presence, otherwise false.

createError

public final Presence createError(StanzaError error)

Description copied from class: Stanza

Creates an error response for this stanza.

Specified by:

createError in class Stanza

Parameters:

error - The error which is appended to the stanza.

Returns:

The error response.

See Also:

Stanza.getError()

createError

public final Presence createError(Condition condition)

Description copied from class: Stanza

Creates an error response for this stanza.

Specified by:

createError in class Stanza

Parameters:

condition - The error condition which is appended to the stanza.

Returns:

The error response.

See Also:

Stanza.getError()

equals

public final boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

compareTo

public final int compareTo(Presence o)

Specified by:

compareTo in interface Comparable<Presence>

toString

public final String toString()

Overrides:

toString in class Stanza