ABLE 2.0.0 07/02/2003 10:25:01

com.ibm.able.conversation
Interface MessageForm

All Known Implementing Classes:
ConversationSetupForm, TextMessageForm, StartCPForm, AmabSelectionMessageForm, AmabOfferMessageForm

public interface MessageForm

Classes that implement this interface are used to assemble and disassemble TransportMessages, converting them to & from strongly-typed objects (the "constituent data") which are defined by the particular MessageForm class itself.

OLD VERSION -- TO BE DELETED Replaced by com.ibm.conversation.MessageTransform.

Many MessageForm classes will have user-configurable properties, which help determine the way the MessageForm converts between messages and constituent data. Properties are not to be confused with the constituent data, and are not involved in the getData/setData methods.

It's up to the MessageForm designer to decide what should be a property, and what should be part of the constituent data.

Intended usage is as follows:
1. For converting data into a message
1a. Set the by calling setData(...) or by calling class-specific property- setters (e.g., mySpecialMessageForm.setPrice(99.98), etc.)
1b. invoke the form() method. E.g., TransportMessage myMessage = mySpecialMessageForm.form();
2. For converting a message into data
2a. Invoke parse(...) method. E.g., boolean isParsed = mySpecialMessageForm.parse(theMessage);
2b. Get the data by calling getData(...) or by calling class-specific property-getters (e.g., double thePrice = mySpecialMessageForm.getPrice(), etc.)

TO DO: This should form & parse javax.agent.Payload, not TransportMessage.


Method Summary
 void clearData()
          Reset the constituent data to null or default values.
 javax.agent.Payload formMessagePayload()
          Creates a message, using constituent data that was stored inside this MessageForm object.
 java.lang.Object[] getData()
          Package & return the constituent data in the form of an array of Objects.
 boolean parseMessagePayload(javax.agent.Payload messagePayload)
          Parses the message into its constituent data, which is (supposed to be) stored inside this message-form object in a type-specific way.
 javax.agent.Payload sampleMessagePayload()
          Return a "sample message" showing the format, but with dummy data values.
 void setData(java.lang.Object[] data)
          Try to set the constituent data by means of the supplied arguments.
 

Method Detail

parseMessagePayload

public boolean parseMessagePayload(javax.agent.Payload messagePayload)
Parses the message into its constituent data, which is (supposed to be) stored inside this message-form object in a type-specific way.
Returns:
true if parsing was fully successful, false if not.

formMessagePayload

public javax.agent.Payload formMessagePayload()
                                       throws java.lang.IllegalStateException
Creates a message, using constituent data that was stored inside this MessageForm object. If there's something wrong with the data--e.g., if it hasn't been set, or has been set to bad values, throws an IllegalStateException.

sampleMessagePayload

public javax.agent.Payload sampleMessagePayload()
Return a "sample message" showing the format, but with dummy data values. This is inherently limited, because we're not characterizing the range of possible messages. We're only giving one example.

setData

public void setData(java.lang.Object[] data)
             throws java.lang.IllegalArgumentException
Try to set the constituent data by means of the supplied arguments. Does not expect to see any properties in the array. Throws an IllegalArgumentException when the array data doesn't have the right elements.

getData

public java.lang.Object[] getData()
Package & return the constituent data in the form of an array of Objects. Does not include the properties in the array. If the constituent data is null, returns an array of the appropriate length, but with null-valued elements.

clearData

public void clearData()
Reset the constituent data to null or default values. Does not affect the properties.

ABLE 2.0.0 07/02/2003 10:25:01

(C) Copyright IBM Corporation 1999, 2003