Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.ibm.conversation
Interface MessageTransform

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:

- Testing whether an inbound message matches a given transition in a conversation policy.
- Translating a valid inbound message into decision-data to be given to the decision logic for processing.
- Testing whether outbound decision data matches the transition given by the decision name.
- Translating valid outbound decision data into a message to be given to the messaging system for delivery.

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).

Overview | Package | Class | Use | Tree | Serialized | Deprecated | Index | Help
| ABLE 2.3.0 07/13/2005 14:21:00
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

(C) Copyright IBM Corporation 1999, 2005