org.jivesoftware.smack.packet

Class Message

java.lang.Object

org.jivesoftware.smack.packet.Stanza

org.jivesoftware.smack.packet.Message

All Implemented Interfaces:

java.lang.Cloneable, Element, Packet, TopLevelStreamElement, TypedCloneable<Message>

public final class Message
extends Stanza
implements TypedCloneable<Message>

Represents XMPP message packets. A message can be one of several types:

• Message.Type.NORMAL -- (Default) a normal text message used in email like interface.
• Message.Type.CHAT -- a typically short text message used in line-by-line chat interfaces.
• Message.Type.GROUP_CHAT -- a chat message sent to a groupchat server for group chats.
• Message.Type.HEADLINE -- a text message to be displayed in scrolling marquee displays.
• Message.Type.ERROR -- indicates a messaging error.

For each message type, different message fields are typically used as follows:

	Message type
Field	Normal	Chat	Group Chat	Headline	XMPPError
subject	SHOULD	SHOULD NOT	SHOULD NOT	SHOULD NOT	SHOULD NOT
thread	OPTIONAL	SHOULD	OPTIONAL	OPTIONAL	SHOULD NOT
body	SHOULD	SHOULD	SHOULD	SHOULD	SHOULD NOT
error	MUST NOT	MUST NOT	MUST NOT	MUST NOT	MUST

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Message.Body Represents a message body, its language and the content of the message.
static class	Message.Subject Represents a message subject, its language and the content of the subject.
static class	Message.Type Represents the type of a message.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BODY
static java.lang.String	ELEMENT

Fields inherited from class org.jivesoftware.smack.packet.Stanza

DEFAULT_LANGUAGE, ITEM, language, TEXT

Constructor Summary

Constructors

Constructor and Description
Message() Creates a new, "normal" message.
Message(Message other) Copy constructor.
Message(java.lang.String to) Creates a new "normal" message to the specified recipient.
Message(java.lang.String to, Message.Type type) Creates a new message of the specified type to a recipient.
Message(java.lang.String to, java.lang.String body) Creates a new message to the specified recipient and with the specified body.

Method Summary

Modifier and Type	Method and Description
Message.Body	addBody(java.lang.String language, java.lang.String body) Adds a body with a corresponding language.
Message.Subject	addSubject(java.lang.String language, java.lang.String subject) Adds a subject with a corresponding language.
Message	clone() Creates and returns a copy of this message stanza.
java.util.Set<Message.Body>	getBodies() Returns a set of all bodies in this Message, including the default message body accessible from getBody().
java.lang.String	getBody() Returns the default body of the message, or null if the body has not been set.
java.lang.String	getBody(java.lang.String language) Returns the body corresponding to the language.
java.util.List<java.lang.String>	getBodyLanguages() Returns all the languages being used for the bodies, not including the default body.
java.lang.String	getSubject() Returns the default subject of the message, or null if the subject has not been set.
java.lang.String	getSubject(java.lang.String language) Returns the subject corresponding to the language.
java.util.List<java.lang.String>	getSubjectLanguages() Returns all the languages being used for the subjects, not including the default subject.
java.util.Set<Message.Subject>	getSubjects() Returns a set of all subjects in this Message, including the default message subject accessible from getSubject().
java.lang.String	getThread() Returns the thread id of the message, which is a unique identifier for a sequence of "chat" messages.
Message.Type	getType() Returns the type of the message.
boolean	removeBody(Message.Body body) Removes the body from the message and returns true if the body was removed.
boolean	removeBody(java.lang.String language) Removes the body with the given language from the message.
boolean	removeSubject(Message.Subject subject) Removes the subject from the message and returns true if the subject was removed.
boolean	removeSubject(java.lang.String language) Removes the subject with the given language from the message.
void	setBody(java.lang.String body) Sets the body of the message.
void	setSubject(java.lang.String subject) Sets the subject of the message.
void	setThread(java.lang.String thread) Sets the thread id of the message, which is a unique identifier for a sequence of "chat" messages.
void	setType(Message.Type type) Sets the type of the message.
XmlStringBuilder	toXML() Returns the XML representation of this Element.

Methods inherited from class org.jivesoftware.smack.packet.Stanza

addCommonAttributes, addExtension, addExtensions, appendErrorIfExists, getDefaultLanguage, getError, getExtension, getExtension, getExtensions, getExtensions, getExtensionsXML, getFrom, getLanguage, getPacketID, getStanzaId, getTo, hasExtension, hasExtension, hasStanzaIdSet, overrideExtension, removeExtension, removeExtension, setError, setFrom, setLanguage, setPacketID, setStanzaId, setTo, toString

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ELEMENT

public static final java.lang.String ELEMENT

See Also:

Constant Field Values

BODY

public static final java.lang.String BODY

See Also:

Constant Field Values

Constructor Detail

Message

public Message()

Creates a new, "normal" message.

Message

public Message(java.lang.String to)

Creates a new "normal" message to the specified recipient.

Parameters:

to - the recipient of the message.

Message

public Message(java.lang.String to,
               Message.Type type)

Creates a new message of the specified type to a recipient.

Parameters:

to - the user to send the message to.

type - the message type.

Message

public Message(java.lang.String to,
               java.lang.String body)

