com.echomine.jabber.msg
Class DataXMessage

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

public class DataXMessage
extends JabberJDOMMessage

This extension adds the new form-based data submission and retrieval mechanism using the jabber:x:data namespace. The Data Gathering and Reporting interface may not be supported by all message types. As of the current implementation, the X message may be present in a chat message, a presence message, and an iq message. Certain rules are present for each type of message and requires that it conforms to the JEP standards (take a look at the JEP to know the limitations and restrictions). It is suggested that you read up on the JEP and know the details of working with this namespace before using it. Alot of the support requires developer support. The API is unable to make things easier for you in that way because of the data used in this message is for displaying results to the user.

Current implementation has a known issue. Under JEP specification, the search results/items can be sent back to the requester in multiple message chunks with the same message ID. However, in Muse's current implementation, if you set this message to listen for a reply and you send this message in a synchronized manner, the call will return upon receiving the first message result and ignore the rest of the result messages. In order to workaround this issue, you should not send this message synchronously if you are submitting a search request that will return results. Rather, you should specifically create a listener that will listen for the incoming messages and combine all the incoming result messages of the same Message ID to form your total results.

Current Implementation: JEP-0004 Version 2.1

Since:
0.8a4
See Also:
DataXField, DataXOption

Field Summary
static java.lang.String EMPTY_STRING
           
static java.lang.String TYPE_CANCEL
           
static java.lang.String TYPE_FORM
           
static java.lang.String TYPE_RESULT
           
static java.lang.String TYPE_SUBMIT
           
 
Fields inherited from class com.echomine.jabber.JabberMessage
messageID
 
Constructor Summary
DataXMessage()
          constructs a default message of type submit
DataXMessage(java.lang.String formType)
          constructs a default message of the type specified
 
Method Summary
 void addField(DataXField field)
          adds a field to the field list
 void addItemField(DataXField field)
          adds a field to the item field list
 void addReportedField(DataXField field)
          adds a field to the reported field list
 java.lang.String encode()
          The default encoding will serialize the DOM Tree.
 java.util.List getFields()
          retrieves the list of fields from the message.
 java.lang.String getFormType()
          Retrieves the form type for the data.
 java.lang.String getInstructions()
           
 java.util.List getItemFields()
          retrieves the list of result items from the message.
 int getMessageType()
          the default message type is unknown.
 java.util.List getReportedFields()
          retrieves the list of reported fields from the message.
 java.lang.String getTitle()
          retrieves the optional title that goes along with the form
 JabberMessage parse(JabberMessageParser parser, Element msgTree)
          parses the incoming data
 void setFormType(java.lang.String formType)
          sets the form type to one of the types as presented by the constants in this class.
 void setInstructions(java.lang.String instructions)
          sets the instructions to fill out the form, null to set it as non-existent.
 void setTitle(java.lang.String title)
          sets the form title to the title specified.
 
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

TYPE_SUBMIT

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

TYPE_CANCEL

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

TYPE_RESULT

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

TYPE_FORM

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

EMPTY_STRING

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

DataXMessage

public DataXMessage()
constructs a default message of type submit


DataXMessage

public DataXMessage(java.lang.String formType)
constructs a default message of the type specified

Method Detail

getFormType

public java.lang.String getFormType()
Retrieves the form type for the data. This can either be submit (indicating that the data is to be submitted), cancel (cancellation of request to fill out the form), form (a form containing data to be filled out), and result (the result after form submission, such as search results).

Returns:
the form type

setFormType

public void setFormType(java.lang.String formType)
sets the form type to one of the types as presented by the constants in this class.

Parameters:
formType - the form type

getInstructions

public java.lang.String getInstructions()
Returns:
the instructions that comes with the form, empty string if there is none

setInstructions

public void setInstructions(java.lang.String instructions)
sets the instructions to fill out the form, null to set it as non-existent.


getTitle

public java.lang.String getTitle()
retrieves the optional title that goes along with the form

Returns:
the form title, or empty string if there is none

setTitle

public void setTitle(java.lang.String title)
sets the form title to the title specified. Set to null for empty/non-existent

Parameters:
title - the form title

getFields

public java.util.List getFields()
retrieves the list of fields from the message. The list is not modifiable.

Returns:
an unmodifiable list of DataXField objects

getReportedFields

public java.util.List getReportedFields()
retrieves the list of reported fields from the message. The list is not modifiable. This list is normally used to indicate the column headers for incoming item results.

Returns:
an unmodifiable list of DataXField objects

getItemFields

public java.util.List getItemFields()
retrieves the list of result items from the message. The list is not modifiable. This list is normally used to represent item results for searches

Returns:
an unmodifiable list of DataXField objects

addField

public void addField(DataXField field)
adds a field to the field list


addReportedField

public void addReportedField(DataXField field)
adds a field to the reported field list


addItemField

public void addItemField(DataXField field)
adds a field to the item field list


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:
the message type for this class
See Also:
JabberCode

parse

public JabberMessage parse(JabberMessageParser parser,
                           Element msgTree)
                    throws ParseException
parses the incoming data

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

encode

public java.lang.String encode()
                        throws ParseException
Description copied from class: JabberJDOMMessage
The default encoding will serialize the DOM Tree. If there are X Messages, it will also get included one level below the main "root" element. By one level below, it means that the X Messages will be put as children of the DOM Tree's main element. If this is not a desired behavior, you will need to override and encode your own message.

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


Copyright © 2001-2005 Echomine. All Rights Reserved.