Using the JMS Transport

You can select JMS as the transport protocol for proxy and business services of any service type (except Transport Typed Service type for business service). The proxy services and business services can be configured to use the JMS transport as described in:

When you configure a proxy service, you can use a Transport Header action to set the header values in messages. For more information, see Transport Headers.

For information about interoperability of Oracle Service Bus with WebSphere MQ, see Using the WebSphere JMS MQ Interface in Native MQ Transport User Guide.

In Oracle Service Bus, you can use the default dispatch policy when you configure a service or, optionally, configure custom work managers in WLS. For more information, see “Creating a Work Manager” in Using the WS Transport in WS Transport User Guide.

Configuring Proxy Services using JMS Transport Protocol

You can select the JMS transport protocol when you configure any type of proxy service and the endpoint URI is of the form:

host: is the name of the system that hosts the service.

In a cluster: The host names in the JMS URI must exactly match the host names of the cluster servers as they are configured in WebLogic Server.

port: is the port number at which the connection is made.
[,host:port]*: indicates that you can configure multiple hosts with corresponding ports.
factoryJndiName: The name of the JNDI Connection Factory. For more information on how to define a connection factory queue, see Configure resources for JMS system modules in Administration Console Online Help.
destJndiName: is the name of the JNDI destination.

To target a JMS destination to multiple servers, use the following format of the URI: jms://

host1:port,host2:port/QueueConnectionFactory/destJndiName

where QueueConnectionFactory is name of the connection factory queue. For more information on how to define a connection factory queue, see Configure resources for JMS system modules in Administration Console Online Help.

To configure a proxy service using JMS transport protocol you must specify values for the following fields:

Destination Type: You must specify the destination to be of one of the following:

Queue: This defines a point-to-point destination type. You can use this destination type for peer asynchronous communications. A message, which is delivered to a queue is distributed to only one destination.
Topic: This defines a publish or a subscribe destination type. You can use this destination type for peer asynchronous communications. A message, which is delivered to a topic is distributed to all the subscribers of the topic.

Is Response Required: If you expect a response to the outbound message, you must specify the following parameters for the response message:

Response Correlation Pattern: This configures the design pattern for JMS response message to be one of the following:

JMS Correlation ID: You must select JMS Correlation ID design pattern for your message if you want to correlate by JMS Correlation ID and send the response to the URI configured in the Response URI field.

Note: The Response URI field is active only when you select JMS Correlation ID design pattern for your response message.

JMS Message ID: You can JMS Message ID design pattern for your message if you want to correlate by JMS Message ID and send the response to the JMSReplyTo Destination by configuring the Response Connection Factory field.

Note: The Response Connection Factory field is active only when you select JMS Message ID design pattern for your response message.

Response Message Type: You can set type of the response message to Bytes or Text.
Response Encoding: You can set the encoding for the response message. The default encoding is UTF-8.
Client Response Timeout: This parameter specifies the response timeout interval, in seconds.

Request Encoding: You can set the encoding for the request message. The default encoding is UTF-8.

Dispatch Policy: This specifies the dispatch policy for the endpoint. You must configure Work Managers in the WebLogic Server Administration Console in order to have other dispatch policies in addition to the default dispatch policy. For information about work managers, see Using Work Managers to Optimize Scheduled Work and Create Work Manager in WebLogic Server Administration Console Online Help.

Advanced Settings: Click the icon to expand the Advanced Settings section. Configuring parameters in this section is optional.

You can set the following parameters in the section:

Use SSL: This specifies whether the connections can be made over SSL or not.
Message Selector: You can use this field to specify the criteria for selecting messages.
Durable Subscription: You can check if the subscription is durable only if the destination type is Topic.
Retry Count: In this field you can configure the maximum number of retries for the connection.
Retry Interval: In this field you can configure the time interval in milliseconds between consecutive retries.
Error Destination: In this field you can configure the name of the target destination for the messages, which have reached the maximum number of retry count.
Expiration Policy: In this field you can specify the message expiration policy to be used when you encounter an expired message at a WebLogic Server or a JMS destination.
Is XA Required: This represents if the connection factory is XA or not. When enabled, and if the connection factory is available, make sure that the connection factory is of XA type.
Synchronous Transactional: Specifies that the response pipeline inherits the transaction from the request pipeline. This means that the transaction will not commit until both pipelines have completed. This field is enabled only when the Is Response Required field is checked.
JMS Service Account: In this field you can specify the name of the service account resource to be used to make the connection over the secured socket layer. The same service account is used for both JNDI and JMS purposes.

