Message


1   /**
2    * $RCSfile: Message.java,v $
3    * $Revision: 1.14 $
4    * $Date: 2005/03/10 22:35:03 $
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   * Message packet.<p>
29   *
30   * A message can have one of several {@link Type Types}. For each message type,
31   * different message fields are typically used as follows:
32   *
33   * <p>
34   * <table border="1">
35   * <tr><td>&nbsp;</td><td colspan="5"><b>Message type</b></td></tr>
36   * <tr><td><i>Field</i></td><td><b>Normal</b></td><td><b>Chat</b></td><td><b>Group Chat</b></td><td><b>Headline</b></td><td><b>Error</b></td></tr>
37   * <tr><td><i>subject</i></td> <td>SHOULD</td><td>SHOULD NOT</td><td>SHOULD NOT</td><td>SHOULD NOT</td><td>SHOULD NOT</td></tr>
38   * <tr><td><i>thread</i></td>  <td>OPTIONAL</td><td>SHOULD</td><td>OPTIONAL</td><td>OPTIONAL</td><td>SHOULD NOT</td></tr>
39   * <tr><td><i>body</i></td>    <td>SHOULD</td><td>SHOULD</td><td>SHOULD</td><td>SHOULD</td><td>SHOULD NOT</td></tr>
40   * <tr><td><i>error</i></td>   <td>MUST NOT</td><td>MUST NOT</td><td>MUST NOT</td><td>MUST NOT</td><td>MUST</td></tr>
41   * </table>
42   */
43  public class Message extends Packet {
44  
45      /**
46       * Constructs a new Message.
47       */
48      public Message() {
49          this.element = docFactory.createDocument().addElement("message");
50      }
51  
52       /**
53       * Constructs a new Message using an existing Element. This is useful
54       * for parsing incoming message Elements into Message objects.
55       *
56       * @param element the message Element.
57       */
58      public Message(Element element) {
59          super(element);
60      }
61  
62      /**
63       * Constructs a new Message that is a copy of an existing Message.
64       *
65       * @param message the message packet.
66       * @see #createCopy()
67       */
68      private Message(Message message) {
69          Element elementCopy = message.element.createCopy();
70          docFactory.createDocument().add(elementCopy);
71          this.element = elementCopy;
72      }
73  
74      /**
75       * Returns the type of this message
76       *
77       * @return the message type.
78       * @see Type
79       */
80      public Type getType() {
81          String   type = element.attributeValue("type");
82          if (type != null) {
83              return Type.valueOf(type);
84          }
85          else {
86              return Type.normal;
87          }
88      }
89  
90      /**
91       * Sets the type of this message.
92       *
93       * @param type the message type.
94       * @see Type
95       */
96      public void setType(Type type) {
97          element.addAttribute("type", type==null?null:type.toString());
98      }
99  
100     /**
101      * Returns the subject of this message or <tt>null</tt> if there is no subject..
102      *
103      * @return the subject.
104      */
105     public String   getSubject() {
106         return element.elementText("subject");
107     }
108 
109     /**
110      * Sets the subject of this message.
111      *
112      * @param subject the subject.
113      */
114     public void setSubject(String   subject) {
115         Element subjectElement = element.element("subject");
116         // If subject is null, clear the subject.
117         if (subject == null && subjectElement != null) {
118             element.remove(subjectElement);
119             return;
120         }
121         // Do nothing if the new subject is null
122         if (subject == null) {
123             return;
124         }
125         if (subjectElement == null) {
126             subjectElement = element.addElement("subject");
127         }
128         subjectElement.setText(subject);
129     }
130 
131     /**
132      * Returns the body of this message or <tt>null</tt> if there is no body.
133      *
134      * @return the body.
135      */
136     public String   getBody() {
137         return element.elementText("body");
138     }
139 
140     /**
141      * Sets the body of this message.
142      *
143      * @param body the body.
144      */
145     public void setBody(String   body) {
146         Element bodyElement = element.element("body");
147         // If body is null, clear the body.
148         if (body == null) {
149             if (bodyElement != null) {
150                 element.remove(bodyElement);
151             }
152             return;
153         }
154         // Do nothing if the new body is null
155         if (body == null) {
156             return;
157         }
158         if (bodyElement == null) {
159             bodyElement = element.addElement("body");
160         }
161         bodyElement.setText(body);
162     }
163 
164     /**
165      * Returns the thread value of this message, an identifier that is used for
166      * tracking a conversation thread ("instant messaging session")
167      * between two entities. If the thread is not set, <tt>null</tt> will be
168      * returned.
169      *
170      * @return the thread value.
171      */
172     public String   getThread() {
173         return element.elementText("thread");
174     }
175 
176     /**
177      * Sets the thread value of this message, an identifier that is used for
178      * tracking a conversation thread ("instant messaging session")
179      * between two entities.
180      *
181      * @param thread thread value.
182      */
183     public void setThread(String   thread) {
184         Element threadElement = element.element("thread");
185         // If thread is null, clear the thread.
186         if (thread == null) {
187             if (threadElement != null) {
188                 element.remove(threadElement);
189             }
190             return;
191         }
192 
193         if (threadElement == null) {
194             threadElement = element.addElement("thread");
195         }
196         threadElement.setText(thread);
197     }
198 
199     /**
200      * Returns the first child element of this packet that matches the
201      * given name and namespace. If no matching element is found,
202      * <tt>null</tt> will be returned. This is a convenience method to avoid
203      * manipulating this underlying packet's Element instance directly.<p>
204      *
205      * Child elements in extended namespaces are used to extend the features
206      * of XMPP. Examples include a "user is typing" indicator and invitations to
207      * group chat rooms. Although any valid XML can be included in a child element
208      * in an extended namespace, many common features have been standardized
209      * as <a HREF="http://www.jabber.org/jeps">Jabber Enhancement Proposals</a>
210      * (JEPs).
211      *
212      * @param name the element name.
213      * @param namespace the element namespace.
214      * @return the first matching child element, or <tt>null</tt> if there
215      *      is no matching child element.
216      */
217     public Element getChildElement(String   name, String   namespace) {
218         for (Iterator   i=element.elementIterator(name); i.hasNext(); ) {
219             Element element = (Element)i.next();
220             if (element.getNamespaceURI().equals(namespace)) {
221                 return element;
222             }
223         }
224         return null;
225     }
226 
227     /**
228      * Adds a new child element to this packet with the given name and
229      * namespace. The newly created Element is returned. This is a
230      * convenience method to avoid manipulating this underlying packet's
231      * Element instance directly.<p>
232      *
233      * Child elements in extended namespaces are used to extend the features
234      * of XMPP. Examples include a "user is typing" indicator and invitations to
235      * group chat rooms. Although any valid XML can be included in a child element
236      * in an extended namespace, many common features have been standardized
237      * as <a HREF="http://www.jabber.org/jeps">Jabber Enhancement Proposals</a>
238      * (JEPs).
239      *
240      * @param name the element name.
241      * @param namespace the element namespace.
242      * @return the newly created child element.
243      */
244     public Element addChildElement(String   name, String   namespace) {
245         return element.addElement(name, namespace);
246     }
247 
248     /**
249      * Returns a deep copy of this Message.
250      *
251      * @return a deep copy of this Message.
252      */
253     public Message createCopy() {
254         return new Message(this);
255     }
256 
257     /**
258      * Type-safe enumeration for the type of a message. The types are:
259      *
260      *  <ul>
261      *      <li>{@link #normal Message.Type.normal} -- (Default) a normal text message
262      *          used in email like interface.
263      *      <li>{@link #chat Message.Type.cha}t -- a typically short text message used
264      *          in line-by-line chat interfaces.
265      *      <li>{@link #groupchat Message.Type.groupchat} -- a chat message sent to a
266      *          groupchat server for group chats.
267      *      <li>{@link #headline Message.Type.headline} -- a text message to be displayed
268      *          in scrolling marquee displays.
269      *      <li>{@link #error Message.Type.error} -- indicates a messaging error.
270      * </ul>
271      */
272     public enum Type {
273 
274         /**
275          * (Default) a normal text message used in email like interface.
276          */
277         normal,
278 
279         /**
280          * Typically short text message used in line-by-line chat interfaces.
281          */
282         chat,
283 
284         /**
285          * Chat message sent to a groupchat server for group chats.
286          */
287         groupchat,
288 
289         /**
290          * Text message to be displayed in scrolling marquee displays.
291          */
292         headline,
293 
294         /**
295          * Indicates a messaging error.
296          */
297         error;
298     }
299 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags