Package rocks.xmpp.core.stanza.model

Class Message

java.lang.Object

rocks.xmpp.core.stanza.model.Stanza

rocks.xmpp.core.stanza.model.ExtensibleStanza

rocks.xmpp.core.stanza.model.Message

All Implemented Interfaces:

LanguageElement, StreamElement

Direct Known Subclasses:

ClientMessage, ComponentMessage, ServerMessage

public class Message
extends ExtensibleStanza

The implementation of the <message/> element.

5. Exchanging Messages

Once a client has authenticated with a server and bound a resource to an XML stream as described in [XMPP-CORE], an XMPP server will route XML stanzas to and from that client. One kind of stanza that can be exchanged is <message/> (if, that is, messaging functionality is enabled on the server). Exchanging messages is a basic use of XMPP and occurs when a user generates a message stanza that is addressed to another entity. As defined under Section 8, the sender's server is responsible for delivering the message to the intended recipient (if the recipient is on the same local server) or for routing the message to the recipient's server (if the recipient is on a remote server). Thus a message stanza is used to "push" information to another entity.

This class is thread-safe.

See Also:

5.2. Message Syntax

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Message.Type	Represents a <message/> 'type' attribute.

Constructor Summary

Constructors

Constructor	Description
Message()
Message(Jid to)	Constructs an empty message.
Message(Jid to, Message.Type type)	Constructs a message with a type.
Message(Jid to, Message.Type type, String body)	Constructs a message with body and type.
Message(Jid to, Message.Type type, String body, String subject)	Constructs a message with body and type.
Message(Jid to, Message.Type type, String body, String subject, String thread)	Constructs a message with body and type.
Message(Jid to, Message.Type type, String body, String subject, String thread, String parentThread, String id, Jid from, Locale language, Collection<?> extensions, StanzaError error)	Constructs a message with body and type.
Message(Jid to, Message.Type type, Collection<Text> bodies, Collection<Text> subjects, String thread, String parentThread, String id, Jid from, Locale language, Collection<?> extensions, StanzaError error)	Constructs a message with all possible values.

Method Summary

Modifier and Type	Method	Description
Message	createError(Condition condition)	Creates an error response for this stanza.
Message	createError(StanzaError error)	Creates an error response for this stanza.
List<Text>	getBodies()	Gets the bodies.
String	getBody()	Gets the default body (which has no language attribute).
String	getParentThread()	Gets the parent thread.
String	getSubject()	Gets the default subject (which has no language attribute).
List<Text>	getSubjects()	Gets the subjects.
String	getThread()	Gets the thread.
Message.Type	getType()	Gets the message type.
boolean	isNormal()	Indicates, whether this message is a normal message, i.e. if the type or the message is either Message.Type.NORMAL, null or otherwise unknown, this method returns true.
void	setBody(String body)	Sets the default body element.
void	setParentThread(String parent)	Sets the parent thread.
void	setSubject(String subject)	Sets the default subject.
void	setThread(String thread)	Sets the thread.
void	setType(Message.Type type)	Sets the message type.
String	toString()

Methods inherited from class rocks.xmpp.core.stanza.model.ExtensibleStanza

addExtension, addExtensions, addExtensions, getExtensions, getExtensions, putExtension, removeExtension

Methods inherited from class rocks.xmpp.core.stanza.model.Stanza

getError, getExtension, getFrom, getId, getLanguage, getTo, hasExtension, isToItselfOrServer, setError, setFrom, setId, setLanguage, setTo

Methods inherited from class java.lang.Object

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

Constructor Detail

Message

public Message()

Message

public Message(Jid to)

Constructs an empty message.

Parameters:

to - The recipient.

Message

public Message(Jid to,
               Message.Type type)

Constructs a message with a type.

Parameters:

to - The recipient.

type - The message type.

Message

public Message(Jid to,
               Message.Type type,
               String body)

Constructs a message with body and type.

Parameters:

to - The recipient.

body - The message body.

type - The message type.

Message

public Message(Jid to,
               Message.Type type,
               String body,
               String subject)

Constructs a message with body and type.

Parameters:

to - The recipient.

body - The message body.

type - The message type.

subject - The subject.

Message

public Message(Jid to,
               Message.Type type,
               String body,
               String subject,
               String thread)

Constructs a message with body and type.

Parameters:

to - The recipient.

body - The message body.

type - The message type.

subject - The subject.

thread - The thread.

Message

public Message(Jid to,
               Message.Type type,
               String body,
               String subject,
               String thread,
               String parentThread,
               String id,
               Jid from,
               Locale language,
               Collection<?> extensions,
               StanzaError error)

Constructs a message with body and type.

Parameters:

to - The recipient.

body - The message body.

type - The message type.

subject - The subject.

thread - The thread.

parentThread - The parent thread.

from - The sender.

id - The id.

language - The language.

extensions - The extensions.

error - The error.

Message

public Message(Jid to,
               Message.Type type,
               Collection<Text> bodies,
               Collection<Text> subjects,
               String thread,
               String parentThread,
               String id,
               Jid from,
               Locale language,
               Collection<?> extensions,
               StanzaError error)

Constructs a message with all possible values.

Parameters:

to - The recipient.

bodies - The message bodies.

