KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xmpp > packet > 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 JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc("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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc("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 JavaDoc name, String JavaDoc namespace) {
257         for (Iterator JavaDoc 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 JavaDoc name, String JavaDoc 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 }
Popular Tags