public class Presence extends ExtensibleStanza implements java.lang.Comparable<Presence>
The implementation of the <presence/>
element.
This class is thread-safe.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).
Modifier and Type | Class and Description |
---|---|
static class |
Presence.Show
Represents a
<presence/> <show/> element. |
static class |
Presence.Type
Represents a
<presence/> ‘type’ attribute. |
Constructor and Description |
---|
Presence()
Constructs an empty presence to indicate availability.
|
Presence(java.lang.Byte priority)
Constructs a presence with a priority.
|
Presence(Jid to)
Constructs a directed presence.
|
Presence(Jid to,
Presence.Show show,
java.lang.String status)
Constructs a directed presence with a specific ‘show’ attribute and status.
|
Presence(Jid to,
Presence.Type type,
Presence.Show show,
java.util.Collection<Text> status,
java.lang.Byte priority,
java.lang.String id,
Jid from,
java.util.Locale language,
java.util.Collection<?> extensions,
StanzaError error)
Constructs a presence with all possible values.
|
Presence(Jid to,
Presence.Type type,
java.lang.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,
java.lang.String status,
java.lang.String id)
Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.
|
Presence(Presence.Show show)
Constructs a presence with a specific ‘show’ value.
|
Presence(Presence.Show show,
java.lang.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,
java.lang.Byte priority)
Constructs a presence of a specific type.
|
Modifier and Type | Method and 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.
|
java.lang.Byte |
getPriority()
Gets the priority.
|
Presence.Show |
getShow()
Gets the
<show/> element. |
java.lang.String |
getStatus()
Gets the default body (which has no language attribute).
|
java.util.List<Text> |
getStatuses()
Gets the statuses.
|
Presence.Type |
getType()
Gets the type of the presence.
|
boolean |
isAvailable()
Indicates, whether an entity is available.
|
void |
setPriority(byte priority)
Sets the priority.
|
void |
setShow(Presence.Show show)
Sets the
<show/> element. |
void |
setStatus(java.lang.String text)
Sets the default status element.
|
void |
setType(Presence.Type type)
Sets the type of the presence.
|
java.lang.String |
toString() |
addExtension, addExtensions, addExtensions, getExtensions, getExtensions, putExtension, removeExtension
getError, getExtension, getFrom, getId, getLanguage, getTo, hasExtension, isToItselfOrServer, setError, setFrom, setId, setLanguage, setTo
public Presence()
Constructs an empty presence to indicate availability.
public Presence(java.lang.Byte priority)
Constructs a presence with a priority.
priority
- The priority.public Presence(Presence.Show show)
Constructs a presence with a specific ‘show’ value.
show
- The ‘show’ value.public Presence(Presence.Show show, java.lang.Byte priority)
Constructs a presence with a specific ‘show’ value and priority.
show
- The ‘show’ value.priority
- The priority.public Presence(Presence.Type type)
Constructs a presence of a specific type.
type
- The type.public Presence(Presence.Type type, java.lang.Byte priority)
Constructs a presence of a specific type.
type
- The type.priority
- The priority.public Presence(Jid to)
Constructs a directed presence.
to
- The recipient.public Presence(Jid to, Presence.Show show, java.lang.String status)
Constructs a directed presence with a specific ‘show’ attribute and status.
to
- The recipient.show
- The ‘show’ value.status
- The status.public Presence(Jid to, Presence.Type type, java.lang.String status)
Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.
to
- The recipient.type
- The type.status
- The status.public Presence(Jid to, Presence.Type type, java.lang.String status, java.lang.String id)
Constructs a directed presence, which is useful for requesting subscription or for exiting a multi-user chat.
to
- The recipient.type
- The type.status
- The status.id
- The id.public Presence(Jid to, Presence.Type type, Presence.Show show, java.util.Collection<Text> status, java.lang.Byte priority, java.lang.String id, Jid from, java.util.Locale language, java.util.Collection<?> extensions, StanzaError error)
Constructs a presence with all possible values.
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.public final boolean isAvailable()
Indicates, whether an entity is available.
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”.
public final Presence.Show getShow()
Gets the <show/>
element.
<show/>
element.Presence.Show
public final void setShow(Presence.Show show)
Sets the <show/>
element.
show
- The <show/>
element.getShow()
public final java.lang.Byte getPriority()
Gets the priority.
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.
public final void setPriority(byte priority)
Sets the priority.
priority
- The priority.getPriority()
public final Presence.Type getType()
Gets the type of the presence.
Presence.Type
public final void setType(Presence.Type type)
Sets the type of the presence.
type
- The type.getType()
public final java.util.List<Text> getStatuses()
Gets the statuses.
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.
getStatus()
public final java.lang.String getStatus()
Gets the default body (which has no language attribute).
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.
getStatuses()
public final void setStatus(java.lang.String text)
Sets the default status element.
text
- The status text.()
public final Presence createError(StanzaError error)
Stanza
Creates an error response for this stanza.
createError
in class Stanza
error
- The error which is appended to the stanza.Stanza.getError()
public final Presence createError(Condition condition)
Stanza
Creates an error response for this stanza.
createError
in class Stanza
condition
- The error condition which is appended to the stanza.Stanza.getError()
public final int compareTo(Presence o)
compareTo
in interface java.lang.Comparable<Presence>
Copyright © 2014–2019 XMPP.rocks. All rights reserved.