type - The message type.

subjects - The subjects.

thread - The thread.

parentThread - The parent thread.

from - The sender.

id - The id.

language - The language.

extensions - The extensions.

error - The error.

Method Detail

getBodies

public final List<Text> getBodies()

Gets the bodies.

5.2.3. Body Element

The <body/> element contains human-readable XML character data that specifies the textual contents of the message; this child element is normally included but is OPTIONAL.

There are no attributes defined for the <body/> element, with the exception of the 'xml:lang' attribute. Multiple instances of the <body/> element MAY be included in a message stanza for the purpose of providing alternate versions of the same body, but only if each instance possesses an 'xml:lang' attribute with a distinct language value.

Returns:

The list of bodies.

See Also:

getBody()

getBody

public final String getBody()

Gets the default body (which has no language attribute).

5.2.3. Body Element

The <body/> element contains human-readable XML character data that specifies the textual contents of the message; this child element is normally included but is OPTIONAL.

If there's no default body, but only bodies with a language attribute, the first body is returned.

If there are no bodies at all, null is returned.

Returns:

The body or null.

See Also:

getBodies()

setBody

public final void setBody(String body)

Sets the default body element.

Parameters:

body - The body text.

See Also:

getBody()

getSubjects

public final List<Text> getSubjects()

Gets the subjects.

5.2.4. Subject Element

The <subject/> element contains human-readable XML character data that specifies the topic of the message.

There are no attributes defined for the <subject/> element, with the exception of the 'xml:lang' attribute inherited from [XML]. Multiple instances of the <subject/> element MAY be included for the purpose of providing alternate versions of the same subject, but only if each instance possesses an 'xml:lang' attribute with a distinct language value.

Returns:

The list of subjects.

See Also:

getSubject()

getSubject

public final String getSubject()

Gets the default subject (which has no language attribute).

5.2.4. Subject Element

The <subject/> element contains human-readable XML character data that specifies the topic of the message.

If there's no default subject, but only subjects with a language attribute, the first subject is returned.

If there are no subjects at all, null is returned.

Returns:

The subject or null.

See Also:

getSubjects()

setSubject

public final void setSubject(String subject)

Sets the default subject.

Parameters:

subject - The subject text.

See Also:

getSubject()

getType

public final Message.Type getType()

Gets the message type. This may also return null. If you want to check for a 'normal' message, you should prefer isNormal().

5.2.2. Type Attribute

Common uses of the message stanza in instant messaging applications include: single messages; messages sent in the context of a one-to-one chat session; messages sent in the context of a multi-user chat room; alerts, notifications, or other information to which no reply is expected; and errors. These uses are differentiated via the 'type' attribute.

Returns:

The message type.

See Also:

isNormal()

setType

public final void setType(Message.Type type)

Sets the message type.

Parameters:

type - The message type.

See Also:

getType()

isNormal

public final boolean isNormal()

Indicates, whether this message is a normal message, i.e. if the type or the message is either Message.Type.NORMAL, null or otherwise unknown, this method returns true.

5.2.2. Type Attribute

If an application receives a message with no 'type' attribute or the application does not understand the value of the 'type' attribute provided, it MUST consider the message to be of type "normal" (i.e., "normal" is the default).

Returns:

True, if this message's type is normal or unspecified.

See Also:

getType()

getThread

public final String getThread()

Gets the thread.

5.2.5. Thread Element

The primary use of the XMPP <thread/> element is to uniquely identify a conversation thread or "chat session" between two entities instantiated by <message/> stanzas of type 'chat'. However, the XMPP <thread/> element MAY also be used to uniquely identify an analogous thread between two entities instantiated by <message/> stanzas of type 'headline' or 'normal', or among multiple entities in the context of a multi-user chat room instantiated by <message/> stanzas of type 'groupchat'. It MAY also be used for <message/> stanzas not related to a human conversation, such as a game session or an interaction between plugins. The <thread/> element is not used to identify individual messages, only conversations or messaging sessions.

Returns:

The thread.

setThread

public final void setThread(String thread)

Sets the thread.

Parameters:

thread - The thread.

See Also:

getThread()

getParentThread

public final String getParentThread()

Gets the parent thread.

5.2.5. Thread Element

The <thread/> element MAY possess a 'parent' attribute that identifies another thread of which the current thread is an offshoot or child. The 'parent' attribute MUST conform to the syntax of the <thread/> element itself and its value MUST be different from the XML character data of the <thread/> element on which the 'parent' attribute is included.

Returns:

The parent thread.

setParentThread

public final void setParentThread(String parent)

Sets the parent thread.

Parameters:

parent - The parent thread.

See Also:

getParentThread()

createError

public final Message createError(StanzaError error)

Description copied from class: Stanza

Creates an error response for this stanza.

Specified by:

createError in class Stanza

Parameters:

error - The error which is appended to the stanza.

Returns:

The error response.

See Also:

Stanza.getError()

createError

public final Message createError(Condition condition)

Description copied from class: Stanza

Creates an error response for this stanza.

Specified by:

createError in class Stanza

Parameters:

condition - The error condition which is appended to the stanza.

Returns:

The error response.

See Also:

Stanza.getError()

toString

public final String toString()

Overrides:

toString in class Stanza