Creating Applications Using JMS , 9 of 9

Message Transformation with JMS

The following topics are discussed in this section:

Defining Message Transformations

Transformations can be defined to map messages of one format to another. Transformations are useful when applications that use different formats to represent the same information have to be integrated. Transformations can be SQL expressions and PLSQL functions.

The transformations can be created using the DBMS_TRANSFORM.create_transformation procedure. Transformation can be specified for the following operations:

Sending a message to a queue or topic
Receiving a message from a queue, or topic
Creating a Topic Subscriber
Creating a Remote Subscriber. This will enable propagation of messages between Topics of different formats.

The Message Transformation feature is an AQ extension to the standard JMS interface.

Example Scenario

In the BooksOnLine example, we will consider the order entry and shipping applications. For these examples, we will use topics with ADT type payloads.

Example Code

Lets say that the Order entry topic OE.OE_bookedorders_topic has a payload of type OE.OE_ORDER

create or replace TYPE OE_order as OBJECT ( 
             orderno         NUMBER, 
             status          VARCHAR2(30), 
             ordertype       VARCHAR2(30), 
             orderregion     VARCHAR2(30), 
             customer        CUSTOMER_TYP, 
             paymentmethod   VARCHAR2(30), 
             creditcard#     VARCHAR2(30);
             items           ORDERITEMLIST_VARTYP, 
             order_date      DATE,
             total           NUMBER);

The Western Shipping topic WS_bookedorders_topic has payload of type WS.WS_ORDER:

create or replace TYPE WS_Order AS OBJECT (
	       customer_name   VARCHAR2(100), 
	       address         VARCHAR2(1000),
	       city            VARCHAR2(1000),
	       state           VARCHAR2(1000),
     	  country         VARCHAR2(1000),
	       zipcode         VARCHAR2(1000),
       orderno         NUMBER, 
       status          VARCHAR2(30), 
       ordertype       VARCHAR2(30), 
       items           ORDERITEMLIST_VARTYP, 
       order_date      VARCHAR2(10));

The java classes (that implement the CustomDatum interface) can be generated for these types using the Jpublisher utility.

We will define a transformation that defines the mapping from OE.OE_Order to WS.WS_ORDER as:

execute dbms_transform.create_transformation(
	schema => 'OE',
        name => 'OE2WS',
        from_schema => 'OE,
        from_type => 'OE_order',
        to_schema => 'WS',
        to_type => 'WS_order',
        transformation => 'OE_order(source.user_data.customer.name, \
            source.user_data.customer.street, \
            source.user_data.customer.city, \
            source.user_data.customer.state, \
	            source.user_data.customer.country, \
	            source.user_data.customer.zipcode, \
	            source.user_data.customer.country, \
	            source.user_data.orderno, \
	            source.user_data.status, \
	            source.user_data.ordertype, \
	            source.user_date.items, \
            TO_CHAR(source.user_date.order_date, 'MM:DD:YYYY'))');

Sending Messages to a Destination Using a Transformation

A transformation can be supplied when sending/publishing a message to a queue/topic. The transformation will be applied before putting the message into the queue/topic.

The application can specify a transformation using the setTransformation interface in the AQjmsQueueSender and AQjmsTopicPublisher interfaces.

Example Code

Lets say that the orders that are processed by the order entry application should be published to the WS_bookedorders_topic.

The transformation OE2WS (defined in the previous section) is supplied so that the messages are inserted into the topic in the correct format.

public void ship_booked_orders(TopicSession    jms_session,
                         		      	AQjmsADTMessage adt_message)				    
{
       TopicPublisher  publisher;
       Topic           topic;

       try
       {
         /* get a handle to the WS_bookedorders_topic */
	         topic = ((AQjmsSession)jms_session).getTopic("WS", 
	                                                      "WS_bookedorders_topic");
        	 publisher = jms_session.createPublisher(topic);

         /* set the transformation in the publisher */
       	 ((AQjmsTopicPublisher)publisher).setTransformation("OE2WS");

        	 publisher.publish(topic, adt_message);

	       }
	       catch (JMSException ex)
	       {
	          System.out.println("Exception :" ex);
       }
}

Receiving Messages from a Destination Using a Transformation

A transformation can be applied when receiving a message from a queue or topic. The transformation will be applied to the message before returning it to JMS application.

