Shuyi Chen | d7955ce | 2013-05-22 14:51:55 -0700 | [diff] [blame] | 1 | /** |
| 2 | * $RCSfile$ |
| 3 | * $Revision$ |
| 4 | * $Date$ |
| 5 | * |
| 6 | * Copyright 2003-2007 Jive Software. |
| 7 | * |
| 8 | * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License"); |
| 9 | * you may not use this file except in compliance with the License. |
| 10 | * You may obtain a copy of the License at |
| 11 | * |
| 12 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 13 | * |
| 14 | * Unless required by applicable law or agreed to in writing, software |
| 15 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 16 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 17 | * See the License for the specific language governing permissions and |
| 18 | * limitations under the License. |
| 19 | */ |
| 20 | |
| 21 | package org.jivesoftware.smack.packet; |
| 22 | |
| 23 | import org.jivesoftware.smack.util.StringUtils; |
| 24 | |
| 25 | /** |
| 26 | * Represents XMPP presence packets. Every presence packet has a type, which is one of |
| 27 | * the following values: |
| 28 | * <ul> |
| 29 | * <li>{@link Presence.Type#available available} -- (Default) indicates the user is available to |
| 30 | * receive messages. |
| 31 | * <li>{@link Presence.Type#unavailable unavailable} -- the user is unavailable to receive messages. |
| 32 | * <li>{@link Presence.Type#subscribe subscribe} -- request subscription to recipient's presence. |
| 33 | * <li>{@link Presence.Type#subscribed subscribed} -- grant subscription to sender's presence. |
| 34 | * <li>{@link Presence.Type#unsubscribe unsubscribe} -- request removal of subscription to |
| 35 | * sender's presence. |
| 36 | * <li>{@link Presence.Type#unsubscribed unsubscribed} -- grant removal of subscription to |
| 37 | * sender's presence. |
| 38 | * <li>{@link Presence.Type#error error} -- the presence packet contains an error message. |
| 39 | * </ul><p> |
| 40 | * |
| 41 | * A number of attributes are optional: |
| 42 | * <ul> |
| 43 | * <li>Status -- free-form text describing a user's presence (i.e., gone to lunch). |
| 44 | * <li>Priority -- non-negative numerical priority of a sender's resource. The |
| 45 | * highest resource priority is the default recipient of packets not addressed |
| 46 | * to a particular resource. |
| 47 | * <li>Mode -- one of five presence modes: {@link Mode#available available} (the default), |
| 48 | * {@link Mode#chat chat}, {@link Mode#away away}, {@link Mode#xa xa} (extended away), and |
| 49 | * {@link Mode#dnd dnd} (do not disturb). |
| 50 | * </ul><p> |
| 51 | * |
| 52 | * Presence packets are used for two purposes. First, to notify the server of our |
| 53 | * the clients current presence status. Second, they are used to subscribe and |
| 54 | * unsubscribe users from the roster. |
| 55 | * |
| 56 | * @see RosterPacket |
| 57 | * @author Matt Tucker |
| 58 | */ |
| 59 | public class Presence extends Packet { |
| 60 | |
| 61 | private Type type = Type.available; |
| 62 | private String status = null; |
| 63 | private int priority = Integer.MIN_VALUE; |
| 64 | private Mode mode = null; |
| 65 | private String language; |
| 66 | |
| 67 | /** |
| 68 | * Creates a new presence update. Status, priority, and mode are left un-set. |
| 69 | * |
| 70 | * @param type the type. |
| 71 | */ |
| 72 | public Presence(Type type) { |
| 73 | setType(type); |
| 74 | } |
| 75 | |
| 76 | /** |
| 77 | * Creates a new presence update with a specified status, priority, and mode. |
| 78 | * |
| 79 | * @param type the type. |
| 80 | * @param status a text message describing the presence update. |
| 81 | * @param priority the priority of this presence update. |
| 82 | * @param mode the mode type for this presence update. |
| 83 | */ |
| 84 | public Presence(Type type, String status, int priority, Mode mode) { |
| 85 | setType(type); |
| 86 | setStatus(status); |
| 87 | setPriority(priority); |
| 88 | setMode(mode); |
| 89 | } |
| 90 | |
| 91 | /** |
| 92 | * Returns true if the {@link Type presence type} is available (online) and |
| 93 | * false if the user is unavailable (offline), or if this is a presence packet |
| 94 | * involved in a subscription operation. This is a convenience method |
| 95 | * equivalent to <tt>getType() == Presence.Type.available</tt>. Note that even |
| 96 | * when the user is available, their presence mode may be {@link Mode#away away}, |
| 97 | * {@link Mode#xa extended away} or {@link Mode#dnd do not disturb}. Use |
| 98 | * {@link #isAway()} to determine if the user is away. |
| 99 | * |
| 100 | * @return true if the presence type is available. |
| 101 | */ |
| 102 | public boolean isAvailable() { |
| 103 | return type == Type.available; |
| 104 | } |
| 105 | |
| 106 | /** |
| 107 | * Returns true if the presence type is {@link Type#available available} and the presence |
| 108 | * mode is {@link Mode#away away}, {@link Mode#xa extended away}, or |
| 109 | * {@link Mode#dnd do not disturb}. False will be returned when the type or mode |
| 110 | * is any other value, including when the presence type is unavailable (offline). |
| 111 | * This is a convenience method equivalent to |
| 112 | * <tt>type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd)</tt>. |
| 113 | * |
| 114 | * @return true if the presence type is available and the presence mode is away, xa, or dnd. |
| 115 | */ |
| 116 | public boolean isAway() { |
| 117 | return type == Type.available && (mode == Mode.away || mode == Mode.xa || mode == Mode.dnd); |
| 118 | } |
| 119 | |
| 120 | /** |
| 121 | * Returns the type of this presence packet. |
| 122 | * |
| 123 | * @return the type of the presence packet. |
| 124 | */ |
| 125 | public Type getType() { |
| 126 | return type; |
| 127 | } |
| 128 | |
| 129 | /** |
| 130 | * Sets the type of the presence packet. |
| 131 | * |
| 132 | * @param type the type of the presence packet. |
| 133 | */ |
| 134 | public void setType(Type type) { |
| 135 | if(type == null) { |
| 136 | throw new NullPointerException("Type cannot be null"); |
| 137 | } |
| 138 | this.type = type; |
| 139 | } |
| 140 | |
| 141 | /** |
| 142 | * Returns the status message of the presence update, or <tt>null</tt> if there |
| 143 | * is not a status. The status is free-form text describing a user's presence |
| 144 | * (i.e., "gone to lunch"). |
| 145 | * |
| 146 | * @return the status message. |
| 147 | */ |
| 148 | public String getStatus() { |
| 149 | return status; |
| 150 | } |
| 151 | |
| 152 | /** |
| 153 | * Sets the status message of the presence update. The status is free-form text |
| 154 | * describing a user's presence (i.e., "gone to lunch"). |
| 155 | * |
| 156 | * @param status the status message. |
| 157 | */ |
| 158 | public void setStatus(String status) { |
| 159 | this.status = status; |
| 160 | } |
| 161 | |
| 162 | /** |
| 163 | * Returns the priority of the presence, or Integer.MIN_VALUE if no priority has been set. |
| 164 | * |
| 165 | * @return the priority. |
| 166 | */ |
| 167 | public int getPriority() { |
| 168 | return priority; |
| 169 | } |
| 170 | |
| 171 | /** |
| 172 | * Sets the priority of the presence. The valid range is -128 through 128. |
| 173 | * |
| 174 | * @param priority the priority of the presence. |
| 175 | * @throws IllegalArgumentException if the priority is outside the valid range. |
| 176 | */ |
| 177 | public void setPriority(int priority) { |
| 178 | if (priority < -128 || priority > 128) { |
| 179 | throw new IllegalArgumentException("Priority value " + priority + |
| 180 | " is not valid. Valid range is -128 through 128."); |
| 181 | } |
| 182 | this.priority = priority; |
| 183 | } |
| 184 | |
| 185 | /** |
| 186 | * Returns the mode of the presence update, or <tt>null</tt> if the mode is not set. |
| 187 | * A null presence mode value is interpreted to be the same thing as |
| 188 | * {@link Presence.Mode#available}. |
| 189 | * |
| 190 | * @return the mode. |
| 191 | */ |
| 192 | public Mode getMode() { |
| 193 | return mode; |
| 194 | } |
| 195 | |
| 196 | /** |
| 197 | * Sets the mode of the presence update. A null presence mode value is interpreted |
| 198 | * to be the same thing as {@link Presence.Mode#available}. |
| 199 | * |
| 200 | * @param mode the mode. |
| 201 | */ |
| 202 | public void setMode(Mode mode) { |
| 203 | this.mode = mode; |
| 204 | } |
| 205 | |
| 206 | /** |
| 207 | * Returns the xml:lang of this Presence, or null if one has not been set. |
| 208 | * |
| 209 | * @return the xml:lang of this Presence, or null if one has not been set. |
| 210 | * @since 3.0.2 |
| 211 | */ |
| 212 | public String getLanguage() { |
| 213 | return language; |
| 214 | } |
| 215 | |
| 216 | /** |
| 217 | * Sets the xml:lang of this Presence. |
| 218 | * |
| 219 | * @param language the xml:lang of this Presence. |
| 220 | * @since 3.0.2 |
| 221 | */ |
| 222 | public void setLanguage(String language) { |
| 223 | this.language = language; |
| 224 | } |
| 225 | |
| 226 | public String toXML() { |
| 227 | StringBuilder buf = new StringBuilder(); |
| 228 | buf.append("<presence"); |
| 229 | if(getXmlns() != null) { |
| 230 | buf.append(" xmlns=\"").append(getXmlns()).append("\""); |
| 231 | } |
| 232 | if (language != null) { |
| 233 | buf.append(" xml:lang=\"").append(getLanguage()).append("\""); |
| 234 | } |
| 235 | if (getPacketID() != null) { |
| 236 | buf.append(" id=\"").append(getPacketID()).append("\""); |
| 237 | } |
| 238 | if (getTo() != null) { |
| 239 | buf.append(" to=\"").append(StringUtils.escapeForXML(getTo())).append("\""); |
| 240 | } |
| 241 | if (getFrom() != null) { |
| 242 | buf.append(" from=\"").append(StringUtils.escapeForXML(getFrom())).append("\""); |
| 243 | } |
| 244 | if (type != Type.available) { |
| 245 | buf.append(" type=\"").append(type).append("\""); |
| 246 | } |
| 247 | buf.append(">"); |
| 248 | if (status != null) { |
| 249 | buf.append("<status>").append(StringUtils.escapeForXML(status)).append("</status>"); |
| 250 | } |
| 251 | if (priority != Integer.MIN_VALUE) { |
| 252 | buf.append("<priority>").append(priority).append("</priority>"); |
| 253 | } |
| 254 | if (mode != null && mode != Mode.available) { |
| 255 | buf.append("<show>").append(mode).append("</show>"); |
| 256 | } |
| 257 | |
| 258 | buf.append(this.getExtensionsXML()); |
| 259 | |
| 260 | // Add the error sub-packet, if there is one. |
| 261 | XMPPError error = getError(); |
| 262 | if (error != null) { |
| 263 | buf.append(error.toXML()); |
| 264 | } |
| 265 | |
| 266 | buf.append("</presence>"); |
| 267 | |
| 268 | return buf.toString(); |
| 269 | } |
| 270 | |
| 271 | public String toString() { |
| 272 | StringBuilder buf = new StringBuilder(); |
| 273 | buf.append(type); |
| 274 | if (mode != null) { |
| 275 | buf.append(": ").append(mode); |
| 276 | } |
| 277 | if (getStatus() != null) { |
| 278 | buf.append(" (").append(getStatus()).append(")"); |
| 279 | } |
| 280 | return buf.toString(); |
| 281 | } |
| 282 | |
| 283 | /** |
| 284 | * A enum to represent the presecence type. Not that presence type is often confused |
| 285 | * with presence mode. Generally, if a user is signed into a server, they have a presence |
| 286 | * type of {@link #available available}, even if the mode is {@link Mode#away away}, |
| 287 | * {@link Mode#dnd dnd}, etc. The presence type is only {@link #unavailable unavailable} when |
| 288 | * the user is signing out of the server. |
| 289 | */ |
| 290 | public enum Type { |
| 291 | |
| 292 | /** |
| 293 | * The user is available to receive messages (default). |
| 294 | */ |
| 295 | available, |
| 296 | |
| 297 | /** |
| 298 | * The user is unavailable to receive messages. |
| 299 | */ |
| 300 | unavailable, |
| 301 | |
| 302 | /** |
| 303 | * Request subscription to recipient's presence. |
| 304 | */ |
| 305 | subscribe, |
| 306 | |
| 307 | /** |
| 308 | * Grant subscription to sender's presence. |
| 309 | */ |
| 310 | subscribed, |
| 311 | |
| 312 | /** |
| 313 | * Request removal of subscription to sender's presence. |
| 314 | */ |
| 315 | unsubscribe, |
| 316 | |
| 317 | /** |
| 318 | * Grant removal of subscription to sender's presence. |
| 319 | */ |
| 320 | unsubscribed, |
| 321 | |
| 322 | /** |
| 323 | * The presence packet contains an error message. |
| 324 | */ |
| 325 | error |
| 326 | } |
| 327 | |
| 328 | /** |
| 329 | * An enum to represent the presence mode. |
| 330 | */ |
| 331 | public enum Mode { |
| 332 | |
| 333 | /** |
| 334 | * Free to chat. |
| 335 | */ |
| 336 | chat, |
| 337 | |
| 338 | /** |
| 339 | * Available (the default). |
| 340 | */ |
| 341 | available, |
| 342 | |
| 343 | /** |
| 344 | * Away. |
| 345 | */ |
| 346 | away, |
| 347 | |
| 348 | /** |
| 349 | * Away for an extended period of time. |
| 350 | */ |
| 351 | xa, |
| 352 | |
| 353 | /** |
| 354 | * Do not disturb. |
| 355 | */ |
| 356 | dnd |
| 357 | } |
| 358 | } |