/** * * Copyright 2003-2007 Jive Software. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jivesoftware.smack.packet; import java.util.Locale; import org.jivesoftware.smack.packet.id.StanzaIdUtil; import org.jivesoftware.smack.util.Objects; import org.jivesoftware.smack.util.StringUtils; import org.jivesoftware.smack.util.TypedCloneable; import org.jivesoftware.smack.util.XmlStringBuilder; import org.jxmpp.jid.Jid; /** * Represents XMPP presence packets. Every presence stanza has a type, which is one of * the following values: *
* * A number of attributes are optional: *
*
* Presence packets 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.
*
* @author Matt Tucker
*/
public final class Presence extends Stanza implements TypedCloneable
* This does not perform a deep clone, as extension elements are shared between the new and old
* instance.
*
* This does not perform a deep clone, as extension elements are shared between the new and old
* instance.
* null
to indicate that the original
* presence stanza did not had an explicit priority set. In which case the priority defaults to 0.
*
* @see RFC 6121 § 4.7.2.3.
*/
private Byte priority;
private Mode mode = null;
/**
* Creates a new presence update. Status, priority, and mode are left un-set.
*
* @param type the type.
*/
public Presence(Type type) {
// Ensure that the stanza ID is set by calling super().
super();
setType(type);
}
/**
* Creates a new presence with the given type and using the given XMPP address as recipient.
*
* @param to the recipient.
* @param type the type.
* @since 4.2
*/
public Presence(Jid to, Type type) {
this(type);
setTo(to);
}
/**
* Creates a new presence update with a specified status, priority, and mode.
*
* @param type the type.
* @param status a text message describing the presence update.
* @param priority the priority of this presence update.
* @param mode the mode type for this presence update.
*/
public Presence(Type type, String status, int priority, Mode mode) {
// Ensure that the stanza ID is set by calling super().
super();
setType(type);
setStatus(status);
setPriority(priority);
setMode(mode);
}
/**
* Copy constructor.
* getType() == Presence.Type.available
. Note that even
* when the user is available, their presence mode may be {@link Mode#away away},
* {@link Mode#xa extended away} or {@link Mode#dnd do not disturb}. Use
* {@link #isAway()} to determine if the user is away.
*
* @return true if the presence type is available.
*/
public boolean isAvailable() {
return type == Type.available;
}
/**
* Returns true if the presence type is {@link Type#available available} and the presence
* mode is {@link Mode#away away}, {@link Mode#xa extended away}, or
* {@link Mode#dnd 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)
.
*
* @return true if the presence type is available and the presence mode is away, xa, or dnd.
*/
public boolean isAway() {
return type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd);
}
/**
* Returns the type of this presence packet.
*
* @return the type of the presence packet.
*/
public Type getType() {
return type;
}
/**
* Sets the type of the presence packet.
*
* @param type the type of the presence packet.
*/
public void setType(Type type) {
this.type = Objects.requireNonNull(type, "Type cannot be null");
}
/**
* 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").
*
* @return the status message.
*/
public String getStatus() {
return status;
}
/**
* Sets the status message of the presence update. The status is free-form text
* describing a user's presence (i.e., "gone to lunch").
*
* @param status the status message.
*/
public void setStatus(String status) {
this.status = status;
}
/**
* Returns the priority of the presence.
*
* @return the priority.
* @see RFC 6121 § 4.7.2.3. Priority Element
*/
public int getPriority() {
if (priority == null) {
return 0;
}
return priority;
}
/**
* Sets the priority of the presence. The valid range is -128 through 127.
*
* @param priority the priority of the presence.
* @throws IllegalArgumentException if the priority is outside the valid range.
* @see RFC 6121 § 4.7.2.3. Priority Element
*/
public void setPriority(int priority) {
if (priority < -128 || priority > 127) {
throw new IllegalArgumentException("Priority value " + priority +
" is not valid. Valid range is -128 through 127.");
}
setPriority((byte) priority);
}
public void setPriority(byte priority) {
this.priority = priority;
}
/**
* Returns the mode of the presence update.
*
* @return the mode.
*/
public Mode getMode() {
if (mode == null) {
return Mode.available;
}
return mode;
}
/**
* Sets the mode of the presence update. A null presence mode value is interpreted
* to be the same thing as {@link Presence.Mode#available}.
*
* @param mode the mode.
*/
public void setMode(Mode mode) {
this.mode = mode;
}
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("Presence Stanza [");
logCommonAttributes(sb);
sb.append("type=").append(type).append(',');
if (mode != null) {
sb.append("mode=").append(mode).append(',');
}
if (!StringUtils.isNullOrEmpty(status)) {
sb.append("status=").append(status).append(',');
}
if (priority != null) {
sb.append("prio=").append(priority).append(',');
}
sb.append(']');
return sb.toString();
}
@Override
public XmlStringBuilder toXML(org.jivesoftware.smack.packet.XmlEnvironment enclosingNamespace) {
XmlStringBuilder buf = new XmlStringBuilder(enclosingNamespace);
buf.halfOpenElement(ELEMENT);
addCommonAttributes(buf, enclosingNamespace);
if (type != Type.available) {
buf.attribute("type", type);
}
buf.rightAngleBracket();
buf.optElement("status", status);
buf.optElement("priority", priority);
if (mode != null && mode != Mode.available) {
buf.element("show", mode);
}
buf.append(getExtensions(), enclosingNamespace);
// Add the error sub-packet, if there is one.
appendErrorIfExists(buf, enclosingNamespace);
buf.closeElement(ELEMENT);
return buf;
}
/**
* Creates and returns a copy of this presence stanza.
*