For more information about configuring proxy services using JMS transport, see JMS Transport Configuration Page in Proxy Services: Creating and Managing in Using the Oracle Service Bus Console.

Transport Headers

The various headers related to the JMS transport are listed in Table 3-1. All the headers except the Unit of Order header are common to both outbound requests and inbound response.

Table 3-1 JMS Transport Headers

Header

Description

JMSMessageID

The JMSMessageID header field contains a value that uniquely identifies the message sent by a provider.

JMSDeliveryMode

The JMSDeliveryMode header field contains the delivery mode specified when the message was sent.

JMSExpiration

This header contains the expiration time of the message that is calculated as the sum of the time-to-live value specified on the send method and the current GMT value.

JMSPriority

The JMSPriority header field contains the priority of the message.

When a message is sent, this field is ignored. After the send operation is complete, the field holds the value that is specified by the method sending the message.

JMSType

The JMSType header field contains the message type identifier that is specified by a client when a message is sent.

JMSCorrelation ID

This is used to link one message with another. For example to link a request message with a response message.

JMSXAppID

This is one of the JMS defined properties that specifies the identity of the application that sends the message. This is set by the JMS provider

JMSXGroupID

This one of the properties defined by JMS that specifies the group id of the message group to which the message belongs. This is set by the client

JMSXGroupSeq

This one of the properties defined by JMS that specifies the sequence of the message inside the message group.

JMS_IBM_Format

This contains the nature of the application data. For more information, see JMS_IBM_FORMAT.

JMS_IBM_Report_Exception

Request exception reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see JMS_IBM_Report_Exception.

JMS_IBM_Report_Expiration

Request expiration reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see JMS_IBM_Report_Expiration.

JMS_IBM_Report_COA

Request a confirm on arrival reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see JMS_IBM_Report_COA.

JMS_IBM_Report_COD

Request a confirm on delivery reports. This also specifies how much of the application data from the message must be retained in the report message. For more information, see JMS_IBM_Report_COD.

JMS_IBM_Report_PAN

Request a positive action notification reports. For more information, see JMS_IBM_Report_PAN.

JMS_IBM_Report_NAN

Request a positive action notification reports. For more information, see JMS_IBM_Report_NAN

JMS_IBM_Report_Pass_Msg_ID

Request that the message identifier of any report or reply message is the same as that of the original message. For more Information, see JMS_IBM_Report_Pass_Msg_ID.

JMS_IBM_Report_Pass_Correl_ID

Request that the correlation identifier of any report or reply message is the same as that of the original message. For more information, see JMS_IBM_Report_Pass_Correl_ID.

JMS_IBM_Report_Discard_Msg

Request that the message is discarded if it cannot be delivered to its intended destination. For more information, see JMS_IBM_Report_Discard_Msg.

JMS_IBM_MsgType

The type of a message. For more information, see JMS_IBM_MsgType.

JMS_IBM_Feedback

This indicates the nature of a report message. For more information, see JMS_IBM_Feedback.

JMS_IBM_Last_Msg_In_Group

Indicates whether the message is the last message in a message group. For more information, see JMS_IBM_Last_Msg_In_Group.

JMS_BEA_UnitOfOrder

Note:

This header is valid only for the Inbound Response.

Configuring Transport Headers

You can configure the transport headers for both inbound and outbound requests in the Message Flow. For information about the transport headers related to the JMS transport, see Transport Headers.

In the pipeline, use a Transport Header action to set the header values in messages. For information about adding transport header actions, see Adding Transport Header Actions in Using the Oracle Service Bus Console.

Configuring Business Services using JMS Transport Protocol

You can select the JMS transport protocol when you configure any type of business service and the endpoint URI is of the form:

host: is the name of the system that hosts the service.

In a cluster: The host names in the JMS URI must exactly match the host names of the cluster servers as they are configured in WebLogic Server.

port: is the port number at which the connection is made.
[,host:port]*: indicates that you can configure multiple hosts with corresponding ports.
factoryJndiName: The name of the JNDI Connection Factory. For more information on how to define a connection factory queue, see Configure resources for JMS system modules in Administration Console Online Help.
destJndiName: is the name of the JNDI destination.

To target a target a JMS destination to multiple servers, use the following format of the URI: jms://host1:port,host2:port/QueueConnectionFactory/destJndiName

