com.echomine.jabber.msg
Class EventXMessage

java.lang.Object
  extended by com.echomine.jabber.JabberMessage
      extended by com.echomine.jabber.JabberJDOMMessage
          extended by com.echomine.jabber.msg.EventXMessage
All Implemented Interfaces:
JabberCode, JabberMessageParsable

public class EventXMessage
extends JabberJDOMMessage
implements JabberCode

This class supports the jabber:x:event namespace. It gives the ability to work with incoming events and also creating outgoing events. You add the X Message to an existing Message. The composing event is generated when the user is actively typing a reply to the message. If the user never completes/sends the reply (or after an idle timeout), an empty jabber:x:event (just contains the id element) should be sent to "clear" the outstanding composing event. It is suggested that the client first check to make sure the recipient of a composing event is also in the roster, as it may not be desireable to send such availability information to unknown contacts. The way the event works is this: First, someone submits a message telling you what kinds of events it can support (or willing to listen to) and includes a message ID. Then recipient then can start sending back events specific for that message, but must include the element inside the message that corresponds to the original message id.

Receiving Event Requests: You can retrieve sender's willingness to receive certain events by simply calling to see which event it advertised itself to see. Multiple events can be set so each event that you're interested in should be checked.

Sending Event Requests: You can send a request along with the message to indicate what events you like the remote to send. You can set multiple event types you want to listen for. Note that, if you set the message ID for the event class, the message is then considered a event reply (not a request anymore). In this case, the event will automatically be cleared because that event is generated by the server, not you.

Receiving Event Replies: you can retrieve information about event replies to your event requests just as you normally would. The only way to tell if the event is a reply and not a request is by looking to see if there is a event Message ID associated with it.

Sending Event Replies: Sending event replies is the same as sending requests, except for the fact that you need to include the original requestor's message ID inside the event to distinguish it as a reply and not a request. You should technically send one event type per event message indicating your current status (delivered, composing, displayed).

Caveats: If you happen to send a composing event reply and would like to clear out the status due to some inactivity or idle time such that the composing message was never sent, then after an idle time period, you should submit another event message that contains only the message id (but no events).

Current Implementation: JEP-0022 Version 1.1


Field Summary
static java.lang.String EVENT_COMPOSING
           
static java.lang.String EVENT_DELIVERED
           
static java.lang.String EVENT_DISPLAYED
           
static java.lang.String EVENT_OFFLINE
           
 
Fields inherited from class com.echomine.jabber.JabberMessage
messageID
 
Fields inherited from interface com.echomine.jabber.JabberCode
MSG_CHAT, MSG_INIT, MSG_IQ, MSG_IQ_AGENTS, MSG_IQ_AUTH, MSG_IQ_BROWSE, MSG_IQ_DISCO_INFO, MSG_IQ_DISCO_ITEMS, MSG_IQ_GATEWAY, MSG_IQ_LAST, MSG_IQ_OOB, MSG_IQ_PRIVATE, MSG_IQ_REGISTER, MSG_IQ_ROSTER, MSG_IQ_SEARCH, MSG_IQ_TIME, MSG_IQ_VACATION, MSG_IQ_VCARD, MSG_IQ_VERSION, MSG_IQ_XMLRPC, MSG_PRESENCE, MSG_UNKNOWN, MSG_X_DATA, MSG_X_DELAY, MSG_X_EVENT, MSG_X_EXPIRE, MSG_X_OOB, MSG_X_PGP_ENCRYPTED, MSG_X_PGP_SIGNED, MSG_X_ROSTER, PARSER_CHAT, PARSER_IQ, PARSER_IQ_AGENTS, PARSER_IQ_AUTH, PARSER_IQ_BROWSE, PARSER_IQ_DISCO_INFO, PARSER_IQ_DISCO_ITEMS, PARSER_IQ_GATEWAY, PARSER_IQ_LAST, PARSER_IQ_OOB, PARSER_IQ_PRIVATE, PARSER_IQ_REGISTER, PARSER_IQ_ROSTER, PARSER_IQ_SEARCH, PARSER_IQ_TIME, PARSER_IQ_VACATION, PARSER_IQ_VCARD, PARSER_IQ_VERSION, PARSER_IQ_XMLRPC, PARSER_PRESENCE, PARSER_X_DATA, PARSER_X_DELAY, PARSER_X_EVENT, PARSER_X_EXPIRE, PARSER_X_OOB, PARSER_X_PGP_ENCRYPTED, PARSER_X_PGP_SIGNED, PARSER_X_ROSTER, XMLNS_CHAT, XMLNS_ERROR_STANZA, XMLNS_ERROR_STREAM, XMLNS_IQ, XMLNS_IQ_AGENTS, XMLNS_IQ_AUTH, XMLNS_IQ_BROWSE, XMLNS_IQ_DISCO_INFO, XMLNS_IQ_DISCO_ITEMS, XMLNS_IQ_GATEWAY, XMLNS_IQ_LAST, XMLNS_IQ_OOB, XMLNS_IQ_PRIVATE, XMLNS_IQ_REGISTER, XMLNS_IQ_ROSTER, XMLNS_IQ_SEARCH, XMLNS_IQ_TIME, XMLNS_IQ_VACATION, XMLNS_IQ_VCARD, XMLNS_IQ_VERSION, XMLNS_IQ_XMLRPC, XMLNS_PRESENCE, XMLNS_STREAM, XMLNS_X_DATA, XMLNS_X_DELAY, XMLNS_X_EVENT, XMLNS_X_EXPIRE, XMLNS_X_OOB, XMLNS_X_PGP_ENCRYPTED, XMLNS_X_PGP_SIGNED, XMLNS_X_ROSTER
 