Creates a new message to the specified recipient and with the specified body.

Parameters:

to - the user to send the message to.

body - the body of the message.

Message

public Message(Message other)

Copy constructor.

This does not perform a deep clone, as extension elements are shared between the new and old instance.

Parameters:

other -

Method Detail

getType

public Message.Type getType()

Returns the type of the message. If no type has been set this method will return Message.Type.normal.

Returns:

the type of the message.

setType

public void setType(Message.Type type)

Sets the type of the message.

Parameters:

type - the type of the message.

getSubject

public java.lang.String getSubject()

Returns the default subject of the message, or null if the subject has not been set. The subject is a short description of message contents.

The default subject of a message is the subject that corresponds to the message's language. (see Stanza.getLanguage()) or if no language is set to the applications default language (see Stanza.getDefaultLanguage()).

Returns:

the subject of the message.

getSubject

public java.lang.String getSubject(java.lang.String language)

Returns the subject corresponding to the language. If the language is null, the method result will be the same as getSubject(). Null will be returned if the language does not have a corresponding subject.

Parameters:

language - the language of the subject to return.

Returns:

the subject related to the passed in language.

getSubjects

public java.util.Set<Message.Subject> getSubjects()

Returns a set of all subjects in this Message, including the default message subject accessible from getSubject().

Returns:

a collection of all subjects in this message.

setSubject

public void setSubject(java.lang.String subject)

Sets the subject of the message. The subject is a short description of message contents.

Parameters:

subject - the subject of the message.

addSubject

public Message.Subject addSubject(java.lang.String language,
                                  java.lang.String subject)

Adds a subject with a corresponding language.

Parameters:

language - the language of the subject being added.

subject - the subject being added to the message.

Returns:

the new Message.Subject

Throws:

java.lang.NullPointerException - if the subject is null, a null pointer exception is thrown

removeSubject

public boolean removeSubject(java.lang.String language)

Removes the subject with the given language from the message.

Parameters:

language - the language of the subject which is to be removed

Returns:

true if a subject was removed and false if it was not.

removeSubject

public boolean removeSubject(Message.Subject subject)

Removes the subject from the message and returns true if the subject was removed.

Parameters:

subject - the subject being removed from the message.

Returns:

true if the subject was successfully removed and false if it was not.

getSubjectLanguages

public java.util.List<java.lang.String> getSubjectLanguages()

Returns all the languages being used for the subjects, not including the default subject.

Returns:

the languages being used for the subjects.

getBody

public java.lang.String getBody()

Returns the default body of the message, or null if the body has not been set. The body is the main message contents.

The default body of a message is the body that corresponds to the message's language. (see Stanza.getLanguage()) or if no language is set to the applications default language (see Stanza.getDefaultLanguage()).

Returns:

the body of the message.

getBody

public java.lang.String getBody(java.lang.String language)

Returns the body corresponding to the language. If the language is null, the method result will be the same as getBody(). Null will be returned if the language does not have a corresponding body.

Parameters:

language - the language of the body to return.

Returns:

the body related to the passed in language.

Since:

3.0.2

getBodies

public java.util.Set<Message.Body> getBodies()

Returns a set of all bodies in this Message, including the default message body accessible from getBody().

Returns:

a collection of all bodies in this Message.

Since:

3.0.2

setBody

public void setBody(java.lang.String body)

Sets the body of the message. The body is the main message contents.

Parameters:

body - the body of the message.

addBody

public Message.Body addBody(java.lang.String language,
                            java.lang.String body)

Adds a body with a corresponding language.

Parameters:

language - the language of the body being added.

body - the body being added to the message.

Returns:

the new Message.Body

Throws:

java.lang.NullPointerException - if the body is null, a null pointer exception is thrown

Since:

3.0.2

removeBody

public boolean removeBody(java.lang.String language)

Removes the body with the given language from the message.

Parameters:

language - the language of the body which is to be removed

Returns:

true if a body was removed and false if it was not.

removeBody

public boolean removeBody(Message.Body body)

Removes the body from the message and returns true if the body was removed.

Parameters:

body - the body being removed from the message.

Returns:

true if the body was successfully removed and false if it was not.

Since:

3.0.2

getBodyLanguages

public java.util.List<java.lang.String> getBodyLanguages()

Returns all the languages being used for the bodies, not including the default body.

Returns:

the languages being used for the bodies.

Since:

3.0.2

getThread

public java.lang.String getThread()

Returns the thread id of the message, which is a unique identifier for a sequence of "chat" messages. If no thread id is set, null will be returned.

Returns:

the thread id of the message, or null if it doesn't exist.

setThread

public void setThread(java.lang.String thread)

Sets the thread id of the message, which is a unique identifier for a sequence of "chat" messages.

Parameters:

thread - the thread id of the message.

toXML

public XmlStringBuilder toXML()

Description copied from interface: Element

Returns the XML representation of this Element.

Specified by:

toXML in interface Element

Returns:

the stanza(/packet) extension as XML.

clone

public Message clone()

Creates and returns a copy of this message stanza.

This does not perform a deep clone, as extension elements are shared between the new and old instance.

Specified by:

clone in interface TypedCloneable<Message>

Overrides:

clone in class java.lang.Object

Returns:

a clone of this message.