Presence


1   /**
2    * $RCSfile: Presence.java,v $
3    * $Revision: 1.14 $
4    * $Date: 2005/06/15 19:15:38 $
5    *
6    * Copyright 2004 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.xmpp.packet;
22  
23  import org.dom4j.Element;
24  
25  import java.util.Iterator  ;
26  
27  /**
28   * Presence packet. Presence packets are used to express an entity's current
29   * network availability and to notify other entities of that availability.
30   * Presence packets are also used to negotiate and manage subscriptions to the
31   * presence of other entities.<p>
32   *
33   * A presence optionally has a {@link Type}.
34   *
35   * @author Matt Tucker
36   */
37  public class Presence extends Packet {
38  
39      /**
40       * Constructs a new Presence.
41       */
42      public Presence() {
43          this.element = docFactory.createDocument().addElement("presence");
44      }
45  
46      /**
47       * Constructs a new Presence with the specified type.
48       *
49       * @param type the presence type.
50       */
51      public Presence(Presence.Type type) {
52          this();
53          setType(type);
54      }
55  
56      /**
57       * Constructs a new Presence using an existing Element. This is useful
58       * for parsing incoming presence Elements into Presence objects.
59       *
60       * @param element the presence Element.
61       */
62      public Presence(Element element) {
63          super(element);
64      }
65  
66      /**
67       * Constructs a new Presence that is a copy of an existing Presence.
68       *
69       * @param presence the presence packet.
70       * @see #createCopy() 
71       */
72      private Presence(Presence presence) {
73          Element elementCopy = presence.element.createCopy();
74          docFactory.createDocument().add(elementCopy);
75          this.element = elementCopy;
76      }
77  
78      /**
79       * Returns true if the presence type is "available". This is a
80       * convenience method that is equivalent to:
81       *
82       * <pre>getType() == null</pre>
83       *
84       */
85      public boolean isAvailable() {
86          return getType() == null;
87      }
88  
89      /**
90       * Returns the type of this presence. If the presence is "available", the
91       * type will be <tt>null</tt> (in XMPP, no value for the type attribute is
92       * defined as available).
93       *
94       * @return the presence type or <tt>null</tt> if "available".
95       * @see Type
96       */
97      public Type getType() {
98          String   type = element.attributeValue("type");
99          if (type == null) {
100             return null;
101         }
102         else {
103             return Type.valueOf(type);
104         }
105     }
106 
107     /**
108      * Sets the type of this presence.
109      *
110      * @param type the presence type.
111      * @see Type
112      */
113     public void setType(Type type) {
114         element.addAttribute("type", type==null?null:type.toString());
115     }
116 
117     /**
118      * Returns the presence "show" value, which specifies a particular availability
119      * status. If the &lt;show&gt; element is not present, this method will return
120      * <tt>null</tt>. The show value can only be set if the presence type is "avaialble".
121      * A <tt>null</tt> show value is used to represent "available", which is the
122      * default.
123      *
124      * @return the presence show value..
125      * @see Show
126      */
127     public Show getShow() {
128         String   show = element.elementText("show");
129         if (show == null) {
130             return null;
131         }
132         else {
133             return Show.valueOf(show);
134         }
135     }
136 
137     /**
138      * Sets the presence "show" value, which specifies a particular availability
139      * status. The show value can only be set if the presence type is "available".
140      * A <tt>null</tt> show value is used to represent "available", which is the
141      * default.
142      *
143      * @param show the presence show value.
144      * @throws IllegalArgumentException if the presence type is not available.
145      * @see Show
146      */
147     public void setShow(Show show) {
148         Element showElement = element.element("show");
149         // If show is null, clear the subject.
150         if (show == null) {
151             if (showElement != null) {
152                 element.remove(showElement);
153             }
154             return;
155         }
156         if (showElement == null) {
157             if (!isAvailable()) {
158                 throw new IllegalArgumentException  ("Cannot set 'show' if 'type' attribute is set.");
159             }
160             showElement = element.addElement("show");
161         }
162         showElement.setText(show.toString());
163     }
164 
165     /**
166      * Returns the status of this presence packet, a natural-language description
167      * of availability status.
168      *
169      * @return the status.
170      */
171     public String   getStatus() {
172         return element.elementText("status");
173     }
174 
175     /**
176      * Sets the status of this presence packet, a natural-language description
177      * of availability status.
178      *
179      * @param status the status.
180      */
181     public void setStatus(String   status) {
182         Element statusElement = element.element("status");
183         // If subject is null, clear the subject.
184         if (status == null) {
185             if (statusElement != null) {
186                 element.remove(statusElement);
187             }
188             return;
189         }
190 
191         if (statusElement == null) {
192             statusElement = element.addElement("status");
193         }
194         statusElement.setText(status);
195     }
196 
197     /**
198      * Returns the priority. The valid priority range is -128 through 128.
199      * If no priority element exists in the packet, this method will return
200      * the default value of 0.
201      *
202      * @return the priority.
203      */
204     public int getPriority() {
205         String   priority = element.elementText("priority");
206         if (priority == null) {
207             return 0;
208         }
209         else {
210             try {
211                 return Integer.parseInt(priority);
212             }
213             catch (Exception   e) {
214                 return 0;
215             }
216         }
217     }
218 
219     /**
220      * Sets the priority. The valid priority range is -128 through 128.
221      *
222      * @param priority the priority.
223      * @throws IllegalArgumentException if the priority is less than -128 or greater
224      *      than 128.
225      */
226     public void setPriority(int priority) {
227         if (priority < -128 || priority > 128) {
228             throw new IllegalArgumentException  ("Priority value of " + priority +
229                     " is outside the valid range of -128 through 128");
230         }
231         Element priorityElement = element.element("priority");
232         if (priorityElement == null) {
233             priorityElement = element.addElement("priority");
234         }
235         priorityElement.setText(Integer.toString(priority));
236     }
237 
238     /**
239      * Returns the first child element of this packet that matches the
240      * given name and namespace. If no matching element is found,
241      * <tt>null</tt> will be returned. This is a convenience method to avoid
242      * manipulating this underlying packet's Element instance directly.<p>
243      *
244      * Child elements in extended namespaces are used to extend the features
245      * of XMPP. Examples include a "user is typing" indicator and invitations to
246      * group chat rooms. Although any valid XML can be included in a child element
247      * in an extended namespace, many common features have been standardized
248      * as <a HREF="http://www.jabber.org/jeps">Jabber Enhancement Proposals</a>
249      * (JEPs).
250      *
251      * @param name the element name.
252      * @param namespace the element namespace.
253      * @return the first matching child element, or <tt>null</tt> if there
254      *      is no matching child element.
255      */
256     public Element getChildElement(String   name, String   namespace) {
257         for (Iterator   i=element.elementIterator(name); i.hasNext(); ) {
258             Element element = (Element)i.next();
259             if (element.getNamespaceURI().equals(namespace)) {
260                 return element;
261             }
262         }
263         return null;
264     }
265 
266     /**
267      * Adds a new child element to this packet with the given name and
268      * namespace. The newly created Element is returned. This is a
269      * convenience method to avoid manipulating this underlying packet's
270      * Element instance directly.<p>
271      *
272      * Child elements in extended namespaces are used to extend the features
273      * of XMPP. Examples include a "user is typing" indicator and invitations to
274      * group chat rooms. Although any valid XML can be included in a child element
275      * in an extended namespace, many common features have been standardized
276      * as <a HREF="http://www.jabber.org/jeps">Jabber Enhancement Proposals</a>
277      * (JEPs).
278      *
279      * @param name the element name.
280      * @param namespace the element namespace.
281      * @return the newly created child element.
282      */
283     public Element addChildElement(String   name, String   namespace) {
284         return element.addElement(name, namespace);
285     }
286 
287     /**
288      * Returns a deep copy of this Presence.
289      *
290      * @return a deep copy of this Presence.
291      */
292     public Presence createCopy() {
293         return new Presence(this);
294     }
295 
296     /**
297      * Represents the type of a presence packet. Note: the presence is assumed
298      * to be "available" when the type attribute of the packet is <tt>null</tt>.
299      * The valid types are:
300      *
301      *  <ul>
302      *      <li>{@link #unavailable Presence.Type.unavailable} -- signals that the
303      *          entity is no longer available for communication.
304      *      <li>{@link #subscribe Presence.Type.subscribe} -- the sender wishes to
305      *          subscribe to the recipient's presence.
306      *      <li>{@link #subscribed Presence.Type.subscribed} -- the sender has allowed
307      *          the recipient to receive their presence.
308      *      <li>{@link #unsubscribe Presence.Type.unsubscribe} -- the sender is
309      *          unsubscribing from another entity's presence.
310      *      <li>{@link #unsubscribed Presence.Type.unsubcribed} -- the subscription
311      *          request has been denied or a previously-granted subscription has been cancelled.
312      *      <li>{@link #probe Presence.Type.probe} -- a request for an entity's current
313      *          presence; SHOULD be generated only by a server on behalf of a user.
314      *      <li>{@link #error Presence.Type.error} -- an error has occurred regarding
315      *          processing or delivery of a previously-sent presence stanza.
316      * </ul>
317      */
318     public enum Type {
319 
320         /**
321          * Typically short text message used in line-by-line chat interfaces.
322          */
323         unavailable,
324 
325         /**
326          * The sender wishes to subscribe to the recipient's presence.
327          */
328         subscribe,
329 
330         /**
331          * The sender has allowed the recipient to receive their presence.
332          */
333         subscribed,
334 
335         /**
336          * The sender is unsubscribing from another entity's presence.
337          */
338         unsubscribe,
339 
340         /**
341          * The subscription request has been denied or a previously-granted
342          * subscription has been cancelled.
343          */
344         unsubscribed,
345 
346         /**
347          * A request for an entity's current presence; SHOULD be
348          * generated only by a server on behalf of a user.
349          */
350         probe,
351 
352         /**
353          * An error has occurred regarding processing or delivery
354          * of a previously-sent presence stanza.
355          */
356         error;
357     }
358 
359     /**
360      * Represents the presence "show" value. Note: a <tt>null</tt> "show" value is the
361      * default, which means "available". Valid values are:
362      *
363      * <ul>
364      *      <li>{@link #chat Presence.Show.chat} -- the entity or resource is actively
365      *          interested in chatting.
366      *      <li>{@link #away Presence.Show.away} -- the entity or resource is
367      *          temporarily away.
368      *      <li>{@link #dnd Presence.Show.dnd} -- the entity or resource is busy
369      *          (dnd = "Do Not Disturb").
370      *      <li>{@link #xa Presence.Show.xa} -- the entity or resource is away for an
371      *          extended period (xa = "eXtended Away").
372      * </ul>
373      */
374     public enum Show {
375 
376         /**
377          * The entity or resource is actively interested in chatting.
378          */
379         chat,
380 
381         /**
382          * The entity or resource is temporarily away.
383          */
384         away,
385 
386         /**
387          * The entity or resource is away for an extended period (xa = "eXtended Away").
388          */
389         xa,
390 
391         /**
392          * The entity or resource is busy (dnd = "Do Not Disturb").
393          */
394         dnd;
395     }
396 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags