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

com.ibm.conversation
Interface MessageTransform

All Known Implementing Classes:
JasMessageTransform

public interface MessageTransform

The MessageTransform interface represents objects that convert between messages and decision data.

A given MessageTransform class represents a particular mapping between messages and decision data. It represents both directions of the mapping: from message to decision data, and vice versa.

MessageTransforms store internal copies of both the message and the decision data. To convert decision data to a message, one must first store the decision data in the MessageTransform, then invoke formAndValidate() to do the transformation, then get the newly formed message from the transform. The procedure for reverse transformation is similar: first store the message in the MessageTransform, then call parseAndValidate(), then get the newly parsed decision data from the transform.

ConversationPolicyHandlers use MessageTransforms for different but related tasks:

MessageTransforms are closely allied with MessageDescriptions. Each send-message transition in a conversation policy specifies, by means of a MessageDescription, the set of messages that match that transition. The ConversationPolicyHandler executing a conversation policy carries out the matching process by obtaining, for the MessageDescription in question, a MessageTransform that can transform messages matching that description. It then attempts to do the transformation. If the transformation is sucessful, then a match has been found, and the transition is taken. If not, then the next transition is attempted.

For outbound decision data, the transition is specified in the decision name. The ConversationPolicyHandler obtains a MessageTransform appropriate to the MessageDescription given by that transition, and uses it to convert the decision data into a message.

Any given MessageTransform is capable of transforming some set of messages. Some MessageTransforms are configurable, so that the set of transformable messages can be modified by configuring the MessageTransform. The configuration information is passed to the MessageTransform in the form of a MessageDescription.

See Also:
MessageTransformFactory, ConversationPolicyHandler

Method Summary
 boolean configureFor(MessageDescription desc)
          Attempts to configure this MessageTransform to fit the given message description.
 boolean formAndValidate()
          Converts decision data stored in this MessageTransform into a message object.
 java.lang.String[] getDecisionArgNames()
          Returns the names of the decision-data parameters stored in this MessageTransform.
 java.lang.Object[] getDecisionArgs()
          Returns the decision-data parameters stored in this MessageTransform.
 java.lang.Class[] getDecisionArgTypes()
          Returns the class types of the decision-data parameters this MessageTransform is able to transform.
 java.lang.Object getMessage()
          Returns the instance of the message object stored in this transform.
 java.lang.Class getMessageType()
          Returns the class type of messages this MessageTransform is able to transform.
 boolean parseAndValidate()
          Converts the message object stored in this MessageTransform into decision data.
 void setDecisionArgs(java.lang.Object[] args)
          Sets the decision-data parameters stored in this MessageTransform.
 void setMessage(java.lang.Object msg)
          Sets the message object stored in this transform.
 

Method Detail

getMessageType

public java.lang.Class getMessageType()
Returns the class type of messages this MessageTransform is able to transform.

Note: this implies that, for any particular MessageTransform instance at any particular time, there is only one such class type. However, it is still possible that the class type may depend on the MessageDescription for which this MessageTransform is configured. I.e., in the following fragment, c1 is not necessarily equal to c2:

     Class c1 = someTransform.getMessageClassType();
     someTransform.configureFor(someDescription);
     Class c2 = someTransform.getMessageClassType();
 

Returns:
The Class type of the messages that can be transformed.

getMessage

public java.lang.Object getMessage()
Returns the instance of the message object stored in this transform.

The message object was either set directly--in anticipation of being parsed--via setMessage(), or else was generated from the stored decision-data via formAndValidate().


setMessage

public void setMessage(java.lang.Object msg)
Sets the message object stored in this transform.

This prepares this MessageTransform for a call to parseAndValidate().

Parameters:
msg - The message object to store.

getDecisionArgNames

public java.lang.String[] getDecisionArgNames()
Returns the names of the decision-data parameters stored in this MessageTransform.

These are meant to be hints about what sort of information is in each object, in the same way that variable names are hints about what the variables contain. This becomes especially useful when the decision data class types are uninformative on their own (e.g., because they're all the same, or because they're very general-purpose classes).

Returns:
An array of names of the decision-data parameters.

getDecisionArgTypes

public java.lang.Class[] getDecisionArgTypes()
Returns the class types of the decision-data parameters this MessageTransform is able to transform.

Note: this implies that, for any particular MessageTransform instance at any particular time, there is only one such array of class types. However, it is still possible that the class types may depend on the MessageDescription for which this MessageTransform is configured. I.e., in the following fragment, the elements of a1 and a2 are not necessarily equal:

     Class[] a1 = someTransform.getDecisionArgTypes();
     someTransform.configureFor(someDescription);
     Class[] a2 = someTransform.getDecisionArgTypes();
 
Returns:
An array of Class types of decision-data parameters.

getDecisionArgs

public java.lang.Object[] getDecisionArgs()
Returns the decision-data parameters stored in this MessageTransform.

These were either set directly--in anticipation of being transformed--via a call to setDecisionArgs(), or else generated from the stored message via a call to parseAndValidate().

Returns:
An array of decision-data parameters.

setDecisionArgs

public void setDecisionArgs(java.lang.Object[] args)
Sets the decision-data parameters stored in this MessageTransform.

This prepares this MessageTransform for a call to formAndValidate().

Parameters:
args - The new decision-data parameters.

configureFor

public boolean configureFor(MessageDescription desc)
Attempts to configure this MessageTransform to fit the given message description.

If the configuration is successful, this MessageTransform will be able to validate, form, and parse messages matching the given description.

MessageTransforms are not required to be configurable for arbitrary message descriptions, or even configurable at all. Therefore, the return value must always be checked to determine whether the transform object involved could in fact be configured to fit the given description.

Parameters:
desc - The MessageDescription to configure this MessageTransform for.
Returns:
true if the attempt at configuration was sucessful; false if not.

formAndValidate

public boolean formAndValidate()
Converts decision data stored in this MessageTransform into a message object.

The message object is accessible via getMessage(). If the decision data is appropriate to this transform, the message that is generated by formAndValidate() conforms to the MessageDescription that this transform is currently configured for.

Returns:
true if the conversion was successful, false if not (e.g., because the decision data was not appropriate to this transform).

parseAndValidate

public boolean parseAndValidate()
Converts the message object stored in this MessageTransform into decision data.

The decision data is accessible via getDecisionArgs(). If the message object is appropriate to this transform--i.e., it conforms to the MessageDescription that this transform is currently configured for--the conversion will succeed.

Returns:
true if the conversion was successful, false if not (e.g., because the message object was not appropriate to this transform).

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

(C) Copyright IBM Corporation 1999, 2003