org.jivesoftware.smack.packet

Class Presence

java.lang.Object

org.jivesoftware.smack.packet.Stanza

org.jivesoftware.smack.packet.MessageOrPresence<PresenceBuilder>

org.jivesoftware.smack.packet.Presence

All Implemented Interfaces:

Element, FullyQualifiedElement, NamedElement, PresenceView, StanzaView, TopLevelStreamElement, XmlLangElement

public final class Presence
extends MessageOrPresence<PresenceBuilder>
implements PresenceView

Represents XMPP presence stanzas. Every presence stanza has a type, which is one of the following values:

• available -- (Default) indicates the user is available to receive messages.
• unavailable -- the user is unavailable to receive messages.
• subscribe -- request subscription to recipient's presence.
• subscribed -- grant subscription to sender's presence.
• unsubscribe -- request removal of subscription to sender's presence.
• unsubscribed -- grant removal of subscription to sender's presence.
• error -- the presence stanza contains an error message.

A number of attributes are optional:

• Status -- free-form text describing a user's presence (i.e., gone to lunch).
• Priority -- non-negative numerical priority of a sender's resource. The highest resource priority is the default recipient of packets not addressed to a particular resource.
• Mode -- one of five presence modes: available (the default), chat, away, xa (extended away), and dnd (do not disturb).

Presence stanzas are used for two purposes. First, to notify the server of the user's current presence status. Second, they are used to subscribe and unsubscribe users from the roster.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Presence.Mode An enum to represent the presence mode.
static class	Presence.Type An enum to represent the presence type.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ELEMENT

Fields inherited from class org.jivesoftware.smack.packet.Stanza

DEFAULT_LANGUAGE, ITEM, language, TEXT

Constructor Summary

Constructors

Constructor and Description
Presence(org.jxmpp.jid.Jid to, Presence.Type type) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
Presence(Presence.Type type) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
Presence(Presence.Type type, java.lang.String status, int priority, Presence.Mode mode) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
Presence(Presence other) Copy constructor.

Method Summary

Modifier and Type	Method and Description
PresenceBuilder	asBuilder()
PresenceBuilder	asBuilder(java.lang.String id)
PresenceBuilder	asBuilder(XMPPConnection connection)
Presence	clone() Deprecated. use asBuilder() instead.
Presence	cloneWithNewId() Deprecated. use asBuilder(XMPPConnection) or asBuilder(String)instead.
java.lang.String	getElementName() Returns the root element name.
Presence.Mode	getMode() Returns the mode of the presence update.
int	getPriority() Returns the priority of the presence.
byte	getPriorityByte() Returns the priority of the presence.
java.lang.String	getStatus() Returns the status message of the presence update, or null if there is not a status.
Presence.Type	getType() Returns the type of this presence stanza.
boolean	isAvailable() Returns true if the presence type is available (online) and false if the user is unavailable (offline), or if this is a presence packet involved in a subscription operation.
boolean	isAway() Returns true if the presence type is available and the presence mode is away, extended away, or do not disturb.
void	setMode(Presence.Mode mode) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
void	setPriority(byte priority)
void	setPriority(int priority) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
void	setStatus(java.lang.String status) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
void	setType(Presence.Type type) Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.
java.lang.String	toString() Returns a short String describing the Stanza.
XmlStringBuilder	toXML(XmlEnvironment enclosingNamespace)

Methods inherited from class org.jivesoftware.smack.packet.Stanza

addCommonAttributes, addExtension, addExtensions, appendErrorIfExists, getDefaultLanguage, getError, getExtension, getExtension, getExtension, getExtensionElement, getExtensions, getExtensions, getExtensions, getExtensions, getExtensionsMap, getFrom, getLanguage, getNamespace, getStanzaId, getTo, hasExtension, hasExtension, hasStanzaIdSet, logCommonAttributes, overrideExtension, removeExtension, removeExtension, setError, setError, setFrom, setLanguage, setNewStanzaId, setStanzaId, setStanzaId, setTo, throwIfNoStanzaId

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.jivesoftware.smack.packet.StanzaView

getError, getExtension, getExtension, getExtensions, getExtensions, getExtensions, getFrom, getStanzaId, getTo, hasExtension, hasExtension, hasExtension

Methods inherited from interface org.jivesoftware.smack.packet.XmlLangElement

getLanguage

Methods inherited from interface org.jivesoftware.smack.packet.FullyQualifiedElement

getQName

Methods inherited from interface org.jivesoftware.smack.packet.Element

toXML, toXML

Field Detail

ELEMENT

public static final java.lang.String ELEMENT

See Also:

Constant Field Values

Constructor Detail

Presence

@Deprecated
public Presence(Presence.Type type)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Creates a new presence update. Status, priority, and mode are left un-set.

Parameters:

type - the type.

Presence

@Deprecated
public Presence(org.jxmpp.jid.Jid to,
                            Presence.Type type)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Creates a new presence with the given type and using the given XMPP address as recipient.

