+

Search Tips   |   Advanced Search

Pass message payload by reference: Usage scenarios and example code for forwarding applications

A JMS forwarder application receives a message (through a connection factory, or if it is a message-driven bean through an activation specification), then sends the message object on to another destination. Explore the different usage scenarios, then code the JMS forwarding applications so that we can safely pass message payloads by reference when forwarding messages from one queue to another within a single server.

When large object messages or bytes messages are sent, the cost in memory and processor use of serializing, deserializing, and copying the message payload can be significant. If we enable the pass message payload by reference properties on a connection factory or activation specification, you tell the default messaging provider to override the JMS 1.1 specification and potentially reduce or bypass this data copying.

In the following figure, messages pass from queue1 on a messaging engine, through a consumer activation specification or connection factory, to a JMS forwarding application. They are then forwarded through a producer connection factory to queue2 on the same messaging engine.

CAUTION:

The parts of the JMS Specification that are bypassed by these properties are defined to ensure message data integrity. Any of the JMS applications that use these properties must strictly follow the rules described or you risk losing data integrity.

Figure 1. Forwarding messages

To understand the usage scenarios and associated example code given in this topic, you must note these important characteristics of a JMS forwarding application:

The following table describes the four forwarding application usage scenarios that affect how set the "pass message payload by reference" properties. Note that, because the producer connection factory has no effect upon the contents of the forwarded message, you set both the consumer properties and the producer/forwarder properties on the consumer connection factory or activation specification.

payload by reference" property settings on the forwarding application usage scenarios. The first column of the table lists the four forwarding application usage scenarios. The second column indicates the consumer property setting for the scenarios. The third column indicates the connection or the activation specification property
Forwarding application usage scenario

consumerDoesNotModify
PayloadAfterGet property setting

producerDoesNotModify
PayloadAfterSet (for connection factories) or

forwarderDoesNotModify
PayloadAfterSet (for activation specifications) property setting

Scenario 1: The application receives a message, looks at the payload but does not modify it, and forwards the message on without modifying or replacing the payload. Enabled Not required, but can be enabled
Scenario 2: The application receives a message, looks at the payload but does not modify it, replaces the payload in the message with a new payload and forwards the message on without modifying the payload after the call to set it into the message. Enabled Enabled
Scenario 3: The application receives a message, looks at and modifies the payload, then sets the modified payload or some other data back into the message and forwards the message on without further modifying the payload after the call to set it into the message. NOT enabled Enabled
Scenario 4: The application receives a message, looks at and modifies the payload, then sets the modified payload or some other data back into the message, then further modifies the payload after the call to set it into the message. NOT enabled NOT enabled

For scenarios 1, 2 and 3 we can enable one or more of the "pass message payload by reference" properties, provided that the forwarding application can guarantee to behave as described in the scenario. To help you achieve this, here is some example code that we can adapt for use in the applications.


Forwarding application: scenario 1

The application receives a message, looks at the payload but does not modify it, and forwards the message on without modifying or replacing the payload.

public void onMessage (Message message)
{
   ObjectMessage oMessage = (ObjectMessage) message;
   DataObject data = oMessage.getObject();
   System.out.print(data.getXXX());
   System.out.print(data.getYYY());

   // get a session to forward on the received message    
   producer.send(message);
   session.close();
}


Forwarding application: scenario 2

The application receives a message, looks at the payload but does not modify it, replaces the payload in the message with a new payload and forwards the message on without modifying the payload after the call to set it into the message.

public void onMessage (Message message)
{
   ObjectMessage oMessage = (ObjectMessage) message;
   DataObject data = oMessage.getObject();
   System.out.print(data.getXXX());
   System.out.print(data.getYYY());

   // get a session to forward on the received message    
   message.setObject(newData);

   producer.send(message);
   session.close();
}
For bytes messages, the application must also guarantee to write only a single full byte array into the message.
byte [] data = myByteData; 
BytesMessage message = session.createBytesMessage(); 
message.writeBytes(data); 
data = null;  
producer.send(message);


Forwarding application: scenario 3

The application receives a message, looks at and modifies the payload, then sets the modified payload or some other data back into the message and forwards the message on without further modifying the payload after the call to set it into the message.

public void onMessage (Message message)
{
   ObjectMessage oMessage = (ObjectMessage) message;
   DataObject data = oMessage.getObject();
   System.out.print(data.getXXX());
   System.out.print(data.getYYY());

   // get a session to forward on the received message 
   data.setXXX(xxx);
   data.setYYY(yyy);
   message.setObject(data);

   producer.send(message);
   session.close();
}
For bytes messages, the application must also guarantee to write only a single full byte array into the message.
byte [] data = myByteData; 
BytesMessage message = session.createBytesMessage(); 
message.writeBytes(data); 
data = null;  
producer.send(message);


Related concepts

  • Why and when to pass the JMS message payload by reference


    Related tasks

  • Configure a unified connection factory for the default messaging provider
  • Configure a queue connection factory for the default messaging provider
  • Configure a topic connection factory for the default messaging provider
  • Configure an activation specification for the default messaging provider

  • createSIBJMSActivationSpec command
  • modifySIBJMSActivationSpec command
  • createSIBJMSConnectionFactory command
  • modifySIBJMSConnectionFactory command


    Related information:

  • Default messaging provider unified connection factory [Settings]
  • Default messaging provider queue connection factory [Settings]
  • Default messaging provider topic connection factory [Settings]
  • JMS activation specification [Settings]