The JMS architecture uses one client interface-to-many messaging servers. The JMS model has two messaging domains, point-to-point and publish-subscribe. In the point-to-point domain, messages are exchanged through a queue and each message is delivered to only one receiver. In the publish-subscribe model, messages are sent to a topic and can be read by many subscribed clients.
You can obtain JMS adapter sample files by accessing theOracle SOA Sample Code site.
The JCA Binding Component is used for the bidirectional integration of the JCA 1.5 resource adapters with BPEL Process Manager. The JCA Binding Component is based on standards and employs the Web service Invocation Framework (WSIF) technology for exposing the underlying JCA interactions as Web services.
For information on Oracle JMS Adapter architecture, adapter integration with Oracle BPEL Process Manager (Oracle BPEL PM), and adapter deployments, refer to Adapter Integration with Components .
Mediator supports Oracle JCA Adapters and enables you to define inbound and outbound adapter services for each. An inbound adapter service receives data from an external messaging system and transforms it into an XML message. An outbound adapter service sends data to a target application by transforming an XML message into the native format of the given adapter.
In the case of the Oracle JMS Adapter service, by using Mediator, you can send or receive messages from a JMS queue or topic.
Oracle BPEL PM pre-dates Mediator, and most of this guide and the samples implicitly assume use with Oracle BPEL PM. However, the adapters work equally well with either Oracle BPEL PM or Mediator. For any mention of Oracle BPEL PM in this chapter, you may substitute Mediator, instead.
The Oracle JMS Adapter includes the following features:
Is based on JMS version 1.0.2b
Is a generic Oracle JMS Adapter
Should work with any JMS provider. However, Oracle JMS Adapter is certified against AQ JMS (JMS providers OJMS 8.1.7, 9.0.1.4, and 9.2), TIBCO JMS, IBM Websphere MQSeries (IBM MQSeries JMS 6.0), Weblogic JMS, Apache, and Active MQ. Contact Oracle Support for additional Providers certification information.
Supports JMS topics and queues
Supports byte, text, and map message types.
Supports these data types only for this release. The Adapter Configuration Wizard provides the Native Format Builder wizard for consuming native data payloads at runtime. The Native Format Builder wizard creates XSD definitions for the underlying native data.
Supports JMS headers and properties
Supports WebLogic Server Unit-of-Order feature
The WebLogic Server Unit-of-Order feature enables a JMS message producer or group of message producers acting as one, to group messages into a single unit that is processed sequentially in the order the messages were created. The message processing of a single message is complete when a message is acknowledged, committed, recovered, or rolled back. Until message processing for a message is complete, the remaining unprocessed messages for that Unit-of-Order are blocked.
This enhancement enables WebLogic Server Unit-of-Order support in SOA JMS adapter. Messages produced using the SOA JMS adapter would enable the user to specify a specific unit-of-order.
Supports jca.message.encoding property
The Oracle JMS Adapter supports the jca.message.encoding
property for inbound and outbound payloads. If the jca.message.encoding
property is used along with the adapter.jms.encoding
property and the nxsd:encoding
attribute, then the jca.message.encoding
property takes precedence over the adapter.jms.encoding
property, and the nxsd:encoding
attribute is given the last preference. The nxsd:encoding
value can be UTF-8, which is typically recommended for interoperability and Unicode support. However, you can specify any legal encoding supported by the Java runtime environment. For a complete listing of supported encodings, visit http://docs.oracle.com/javase/7/docs/technotes/guides/intl/encoding.doc.html
. You can specify the encoding in the (N)XSD associated with the adapter proxy meta data. For example, you can specify the following attribute, nxsd:encoding="iso-8859-1".
The jca.message.encoding
property is supported as an endpoint defined in composite.xml
You can define this property using the Properties tab of the Adapter Configuration Wizard or by editing the composite.xml
file. The jca.message.encoding
property can be passed as a normalized message property for both inbound and outbound interactions.
The following code snippet is an example of setting values in the composite.xml file for message encoding for an inbound service:
<service name="jms_inbound" ui:wsdlLocation="jms_inbound.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter /jms/utf8/jcamessageencoding/ jms_inbound#wsdl.interface(Consume_Message_ptt)"/> <binding.jca config="jms_inbound_jms.jca"> <property name="jca.message.encoding" type="xs:string" many="false" override="may">GBK</property> </binding.jca> </service>
The following code snippet is an example of setting values in the composite.xml file for message encoding for an outbound reference:
<reference name="jms_outbound" ui:wsdlLocation= “jms_outbound.wsdl"> <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/jms/utf8/jcamessageencoding/ jms_outbound#wsdl.interface(Produce_Message_ptt)"/> <binding.jca config="jms_outbound_jms.jca"> <property name="jca.message.encoding" type="xs:string" many="false" override="may">GBK</property> </binding.jca> </reference>
Supports the JMS message selector
Supports the JMS message selector for performing filtering while subscribing to JMS topics and queues. This parameter is based on the SQL 92 language for filtering messages based on fields present in the JMS header and properties section.
Is DOM2 compliant
The Oracle JMS Adapter can process and generate document objects that are compliant with DOM2 specification.
Supports normalized message.
Header manipulation and propagation is a key business integration messaging requirement. Oracle BPEL PM, Mediator, Oracle JCA, and Oracle B2B rely extensively on header support to solve customers' integration requirements. For example, a user can preserve a file name from the source directory to the target directory by propagating it through message headers. Another example: the outbound Oracle JMS Adapter facilitates asynchronous request/response by propagating the correlationId
and the JMSReplyTo
address as JMS headers. In Oracle BPEL Process Manager and Mediator, users can access, manipulate, and set headers with varying degrees of UI support.
For more information, see Correlation Support Within Adapters.
Propagating Headers in a Normalized Message:
Normalized Message is simplified to have only two parts, properties and payload.Typically, properties are name-value pairs of scalar types. To fit the existing complex headers into properties, they are flattened into scalar types.
Manipulating Headers in Design-Time:
The user experience while manipulating headers in design time is simplified, because the complex properties are predetermined. In Mediator, or Oracle BPEL designer, you can manipulate the headers with some reserved key words. For example, in Mediator designer, you can access an inbound Oracle File Adapter, fileName
header by using the following expression:
$nmproperty.InboundFileHeaderType.fileName
However, this method does not address the properties that are dynamically generated based on your input. For example, in the Oracle AQ Adapter Wizard, you are allowed to propagate some of the fields from an AQ object as headers. Based on this user choice, the header definitions are generated. These definitions are not predetermined and hence cannot be accounted for in the list of predetermined property definitions. The user cannot design header manipulation of the dynamic properties before they are defined. To address this limitation, you must generate all the necessary services (composite entry points) and references. This restriction applies only to those services that are expected to generate dynamic properties. Once dynamic properties are generated, they must be captured in some given location for each composite. Only then can the user manipulate the dynamic properties in the Oracle Mediator or Oracle BPEL designer.
Supports specifying a durable JMS subscriber
Supports persistent and nonpersistent modes of a JMS publisher
Does not support outbound retry functionality for AQJMS on Solaris
Note:
When you use the Oracle JMS Adapter to connect to an AQ-JMS provider, and if the database that hosts the AQ destination is 10.1.0.4, then the adapter retry mechanism on the outbound direction fails to reconnect to the database server if the database server goes down. This is because of a client JDBC issue with ojdbc14.jar
. To resolve this you must download the 10.1.0.4 JDBC drivers and use them in the mid tier by replacing the libraries, specifically ojdbc14.jar in $MIDTIER_ORACLE_HOME/jdbc
. For a detailed explanation about how to resolve this issue, refer to Metalink Note 317385.1.
The JMS API specifies three types of acknowledgments that can be sent by the JMS publisher:
DUPS_OK_ACKNOWLEDGE
, for consumers that are not concerned about duplicate messages
AUTO_ACKNOWLEDGE
, in which the session automatically acknowledges the receipt of a message
CLIENT_ACKNOWLEDGE
, in which the client acknowledges the message by calling the message's acknowledge method
Supports tracking message size
The Oracle JMS Adapter is message size aware. The Oracle JMS Adapter calculates the message size and reports the size back to the JCA Binding Component. The API, related to size, exposed by the JCA Binding Component can be used for reporting purposes.
Configuring MapMessage Support in JMS Adapter MapMessage Data Type
A MapMessage
is used to send a set of name-value pairs where names are strings and values are Java primitive types. The entries can be accessed sequentially or randomly by name. The order of the entries is undefined. It inherits from a message and adds a map message body.
Oracle JMS adapter provides support for processing MapMessage
. It now supports one new ActivationSpec and InteractionSpec property, namely JmsMapMessageConsumeActivationSpec
and JmsMapMessageProduceInteractionSpec
.
The following use cases are supported:
Use Case 1.
Entire JMS MapMessage object is processed as payload.
If both PayloadEntry and AttachmentList properties are not defined, the entire JMS MapMessage is converted to XML and the XML file is transferred as the payload. For this use case, both PayloadEntry
and AttachmentList
properties are optional. The following schema is used for conversion:
<schema targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/jms/MapMessage" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/jms/MapMessage" elementFormDefault="qualified"> <element name="MapMessage"> <complexType> <choice maxOccurs="unbounded"> <element name="entry"> <complexType> <simpleContent> <extension base="string"> <attribute name="name" type="string"/> <attribute name="dt" type="string"/> </extension> </simpleContent> </complexType> </element> </choice> </complexType> </element> </schema>
The attribute name
is the name part of the name value pair for a JMS MapMessage entry.
The attribute dt
can have one of the following string values.
Boolean
Byte
Short
Integer
Long
Float
Double
String
Char
ByteArray
Use Case 2. A MapMessage entry (name-value pair) is processed as payload
The PayloadEntry
property specifies that the JMS MapMessage entry name (referring to the name-value pair that should be processed) to be is used as the payload. You have the option to send the payload as an attachment if the AttachmentList
property is defined instead of PayloadEntry
. For this use case, either PayloadEntry
or AttachmentList
property should be specified but not both.
All other MapMessage entries are converted to adapter properties identified by jca.jms.Map.xxxx
, where xxxx
is name of the JMS MapMessage entry (name-value pair).
For the JMS MapMessage sample, see the following samples by accessing the latest SOA Sample code under Middleware & Tools from Sample Code for Developers and Admins page: adapters-jms-104-wlsjms-mapmessage.
Supports Enterprise Information System (EIS) Credentials
The Oracle JMS Adapter supports securing of the Enterprise Information System (EIS) credentials such as the user name and password, whenever it establishes an outbound connection with EIS. You can secure the user name and password for Oracle JMS Adapter by using Oracle WebLogic Server container-managed sign-on.
For more information about support for securing of the Enterprise Information System (EIS) credentials, see Securing Enterprise Information System Credentials.
Supports Streaming Large Payload
Oracle JMS Adapter provides support to stream payload. When you enable this feature, the payload is streamed to a database instead of getting manipulated in the SOA runtime as in a memory DOM. This feature can be used while handling large payloads. To enable support to stream payload, ensure that you select the Enable Streaming check box while defining the consume operation parameters on the Consume Operation Parameters page in Oracle JDeveloper. When the Enable Streaming check box is selected, a corresponding Boolean property EnableStreaming
is appended to the ActivationSpec
properties defined in the respective .jca
file, as shown in the following example. If the EnableStreaming
property does not exist, then the default value of false is assumed.
<activation-spec className="oracle.tip.adapter.jms.inbound. JmsConsumeActivationSpec"> <property name="DestinationName" value="jms/DemoInQueue"/> <property name="UseMessageListener" value="false"/> <property name="PayloadType" value="TextMessage"/> <property name="EnableStreaming" value="true"/> </activation-spec>
Supports Transactions
A transaction enables an application to coordinate a group of messages for production and consumption, treating messages sent or received as a single unit. When an application commits a transaction, all messages it received within the transaction are removed by the JMS provider. The messages it sent within the transaction are delivered as one unit to all JMS consumers. If the application rolls back the transaction, then the messages it received within the transaction are returned to the messaging system and the messages it sent are discarded. The Oracle JMS Adapter supports JMS transactions. A JMS-transacted session supports transactions that are located within the session. A JMS-transacted session's transaction does not have any effects outside of the session.
Supports Error Handling
For information about error handling, refer to Error Handling.
Supports Multiple Consumer Threads
The Oracle JMS Adapter supports an activation endpoint property, adapter.jms.receive.threads
. Setting this property in composite.xml is a preferred way to spawn multiple poller threads for the inbound message flow between the adapter and the Enterprise Information System (EIS). This helps improve performance because multiple poller threads dequeue messages in a round robin fashion; this assists in Distributed scenarios as well.
Note:
When resiliency is enabled and Oracle Event Delivery Network (EDN) subscriber is in quiescent mode, the EDN consumer threads enter into sleep mode. Based on the configuration, for example, MaxStuckThreadTime = 600
(seconds), the sleeping EDN consumer threads are marked as STUCK when the configured MaxStuckThreadTime
is elapsed. These STUCK logging statements in server log are temporary warnings, and have no functional impact. Once the quiescence mode is over and resiliency resumes incoming request processing, these STUCK warnings vanish, and normal processing is resumed.
SOA_Request_WM and SOA_EDN_WM also share the same max constraint. When the number of threads of EDN subscribers is larger than the max constraint, it impacts SOA_Request_WM performance. The work around is either reduce the number of threads of EDN subscribers or increase the max constraint defined by SOAIncomingRequests_maxThreads
Supports Performance Tuning
The Oracle JMS Adapter supports performance tuning. For more information, see Oracle JCA Adapter Tuning Guide and Oracle JCA Adapter Properties.
Note:
Oracle JMS Adapter cannot be used programmatically inside an EJB or JMS client.
Messaging is any mechanism that enables communication between programs. Messages are structured data that one application sends to another. Message-oriented middleware (MOM) is an infrastructure that supports scalable enterprise messaging. MOM ensures fast, and reliable asynchronous communication, guaranteed message delivery, receipt notification, and transaction control.
JMS is a Java interface developed by Sun Microsystems for producing, sending, and receiving messages of an enterprise messaging system. JMS is an API that JMS vendors implement. Oracle provides two implementations of JMS, WLS JMS and Oracle JMS based on Oracle advanced queues. A JMS producer creates JMS messages and a JMS consumer consumes JMS messages.
JMS supports two messaging paradigms, point-to-point (queues) and publish/subscribe (topics).
In point-to-point messaging, the messages are stored in a queue until they are consumed. One or more producers write to the queue and one or more consumers extract messages from the queue. The JMS consumer sends an acknowledgment after consumption of a message; this results in purging of the message from the queue.
In publish/subscribe messaging, producers publish messages to a topic, and the consumer subscribes to a particular topic. Many publishers can publish to the same topic, and many consumers can subscribe to the same topic. All messages published to the topic by the producers are received by all consumers subscribed to the topic. By default, subscribers receive messages only when the subscribers are active. However, JMS API supports durable subscriptions that ensure that consumers receive messages that were published even when the subscribers are not up and running. The durable subscription involves registering the consumer with a unique ID for retrieving messages that were sent when the consumer was inactive. These messages are persisted by the JMS provider and are either sent to the consumer when it becomes active again or purged from storage if the message expires. The JMS producer can be set either to persistent or nonpersistent mode. The messages are not persisted in the latter case and can be used only for nondurable subscriptions.
For scenarios that requires you to work with durable subscriptions on Oracle WebLogic Server, a connector factory with ClientID
property defined is required, as shown in the following example:
<FactoryProperties>ClientID=uniquename</FactoryProperties>
When defining multiple durable subscriber it would entail you to define multiple connector factory each with a unique ClientID
property specified. You must take care to not use the same connector factory for any other adapter interaction (such as outbound interaction if it is used for processing inbound messages) because Oracle WebLogic Server allows a clientid
to be bound only once. For a scenario in which a connector factory with ClientId
defined is used on the inbound to process incoming messages a different connector factory should be used for the outbound adapter interactions.
Note:
You must manually remove durable subscribers that are not used by the BPEL partner link. Oracle JMS Adapter does not automatically remove these durable subscriptions.
The JMS API supports both synchronous and asynchronous communication for message consumption. In the synchronous case, the consumer explicitly calls the receive()
method on the topic or queue. In the asynchronous case, the JMS client registers a message listener for the topic or queue and the message is delivered by calling the listener's onMessage()
method.
The destination property contains the addressing information for a JMS queue or topic.Connections represent a physical connection to the JMS provider. The connection factory is used to create JMS connections. A session is used to create a destination, JMS producer, and JMS consumer objects for a queue or topic.
The JMS message has a mandatory standard header element, an optional properties element, and an optional standard payload element. The payload can be a text message, byte message, map message, stream message, or object message. The properties element is JMS provider-specific and varies from one JMS provider to another.
For information about the Oracle JMS Adapter header properties, see Oracle JMS Adapter Properties.
JMS Adapter can communicate with TIBCO,IBM MQ Series, and other certified third- party Service Providers. If these service providers are stopped and subsequently restarted, the JMS Adapter can successfully connect to them and process any pending messages.
Perform the following steps to ensure connection occurs correctly:
In setDomainEnv.sh
, a startup script for SOA and the WebLogic Console, set
-Dweblogic.transaction.blocking.commit=false
and
-Dweblogic.transaction.blocking.rollback=false
In the WebLogic Console, proceed to -->domain --- > JTA ----- > Advanced ----> CompletionTimeoutSeconds, and set CompletionTimeoutSeconds
to 0.
A property,
"adapter.jms.DistributedDestinationConnectionEveryMember" is available as the Service binding property for the JMS Adapter.
This property takes boolean values [true | false]. Default value is "true ".
When true, the JMS Adapter creates a consumer/subscriber for each member of the Distributed Destinations. If set to false, the JMS Adapter creates a consumer/subscriber for only local members of the distributed destination.When the JMS Adapter is connecting to distributed destination on a remote cluster or a server on remote domain, the property
'adapter.jms.DistributedDestinationConnectionEveryMember' should always be set to true. When the JMS Adapter is connecting to distributed destination on a local cluster, the property can be set to either true or false. If set to true, the JMS Adapter behavior remains the same as before (that is, there is a consumer for each Distributed Destination is created). If set to false, the JMS Adapter only creates consumer/subscriber for the local members.
You will not see this property in the JDeveloper User Interface as a binding property on Service side. Consequently, you must manually add it in the composite.xml as shown below under the <service>/<binding.jca>
tag :
<property name="adapter.jms.DistributedDestinationConnectionEveryMember" type="xs:string" many="false" override="may">false</property>
The section discusses the following uses cases of Oracle JMS Adapter.
Accessing Queues and Topics from WLS JMS Server in a Remote Oracle WebLogic Server Domain
Accessing Queues and Topics Created in 11g from the OC4J 10.1.3.4 Server
Configuring the 11G Server or Later Server to Access Queues Present in 10.1.3.X OC4J .
Accessing Distributed Destinations (Queues and Topics) on the WebLogic Server JMS .
Configuring Oracle JMS Adapter with IBM WebSphere Default JMS Provider
The following use case demonstrates the procedure for configuring Oracle JMS Adapter and examines the resulting WSDL files and associated weblogic-ra.xml
files.
This section includes the following topics:
You must first create an JDeveloper application to contain the SOA composite. Use the following steps to create a new application and a SOA project:
The following are the steps to configure an Oracle JMS Adapter by using the Adapter Configuration Wizard:
The following composite file is generated by the Adapter Configuration Wizard:
<composite name="AQQueue2Queue"revision="1.0" label="2007-09-04_11-58-50_914"mode="active"state="on" xmlns="http://xmlns.oracle.com/sca/1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:orawsp="http://schemas.oracle.com /ws/2006/01/policy"> <import namespace="http://xmlns.oracle.com/pcbpel/adapter /jms/Inbound/"location="Inbound.wsdl" importType="wsdl"/> <import namespace="http://xmlns.oracle.com/pcbpel/ adapter/jms/Outbound/"location="Outbound.wsdl" importType="wsdl"/> <service name="Inbound"> <interface.wsdl interface="http://xmlns.oracle.com/pcbpel/ adapter/jms/Inbound/#wsdl.interface (Consume_Message_ptt)"/> <binding.jca config="Inbound_jms.jca"/> </service> <component name="BPELProcess1"> <implementation.bpel src="BPELProcess1.bpel"/> </component> <reference name="Outbound"> <interface.wsdl interface= "http://xmlns.oracle.com/pcbpel/adapter /jms/Outbound/#wsdl.interface (Produce_Message_ptt)"/> <binding.jca config="Outbound_jms.jca"/> </reference> <wire> <source.uri>Inbound</source.uri> <target.uri>BPELProcess1/Inbound</target.uri> </wire> <wire> <source.uri>BPELProcess1/Outbound</source.uri> <target.uri>Outbound</target.uri> </wire> </composite>
The following code segment defines the name of the adapter and the locations of various necessary schemas and other definition files.
<import namespace="http://xmlns.oracle.com/pcbpel /adapter/jms/Inbound/"location="Inbound.wsdl" importType="wsdl"/> <import namespace="http://xmlns.oracle.com /pcbpel/adapter/jms/Outbound/"location= "Outbound.wsdl" importType="wsdl"/>
This code segment imports the necessary namespace.
<definitions name="Inbound" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/jms/Inbound/" xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" xmlns:imp1="http://xmlns.oracle.com/pcbpel/samples/expense"> <types> <schema xmlns="http://www.w3.org/2001/XMLSchema"> <import namespace="http://xmlns.oracle.com/pcbpel/samples/expense" schemaLocation="xsd/expense.xsd"/> </schema> </types> <message name="ExpenseRecord_msg"> <part name="ExpenseRecord" element="imp1:ExpenseRecord"/> </message> <portType name="Consume_Message_ptt"> <operation name="Consume_Message"> <input message="tns:ExpenseRecord_msg"/> </operation> </portType>
This code segment defines the message type, name, and the port type for the partner link.
<adapter-config name="dequeue" adapter="Jms Adapter xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata"> <connection-factory location="eis/wls/Queue" UIConnectionName="wls3" UIJmsProvider="WLSJMS" adapterRef=""/> <endpoint-activation portType="Consume_Message_ptt" operation="Consume_ Message"> <activation-spec className="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec"> <property name="DestinationName" value="jms/DemoInQueue"/> <property name="UseMessageListener" value="false"/> <property name="PayloadType" value="TextMessage"/> </activation-spec> </endpoint-activation> </adapter-config>
The weblogic-ra.xml
file defines the endpoints for the JMS connection factories. The connection factories include configuration properties for each endpoint. Endpoints are added to accommodate different types of connections, as demonstrated in the following sections. The following example is from the generic weblogic-ra.xml
file:
<connection-instance> <jndi-name>eis/wls/Queue</jndi-name> <connection-properties> <properties> <property> <name>ConnectionFactoryLocation</name> <value>weblogic.jms.XAConnectionFactory</value> </property> <property> <name>FactoryProperties</name> <value></value> </property> <property> <name>AcknowledgeMode</name> <value>AUTO_ACKNOWLEDGE</value> </property> <property> <name>IsTopic</name> <value>false</value> </property> <property> <name>IsTransacted</name> <value>false</value> </property> <property> <name>Username</name> <value></value> </property> <property> <name>Password</name> <value></value> </property> </properties> </connection-properties> </connection-instance>
You can also create a new connection by using the Oracle WebLogic Server Administration Console. The following are the steps for creating a new connection by using the Oracle WebLogic Server Administration Console:
You can specify that the adapter use a third-party JMS Provider for non-Web Logic Server JMS and non-AQJMS connection instances, by supplying a value to the FactoryProperties parameter in the weblogic-ra.xml
file. Specifically, you can provide the ThirdPartyJMSProvider
value to the FactoryProperties parameter. This property is required only when you deploy an adapter to the WebLogic Server.
When this value is set to true, the JMS Adapter does not use DestinationAvailabilityListener
for creating consumers for processing of JMS messages. The default is false. You must ensure you employ code similar to the following snippet:
<property> <name>FactoryProperties</name> <value>ThirdPartyJMSProvider=true</value> </property>
Note:
All pre-populated connection instances on a WebLogic Server reflect the change and consequently, no further tuning is required for those instances. Only when a new non WLS JMS or AQJMS provider access is required do you must add new a connection instance and therefore the ThirdPartyJMSProvider
property.
A produce message operation has certain differences in the definition procedure, particularly in Step 13 of Using the Adapter Configuration Wizard to Configure . Instead of specifying consume operation parameters, you specify the following produce operation parameters. This enables the adapter to produce (send) outbound messages for a JMS destination. The Produce Operation Parameters page is shown in Figure 8-13.
Destination Name:
The JNDI name of the JMS queue or topic to which the message must be delivered. The name to enter is based on the type of JMS provider you use.
For more information about destination name, see the following:
Message Body Type:
The supported values are TextMessage
, BytesMessage
, and MapMessage
. StreamMessage
is not supported in this release.
Delivery Mode:
The values are Persistent
or Nonpersistent
. A persistent delivery mode specifies a persistent JMS publisher; that is, a publisher that stores messages for later use by a durable subscriber. A durable subscriber is a consume message with a durable subscriber ID in the corresponding field in Step 15 of Using the Adapter Configuration Wizard to Configure . A nondurable subscriber loses any messages that are produced when the adapter is not active. A durable subscriber downloads messages that have been stored in the persistent publisher, and therefore does not have to remain active at all time to receive all the messages.
Priority:
Select a priority value, with 9
representing the highest priority and 0
representing the lowest priority. The default is 4
.
TimeToLive:
The amount of time before the message expires and is no longer available to be consumed.
Unit of order
This parameter only applies when the selected JMS Provider is a WebLogic Server JMS provider. It enables a message producer or group of message producers acting as one, to group messages into a single unit that is processed sequentially in the order the messages were created. The message processing of a single message is complete when a message is acknowledged, committed, recovered, or rolled back. Until message processing for a message is complete, the remaining unprocessed messages for that Unit of Order are blocked. This Unit of order
property enables you to set the unit-of-order value for the MessageProducer when producing a message. Refer to the Use Case “Using the WLS JMS Unit-of-Order with the JMS Adapter", and “Using Message Unit-of-Order" in Developing JMS Applications for Oracle WebLogic Server.
JNDI Name
This field enables you to specify the JNDI name for the JMS connection. The deployment descriptor for the deployed instance of the JMS Adapter must associate this JNDI name with a set of configuration properties required by the JMS Adapter to access the JNDI destination at runtime.
Figure 8-13 Produce Operation Parameters Page
This section describes how to configure Oracle JMS Adapter with Tibco JMS for direct connection and non direct connection.
Note:
Read the entire section before making configuration changes, as not all information is available in each subsection. Information related to TIBCO Enterprise Message Service is based on TIBCO Enterprise Message Service User's Guide, Software Release 6.3, February 2012. Refer to TIBCO's documents for latest updates.
Also, note that in the following discussion EMS_HOME
stands for Tibco Enterprise Message Service installation directory.
Use the TIBCO Enterprise Message Service Administration Tool to create a connection factory and queue/topic.
A preconfigured connection factory is often the preferred mechanism; however, Tibco does provide support for dynamically created connection factories. To use these,
You can use a pre-configured Tibco Connection Factory for SSL Connections. To so, you must configure the Tibco server to support SSL.
This section describes how to configure Oracle JMS Adapter with IBM WebSphere MQ JMS for non-XA and XA data sources.
Perform the following steps:
You can configure the JMS Adapter to connect with IBM WebSphere MQ JMS and to use a Multi-Instance Queue Manager.
To do so, use a custom property called connectionNameList
. You can use this property to specify the names and ports of the different instances.
QueueManager=QM1;TransportType=1; ConnectionNameList=slj01aml.us.domain.com(141 4),acb113114.us.domain.com(1414); Channel=SYSTEM.DEF.SVRCONN;ThirdPartyJMSProv ider=true;ClientReconnectOptions=0
This section describes how to configure Oracle JMS Adapter with Active MQ JMS (non-XA only).
Perform the following steps:Copy the following files to the <SOAInstall_DIR>/user_projects/domains/<DOMAIN_NAME>/lib
folder:
/<YOUR-ACTIVEMQ-INSTALL-LOCATION>//activemq-all-5.8.0.jar
Configure the connector factory by modifying the weblogic-ra.xml
file in AS11gR1SOA/soa/connectors/JmsAdapter.rar
as shown in the following example:
<connection-instance> <jndi-name>eis/activemq/Queue</jndi-name> <connection-properties> <properties> <property> <name>ConnectionFactoryLocation</name> <value>org.apache.activemq. ActiveMQConnectionFactory</value> </property> <property> <name>FactoryProperties</name> <value>BrokerURL=tcp://<YOUR-HOST>: <YOUR-PORT>;ThirdPartyJMSProvider=true</value> </property> <property> <name>AcknowledgeMode</name> <value>AUTO_ACKNOWLEDGE</value> </property> <property> <name>IsTopic</name> <value>false</value> </property> <property> <name>IsTransacted</name> <value>true</value> </property> <property> <name>Username</name> <value></value> </property> <property> <name>Password</name> <value></value> </property> </properties> </connection-properties> </connection-instance>
Alternatively, to configure a new connection factory by using the Oracle WebLogic Server Administration Console, use the steps mentioned in Adding an Adapter Connection Factory.
For ActiveMQ Series v5.8, there is XA Support and the Connection Factory to be configured for XA is org.apache.activemq.ActiveMQXAConnectionFactory
. This has been certified with the current release of the JMS Adapter.
This WebLogic Server JMS text message use case for Oracle BPEL PM demonstrates how the Oracle JMS Adapter dequeues from and enqueues to the WebLogicServer JMS Queue.
In the case of a WLS JMS text message scenario for a Mediator business process, you must have the following files from the artifacts.zip
file contained in the adapters-jms-101-wlsjms-textmessageusingqueues
sample:
artifacts/schemas/expense.xsd
You can obtain the adapters-jms-101-wlsjms-textmessageusingqueues
sample by accessing the Oracle SOA Sample Code site.
This section includes the following topics:
You must perform the following prerequisite for the WebLogic Server JMS text message use case for Oracle BPEL PM.
Perform the following steps to create queues required for this use case:
Create the Q2Qorders.xsd file by using the following code:
<?xml version="1.0" ?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd" targetNamespace="http://xmlns.oracle.com/ pcbpel/nxsd/extensions/FileInbound" xmlns:tns="http://xmlns.oracle.com/ pcbpel/nxsd/extensions/FileInbound" elementFormDefault="qualified" attributeFormDefault="unqualified" nxsd:encoding="US-ASCII" nxsd:stream="chars" nxsd:version="NXSD"> <xsd:element name="Items"> <xsd:complexType> <xsd:sequence> <xsd:element name="item" minOccurs="1" maxOccurs="unbounded"> <xsd:complexType> <xsd:sequence> <xsd:element name="Name" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="""> </xsd:element> <xsd:element name="Type" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="""> </xsd:element> <xsd:element name="Quantity" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="," nxsd:quotedBy="""> </xsd:element> <xsd:element name="Rate" type="xsd:string" nxsd:style="terminated" nxsd:terminatedBy="${eol}" nxsd:quotedBy="""> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema> <!--NXSDWIZ:C:\errors\inputFiles\orders.txt:-->
You must establish connectivity between the design-time environment and the server you want to deploy to. Perform the steps mentioned in Creating an Application Server Connection for Oracle JCA Adapters to create an application server connection.
You must create an JDeveloper application to contain the SOA composite. Use the following steps to create an application and an SOA project:
Perform the following steps to create an adapter service that dequeues the message to a queue:
Perform the following steps to create an adapter service to enqueue the request messages and dequeue the corresponding response messages (report) from a queue:
Q2Qorders.xsd
schema file is displayed in the URL in the Message dialog.composite.xml
page is displayed.You must wire the three components that you have created, Inbound adapter service, BPEL process, and Outbound adapter reference. Perform the following steps to wire components:
You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, use the following steps:
You can use the Oracle JMS Adapter to access remote WLS JMS destinations. Remote destinations refer to queues or topics that are defined in a WLS JMS server, which is part of a remote Oracle WebLogic Server domain.
To do so, ensure that you use the connector factory configured to interact to the remote WLS JMS server. You can achieve this by setting the <FactoryProperties> property of the connector factory defined in weblogic-ra.xml
to remote server configuration, as shown in the following example:
<property> <name>FactoryProperties</name> <value>java.naming.factory.initial =weblogic.jndi.WLInitialContextFactory; java.naming.provider.url= t3://<HOST>:<PORT>; java.naming.security.principal= <USERNAME>;java.naming.security.credentials =<PASSWORD> </value> </property>
To enable the Oracle JMS Adapter to read from a remote queue that is present in a remote WLS JMS server, you must configure the following:
You must have a unique domain name and JMS server name in both the servers.
You must enable global trust between the two servers.
Refer to the following link for information about how to enable global trust between servers:
This configuration is appropriate when you connect to queues or topics present in WLS9.2 server.
Note:
When using the JMS adapter to access WebLogic Server secure queues (local or remote domains), ensure that java.naming.security.principal
and java.naming.security.credentials
in the FactoryProperties property are setup correctly with a user who has access to the WLS secure queues.
The JMS Adapter enables you to interact with WebLogic Server JMS destination locations in a domain that are remote to the WebLogicServer domain where SOA is installed.
Two options are supported that enable you to access remote destinations using the JMS adapter:
Direct access using specification of the FactoryProperties
property in the weblogic-ra.xml
file, with access parameters indicating the remote domain.
Configuring the foreign server to access the remote domain.
For inbound use cases, both options are supported. For outbound use cases only, direct access is supported, but configuring the foreign server is not supported.
The Oracle JMS Adapter supports both synchronous and asynchronous request reply interaction patterns.
You can use the Adapter Configuration Wizard to model a process that enables the Oracle JMS Adapter to be used in a synchronous request reply interaction pattern. In this case, the Oracle JMS Adapter sends a request to the request queue and waits for a response from the reply queue before further execution continues.
Underneath, the Oracle JMS Adapter uses a new interaction pattern, JmsRequestReplyInteractionSpec
. This interaction spec allows for a request and reply destination name to be configured.
A variation enables usage of a temporary destination as part of the reply queue. Basically, this pattern enables an Oracle JMS Adapter to send a message to a JMS destination. In turn, the Adapter sets the JMSReplyTo
header to the reply destination.
This value is then used by a third-party client to send the message to the reply destination which is then dequeued by the Oracle JMS Adapter.
When using the Oracle JMS Adapter in a synchronous pattern, you can use an XA ConnectionFactory for JMS or BPEL incoming events, and set the connector factory isTransacted
property to true
in weblogic-ra.xml
. However, if you are using a web service, ensure that you use a non-XA ConnectionFactory, and set the connector factory isTransacted
property to true
in weblogic-ra.xml
.
When you use the Oracle JMS Adapter in a synchronous pattern with Oracle WebLogic Server JMS, the connection factory must be weblogic.jms.ConnectionFactory
or any other non-XA connection factory. Also, if Oracle WebLogic Server JMS is running in the local JVM (the same JVM as the adapter), then you must ensure that the connector factory isTransacted
property is set to false
in weblogic-ra.xml
. You can obtain the following samples by accessing the Oracle sample code site:
adapters-jms-106-wlsjms-syncrequestreply
adapters-jms-107-wlsjms-syncrequestreplywithtemporaryreplydestination
You can use the Adapter Configuration Wizard to model a process that allows Oracle JMS Adapter to be used in an asynchronous request reply interaction pattern.
Basically this pattern allows an JMS Oracle JMS Adapter to send a message to a JMS destination. When a message is received on the reply queue, the Oracle JMS Adapter can route messages to the correct composite or the component instance. The correlation is done based on the JMSMessageID
of the request message, which becomes the JMSCorrelationID
of the reply message, and the conversation ID of the underlying component.
For more information, see the following samples by accessing the Oracle sample code site:
adapters-jms-105-wlsjms-nativecorrelation
This use case demonstrates how the Oracle JMS Adapter dequeues from and enqueues to the AQ JMS Queue.
You can obtain the adapters-jms-108-aqjms-textmessageusingqueues
sample by accessing the Oracle SOA Sample Code site.
This section includes the following topics:
You must perform the following prerequisites to complete this use case:
To configure AQ JMS in Oracle WebLogic Server Administration Console, you must perform the following steps:
Adding an Oracle WebLogic JMS Module
Note that adding an Oracle WebLogic JMS module is optional. You can also create an AQJMS foreign server in a preexisting JMS module.
Navigate to the Oracle WebLogic Server JMS: http://
servername
:
portnumber
/console
.
Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.
The Home page of the Oracle WebLogic Server Administration Console is displayed.
Navigate to Services, Messaging, JMS Modules in the Domain Structure pane.
The Oracle WebLogic Server Administration Console - JMS Modules page is displayed.
Click New to create a new WebLogic JMS module.
The Oracle WebLogic Server Administration Console - Create JMS System Module page is displayed.
Enter a name for the JMS module, and then click Next.
The Oracle WebLogic Server Administration Console-Create JMS System Module page is displayed.
Select a target server where your SOA component is running, and then click Next.
The Oracle WebLogic Server Administration Console - Create JMS System Module page is displayed.
Click Finish.
You have created a JMS module.
Adding an AQJMS Foreign Server to the JMS Module
The next step is to add an AQ JMS foreign server to the JMS module by performing the following:
Click the JMS module that you created.
The Oracle WebLogic Server Administration Console - Settings for AQJMS Module page is displayed.
Click New in the Summary of Resources table to create a new JMS system module resource.
The Oracle WebLogic Server Administration Console - Create a New JMS System Module Resource page is displayed.
Under Choose the type of resource you want to create, select Foreign Server, and click Next.
The Oracle WebLogic Server Administration Console - Create a New JMS System Module Resource page is displayed.
In the Name field, enter a name for the foreign server, and then click Finish.
The Oracle WebLogic Server Administration Console - Settings for <JMS Module Name> page is displayed.
Configuring the AQJMS Foreign Server
The next step is to configure the AQJMS foreign server that you created:
Click the AQ JMS Foreign Server listed under the Summary of Resources table.
The Oracle WebLogic Server Administration Console - Settings for TestAQJMS_ForeignServer page is displayed.
Enter the following values:
JNDI Initial Context Factory: oracle.jms.AQjmsInitialContextFactory
If the AQJMS Foreign Server is used by the WebLogic server side components, then you must configure a data source with this AQ JMS Foreign Server, by specifying the following values:
In the JNDI Properties field, enter datasource=<datasource jndi location>. Replace the place holder with the JNDI location of your data source.
However, if the AQJMS Foreign Server is used by WebLogic application client, then you must configure the JDBC URL with the AQ JMS foreign server you created.
JNDI Connection URL: Specify the URL that WebLogic Server uses to contact the JNDI provider.
This value is required only if the AQJMS foreign server is used by the WebLogic application client.
JNDI Properties Credential: Specify any Credentials that must be set for the JNDI provider.
This value is required only if the AQJMS foreign server is used by the Weblogic application client.
Note:
If you want to use an Oracle RAC database as adapter endpoint, the datasource pointed by the JNDI property, mentioned in the preceding step, must point to a multi data source.
Individual data sources and multi data sources used for such endpoints must use the recommended setting listed in Recommended Setting for Data Sources Used by Oracle JCA Adapters.
Adding Connection Factories to the AQ JMS Foreign Server
To add connection factories to the AQJMS foreign server:
In the Connection Factories tab in the Settings for <Foreign Server Name> page, select the AQJMS foreign server that you created.
Click New.
The Oracle WebLogic Server Administration Console - Create a New Foreign JMS Connection Factory page is displayed.
In the Name field, enter a name for this connection factory. This is a logical name that would be referenced by Oracle WebLogic Server.
In the Local JNDI Name field, enter the local JNDI name that you would use in your application to look up this connection factory.
Note:
Ensure that you specify aqjms/XAQueueConnectionFactory
for local JNDI name if you are connecting to a queue with JNDI name eis/aqjms/Queue that is provided with the sample use case, AQQueuetoQueue
.
Else, specify aqjms/XATopicConnectionFactory
if you are connecting to a topic with JNDI name eis/aqjms/Topic
.
In the Remote JNDI Name field, enter one of the following values depending on your requirement. If you use this connection factory in a global transaction, then use an XA-based connection factory, else use non-XA based connection factory.
QueueConnectionFactory
TopicConnectionFactory
ConnectionFactory
XAQueueConnectionFactory
XATopicConnectionFactory
XAConnectionFactory
Click OK.
Adding Destinations to the AQJMS Foreign Server
To add destinations to the AQJMS foreign server:
Queues/<queue name>.
If the destination is a queue, or enter Topics/<topic name>
if the destination is a topic.You have configured AQJMS in an Oracle WebLogic Server.
To create queues:
setup_user.sql
script.create_start_queues.sql
script.These scripts are located in the adapters-jms-108-aqjms-textmessageusingqueues
sample artifacts/sql
directory. You can obtain the adapters-jms-108-aqjms-textmessageusingqueues
sample by accessing the Oracle SOA Sample Code site.
You must establish connectivity between the design-time environment and the server you want to deploy to. Perform the steps mentioned in Creating an Application Server Connection for Oracle JCA Adapters to create an application server connection.
You must create an JDeveloper application to contain the SOA composite. Use the following steps to create a new application and an SOA project:
Perform the following steps to create an adapter service to dequeue the message to a queue:
Perform the following steps to create an adapter service that enqueues the request messages and dequeue the corresponding response messages (report) from a queue:
You must wire the three components that you have created: Inbound adapter service, BPEL process, and Outbound adapter reference.
Perform the following steps to wire the components:
Note:
When using Oracle JMS Adapter to dequeue from AQ JMS Topics with durable subscriptions, if you notice that the dequeue operation exhibits slow performance, then you can speed up the entire performance by using multiple inbound threads for each adapter service.
Oracle JMS Adapter allows multiple inbound threads if you specify an endpoint property adapter.jms.receive.threads
.
However, this workaround is not applicable when using non-durable subscriptions because doing using the workaround in that scenario results in duplicate messages.
You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile by using JDeveloper, perform the following steps:
You can monitor the deployed composite by using the Fusion Middleware Control Console. Perform the following steps:
http://
servername
:portnumber
/em
. The composite you deployed is displayed in the Application Navigator.AQQueue2Queue
.java
.This section describes the procedure for accessing queues and topics you created in Oracle Application Server 11g or 12.1.3 from OC4J 10.1.3.4.
To do this, you must configure Oracle BPEL PM JMS adapter with Oracle WebLogic Server.
The following are the steps to configure Oracle BPEL PM JMS adapter with Oracle WebLogic Server:
Create the wlfullclient.jar
file using the following steps:
Change to the server/lib
directory, as shown in the following example:
cd WL_HOME/server/lib
Use the following command to create the wlfullclient.jar
file in the server/lib
directory:
java -jar ../../../modules/com.bea.core.jarbuilder_X.X.X.X.jar
where X.X.X.X
is the version number of the jarbuilder module in the WL_HOME
/server/lib
directory. For example:
java -jar ../../../modules/com.bea.core.jarbuilder_1.0.1.0.jar
Copy the wlfullclient.jar
file to the 10.1.3.4. server at the following location:
<ORACLEAS_HOME>/j2ee/<OC4J_INSTANCE>/connectors/ JmsAdapter/JmsAdapter
Configure the connector factory setting in the oc4j-ra.xml
file, as shown in the following example:
<connector-factory location="eis/wlsjms/Queue" connector-name="Jms Adapter"> <config-property name="connectionFactoryLocation" value="weblogic.jms.ConnectionFactory"/> <config-property name="factoryProperties" value="java.naming.factory.initial=weblogic.jndi. WLInitialContextFactory;java.naming.provider.url=t3: //<WLS-SERVER-NAME>: <WLS-SERVER-PORT>; java.naming.security.principal=<USER>; java.naming.security.credentials= <PASSWORD>"/> <config-property name="acknowledgeMode" value="AUTO_ACKNOWLEDGE"/> <config-property name="isTopic" value="false"/> <config-property name="isTransacted" value="false"/> <config-property name="username" value=""/> <config-property name="password" value=""/> <connection-pooling use="none"> </connection-pooling> <security-config use="none"> </security-config> </connector-factory>
Note:
The isTransacted
configuration property value must typically be set to FALSE
. Currently, XA integration with WebLogic JMS is not supported unless the adapter is deployed on the Oracle WebLogic Server. Also note that <WLS-SERVER-NAME>
must be replaced by the actual Weblogic Server name hosting the queues, and <WLS-SERVER-PORT>
must be replaced by the actual port value for Weblogic Server hosting the queues.
Modify the server.xml
file of the 10.1.3.4 server to include the environment-naming-url-factory-enabled="true"
property, as shown in the following example:
<application-server ... ... environment-naming-url-factory-enabled="true" ... >
Restart the 10.1.3.4 server to ensure the changes occur.
You can configure your 11G or later server to access queues present in 10.1.3.x OC4J with the following steps.
Copy the following jar files under the domains/<DOMAIN_NAME>/lib
folder of the WebLogic Server:
$J2EE_HOME/lib/jms.jar
$J2EE_HOME/lib/jta.jar
$J2EE_HOME/oc4jclient.jar
$AS_HOME/opmn/lib/optic.jar
The next step is to add the Connector Factory in the weblogic-ra.xml
file:
<connection-instance> <jndi-name>eis/oc4jjms/Queue</jndi-name> <connection-properties> <properties> <property> <name>ConnectionFactoryLocation</name> <value>jms/XAQueueConnectionFactory</value> </property> <property> <name>FactoryProperties</name> <value>java.naming.factory.initial=com. evermind.server.rmi.RMIInitialContextFactory; java.naming.provider.url= <PROVIDER_URL>; java.naming.security.principal=oc4jadmin; java.naming.security.credentials=welcome1</value> </property> <property> <name>AcknowledgeMode</name> <value>AUTO_ACKNOWLEDGE</value> </property> <property> <name>IsTopic</name> <value>false</value> </property> <property> <name>IsTransacted</name> <value>false</value> </property> <property> <name>Username</name> <value>oc4jadmin</value> </property> </property> <property> <name>Password</name> <value>welcome1</value> </property> </properties> </connection-properties> </connection-instance>
where <PROVIDER_URL>=opmn://localhost:6003
or ormi://localhost:12401
to use against a specific node or, opmn:ormi://localhost:6003:oc4j_soa
to use against the oc4j_soa
instance.
A distributed destination is a set of destinations (queues, set of physical JMS queue members, or topics, set of physical JMS topic members) that are accessible as a single, logical destination to a client.
Note:
For more information on distributed destinations, and a definition of terms used in this context, visit the Using Distributed Destinations pages at http://download.oracle.com/docs/cd/E13222_01/wls/docs103//jms/dds.html
The JMS Adapter can process messages addressed to a distributed destination member after receiving available notification; it can process available, unavailable, and failure notifications related to a distributed destination member.To have the JMS Adapter process such messages when working with Distributed Topics, you must provide additional properties.
When you provide additional properties, you can separate multiple FactoryProperty values with a semicolon. See the following example.
<property> <name>FactoryProperties</name> <value>ClientID=SOACLient2;TopicMessageDistributionAll=true</value> </property>
Also, in scenarios where the JMS adapter interacts with multiple WLS-managed servers in a cluster, you must specify all servers as part of the FactoryProperties
property. These are in turn used to establish correct context for lookup of JMS artifacts; see the following example:
<property> <name>FactoryProperties</name> <value> java.naming.factory.initial=weblogic.jndi. WLInitialContextFactory; java.naming.provider.url=t3://<server1>:<port1>, <server2>:<port2>; java.naming.security.principal= <username>;java.naming.security.credentials =<password> </value> </property>
Replace the brackets <> with values applicable for your environment.
You use three FactoryProperty parameter values to provide adapter access to distributed topics, to specifically enable the Client ID to be shared by multiple connections, to enable the sharing of Durable subscriptions among multiple subscribers, and to specify whether you want one copy of a message per application or per endpoint. The properties include:
ClientIDPolicy
Use the FactoryProperties parameter ClientIDPolicy
property with a value of UNRESTRICTED
to enable the Client ID to be shared by multiple connections. The default, if no value is specified, is UNRESTRICTED
. The non-default value is RESTRICTED
. The default is used in almost all cases, so typically you do not have to set it. See the following example:
</property> <name>FactoryProperties</name> <value>ClientIDPolicy=UNRESTRICTED</value> </property>
SubscriptionSharingPolicy
Use the FactoryProperties parameter with a value of SHARABLE
to enable the sharing of Durable Subscriptions among multiple subscribers.
A value of SubscriptionSharingPolicy EXCLUSIVE
means you cannot share Durable Subscriptions among multiple subscribers. If you do not specify a value, the default is SHARABLE
; in most cases, you do not have to change the value.
<property> <name>FactoryProperties</name> <value>SubscriptionSharingPolicy= SHARABLE</value> </property>
TopicMessageDistributionAll
See the section on Distributed Topics for more information on the TopicMessageDistributionAll
FactoryProperties parameter. You can set it as in the following example:
<property> <name>FactoryProperties</name> <value>TopicMessageDistributionAll=true</value> </property>
Specific inbound and outbound queue and error handling behaviors apply to the JMS Adapter with WebLogic Server JMS Distributed Queues and Distributed Topics.
For inbound queues, the JMS Adapter creates an inbound poller thread and registers a notification listener with the WebLogic Server JMS on endpoint activation; it unregisters notification listener upon endpoint deactivation.
Note:
Internally, that consumer is pinned to a member of the Distributed Queue. You must deploy the adapter with a large number of threads so that all members of the distributed queues could be accounted for.
From the SOA 11.1.1.4.0 version forward, the JMS Adapter fully supports both Distributed Queues and Topics. Newer versions of the JMS Adapter rely on notifications from the WebLogic Server JMS to create and remove consumers for the Distributed Destination members.
Comparing JMS adapter behavior in SOA 11.1.1.3.0 and prior versions (where a consumer is created randomly for more than one member of Distributed Queue) with the new behavior in SOA 11.1.1.4.0 and later, there is no change, except that the JMS Adapter is now able to account for all members without relying on your starting the JMS Adapter with large numbers of poller threads at activation.
The JMS Adapter handles errors in the Distributed environment in the same fashion as such errors are handled in a non-Distributed environment: retriable exceptions lead to message retry; non-retriable exceptions lead to message rejection.
There is no change from the behavior of other Adapters to JMS adapter behavior when the Adapter produces a message to a Distributed Queue.
JMS messages for Distributed Destinations are produced by creating a MessageProducer for the Distributed Destination and not for a specific member.
Outbound errors are processed based on fault-policies previously defined for the outbound reference.
For inbound adapters with distributed topics, the JMS Adapter registers a notification listener with the WebLogic Server JMS on endpoint activation. The JMS Adapter creates an inbound poller thread for each available notification received from WebLogic Server JMS for a Distributed Topic member.
The inbound poller thread stops working and necessary cleanup is performed if an unavailable notification is received for the member for which the poller thread was created. The durable subscription is maintained in a similar fashion as in a non-Distributed topic scenario.
The Adapter unregisters the notification listener upon endpoint deactivation. Any message arriving at a Distributed Topic is processed based on the various settings used and the type of Distributed Destination in use: either one copy of a message per application, or one copy of a message per adapter endpoint.
The behaviors for each of these types of Distributed Destination follow.
The default behavior for WebLogic Server Partitioned Distributed Topics when used with the JMS Adapter is to provide one copy of a message per application. Each message must be processed exactly once (that is, there is no duplicate processing.). In this scenario, where there is one copy of a message per application, the client id and subscription name are the same for every Distributed Destination and each adapter instance creates subscriptions on every member. The name is unique and immutable across server restarts.When using Partitioned Distributed Topics you must configure the JMS adapter to use unrestricted clientid and shared subscription policy. These two are the default settings for the JMS Adapter.When using Replicated Distributed Topics, you must configure JMS adapter to use the unrestricted clientid and shared subscription policy, which are the default settings. In addition, you must specify the following message selector, NOT JMS_WL_DDForwarded
when defining an activation spec.
To achieve better performance, you should use Partitioned Distributed Topics.
Refer to the following example, consisting of a snippet of a connection instance from the weblogic-ra.xml
file for a local cluster:
<property> <name>FactoryProperties</name> <value>ClientID=SOAClient1;</value> </property>
The second type of scenario you can employ with Distributed Topics is to have one copy of message per adapter endpoint. In this case, either the client id or the subscription name is unique for each adapter instance. The unique part of the member name is immutable across server restarts.
When using Partitioned Distributed Topics you have to configure the JMS Adapter to use unrestricted clientid and shared subscription policy, which are the default settings.
At the same time, to achieve subscription name uniqueness, the JMS Adapter requires that the property TopicMessageDistributionAll
(default value of false) is set to true. You can define this property by setting the FactoryProperties
property of the connection instance in the weblogic-ra.xml
file.
An example usage (a snippet of a connection instance from a weblogic-ra.xml
file for a local cluster) is:
<name>FactoryProperties</name> <value>ClientID=SOAClient2; TopicMessageDistributionAll=true</value> </property>
To achieve better performance, you should use Partitioned Distributed Topics.
When using Replicated Distributed Topics, configure the JMS Adapter to use unrestricted clientid and shared subscription policy, which are the default settings.
At the same time, to achieve subscription name uniqueness, the JMS adapter requires that the property TopicMessageDistributionAll
(default value of false) is set to true. You can define this property by setting the FactoryProperties
property of the connection instance in weblogic-ra.xml
. An example usage (snippet of connection instance from weblogic-ra.xml
for a local cluster) is:
<name>FactoryProperties</name> <value> ClientID=SOAClient2; TopicMessageDistributionAll=true</value> </property>
In addition, you must specify the message selector, NOT JMS_WL_DDForwarded
when defining an activation spec.
Specify a message selector when defining an activation spec. The message selector is required when you create one copy of message per adapter Endpoint.
To specify the selector, use the JMS Adapter Wizard when modeling a composite application that reads from Replicated Distributed Topic The metadata for the message selector you specify are captured in the .jca
file.
The following is an example of a message selector defined in an activation spec.This message selector filters out the copy of the forwarded message when sending a message to a destination subscriber.
This message selector is only applicable for when using Replicated Distributed Topics.
<activation-spec className="oracle.tip.adapter.jms.inbound.JmsConsumeActivationSpec"> <property name="DestinationName" value="jms/DemoInTopic"/> <property name="UseMessageListener" value="false"/> <property name="DurableSubscriber" value="dsub1"/> <property name="MessageSelector" value="NOT JMS_WL_DDForwarded"/> <property name="PayloadType" value="TextMessage"/> </activation-spec>
With Distributed Topics, retriable exceptions lead to message retry, while non- retriable exceptions lead to message rejection.
Available/Unavailable/Failure notification does not impact the working of the outbound adapter reference. The message is produced by creating a MessageProducer for the Distributed Destination and not for a specific member.
In the Distributed Topics environment, as elsewhere, an error is processed based on the fault policies defined for the outbound reference.
Remote Distributed Queue support is feasible back to WLS JMS version 9.0 using the DestinationAvailabilityListener API. A remote Distributed Topic cannot be supported if it is older than WebLogic 10.3.4, as “shared subscriptions", “unrestricted client ids", the “not forwarded" selector, and even “partitioned" Distributed Topics are not supported. You must instead directly reference a DT member JNDI name, and deal with the single subscriber per subscription limitation.
This section describes how to configure Oracle JMS Adapter for IBM WebSphere 7.x JMS.
Copy the following files from under the <WAS_INSTALL DIR>/fmwwas-nd/websphere/runtimes
directory to the SOAInstall_DIR>/user_projects/domains/<DOMAIN_NAME>/
lib folder:
com.ibm.jaxws.thinclient_7.0.0.jar
com.ibm.ws.admin.client_7.0.0.jar
com.ibm.ws.ejb.thinclient_7.0.0.jar
com.ibm.ws.jpa.thinclient_7.0.0.jar
com.ibm.ws.messagingClient.jar
com.ibm.ws.orb_7.0.0.jar
com.ibm.ws.sib.client.thin.jms_7.0.0.jar
com.ibm.ws.sib.client_ExpeditorDRE_7.0.0.jar
com.ibm.ws.webservices.thinclient_7.0.0.jar
ejb3exceptions.jar
sibc.jmsra.rar
sibc.nls.zip
Configure the connector factory by modifying the weblogic-ra.xml
file in the soa/connectors/JmsAdapter.rar
, as shown in the following example
Example - Configure the Connection Factory
<connection-instance> <jndi-name>eis/webspherejms/Queue</jndi-name> <connection-properties> <properties> <property> <name>ConnectionFactoryLocation</name> <value><QUEUE_CONECTION_FACTORY></value> </property> <property> <name>FactoryProperties</name> <value>java.naming.provider. url=iiop://<HOST_NAME>:<PORT>; java.naming.factory.initial=com.ibm. websphere.naming.WsnInitialContextFactory; java.naming.security.principal=<USERNAME>; java.naming.security.credentials=<PASSWORD>; ThirdPartyJMSProvider=true </value> </property> <property> <name>AcknowledgeMode</name> <value>AUTO_ACKNOWLEDGE</value> </property> <property> <name>IsTopic</name> <value>false</value> </property> <property> <name>IsTransacted</name> <value>true</value> </property> <property> <name>Username</name> <value><USERNAME></value> </property> <property> <name>Password</name> <value><PASSWORD></value> </property> </properties> </connection-properties> </connection-instance> <connection-instance> <jndi-name>eis/webspherejms/Topic</jndi-name> <connection-properties> <properties> <property> <name>ConnectionFactoryLocation</name> <value><TOPIC_CONECTION_FACTORY></value> </property> <property> <name>FactoryProperties</name> <value>java.naming.provider.url= iiop://<HOST_NAME>:<PORT>; java.naming.factory.initial=com.ibm.websphere. naming.WsnInitialContextFactory; java.naming.security.principal=<USERNAME>; java.naming.security.credentials=<PASSWORD>; ThirdPartyJMSProvider=true </value> </property> <property> <name>AcknowledgeMode</name> <value>AUTO_ACKNOWLEDGE</value> </property> <property> <name>IsTopic</name> <value>true</value> </property> <property> <name>IsTransacted</name> <value>true</value> </property> <property> <name>Username</name> <value><USERNAME></value> </property> <property> <name>Password</name> <value><PASSWORD></value> </property> </properties> </connection-properties> </connection-instance>
<QUEUE_CONECTION_FACTORY>
and <TOPIC_CONECTION_FACTORY
> refer to the JNDI name of the Queue and Topic connection factory, respectively created in WebSphere 7.0 for the default JMS provider.
Alternatively, you can configure a new connection factory by using the Oracle WebLogic Server Administration Console, and use the steps mentioned in Adding an Adapter Connection Factory.
Note:
The JMS Adapter can only be used in non-XA mode when interacting with WebSphere 7.x JMS.
The Request-Reply configuration feature enables you to perform the following:
Combine Request and Reply in a single configuration step. In the prior releases of the Oracle SOA Suite, you would require to configure two distinct adapters.
Automatic correlation without your needing to configure BPEL correlation set. This works seamlessly in Mediator and BPMN as well.
To configure the JMS Adapter Request-Reply feature:
Drag and drop a JMS Adapter onto the External References swim lane in the JDeveloper composite editor.
Figure 8-26 Dragging and Dropping a JMS Adapter into External References Swimlane
Enter default values for the first few screens in the JMS Configuration Adapter wizard until you reach the screen where the JMS Configuration Adapter wizard prompts you to enter the operation name. Select Request-Reply as the “Operation Type" and Asynchronous as “Operation Name".
Figure 8-27 Operations Screen for Request/Reply
Select the Request and Reply queues in the following screens of the wizard. The message is enqueued in the Request queue and the reply is returned in the Reply queue.
Figure 8-28 The Request Operation Parameters Screen
Figure 8-29 Reply Operation Parameters Screen
The reason we have used such a selector is that the back-end system that reads from the request queue and generates the response in the response queue actually generates more than one response and hence we must use a filter to exclude the unwanted responses.
Select the message schema for and a response.
Figure 8-30 Selecting Message Schema for Request and for Response
Add an <invoke> activity in BPEL corresponding to the JMS Adapter partner link. An additional header is set as the third-party application used requires this.
Figure 8-31 Invoke BPEL Properties Dialog Corresponding to the JMS Adapter Link
Add a <receive> activity just after the <invoke> activity, and select the Reply operation. Ensure that the Create Instance option is unchecked.
Figure 8-32 Receive Dialog for Reply Operation
You can use the SOA JMS Adapter to produce messages that create a specific unit-of-order for the messages.The Adapter InteractionSpec supports a property called UnitOfOrder
, which you configured when modelling an adapter reference, through the Produce Operations page of the JMS Adapter Configuration Wizard. See the description of this page in the section, "Produce Message Procedure".
You use this UnitOfOrder
property to set the unit-of-order value for the MessageProducer when producing a message. The new field is only visible if the JMS provider is WebLogic Server JMS.
The JMS Adapter enables you to override this unit-of-order used when producing a message to a WLS destination.
To perform this override, the JMS Adapter supports a Normalized message property called jca.jms.WeblogicUnitOfOrder
. This value overrides the value specified using the property UnitOfOrder
for the JmsProduceInteractionSpec
.
You can modify the value of the UnitOfOrder
spec property from the EM console. Any outbound interactions after that point use the new value you supply.
If you define neither the property jca.jms.WeblogicUnitOfOrder
nor the JmsProduceInteractionSpec
property UnitOfOrder
, no unit-of-order value is set by JMS Adapter and the default unit-of-order, if specified administratively on the connection factory and destination, takes effect.
The JMS unit-of-order feature only works with the WebLogic Server. For non Web Logic Server destinations, the property jca.jms.WeblogicUnitOfOrder
(if one exists) are ignored.
You can obtain user-specified value from the interaction spec instance.
All JMS message properties are available as Normalized Message properties. You can get the unit-of-order property by looking up the Normalized message property jca.jms.JMSProperty.JMS_BEA_UnitOfOrder
on the delivered message.
The Oracle JMS Adapter supports the synchronous consume (mid-process receive) interaction pattern.
You can use the Adapter Configuration Wizard to model a process that enables the Oracle JMS Adapter to be used in such a synchronous consume interaction pattern. In this case, the Oracle JMS Adapter dequeues a message from a specified queue while the process is executing (hence the name mid-process receive).
If the queue is empty, execution still continues. Underneath, the Oracle JMS Adapter uses a new interaction pattern JmsReceiveNoWaitInteractionSpec
.
When modeling the JMS Synchronous Consume using the JMS Adapter Configuration Wizard, you must provide the queue name used for the dequeue. For this operation, the JMS Adapter supports all the other jca properties configured when the current Consume operation is configured.
In a scenario using this operation, the BPEL Process continues executing the next step in the process if the JMS Adapter did not have any messages on the queue to dequeue.