The transformation can be specified via setTransformation( ) interface of the AQjmsQueueReceiver, AQjmsTopicSubscriber and AQjmsTopicReceiver.

Example Code

Lets say the Western Shipping application retrieves messages from the OE_bookedorders_topic. It specifies the transformation 'OE2WS' to retrieve the message as the WS_order ADT.

Lets say that the WSOrder Java class has been generated by Jpublisher to map to the Oracle Object WS.WS_order

public AQjmsAdtMessage retrieve_booked_orders(TopicSession jms_session)
       AQjmsTopicReceiver  receiver;
       Topic               topic;
       Message             msg = null;

       try
       {
         /* get a handle to the OE_bookedorders_topic */
        	 topic = ((AQjmsSession)jms_session).getTopic("OE", 
                   "OE_bookedorders_topic");

	         /* Create a receiver for WShip */
        	 receiver = ((AQjmsSession)jms_session).createTopicReceiver(topic,    
                                      "WShip, null, WSOrder.getFactory());

         /* set the transformation in the publisher */
        	 receiver.setTransformation("OE2WS");

        	 msg = receiver.receive(10);
      	 }
	       catch (JMSException ex)
	       {
	          System.out.println("Exception :" ex);
       }
	 
       return (AQjmsAdtMessage)msg;
}

Specifying Transformations for Topic Subscribers

A transformation can also be specified when creating Topic Subscribers using the CreateDurableSubscriber call. The transformation is applied to the retrieved message before returning it to the subscriber. If the subscriber specified in the CreateDurableSubscriber already exists, it's transformation is set to the specified transformation.

Example Code

The Western Shipping application subscribes to the OE_bookedorders_topic with the transformation 'OE2WS'. This transformation is applied to the messages and the returned message is of Oracle Object type WS.WS_orders.

Lets say that the WSOrder java class has been generated by Jpublisher to map to the Oracle Object WS.WS_order:

public AQjmsAdtMessage retrieve_booked_orders(TopicSession jms_session)
{
       TopicSubscriber     subscriber;
       Topic               topic;
       AQjmsAdtMessage     msg = null;

       try
       {
         /* get a handle to the OE_bookedorders_topic */
	         topic = ((AQjmsSession)jms_session).getTopic("OE", 
                                                 "OE_bookedorders_topic");

         /* create a subscriber with the transformation OE2WS */
	        	 subs = ((AQjmsSession)jms_session).createDurableSubscriber(topic, 	
                 'WShip', null, false, WSOrder.getFactory(), "OE2WS");

        	 msg = subscriber.receive(10);
      	 }
      	 catch (JMSException ex)
	       {
	           System.out.println("Exception :" ex);
       }
	 
       return (AQjmsAdtMessage)msg;
}

Specifying Transformations for Remote Subscribers

AQ allows a remote subscriber, that is a subscriber at another database, to subscribe to a topic.

Transformations can be specified when creating remote subscribers using the createRemoteSubscriber. This enables propagation of messages between Topics of different formats. When a message published at a topic meets the criterion of a remote subscriber, AQ will automatically propagate the message to the queue/topic at the remote database specified for the remote subscriber. If a transformation is also specified, AQ will apply the transformation to the message before propagating it to the queue/topic at the remote database.

Example Code

A remote subscriber is created at the OE.OE_bookedorders_topic so that messages are automatically propagated to the WS.WS_bookedorders_topic. The transformation OE2WS is specified when creating the remote subscriber so that the messages reaching the WS_bookedorders_topic have the correct format.

Lets say that the WSOrder java class has been generated by Jpublisher to map to the Oracle Object WS.WS_order

public void create_remote_sub(TopicSession jms_session)
{
     AQjmsAgent          subscriber;
     Topic               topic;

     try
     {
       /* get a handle to the OE_bookedorders_topic */
       topic = ((AQjmsSession)jms_session).getTopic("OE", 
	                                            "OE_bookedorders_topic");
        
       subscriber = new AQjmsAgent("WShip", "WS.WS_bookedorders_topic");

       ((AQjmsSession )jms_session).createRemoteSubscriber(topic, 
                                subscriber, null, WSOrder.getFactory(),"OE2WS");
     }
     catch (JMSException ex)
     {
       System.out.println("Exception :" ex);
     }
}