MessageEvent


1   /**
2    * $RCSfile$
3    * $Revision: 2407 $
4    * $Date: 2004-11-02 20:37:00 -0300 (Tue, 02 Nov 2004) $
5    *
6    * Copyright 2003-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.jivesoftware.smackx.packet;
22  
23  import java.util.*;
24  
25  import org.jivesoftware.smack.packet.PacketExtension;
26  
27  /**
28   * Represents message events relating to the delivery, display, composition and cancellation of 
29   * messages.<p>
30   * 
31   * There are four message events currently defined in this namespace:
32   * <ol>
33   * <li>Offline<br>
34   * Indicates that the message has been stored offline by the intended recipient's server. This 
35   * event is triggered only if the intended recipient's server supports offline storage, has that 
36   * support enabled, and the recipient is offline when the server receives the message for delivery.</li>
37   * 
38   * <li>Delivered<br>
39   * Indicates that the message has been delivered to the recipient. This signifies that the message
40   * has reached the recipient's XMPP client, but does not necessarily mean that the message has 
41   * been displayed. This event is to be raised by the XMPP client.</li>
42   * 
43   * <li>Displayed<br>
44   * Once the message has been received by the recipient's XMPP client, it may be displayed to the
45   * user. This event indicates that the message has been displayed, and is to be raised by the 
46   * XMPP client. Even if a message is displayed multiple times, this event should be raised only 
47   * once.</li>
48   * 
49   * <li>Composing<br>
50   * In threaded chat conversations, this indicates that the recipient is composing a reply to a 
51   * message. The event is to be raised by the recipient's XMPP client. A XMPP client is allowed
52   * to raise this event multiple times in response to the same request, providing the original 
53   * event is cancelled first.</li>
54   * </ol>
55   *
56   * @author Gaston Dombiak
57   */
58  public class MessageEvent implements PacketExtension {
59  
60      public static final String   OFFLINE = "offline";
61      public static final String   COMPOSING = "composing";
62      public static final String   DISPLAYED = "displayed";
63      public static final String   DELIVERED = "delivered";
64      public static final String   CANCELLED = "cancelled";
65  
66      private boolean offline = false;
67      private boolean delivered = false;
68      private boolean displayed = false;
69      private boolean composing = false;
70      private boolean cancelled = true;
71  
72      private String   packetID = null;
73  
74      /**
75      * Returns the XML element name of the extension sub-packet root element.
76      * Always returns "x"
77      *
78      * @return the XML element name of the packet extension.
79      */
80      public String   getElementName() {
81          return "x";
82      }
83  
84      /** 
85       * Returns the XML namespace of the extension sub-packet root element.
86       * According the specification the namespace is always "jabber:x:event"
87       *
88       * @return the XML namespace of the packet extension.
89       */
90      public String   getNamespace() {
91          return "jabber:x:event";
92      }
93  
94      /**
95       * When the message is a request returns if the sender of the message requests to be notified
96       * when the receiver is composing a reply.
97       * When the message is a notification returns if the receiver of the message is composing a 
98       * reply.
99       * 
100      * @return true if the sender is requesting to be notified when composing or when notifying
101      * that the receiver of the message is composing a reply
102      */
103     public boolean isComposing() {
104         return composing;
105     }
106 
107     /**
108      * When the message is a request returns if the sender of the message requests to be notified
109      * when the message is delivered.
110      * When the message is a notification returns if the message was delivered or not.
111      * 
112      * @return true if the sender is requesting to be notified when delivered or when notifying 
113      * that the message was delivered 
114      */
115     public boolean isDelivered() {
116         return delivered;
117     }
118 
119     /**
120      * When the message is a request returns if the sender of the message requests to be notified
121      * when the message is displayed.
122      * When the message is a notification returns if the message was displayed or not.
123      * 
124      * @return true if the sender is requesting to be notified when displayed or when notifying 
125      * that the message was displayed
126      */
127     public boolean isDisplayed() {
128         return displayed;
129     }
130 
131     /**
132      * When the message is a request returns if the sender of the message requests to be notified
133      * when the receiver of the message is offline.
134      * When the message is a notification returns if the receiver of the message was offline.
135      * 
136      * @return true if the sender is requesting to be notified when offline or when notifying 
137      * that the receiver of the message is offline
138      */
139     public boolean isOffline() {
140         return offline;
141     }
142 
143     /**
144      * When the message is a notification returns if the receiver of the message cancelled 
145      * composing a reply.
146      * 
147      * @return true if the receiver of the message cancelled composing a reply
148      */
149     public boolean isCancelled() {
150         return cancelled;
151     }
152 
153     /**
154      * Returns the unique ID of the message that requested to be notified of the event.
155      * The packet id is not used when the message is a request for notifications
156      *
157      * @return the message id that requested to be notified of the event.
158      */
159     public String   getPacketID() {
160         return packetID;
161     }
162 
163     /**
164      * Returns the types of events. The type of event could be:
165      * "offline", "composing","delivered","displayed", "offline"
166      *
167      * @return an iterator over all the types of events of the MessageEvent.
168      */
169     public Iterator getEventTypes() {
170         ArrayList allEvents = new ArrayList();
171         if (isDelivered()) {
172             allEvents.add(MessageEvent.DELIVERED);
173         }
174         if (isCancelled()) {
175             allEvents.add(MessageEvent.CANCELLED);
176         }
177         if (isComposing()) {
178             allEvents.add(MessageEvent.COMPOSING);
179         }
180         if (isDisplayed()) {
181             allEvents.add(MessageEvent.DISPLAYED);
182         }
183         if (isOffline()) {
184             allEvents.add(MessageEvent.OFFLINE);
185         }
186         return allEvents.iterator();
187     }
188 
189     /**
190      * When the message is a request sets if the sender of the message requests to be notified
191      * when the receiver is composing a reply.
192      * When the message is a notification sets if the receiver of the message is composing a 
193      * reply.
194      * 
195      * @param composing sets if the sender is requesting to be notified when composing or when 
196      * notifying that the receiver of the message is composing a reply
197      */
198     public void setComposing(boolean composing) {
199         this.composing = composing;
200         setCancelled(false);
201     }
202 
203     /**
204      * When the message is a request sets if the sender of the message requests to be notified
205      * when the message is delivered.
206      * When the message is a notification sets if the message was delivered or not.
207      * 
208      * @param delivered sets if the sender is requesting to be notified when delivered or when 
209      * notifying that the message was delivered 
210      */
211     public void setDelivered(boolean delivered) {
212         this.delivered = delivered;
213         setCancelled(false);
214     }
215 
216     /**
217      * When the message is a request sets if the sender of the message requests to be notified
218      * when the message is displayed.
219      * When the message is a notification sets if the message was displayed or not.
220      * 
221      * @param displayed sets if the sender is requesting to be notified when displayed or when 
222      * notifying that the message was displayed
223      */
224     public void setDisplayed(boolean displayed) {
225         this.displayed = displayed;
226         setCancelled(false);
227     }
228 
229     /**
230      * When the message is a request sets if the sender of the message requests to be notified
231      * when the receiver of the message is offline.
232      * When the message is a notification sets if the receiver of the message was offline.
233      * 
234      * @param offline sets if the sender is requesting to be notified when offline or when 
235      * notifying that the receiver of the message is offline
236      */
237     public void setOffline(boolean offline) {
238         this.offline = offline;
239         setCancelled(false);
240     }
241 
242     /**
243      * When the message is a notification sets if the receiver of the message cancelled 
244      * composing a reply.
245      * The Cancelled event is never requested explicitly. It is requested implicitly when
246      * requesting to be notified of the Composing event.
247      * 
248      * @param cancelled sets if the receiver of the message cancelled composing a reply
249      */
250     public void setCancelled(boolean cancelled) {
251         this.cancelled = cancelled;
252     }
253 
254     /**
255      * Sets the unique ID of the message that requested to be notified of the event.
256      * The packet id is not used when the message is a request for notifications
257      *
258      * @param packetID the message id that requested to be notified of the event.
259      */
260     public void setPacketID(String   packetID) {
261         this.packetID = packetID;
262     }
263 
264     /**
265      * Returns true if this MessageEvent is a request for notifications.
266      * Returns false if this MessageEvent is a notification of an event.
267      *
268     * @return true if this message is a request for notifications.
269      */
270     public boolean isMessageEventRequest() {
271         return this.packetID == null;
272     }
273 
274     /**
275      * Returns the XML representation of a Message Event according the specification.
276      * 
277      * Usually the XML representation will be inside of a Message XML representation like
278      * in the following examples:<p>
279      * 
280      * Request to be notified when displayed:
281      * <pre>
282      * &lt;message
283      *    to='romeo@montague.net/orchard'
284      *    from='juliet@capulet.com/balcony'
285      *    id='message22'&gt;
286      * &lt;x xmlns='jabber:x:event'&gt;
287      *   &lt;displayed/&gt;
288      * &lt;/x&gt;
289      * &lt;/message&gt;
290      * </pre>
291      * 
292      * Notification of displayed:
293      * <pre>
294      * &lt;message
295      *    from='romeo@montague.net/orchard'
296      *    to='juliet@capulet.com/balcony'&gt;
297      * &lt;x xmlns='jabber:x:event'&gt;
298      *   &lt;displayed/&gt;
299      *   &lt;id&gt;message22&lt;/id&gt;
300      * &lt;/x&gt;
301      * &lt;/message&gt;
302      * </pre>
303      * 
304      */
305     public String   toXML() {
306         StringBuffer   buf = new StringBuffer  ();
307         buf.append("<").append(getElementName()).append(" xmlns=\"").append(getNamespace()).append(
308             "\">");
309         // Note: Cancellation events don't specify any tag. They just send the packetID
310 
311         // Add the offline tag if the sender requests to be notified of offline events or if 
312         // the target is offline
313         if (isOffline())
314             buf.append("<").append(MessageEvent.OFFLINE).append("/>");
315         // Add the delivered tag if the sender requests to be notified when the message is 
316         // delivered or if the target notifies that the message has been delivered
317         if (isDelivered())
318             buf.append("<").append(MessageEvent.DELIVERED).append("/>");
319         // Add the displayed tag if the sender requests to be notified when the message is 
320         // displayed or if the target notifies that the message has been displayed
321         if (isDisplayed())
322             buf.append("<").append(MessageEvent.DISPLAYED).append("/>");
323         // Add the composing tag if the sender requests to be notified when the target is 
324         // composing a reply or if the target notifies that he/she is composing a reply
325         if (isComposing())
326             buf.append("<").append(MessageEvent.COMPOSING).append("/>");
327         // Add the id tag only if the MessageEvent is a notification message (not a request)
328         if (getPacketID() != null)
329             buf.append("<id>").append(getPacketID()).append("</id>");
330         buf.append("</").append(getElementName()).append(">");
331         return buf.toString();
332     }
333 
334 }
335
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags