Source code

001/**
002 *
003 * Copyright 2003-2007 Jive Software.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.jivesoftware.smack.packet;
019
020import java.util.Locale;
021
022import org.jivesoftware.smack.packet.id.StanzaIdUtil;
023import org.jivesoftware.smack.util.Objects;
024import org.jivesoftware.smack.util.StringUtils;
025import org.jivesoftware.smack.util.TypedCloneable;
026import org.jivesoftware.smack.util.XmlStringBuilder;
027
028import org.jxmpp.jid.Jid;
029
030/**
031 * Represents XMPP presence packets. Every presence stanza(/packet) has a type, which is one of
032 * the following values:
033 * <ul>
034 *      <li>{@link Presence.Type#available available} -- (Default) indicates the user is available to
035 *          receive messages.
036 *      <li>{@link Presence.Type#unavailable unavailable} -- the user is unavailable to receive messages.
037 *      <li>{@link Presence.Type#subscribe subscribe} -- request subscription to recipient's presence.
038 *      <li>{@link Presence.Type#subscribed subscribed} -- grant subscription to sender's presence.
039 *      <li>{@link Presence.Type#unsubscribe unsubscribe} -- request removal of subscription to
040 *          sender's presence.
041 *      <li>{@link Presence.Type#unsubscribed unsubscribed} -- grant removal of subscription to
042 *          sender's presence.
043 *      <li>{@link Presence.Type#error error} -- the presence stanza(/packet) contains an error message.
044 * </ul><p>
045 *
046 * A number of attributes are optional:
047 * <ul>
048 *      <li>Status -- free-form text describing a user's presence (i.e., gone to lunch).
049 *      <li>Priority -- non-negative numerical priority of a sender's resource. The
050 *          highest resource priority is the default recipient of packets not addressed
051 *          to a particular resource.
052 *      <li>Mode -- one of five presence modes: {@link Mode#available available} (the default),
053 *          {@link Mode#chat chat}, {@link Mode#away away}, {@link Mode#xa xa} (extended away), and
054 *          {@link Mode#dnd dnd} (do not disturb).
055 * </ul><p>
056 *
057 * Presence packets are used for two purposes. First, to notify the server of
058 * the user's current presence status. Second, they are used to subscribe and
059 * unsubscribe users from the roster.
060 *
061 * @author Matt Tucker
062 */
063public final class Presence extends Stanza implements TypedCloneable<Presence> {
064
065    public static final String ELEMENT = "presence";
066
067    private Type type = Type.available;
068    private String status = null;
069
070    /**
071     * The priority of the presence. The magic value {@link Integer#MIN_VALUE} is used to indicate that the original
072     * presence stanza did not had an explicit priority set. In which case the priority defaults to 0.
073     *
074     * @see <a href="https://tools.ietf.org/html/rfc6121#section-4.7.2.3">RFC 6121 § 4.7.2.3.</a>
075     */
076    private int priority = Integer.MIN_VALUE;
077
078    private Mode mode = null;
079
080    /**
081     * Creates a new presence update. Status, priority, and mode are left un-set.
082     *
083     * @param type the type.
084     */
085    public Presence(Type type) {
086        // Ensure that the stanza ID is set by calling super().
087        super();
088        setType(type);
089    }
090
091    /**
092     * Creates a new presence with the given type and using the given XMPP address as recipient.
093     *
094     * @param to the recipient.
095     * @param type the type.
096     * @since 4.2
097     */
098    public Presence(Jid to, Type type) {
099        this(type);
100        setTo(to);
101    }
102
103    /**
104     * Creates a new presence update with a specified status, priority, and mode.
105     *
106     * @param type the type.
107     * @param status a text message describing the presence update.
108     * @param priority the priority of this presence update.
109     * @param mode the mode type for this presence update.
110     */
111    public Presence(Type type, String status, int priority, Mode mode) {
112        // Ensure that the stanza ID is set by calling super().
113        super();
114        setType(type);
115        setStatus(status);
116        setPriority(priority);
117        setMode(mode);
118    }
119
120    /**
121     * Copy constructor.
122     * <p>
123     * This does not perform a deep clone, as extension elements are shared between the new and old
124     * instance.
125     * </p>
126     *
127     * @param other
128     */
129    public Presence(Presence other) {
130        super(other);
131        this.type = other.type;
132        this.status = other.status;
133        this.priority = other.priority;
134        this.mode = other.mode;
135    }
136
137    /**
138     * Returns true if the {@link Type presence type} is available (online) and
139     * false if the user is unavailable (offline), or if this is a presence packet
140     * involved in a subscription operation. This is a convenience method
141     * equivalent to <tt>getType() == Presence.Type.available</tt>. Note that even
142     * when the user is available, their presence mode may be {@link Mode#away away},
143     * {@link Mode#xa extended away} or {@link Mode#dnd do not disturb}. Use
144     * {@link #isAway()} to determine if the user is away.
145     *
146     * @return true if the presence type is available.
147     */
148    public boolean isAvailable() {
149        return type == Type.available;    
150    }
151
152    /**
153     * Returns true if the presence type is {@link Type#available available} and the presence
154     * mode is {@link Mode#away away}, {@link Mode#xa extended away}, or
155     * {@link Mode#dnd do not disturb}. False will be returned when the type or mode
156     * is any other value, including when the presence type is unavailable (offline).
157     * This is a convenience method equivalent to
158     * <tt>type == Type.available &amp;&amp; (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd)</tt>.
159     *
160     * @return true if the presence type is available and the presence mode is away, xa, or dnd.
161     */
162    public boolean isAway() {
163        return type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd); 
164    }
165
166    /**
167     * Returns the type of this presence packet.
168     *
169     * @return the type of the presence packet.
170     */
171    public Type getType() {
172        return type;
173    }
174
175    /**
176     * Sets the type of the presence packet.
177     *
178     * @param type the type of the presence packet.
179     */
180    public void setType(Type type) {
181        this.type = Objects.requireNonNull(type, "Type cannot be null");
182    }
183
184    /**
185     * Returns the status message of the presence update, or <tt>null</tt> if there
186     * is not a status. The status is free-form text describing a user's presence
187     * (i.e., "gone to lunch").
188     *
189     * @return the status message.
190     */
191    public String getStatus() {
192        return status;
193    }
194
195    /**
196     * Sets the status message of the presence update. The status is free-form text
197     * describing a user's presence (i.e., "gone to lunch").
198     *
199     * @param status the status message.
200     */
201    public void setStatus(String status) {
202        this.status = status;
203    }
204
205    /**
206     * Returns the priority of the presence, or Integer.MIN_VALUE if no priority has been set.
207     *
208     * @return the priority.
209     * @see <a href="https://tools.ietf.org/html/rfc6121#section-4.7.2.3">RFC 6121 § 4.7.2.3. Priority Element</a>
210     */
211    public int getPriority() {
212        if (priority == Integer.MIN_VALUE) {
213            return 0;
214        }
215        return priority;
216    }
217
218    /**
219     * Sets the priority of the presence. The valid range is -128 through 127.
220     *
221     * @param priority the priority of the presence.
222     * @throws IllegalArgumentException if the priority is outside the valid range.
223     * @see <a href="https://tools.ietf.org/html/rfc6121#section-4.7.2.3">RFC 6121 § 4.7.2.3. Priority Element</a>
224     */
225    public void setPriority(int priority) {
226        if (priority < -128 || priority > 127) {
227            throw new IllegalArgumentException("Priority value " + priority +
228                    " is not valid. Valid range is -128 through 127.");
229        }
230        this.priority = priority;
231    }
232
233    /**
234     * Returns the mode of the presence update.
235     *
236     * @return the mode.
237     */
238    public Mode getMode() {
239        if (mode == null) {
240            return Mode.available;
241        }
242        return mode;
243    }
244
245    /**
246     * Sets the mode of the presence update. A null presence mode value is interpreted
247     * to be the same thing as {@link Presence.Mode#available}.
248     *
249     * @param mode the mode.
250     */
251    public void setMode(Mode mode) {
252        this.mode = mode;
253    }
254
255    @Override
256    public String toString() {
257        StringBuilder sb = new StringBuilder();
258        sb.append("Presence Stanza [");
259        logCommonAttributes(sb);
260        sb.append("type=").append(type).append(',');
261        if (mode != null) {
262            sb.append("mode=").append(mode).append(',');
263        }
264        if (!StringUtils.isNullOrEmpty(status)) {
265            sb.append("status=").append(status).append(',');
266        }
267        if (priority != Integer.MIN_VALUE) {
268            sb.append("prio=").append(priority).append(',');
269        }
270        sb.append(']');
271        return sb.toString();
272    }
273
274    @Override
275    public XmlStringBuilder toXML() {
276        XmlStringBuilder buf = new XmlStringBuilder();
277        buf.halfOpenElement(ELEMENT);
278        addCommonAttributes(buf);
279        if (type != Type.available) {
280            buf.attribute("type", type);
281        }
282        buf.rightAngleBracket();
283
284        buf.optElement("status", status);
285        if (priority != Integer.MIN_VALUE) {
286            buf.element("priority", Integer.toString(priority));
287        }
288        if (mode != null && mode != Mode.available) {
289            buf.element("show", mode);
290        }
291        buf.append(getExtensionsXML());
292
293        // Add the error sub-packet, if there is one.
294        appendErrorIfExists(buf);
295
296        buf.closeElement(ELEMENT);
297
298        return buf;
299    }
300
301    /**
302     * Creates and returns a copy of this presence stanza.
303     * <p>
304     * This does not perform a deep clone, as extension elements are shared between the new and old
305     * instance.
306     * </p>
307     * @return a clone of this presence.
308     */
309    @Override
310    public Presence clone() {
311        return new Presence(this);
312    }
313
314    /**
315     * Clone this presence and set a newly generated stanza ID as the clone's ID.
316     *
317     * @return a "clone" of this presence  with a different stanza ID.
318     * @since 4.1.2
319     */
320    public Presence cloneWithNewId() {
321        Presence clone = clone();
322        clone.setStanzaId(StanzaIdUtil.newStanzaId());
323        return clone;
324    }
325
326    /**
327     * An enum to represent the presence type. Note that presence type is often confused
328     * with presence mode. Generally, if a user is signed in to a server, they have a presence
329     * type of {@link #available available}, even if the mode is {@link Mode#away away},
330     * {@link Mode#dnd dnd}, etc. The presence type is only {@link #unavailable unavailable} when
331     * the user is signing out of the server.
332     */
333    public enum Type {
334
335       /**
336        * The user is available to receive messages (default).
337        */
338        available,
339
340        /**
341         * The user is unavailable to receive messages.
342         */
343        unavailable,
344
345        /**
346         * Request subscription to recipient's presence.
347         */
348        subscribe,
349
350        /**
351         * Grant subscription to sender's presence.
352         */
353        subscribed,
354
355        /**
356         * Request removal of subscription to sender's presence.
357         */
358        unsubscribe,
359
360        /**
361         * Grant removal of subscription to sender's presence.
362         */
363        unsubscribed,
364
365        /**
366         * The presence stanza(/packet) contains an error message.
367         */
368        error,
369
370        /**
371         * A presence probe as defined in section 4.3 of RFC 6121.
372         */
373        probe,
374        ;
375
376        /**
377         * Converts a String into the corresponding types. Valid String values that can be converted
378         * to types are: "available", "unavailable", "subscribe", "subscribed", "unsubscribe",
379         * "unsubscribed" and "error".
380         * 
381         * @param string the String value to covert.
382         * @return the corresponding Type.
383         * @throws IllegalArgumentException when not able to parse the string parameter
384         * @throws NullPointerException if the string is null
385         */
386        public static Type fromString(String string) {
387            return Type.valueOf(string.toLowerCase(Locale.US));
388        }
389    }
390
391    /**
392     * An enum to represent the presence mode.
393     */
394    public enum Mode {
395
396        /**
397         * Free to chat.
398         */
399        chat,
400
401        /**
402         * Available (the default).
403         */
404        available,
405
406        /**
407         * Away.
408         */
409        away,
410
411        /**
412         * Away for an extended period of time.
413         */
414        xa,
415
416        /**
417         * Do not disturb.
418         */
419        dnd;
420
421        /**
422         * Converts a String into the corresponding types. Valid String values that can be converted
423         * to types are: "chat", "available", "away", "xa", and "dnd".
424         * 
425         * @param string the String value to covert.
426         * @return the corresponding Type.
427         * @throws IllegalArgumentException when not able to parse the string parameter
428         * @throws NullPointerException if the string is null
429         */
430        public static Mode fromString(String string) {
431            return Mode.valueOf(string.toLowerCase(Locale.US));
432        }
433    }
434}