org.jivesoftware.smackx.packet
Class MessageEvent

java.lang.Object
  org.jivesoftware.smackx.packet.MessageEvent

All Implemented Interfaces:

PacketExtension

public class MessageEvent
extends Object
implements PacketExtension

Represents message events relating to the delivery, display, composition and cancellation of messages.

There are four message events currently defined in this namespace:

1. Offline
   Indicates that the message has been stored offline by the intended recipient's server. This event is triggered only if the intended recipient's server supports offline storage, has that support enabled, and the recipient is offline when the server receives the message for delivery.
2. Delivered
   Indicates that the message has been delivered to the recipient. This signifies that the message has reached the recipient's XMPP client, but does not necessarily mean that the message has been displayed. This event is to be raised by the XMPP client.
3. Displayed
   Once the message has been received by the recipient's XMPP client, it may be displayed to the user. This event indicates that the message has been displayed, and is to be raised by the XMPP client. Even if a message is displayed multiple times, this event should be raised only once.
4. Composing
   In threaded chat conversations, this indicates that the recipient is composing a reply to a message. The event is to be raised by the recipient's XMPP client. A XMPP client is allowed to raise this event multiple times in response to the same request, providing the original event is cancelled first.

Author:

Gaston Dombiak

Field Summary

static String	CANCELLED
static String	COMPOSING
static String	DELIVERED
static String	DISPLAYED
static String	OFFLINE

Constructor Summary

MessageEvent()

Method Summary

String	getElementName() Returns the XML element name of the extension sub-packet root element.
Iterator	getEventTypes() Returns the types of events.
String	getNamespace() Returns the XML namespace of the extension sub-packet root element.
String	getPacketID() Returns the unique ID of the message that requested to be notified of the event.
boolean	isCancelled() When the message is a notification returns if the receiver of the message cancelled composing a reply.
boolean	isComposing() When the message is a request returns if the sender of the message requests to be notified when the receiver is composing a reply.
boolean	isDelivered() When the message is a request returns if the sender of the message requests to be notified when the message is delivered.
boolean	isDisplayed() When the message is a request returns if the sender of the message requests to be notified when the message is displayed.
boolean	isMessageEventRequest() Returns true if this MessageEvent is a request for notifications.
boolean	isOffline() When the message is a request returns if the sender of the message requests to be notified when the receiver of the message is offline.
void	setCancelled(boolean cancelled) When the message is a notification sets if the receiver of the message cancelled composing a reply.
void	setComposing(boolean composing) When the message is a request sets if the sender of the message requests to be notified when the receiver is composing a reply.
void	setDelivered(boolean delivered) When the message is a request sets if the sender of the message requests to be notified when the message is delivered.
void	setDisplayed(boolean displayed) When the message is a request sets if the sender of the message requests to be notified when the message is displayed.
void	setOffline(boolean offline) When the message is a request sets if the sender of the message requests to be notified when the receiver of the message is offline.
void	setPacketID(String packetID) Sets the unique ID of the message that requested to be notified of the event.
String	toXML() Returns the XML representation of a Message Event according the specification.

Methods inherited from class java.lang.Object

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

Field Detail

OFFLINE

public static final String OFFLINE

See Also:

Constant Field Values

COMPOSING

public static final String COMPOSING

See Also:

Constant Field Values

DISPLAYED

public static final String DISPLAYED

See Also:

Constant Field Values

DELIVERED

public static final String DELIVERED

See Also:

Constant Field Values

CANCELLED

public static final String CANCELLED

See Also:

Constant Field Values

Constructor Detail

MessageEvent

public MessageEvent()

Method Detail

getElementName

public String getElementName()

Returns the XML element name of the extension sub-packet root element. Always returns "x"

Specified by:

getElementName in interface PacketExtension

Returns:

the XML element name of the packet extension.

getNamespace

public String getNamespace()

Returns the XML namespace of the extension sub-packet root element. According the specification the namespace is always "jabber:x:event"

Specified by:

getNamespace in interface PacketExtension

Returns:

the XML namespace of the packet extension.

isComposing

public boolean isComposing()

