/**
* $RCSfile$
* $Revision: 6565 $
* $Date: 2007-01-04 16:25:02 -0800 (Thu, 04 Jan 2007) $
*
* Copyright 2004 Jive Software.
*
* All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.xmpp.packet;
import org.dom4j.Element;
import java.util.Iterator;
/**
* Message packet.<p>
*
* A message can have one of several {@link Type Types}. For each message type,
* different message fields are typically used as follows:
*
* <p>
* <table border="1">
* <tr><td> </td><td colspan="5"><b>Message type</b></td></tr>
* <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>
* <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>
* <tr><td><i>thread</i></td> <td>OPTIONAL</td><td>SHOULD</td><td>OPTIONAL</td><td>OPTIONAL</td><td>SHOULD NOT</td></tr>
* <tr><td><i>body</i></td> <td>SHOULD</td><td>SHOULD</td><td>SHOULD</td><td>SHOULD</td><td>SHOULD NOT</td></tr>
* <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>
* </table>
*/
public class Message extends Packet {
/**
* Constructs a new Message.
*/
public Message() {
this.element = docFactory.createDocument().addElement("message");
}
/**
* Constructs a new Message using an existing Element. This is useful
* for parsing incoming message Elements into Message objects.
*
* @param element the message Element.
*/
public Message(Element element) {
super(element);
}
/**
* Constructs a new Message using an existing Element. This is useful
* for parsing incoming message Elements into Message objects. Stringprep validation
* on the TO address can be disabled. The FROM address will not be validated since the
* server is the one that sets that value.
*
* @param element the message Element.
* @param skipValidation true if stringprep should not be applied to the TO address.
*/
public Message(Element element, boolean skipValidation) {
super(element, skipValidation);
}
/**
* Constructs a new Message that is a copy of an existing Message.
*
* @param message the message packet.
* @see #createCopy()
*/
private Message(Message message) {
Element elementCopy = message.element.createCopy();
docFactory.createDocument().add(elementCopy);
this.element = elementCopy;
// Copy cached JIDs (for performance reasons)
this.toJID = message.toJID;
this.fromJID = message.fromJID;
}
/**
* Returns the type of this message
*
* @return the message type.
* @see Type
*/
public Type getType() {
String type = element.attributeValue("type");
if (type != null) {
return Type.valueOf(type);
}
else {
return Type.normal;
}
}
/**
* Sets the type of this message.
*
* @param type the message type.
* @see Type
*/
public void setType(Type type) {
element.addAttribute("type", type==null?null:type.toString());
}
/**
* Returns the subject of this message or <tt>null</tt> if there is no subject..
*
* @return the subject.
*/
public String getSubject() {
return element.elementText("subject");
}
/**
* Sets the subject of this message.
*
* @param subject the subject.
*/
public void setSubject(String subject) {
Element subjectElement = element.element("subject");
// If subject is null, clear the subject.
if (subject == null && subjectElement != null) {
element.remove(subjectElement);
return;
}
// Do nothing if the new subject is null
if (subject == null) {
return;
}
if (subjectElement == null) {
subjectElement = element.addElement("subject");
}
subjectElement.setText(subject);
}
/**
* Returns the body of this message or <tt>null</tt> if there is no body.
*
* @return the body.
*/
public String getBody() {
return element.elementText("body");
}
/**
* Sets the body of this message.
*
* @param body the body.
*/
public void setBody(String body) {
Element bodyElement = element.element("body");
// If body is null, clear the body.
if (body == null) {
if (bodyElement != null) {
element.remove(bodyElement);
}
return;
}
// Do nothing if the new body is null
if (body == null) {
return;
}
if (bodyElement == null) {
bodyElement = element.addElement("body");
}
bodyElement.setText(body);
}
/**
* Returns the thread value of this message, an identifier that is used for
* tracking a conversation thread ("instant messaging session")
* between two entities. If the thread is not set, <tt>null</tt> will be
* returned.
*
* @return the thread value.
*/
public String getThread() {
return element.elementText("thread");
}
/**
* Sets the thread value of this message, an identifier that is used for
* tracking a conversation thread ("instant messaging session")
* between two entities.
*
* @param thread thread value.
*/
public void setThread(String thread) {
Element threadElement = element.element("thread");
// If thread is null, clear the thread.
if (thread == null) {
if (threadElement != null) {
element.remove(threadElement);
}
return;
}
if (threadElement == null) {
threadElement = element.addElement("thread");
}
threadElement.setText(thread);
}
/**
* Returns the first child element of this packet that matches the
* given name and namespace. If no matching element is found,
* <tt>null</tt> will be returned. This is a convenience method to avoid
* manipulating this underlying packet's Element instance directly.<p>
*
* Child elements in extended namespaces are used to extend the features
* of XMPP. Examples include a "user is typing" indicator and invitations to
* group chat rooms. Although any valid XML can be included in a child element
* in an extended namespace, many common features have been standardized
* as <a href="http://www.jabber.org/jeps">Jabber Enhancement Proposals</a>
* (JEPs).
*
* @param name the element name.
* @param namespace the element namespace.
* @return the first matching child element, or <tt>null</tt> if there
* is no matching child element.
*/
public Element getChildElement(String name, String namespace) {
for (Iterator i=element.elementIterator(name); i.hasNext(); ) {
Element element = (Element)i.next();
if (element.getNamespaceURI().equals(namespace)) {
return element;
}
}
return null;
}
/**
* Adds a new child element to this packet with the given name and
* namespace. The newly created Element is returned. This is a
* convenience method to avoid manipulating this underlying packet's
* Element instance directly.<p>
*
* Child elements in extended namespaces are used to extend the features
* of XMPP. Examples include a "user is typing" indicator and invitations to
* group chat rooms. Although any valid XML can be included in a child element
* in an extended namespace, many common features have been standardized
* as <a href="http://www.jabber.org/jeps">Jabber Enhancement Proposals</a>
* (JEPs).
*
* @param name the element name.
* @param namespace the element namespace.
* @return the newly created child element.
*/
public Element addChildElement(String name, String namespace) {
return element.addElement(name, namespace);
}
/**
* Returns a deep copy of this Message.
*
* @return a deep copy of this Message.
*/
public Message createCopy() {
return new Message(this);
}
/**
* Type-safe enumeration for the type of a message. The types are:
*
* <ul>
* <li>{@link #normal Message.Type.normal} -- (Default) a normal text message
* used in email like interface.
* <li>{@link #chat Message.Type.cha}t -- a typically short text message used
* in line-by-line chat interfaces.
* <li>{@link #groupchat Message.Type.groupchat} -- a chat message sent to a
* groupchat server for group chats.
* <li>{@link #headline Message.Type.headline} -- a text message to be displayed
* in scrolling marquee displays.
* <li>{@link #error Message.Type.error} -- indicates a messaging error.
* </ul>
*/
public enum Type {
/**
* (Default) a normal text message used in email like interface.
*/
normal,
/**
* Typically short text message used in line-by-line chat interfaces.
*/
chat,
/**
* Chat message sent to a groupchat server for group chats.
*/
groupchat,
/**
* Text message to be displayed in scrolling marquee displays.
*/
headline,
/**
* Indicates a messaging error.
*/
error;
}
}