Parameters:

to - the recipient.

type - the type.

Since:

4.2

Presence

@Deprecated
public Presence(Presence.Type type,
                            java.lang.String status,
                            int priority,
                            Presence.Mode mode)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Creates a new presence update with a specified status, priority, and mode.

Parameters:

type - the type.

status - a text message describing the presence update.

priority - the priority of this presence update.

mode - the mode type for this presence update.

Presence

public Presence(Presence other)

Copy constructor.

This does not perform a deep clone, as extension elements are shared between the new and old instance.

Parameters:

other - TODO javadoc me please

Method Detail

isAvailable

public boolean isAvailable()

Returns true if the presence type is available (online) and false if the user is unavailable (offline), or if this is a presence packet involved in a subscription operation. This is a convenience method equivalent to getType() == Presence.Type.available. Note that even when the user is available, their presence mode may be away, extended away or do not disturb. Use isAway() to determine if the user is away.

Returns:

true if the presence type is available.

isAway

public boolean isAway()

Returns true if the presence type is available and the presence mode is away, extended away, or do not disturb. False will be returned when the type or mode is any other value, including when the presence type is unavailable (offline). This is a convenience method equivalent to type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd).

Returns:

true if the presence type is available and the presence mode is away, xa, or dnd.

getType

public Presence.Type getType()

Description copied from interface: PresenceView

Returns the type of this presence stanza.

Specified by:

getType in interface PresenceView

Returns:

the type of the presence stanza.

setType

@Deprecated
public void setType(Presence.Type type)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Sets the type of the presence packet.

Parameters:

type - the type of the presence packet.

getStatus

public java.lang.String getStatus()

Description copied from interface: PresenceView

Returns the status message of the presence update, or null if there is not a status. The status is free-form text describing a user's presence (i.e., "gone to lunch").

Specified by:

getStatus in interface PresenceView

Returns:

the status message.

setStatus

@Deprecated
public void setStatus(java.lang.String status)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Sets the status message of the presence update. The status is free-form text describing a user's presence (i.e., "gone to lunch").

Parameters:

status - the status message.

getPriority

public int getPriority()

Description copied from interface: PresenceView

Returns the priority of the presence.

Specified by:

getPriority in interface PresenceView

Returns:

the priority.

See Also:

RFC 6121 § 4.7.2.3. Priority Element

getPriorityByte

public byte getPriorityByte()

Description copied from interface: PresenceView

Returns the priority of the presence.

Specified by:

getPriorityByte in interface PresenceView

Returns:

the priority.

See Also:

RFC 6121 § 4.7.2.3. Priority Element

setPriority

@Deprecated
public void setPriority(int priority)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Sets the priority of the presence. The valid range is -128 through 127.

Parameters:

priority - the priority of the presence.

Throws:

java.lang.IllegalArgumentException - if the priority is outside the valid range.

See Also:

RFC 6121 § 4.7.2.3. Priority Element

setPriority

public void setPriority(byte priority)

getMode

public Presence.Mode getMode()

Description copied from interface: PresenceView

Returns the mode of the presence update.

Specified by:

getMode in interface PresenceView

Returns:

the mode.

setMode

@Deprecated
public void setMode(Presence.Mode mode)

Deprecated. use PresenceBuilder or XMPPConnection.getStanzaFactory() instead.

Sets the mode of the presence update. A null presence mode value is interpreted to be the same thing as Presence.Mode.available.

Parameters:

mode - the mode.

getElementName

public java.lang.String getElementName()

Description copied from interface: NamedElement

Returns the root element name.

Specified by:

getElementName in interface NamedElement

Returns:

the element name.

asBuilder

public PresenceBuilder asBuilder()

Specified by:

asBuilder in class MessageOrPresence<PresenceBuilder>

asBuilder

public PresenceBuilder asBuilder(java.lang.String id)

Specified by:

asBuilder in class MessageOrPresence<PresenceBuilder>

asBuilder

public PresenceBuilder asBuilder(XMPPConnection connection)

Specified by:

asBuilder in class MessageOrPresence<PresenceBuilder>

toString

public java.lang.String toString()

Description copied from class: Stanza

Returns a short String describing the Stanza. This method is suited for log purposes.

Specified by:

toString in class Stanza

toXML

public XmlStringBuilder toXML(XmlEnvironment enclosingNamespace)

Specified by:

toXML in interface Element

clone

@Deprecated
public Presence clone()

Deprecated. use asBuilder() instead.

Creates and returns a copy of this presence stanza.

This does not perform a deep clone, as extension elements are shared between the new and old instance.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this presence.

cloneWithNewId

@Deprecated
public Presence cloneWithNewId()

Deprecated. use asBuilder(XMPPConnection) or asBuilder(String)instead.

Clone this presence and set a newly generated stanza ID as the clone's ID.

Returns:

a "clone" of this presence with a different stanza ID.

Since:

4.1.2