Constructor Summary
EventXMessage()
          constructs a default Delay message (with the x element)
 
Method Summary
 java.lang.String encode()
          overrides the parent's method to first add the stored attributes into the DOM and then call the parent's method to encode the data into a string.
 java.lang.String getEventMessageID()
          retrieves the sender's message ID associated with the event.
 int getMessageType()
          the default message type is unknown.
 boolean isAllClear()
          this method checks for you to see if all the event flags are NOT set.
 boolean isComposing()
           
 boolean isDelivered()
           
 boolean isDisplayed()
           
 boolean isOffline()
           
 JabberMessage parse(JabberMessageParser parser, Element msgTree)
          parses out the data from the message
 void reset()
          this will reset all the flags to false.
 void setComposing(boolean composing)
           
 void setDelivered(boolean delivered)
           
 void setDisplayed(boolean displayed)
           
 void setEventMessageID(java.lang.String msgID)
          sets the event message id.
 void setOffline(boolean offline)
          sets the offline flag.
 
Methods inherited from class com.echomine.jabber.JabberJDOMMessage
getDOM, getXMLOutputter, setMessageID, toString
 
Methods inherited from class com.echomine.jabber.JabberMessage
getMessageID, getReplyMessage, getTimeout, getXMessage, getXMessages, interrupt, isReplyRequired, isSendXMessages, isSynchronized, replyReceived, setReplyRequired, setSendXMessages, setSynchronized, setTimeout, setXMessage, setXMessages
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

EVENT_OFFLINE

public static final java.lang.String EVENT_OFFLINE
See Also:
Constant Field Values

EVENT_DELIVERED

public static final java.lang.String EVENT_DELIVERED
See Also:
Constant Field Values

EVENT_COMPOSING

public static final java.lang.String EVENT_COMPOSING
See Also:
Constant Field Values

EVENT_DISPLAYED

public static final java.lang.String EVENT_DISPLAYED
See Also:
Constant Field Values
Constructor Detail

EventXMessage

public EventXMessage()
constructs a default Delay message (with the x element)

Method Detail

reset

public void reset()
this will reset all the flags to false. Basically it means the message won't send any events. The message ID will also be reset.


getEventMessageID

public java.lang.String getEventMessageID()
retrieves the sender's message ID associated with the event. This is NOT the message ID of the message itself since X Messages never use those message ID's.

Returns:
the event message ID or null if none exists

setEventMessageID

public void setEventMessageID(java.lang.String msgID)
sets the event message id. By setting the event message id, the offline event will be cleared if it exists. The event message id should be the original sender's real Message ID (from the tag).


isOffline

public boolean isOffline()

isDisplayed

public boolean isDisplayed()

isComposing

public boolean isComposing()

isDelivered

public boolean isDelivered()

isAllClear

public boolean isAllClear()
this method checks for you to see if all the event flags are NOT set. This is useful when you need to find out if the message is sent to you to reset the event status (ie. clear the "composing" status when idle timeout occurs).


setOffline

public void setOffline(boolean offline)
sets the offline flag. By setting the offline to true, the message id will automatically be cleared because offline events are only sent in requests while messsage id's are sent only in replies.


setDisplayed

public void setDisplayed(boolean displayed)

setComposing

public void setComposing(boolean composing)

setDelivered

public void setDelivered(boolean delivered)

parse

public JabberMessage parse(JabberMessageParser parser,
                           Element msgTree)
                    throws ParseException
parses out the data from the message

Specified by:
parse in interface JabberMessageParsable
Overrides:
parse in class JabberJDOMMessage
Throws:
ParseException

encode

public java.lang.String encode()
                        throws ParseException
overrides the parent's method to first add the stored attributes into the DOM and then call the parent's method to encode the data into a string.

Overrides:
encode in class JabberJDOMMessage
Throws:
ParseException - if something went wrong during encoding

getMessageType

public int getMessageType()
Description copied from class: JabberJDOMMessage
the default message type is unknown. It doesn't mean that there is no type. It just means that there is no known message parser for this particular object.

Overrides:
getMessageType in class JabberJDOMMessage
Returns:
a message code that is unique to the message
See Also:
JabberCode


Copyright © 2001-2005 Echomine. All Rights Reserved.