MessageTransformer (Message Queue, 5.1 API Specification)
Date: 2019-01-27

com.sun.messaging.bridge.api

## Class MessageTransformer<T,S>

- java.lang.Object
- - com.sun.messaging.bridge.api.MessageTransformer<T,S>

-     public abstract class MessageTransformer<T,S>
      extends java.lang.Object

  The message transformer class to be extended by user. Its implementation must provide a public zero-argument constructor. The following is an example usage of this class for MQ STOMP bridge

       import java.util.*;
       import javax.jms.*;
       import com.sun.messaging.bridge.api.MessageTransformer;

       public class MessageTran extends MessageTransformer <Message, Message> {

       public Message transform(Message message,
                                boolean readOnly,
                                String charsetName,
                                String source,
                                String target,
                                Properties properties)
                                throws Exception {

          Message m = message;
          if (source.equals(STOMP)) { //from STOMP client to Java Message Queue
              //convert any invalid headers from STOMP SEND frame
              if (properties != null) {
                  ......
                  //convert key to valid JMS message property name, then call m.setStringProperty()
                  ......
              }

          } else if (source.equals(SUN_MQ)) { //from Java Message Queue to STOMP client

              if (message instanceof ObjectMessage) {

                  //create a new BytesMessage for message to be transformed to
                  BytesMessage bm = (BytesMessage)createJMSMessage(JMSMessageType.BYTESMESSAGE);

                  //convert message to the BytesMessage
                  ......
                  m = bm;
              } else {
                  ....
              }
          }
          return m;
       }

  Author:
    amyk

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MessageTransformer.JMSMessageType`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `STOMP` The predefined provider name for JMS message to/from STOMP client
    `static java.lang.String` | `SUN_MQ` The predefined provider name for JMS message to/from Sun Java Message Queue

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MessageTransformer()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `branchTo(java.lang.Object d)` To be called from the transform() method when needs to tell the bridge to branch the message that is to be returned by the transform() call to a different destination in the target provider
    `protected javax.jms.Message` | `createJMSMessage(MessageTransformer.JMSMessageType type)` Create a JMS message object.
    `protected javax.jms.Queue` | `createQueue(java.lang.String queueName)` To be called from the transform() method when needs to create a JMS Queue object to the target provider
    `protected javax.jms.Topic` | `createTopic(java.lang.String topicName)` To be called from the transform() method when needs to create a JMS Topic object to the target provider
    `java.lang.Object` | `getBranchTo()` This method is called by the bridge service after transform() is returned for bridge types that support branchTo()
    `void` | `init(java.lang.Object obj, java.lang.String bridgeType)` This method is called by the bridge service before transform() is called.
    `boolean` | `isNoTransfer()` This method is called by the bridge service after transform() is returned for bridge types that support noTransfer()
    `protected void` | `noTransfer()` To be called from the transform() method when needs to tell the bridge to consume from source and not transfer to target the message that is to be returned by the transform() call
    `abstract T` | `transform(S message, boolean readOnly, java.lang.String charsetName, java.lang.String source, java.lang.String target, java.util.Properties properties)` To be implemented by user

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SUN_MQ

          public static final java.lang.String SUN_MQ

      The predefined provider name for JMS message to/from Sun Java Message Queue
      See Also:
        Constant Field Values

    - #### STOMP

          public static final java.lang.String STOMP

      The predefined provider name for JMS message to/from STOMP client
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MessageTransformer

          public MessageTransformer()

  - ### Method Detail

    - #### init

          public final void init(java.lang.Object obj,
                                 java.lang.String bridgeType)

      This method is called by the bridge service before transform() is called. A message transformer object is initialized by init() each time before transform() is called. After transform() returns, it's back to uninitialized state.

    - #### getBranchTo

          public final java.lang.Object getBranchTo()

      This method is called by the bridge service after transform() is returned for bridge types that support branchTo()

    - #### isNoTransfer

          public final boolean isNoTransfer()

      This method is called by the bridge service after transform() is returned for bridge types that support noTransfer()

    - #### createJMSMessage

          protected final javax.jms.Message createJMSMessage(MessageTransformer.JMSMessageType type)
                                                      throws java.lang.Exception

      Create a JMS message object. This method is to be used in tranform() method implemenation when it needs to create a new JMS message
      Parameters:
        `type` - the type of the JMS message to be created
      Returns:
        a newly created uninitialized JMS message object
      Throws:
        `java.lang.IllegalStateException` - if this MessageTransfomer object is not initialized
        `java.lang.Exception` - if fails to create the JMS Message

    - #### createQueue

          protected final javax.jms.Queue createQueue(java.lang.String queueName)
                                               throws java.lang.Exception

      To be called from the transform() method when needs to create a JMS Queue object to the target provider
      Parameters:
        `queueName` - the name of the Queue
      Returns:
        a javax.jms.Queue object
      Throws:
        `java.lang.IllegalStateException` - if this MessageTransfomer object is not initialized
        `java.lang.Exception` - if fails to create the Queue object

    - #### createTopic

          protected final javax.jms.Topic createTopic(java.lang.String topicName)
                                               throws java.lang.Exception

      To be called from the transform() method when needs to create a JMS Topic object to the target provider
      Parameters:
        `topicName` - the name of the Topic
      Returns:
        a javax.jms.Topic object
      Throws:
        `java.lang.IllegalStateException` - if this MessageTransfomer object is not initialized
        `java.lang.Exception` - if fails to create the Topic object

    - #### branchTo

          protected final void branchTo(java.lang.Object d)
                                 throws java.lang.Exception

      To be called from the transform() method when needs to tell the bridge to branch the message that is to be returned by the transform() call to a different destination in the target provider
      Parameters:
        `d` - a java.lang.String or javax.jms.Destination object that specifies the destination in target provider to branch the message to
      Throws:
        `java.lang.IllegalStateException` - if this MessageTransfomer object is not initialized
        `java.lang.IllegalArgumentException` - if null or unexpected object type passed in
        `java.lang.UnsupportedOperationException` - if the operation is not supported for the bridge type
        `java.lang.Exception` - if fails to create the JMS Message

    - #### noTransfer

          protected final void noTransfer()
                                   throws java.lang.Exception

      To be called from the transform() method when needs to tell the bridge to consume from source and not transfer to target the message that is to be returned by the transform() call
      Throws:
        `java.lang.IllegalStateException` - if this MessageTransfomer object is not initialized
        `java.lang.UnsupportedOperationException` - if the operation is not supported for the bridge type
        `java.lang.Exception`

    - #### transform

          public abstract T transform(S message,
                                      boolean readOnly,
                                      java.lang.String charsetName,
                                      java.lang.String source,
                                      java.lang.String target,
                                      java.util.Properties properties)
                               throws java.lang.Exception

      To be implemented by user
      Parameters:
        `message` - the message object to be tranformed.
        `readOnly` - if the message is in read-only mode
        `charsetName` - the charset name for message if applicable, null if not available
        `source` - the source provider name
        `target` - the target provider name
        `properties` - any properties for the transform() call, null if none
      Returns:
        a message object that is transformed from the passed in message
      Throws:
        `java.lang.Exception` - if unable to transform message

Copyright (c) 2010, 2017 Oracle and/or its affiliates. All rights reserved.