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 private int priority = Integer.MIN_VALUE; 070 private Mode mode = null; 071 072 /** 073 * Creates a new presence update. Status, priority, and mode are left un-set. 074 * 075 * @param type the type. 076 */ 077 public Presence(Type type) { 078 // Ensure that the stanza ID is set by calling super(). 079 super(); 080 setType(type); 081 } 082 083 /** 084 * Creates a new presence with the given type and using the given XMPP address as recipient. 085 * 086 * @param to the recipient. 087 * @param type the type. 088 * @since 4.2 089 */ 090 public Presence(Jid to, Type type) { 091 this(type); 092 setTo(to); 093 } 094 095 /** 096 * Creates a new presence update with a specified status, priority, and mode. 097 * 098 * @param type the type. 099 * @param status a text message describing the presence update. 100 * @param priority the priority of this presence update. 101 * @param mode the mode type for this presence update. 102 */ 103 public Presence(Type type, String status, int priority, Mode mode) { 104 // Ensure that the stanza ID is set by calling super(). 105 super(); 106 setType(type); 107 setStatus(status); 108 setPriority(priority); 109 setMode(mode); 110 } 111 112 /** 113 * Copy constructor. 114 * <p> 115 * This does not perform a deep clone, as extension elements are shared between the new and old 116 * instance. 117 * </p> 118 * 119 * @param other 120 */ 121 public Presence(Presence other) { 122 super(other); 123 this.type = other.type; 124 this.status = other.status; 125 this.priority = other.priority; 126 this.mode = other.mode; 127 } 128 129 /** 130 * Returns true if the {@link Type presence type} is available (online) and 131 * false if the user is unavailable (offline), or if this is a presence packet 132 * involved in a subscription operation. This is a convenience method 133 * equivalent to <tt>getType() == Presence.Type.available</tt>. Note that even 134 * when the user is available, their presence mode may be {@link Mode#away away}, 135 * {@link Mode#xa extended away} or {@link Mode#dnd do not disturb}. Use 136 * {@link #isAway()} to determine if the user is away. 137 * 138 * @return true if the presence type is available. 139 */ 140 public boolean isAvailable() { 141 return type == Type.available; 142 } 143 144 /** 145 * Returns true if the presence type is {@link Type#available available} and the presence 146 * mode is {@link Mode#away away}, {@link Mode#xa extended away}, or 147 * {@link Mode#dnd do not disturb}. False will be returned when the type or mode 148 * is any other value, including when the presence type is unavailable (offline). 149 * This is a convenience method equivalent to 150 * <tt>type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd)</tt>. 151 * 152 * @return true if the presence type is available and the presence mode is away, xa, or dnd. 153 */ 154 public boolean isAway() { 155 return type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd); 156 } 157 158 /** 159 * Returns the type of this presence packet. 160 * 161 * @return the type of the presence packet. 162 */ 163 public Type getType() { 164 return type; 165 } 166 167 /** 168 * Sets the type of the presence packet. 169 * 170 * @param type the type of the presence packet. 171 */ 172 public void setType(Type type) { 173 this.type = Objects.requireNonNull(type, "Type cannot be null"); 174 } 175 176 /** 177 * Returns the status message of the presence update, or <tt>null</tt> if there 178 * is not a status. The status is free-form text describing a user's presence 179 * (i.e., "gone to lunch"). 180 * 181 * @return the status message. 182 */ 183 public String getStatus() { 184 return status; 185 } 186 187 /** 188 * Sets the status message of the presence update. The status is free-form text 189 * describing a user's presence (i.e., "gone to lunch"). 190 * 191 * @param status the status message. 192 */ 193 public void setStatus(String status) { 194 this.status = status; 195 } 196 197 /** 198 * Returns the priority of the presence, or Integer.MIN_VALUE if no priority has been set. 199 * 200 * @return the priority. 201 * @see <a href="https://tools.ietf.org/html/rfc6121#section-4.7.2.3">RFC 6121 § 4.7.2.3. Priority Element</a> 202 */ 203 public int getPriority() { 204 return priority; 205 } 206 207 /** 208 * Sets the priority of the presence. The valid range is -128 through 127. 209 * 210 * @param priority the priority of the presence. 211 * @throws IllegalArgumentException if the priority is outside the valid range. 212 * @see <a href="https://tools.ietf.org/html/rfc6121#section-4.7.2.3">RFC 6121 § 4.7.2.3. Priority Element</a> 213 */ 214 public void setPriority(int priority) { 215 if (priority < -128 || priority > 127) { 216 throw new IllegalArgumentException("Priority value " + priority + 217 " is not valid. Valid range is -128 through 127."); 218 } 219 this.priority = priority; 220 } 221 222 /** 223 * Returns the mode of the presence update. 224 * 225 * @return the mode. 226 */ 227 public Mode getMode() { 228 if (mode == null) { 229 return Mode.available; 230 } 231 return mode; 232 } 233 234 /** 235 * Sets the mode of the presence update. A null presence mode value is interpreted 236 * to be the same thing as {@link Presence.Mode#available}. 237 * 238 * @param mode the mode. 239 */ 240 public void setMode(Mode mode) { 241 this.mode = mode; 242 } 243 244 @Override 245 public String toString() { 246 StringBuilder sb = new StringBuilder(); 247 sb.append("Presence Stanza ["); 248 logCommonAttributes(sb); 249 sb.append("type=").append(type).append(','); 250 if (mode != null) { 251 sb.append("mode=").append(mode).append(','); 252 } 253 if (!StringUtils.isNullOrEmpty(status)) { 254 sb.append("status=").append(status).append(','); 255 } 256 if (priority != Integer.MIN_VALUE) { 257 sb.append("prio=").append(priority).append(','); 258 } 259 sb.append(']'); 260 return sb.toString(); 261 } 262 263 @Override 264 public XmlStringBuilder toXML() { 265 XmlStringBuilder buf = new XmlStringBuilder(); 266 buf.halfOpenElement(ELEMENT); 267 addCommonAttributes(buf); 268 if (type != Type.available) { 269 buf.attribute("type", type); 270 } 271 buf.rightAngleBracket(); 272 273 buf.optElement("status", status); 274 if (priority != Integer.MIN_VALUE) { 275 buf.element("priority", Integer.toString(priority)); 276 } 277 if (mode != null && mode != Mode.available) { 278 buf.element("show", mode); 279 } 280 buf.append(getExtensionsXML()); 281 282 // Add the error sub-packet, if there is one. 283 appendErrorIfExists(buf); 284 285 buf.closeElement(ELEMENT); 286 287 return buf; 288 } 289 290 /** 291 * Creates and returns a copy of this presence stanza. 292 * <p> 293 * This does not perform a deep clone, as extension elements are shared between the new and old 294 * instance. 295 * </p> 296 * @return a clone of this presence. 297 */ 298 @Override 299 public Presence clone() { 300 return new Presence(this); 301 } 302 303 /** 304 * Clone this presence and set a newly generated stanza ID as the clone's ID. 305 * 306 * @return a "clone" of this presence with a different stanza ID. 307 * @since 4.1.2 308 */ 309 public Presence cloneWithNewId() { 310 Presence clone = clone(); 311 clone.setStanzaId(StanzaIdUtil.newStanzaId()); 312 return clone; 313 } 314 315 /** 316 * An enum to represent the presence type. Note that presence type is often confused 317 * with presence mode. Generally, if a user is signed in to a server, they have a presence 318 * type of {@link #available available}, even if the mode is {@link Mode#away away}, 319 * {@link Mode#dnd dnd}, etc. The presence type is only {@link #unavailable unavailable} when 320 * the user is signing out of the server. 321 */ 322 public enum Type { 323 324 /** 325 * The user is available to receive messages (default). 326 */ 327 available, 328 329 /** 330 * The user is unavailable to receive messages. 331 */ 332 unavailable, 333 334 /** 335 * Request subscription to recipient's presence. 336 */ 337 subscribe, 338 339 /** 340 * Grant subscription to sender's presence. 341 */ 342 subscribed, 343 344 /** 345 * Request removal of subscription to sender's presence. 346 */ 347 unsubscribe, 348 349 /** 350 * Grant removal of subscription to sender's presence. 351 */ 352 unsubscribed, 353 354 /** 355 * The presence stanza(/packet) contains an error message. 356 */ 357 error, 358 359 /** 360 * A presence probe as defined in section 4.3 of RFC 6121. 361 */ 362 probe, 363 ; 364 365 /** 366 * Converts a String into the corresponding types. Valid String values that can be converted 367 * to types are: "available", "unavailable", "subscribe", "subscribed", "unsubscribe", 368 * "unsubscribed" and "error". 369 * 370 * @param string the String value to covert. 371 * @return the corresponding Type. 372 * @throws IllegalArgumentException when not able to parse the string parameter 373 * @throws NullPointerException if the string is null 374 */ 375 public static Type fromString(String string) { 376 return Type.valueOf(string.toLowerCase(Locale.US)); 377 } 378 } 379 380 /** 381 * An enum to represent the presence mode. 382 */ 383 public enum Mode { 384 385 /** 386 * Free to chat. 387 */ 388 chat, 389 390 /** 391 * Available (the default). 392 */ 393 available, 394 395 /** 396 * Away. 397 */ 398 away, 399 400 /** 401 * Away for an extended period of time. 402 */ 403 xa, 404 405 /** 406 * Do not disturb. 407 */ 408 dnd; 409 410 /** 411 * Converts a String into the corresponding types. Valid String values that can be converted 412 * to types are: "chat", "available", "away", "xa", and "dnd". 413 * 414 * @param string the String value to covert. 415 * @return the corresponding Type. 416 * @throws IllegalArgumentException when not able to parse the string parameter 417 * @throws NullPointerException if the string is null 418 */ 419 public static Mode fromString(String string) { 420 return Mode.valueOf(string.toLowerCase(Locale.US)); 421 } 422 } 423}