When the message is a request returns if the sender of the message requests to be notified when the receiver is composing a reply. When the message is a notification returns if the receiver of the message is composing a reply.

Returns:

true if the sender is requesting to be notified when composing or when notifying that the receiver of the message is composing a reply

isDelivered

public boolean isDelivered()

When the message is a request returns if the sender of the message requests to be notified when the message is delivered. When the message is a notification returns if the message was delivered or not.

Returns:

true if the sender is requesting to be notified when delivered or when notifying that the message was delivered

isDisplayed

public boolean isDisplayed()

When the message is a request returns if the sender of the message requests to be notified when the message is displayed. When the message is a notification returns if the message was displayed or not.

Returns:

true if the sender is requesting to be notified when displayed or when notifying that the message was displayed

isOffline

public boolean isOffline()

When the message is a request returns if the sender of the message requests to be notified when the receiver of the message is offline. When the message is a notification returns if the receiver of the message was offline.

Returns:

true if the sender is requesting to be notified when offline or when notifying that the receiver of the message is offline

isCancelled

public boolean isCancelled()

When the message is a notification returns if the receiver of the message cancelled composing a reply.

Returns:

true if the receiver of the message cancelled composing a reply

getPacketID

public String getPacketID()

Returns the unique ID of the message that requested to be notified of the event. The packet id is not used when the message is a request for notifications

Returns:

the message id that requested to be notified of the event.

getEventTypes

public Iterator getEventTypes()

Returns the types of events. The type of event could be: "offline", "composing","delivered","displayed", "offline"

Returns:

an iterator over all the types of events of the MessageEvent.

setComposing

public void setComposing(boolean composing)

When the message is a request sets if the sender of the message requests to be notified when the receiver is composing a reply. When the message is a notification sets if the receiver of the message is composing a reply.

Parameters:

composing - sets if the sender is requesting to be notified when composing or when notifying that the receiver of the message is composing a reply

setDelivered

public void setDelivered(boolean delivered)

When the message is a request sets if the sender of the message requests to be notified when the message is delivered. When the message is a notification sets if the message was delivered or not.

Parameters:

delivered - sets if the sender is requesting to be notified when delivered or when notifying that the message was delivered

setDisplayed

public void setDisplayed(boolean displayed)

When the message is a request sets if the sender of the message requests to be notified when the message is displayed. When the message is a notification sets if the message was displayed or not.

Parameters:

displayed - sets if the sender is requesting to be notified when displayed or when notifying that the message was displayed

setOffline

public void setOffline(boolean offline)

When the message is a request sets if the sender of the message requests to be notified when the receiver of the message is offline. When the message is a notification sets if the receiver of the message was offline.

Parameters:

offline - sets if the sender is requesting to be notified when offline or when notifying that the receiver of the message is offline

setCancelled

public void setCancelled(boolean cancelled)

When the message is a notification sets if the receiver of the message cancelled composing a reply. The Cancelled event is never requested explicitly. It is requested implicitly when requesting to be notified of the Composing event.

Parameters:

cancelled - sets if the receiver of the message cancelled composing a reply

setPacketID

public void setPacketID(String packetID)

Sets the unique ID of the message that requested to be notified of the event. The packet id is not used when the message is a request for notifications

Parameters:

packetID - the message id that requested to be notified of the event.

isMessageEventRequest

public boolean isMessageEventRequest()

Returns true if this MessageEvent is a request for notifications. Returns false if this MessageEvent is a notification of an event.

Returns:

true if this message is a request for notifications.

toXML

public String toXML()

Returns the XML representation of a Message Event according the specification. Usually the XML representation will be inside of a Message XML representation like in the following examples:

Request to be notified when displayed:

 <message
    to='romeo@montague.net/orchard'
    from='juliet@capulet.com/balcony'
    id='message22'>
 <x xmlns='jabber:x:event'>
   <displayed/>
 </x>
 </message>
 

Notification of displayed:

 <message
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'>
 <x xmlns='jabber:x:event'>
   <displayed/>
   <id>message22</id>
 </x>
 </message>
 

Specified by:

toXML in interface PacketExtension

Returns:

the packet extension as XML.