When you register a JMS business service, you must manually edit the URI from the WSDL file when adding it to the service definition. The URI format is as follows:

To configure a business service using the JMS transport protocol you must specify values for the following fields:

Destination Type: You can specify the destination to be of one of the following:

Queue: This defines a point-to-point destination type. You can use this destination type for peer asynchronous communications. A message, which is delivered to a queue is sent to only one destination.
Topic: This defines a publish or a subscribe destination type. You can use this destination type for peer asynchronous communications. A message, which is delivered to a topic is distributed to all the subscribers of the topic.

Is Response Required: You can specify if you expect a response to the outbound message. If you expect a response you must specify the following parameters for the response message:

Response Correlation Pattern: You can configure the design pattern for JMS response message to be one of the following:

JMS Correlation ID: You must select a JMS Correlation ID design pattern for your message if you want to correlate by JMS Correlation ID and send the response to the URI configured in the Response URI field.

Note: The Response URI field is active only when you select JMS Correlation ID design pattern for your response message.

JMS Message ID: You must select JMS Message ID design pattern for your message if you want to correlate by JMS Message ID and send the response to the JMSReplyTo Destination by configuring the Response Connection Factory field.

Note: The Response Connection Factory field is active only when you select JMS Message ID design pattern for your response message.

Response JNDI Names: You can specify the JNDI names of the response destinations. You need to configure one for each server in the domain.
Response Message Type: You can set type of the response message to Bytes or Text.
Response Encoding: You can set the encoding for the response message. The default encoding is UTF-8.
Response Timeout: The amount of time to wait for a response, the response timeout interval, in seconds.

Request Encoding: You can set the encoding for the request message. The default encoding is UTF-8.
Dispatch Policy: You can specify the dispatch policy for the endpoint. You must configure Work Managers in the WebLogic Server Administration Console in order to have other dispatch policies in addition to the default dispatch policy. For more information on how to configure a Work Manager, see Create a Global Work Manager in WebLogic Server Administration Console.
Advanced Settings: To configure the advance settings click on icon on the right hand side to expand the advanced settings section. Configuring parameters in this section is optional.

You can set the following parameters in the section:

Use SSL: This specifies if the connections can be made over SSL or not.
Expiration: This specifies the time interval in milliseconds after which the message will expire. Default value is 0, which means that the message never expires.
Enable Message Persistence: This represents the mode of delivery of the JMS message. When this option is enabled, the delivery mode is persistent else non-persistent.
Unit Of Order: This is a value added feature of WebLogic, which enables a message producer to group messages into a single unit with respect to the order of processing. This single unit is called the Unit of Order. All the messages in a unit must be processed sequentially in the same order they were created.

Note:

This is supported by WebLogic Server 9.0.

Pass Caller’s Subject: This specifies that Oracle Service Bus is to pass the authenticated subject when sending a message. When you enable this field and the business service targets JMS resources in a different domain, enable global trust on both domains. See Configuring Security for a WebLogic Domain in Securing WebLogic Server.
JMS Service Account: You can select the service account resource to be used for the JMS server connection. The same service account is used for both JNDI and JMS purposes.

Error Handling

You can configure JMS-transport business services to handle application and communications errors as follows:

Application errors

You can specify whether or not to retry business service endpoint URIs when application errors occur. For more information, see Retry Application Errors option in Creating and Configuring Business Services - Transport Configuration page in Using the Oracle Service Bus Console.

An application error occurs when for a JMS business service configured with request/response, the System.getProperty("com.bea.wli.sb.transports.jms.ErrorPropertyName", "SERVER_ERROR") property is true in the response message. In this scenario, the JMS transport provider calls the error method with the TRANSPORT_ERROR_APPLICATION error code.

Communication errors

You can configure business service URIs to be taken offline when such communication errors occur. When you configure the operational settings for the business service, you can enable the business service endpoint URIs to be taken offline after the specified retry interval. For more information, see “Configuring Operational Settings for Business Services” and “Viewing Business Services Endpoint URIs Metrics” in Monitoring in Using the Oracle Service Bus Console.

Connection errors occur when any JMS exceptions or naming exceptions occur during any of the following activities:

Looking up a JMS connection factory.
Creating a JMS connection from a JMS connection factory.
Creating a JMS session using a connection object.
Looking up of a JMS destination.
Creating a sender from the session object.
Sending a JMS message using the sender and destination object.