This chapter describes how to use the Oracle JCA Adapter for MQ Series (Oracle MQ Series Adapter), which works with Oracle BPEL Process Manager (Oracle BPEL PM) and Oracle Mediator (Mediator) as an external service. The chapter describes JCA Adapter for MQ Series concepts, features, configuration and use cases.
This chapter includes the following sections:
Message queuing is a technique for asynchronous program-to-program communication. It enables application integration by allowing independent applications on a distributed system to communicate with each other. One application sends messages to a queue owned by a queue manager, and another application retrieves the messages from the queue. The communication between applications is maintained even if the applications run at different times or are temporarily unavailable.
The basic concepts of message queuing are described in the following list:
Messaging is the mechanism that allows two entities to communicate by sending and receiving messages. Messaging can be of two types, synchronous and asynchronous. In synchronous messaging, the sender of the message places a message on a message queue and then waits for a reply to its message before resuming its own processing. In asynchronous messaging, the sender of the message proceeds with its own processing without waiting for a reply.
Messages are structured data sent by one program and intended for another program.
Message queues are objects that store messages in an application. Applications can put messages to the queues and get messages from the queues. A queue is managed by a queue manager.
A queue manager provides messaging and queuing services to applications through an application programming interface. It provides you with access to the queues and also transfers messages to other queue managers through message channels.
A message channel provides a communication path between two queue managers. It connects queue managers. A message channel can transmit messages in one direction only.
A transmission queue is used to temporarily store messages that are destined for a remote queue manager.
If a message is very large, then it can be divided into multiple small messages, called segments. Each segment has a group ID and an offset. All segments of a message have the same group ID. The last segment of the message is marked with a flag.
A message group consists of a set of related messages with the same group ID. Each message in a message group has a message sequence number. The last message in a message group is marked with a flag.
A cluster is a group of queue managers that are logically associated.
To enqueue is to put a message in a queue whereas to dequeue is to get a message from a queue, as shown in Figure 10-1.
In a request/response interaction, a program sends a message to another program asking for a reply. The request message contains information about where the reply should be sent. The receiving program sends a reply message in response to the request message. The request/response interaction is shown in Figure 10-2.
For more information about the interaction scenarios supported by the Oracle MQ Series Adapter, see Section 10.4.1.2, "Dequeue Message".
Messaging and Queuing Series (MQ Series) is a set of products and standards developed by IBM. MQ Series provides a queuing infrastructure that provides guaranteed message delivery, security, and priority-based messaging.
Note:
The Oracle MQ Series Adapter is certified on IBM WebSphere MQ V7.5.
The communication process between an MQ Series application and an MQ Series server is shown in Figure 10-3. An MQ Series client enables an application to connect to a queue manager on a remote computer.
Figure 10-3 The MQ Series Communication Process
Every queue in MQ Series belongs to a queue manager. A queue manager has a unique name and provides messaging and queuing services to applications through a Message Queue Interface (MQI) channel. A queue manager also provides access to the queues created on it and transfers messages to other queue managers through message channels.
In MQ Series, data is sent in the form of messages. The sending application constructs a message and sends it to a queue by using API calls. The message remains in the queue until the receiving application is ready to receive it. The receiving application gets the messages from the queue by using API calls.
For sending messages to a remote queue, the remote queue definition must be defined locally. The remote queue definition consists of the destination queue name and the transmission queue name.
Figure 10-4 displays the message structure of an MQ Series message.
An MQ Series message consists of the following parts, as shown in Figure 10-4:
The message header contains information such as unique message ID, message type, message priority, and routing information. Every MQ Series message must have a message header.
The optional header is required for communication with specific applications, such as the CICS application.
For more information, see Section 10.4.8, "Integration with CICS".
This contains the actual data, for example, a record from an indexed or flat file or a row or column from a DB2 table.
Oracle BPEL Process Manager and Mediator include the Oracle MQ Series Adapter. The Oracle MQ Series Adapter enables applications to connect to MQ Series queue managers and place MQ Series messages on queues or to remove MQ Series messages from queues.
This section contains the following topics:
Section 10.2.2, "Oracle MQ Series Adapter Integration with Oracle BPEL Process Manager"
Section 10.2.3, "Oracle MQ Series Adapter Integration with Mediator"
The Oracle MQ Series Adapter provides all native MQ Series functionalities. Although you can configure the Oracle JCA Adapter for JMS (Oracle JMS Adapter) with MQ Series provider, it provides only the JMS functionalities provided by MQ Series and not the native MQ Series functionalities. The following list explains the advantages of Oracle MQ Series Adapter over the Oracle JMS Adapter:
The Oracle MQ Series Adapter supports Positive Action Notification (PAN) and Negative Action Notification (NAN).
The Oracle MQ Series Adapter supports report messages such as confirmation on delivery, confirmation on arrival, exception report, and expiry report.
The Oracle MQ Series Adapter supports sending unwanted or corrupted messages to a dead-letter queue.
The Oracle MQ Series Adapter provides advanced filter options, such as filtering message belonging to a group.
The Oracle MQ Series Adapter is faster and easier to use.
Note:
The MQ Series version that the Oracle MQ Series Adapter is certified is 7.5 version, both on Windows and Linux.
The Oracle MQ Series Adapter is automatically integrated with Oracle BPEL Process Manager. When you create a partner link or an MQ adapter service in Oracle JDeveloper (JDeveloper), the Adapter Configuration Wizard is started.
This wizard enables you to select and configure the Oracle MQ Series Adapter or other Oracle JCA Adapters. The Adapter Configuration Wizard then prompts you to enter a service name, as shown in Figure 10-5.
When the configuration is complete, a WSDL file of the same name is created in the Application Navigator section of JDeveloper. This WSDL file contains the configuration information you specify with the Adapter Configuration Wizard.
The Operations page of the Adapter Configuration Wizard prompts you to select an operation to perform. Based on your selection, different Adapter Configuration Wizard pages appear and prompt you for configuration information.
Table 10-1 lists the available operations and provides references to sections that describe the information about these operations.
Table 10-1 Supported Operations for Oracle BPEL Process Manager
The Oracle MQ Series Adapter is automatically integrated with Mediator. When you create an MQ adapter service in JDeveloper Mediator Designer, the Adapter Configuration Wizard is started.
This wizard enables you to select and configure the Oracle MQ Series Adapter. When the configuration is complete, a WSDL file of the same name is created in the Application Navigator section of JDeveloper. This WSDL file contains the configuration information you specify in the Adapter Configuration Wizard.
The Operations page of the Adapter Configuration Wizard prompts you to select an operation to perform. Based on your selection, different Adapter Configuration Wizard pages appear and prompt you for configuration information. Table 10-2 lists the available operations and provides references to sections that describe the configuration information you must provide.
Table 10-2 Supported Operations for Oracle Mediator
Operation | See Section... |
---|---|
Enqueue Message |
|
Dequeue Message |
|
Request-Response |
Section 10.4.1.6, "Synchronous Request-Response (Mediator As Server)" Section 10.4.1.8, "Synchronous Request-Response (Oracle Mediator as Client)" Section 10.4.1.9, "Asynchronous Request-Response (Oracle Mediator As Client)" |
Outbound Dequeue |
This section explains the following features of the Oracle MQ Series Adapter:
The RFH2 header is an extensible header. The RFH2 header enables you to add more header properties to the payload. The RFH2 header carries JMS-specific data that is associated with the message content and can also carry additional information that is not directly associated with JMS.
The RFH2 header consists of two parts, a fixed portion and a variable portion. There can be multiple RFH2 headers in the same message.
The fixed portion is modeled on the standard
WebSphere MQ header pattern and consists of the following fields:
Structure identifier.
Must be MQRFH_STRUC_ID (value: "RFH ") (initial value).
MQRFH_STRUC_ID_ARRAY (value: "R","F","H"," ") is also defined in the usual way.
Structure version number.
Must be MQRFH_VERSION_2 (value: 2) (initial value).
Total length of MQRFH2, including the NameValueData fields.
The value set into StrucLength must be a multiple of 4 (the data in the NameValueData fields may be padded with space characters to achieve this).
Data encoding.
Encoding of any numeric data in the portion of the message following MQRFH2 (the next header, or the message data following this header).
Coded character set identifier.
Representation of any character data in the portion of the message following MQRFH2 (the next header, or the message data following this header).
Format name.
Format name for the portion of the message following MQRFH2.
Flags.
MQRFH_NO_FLAGS =0. No flags set.
The coded character set identifier (CCSID) for the NameValueData character strings contained in this header. The NameValueData may be coded in a character set that differs from the other character strings that are contained in the header (StrucID and Format).
If the NameValueCCSID field is a 2-byte Unicode CCSID (1200, 13488, or 17584), then the byte order of the Unicode CCSID is the same as the byte ordering of the numeric fields in MQRFH2. (For example, Version, StrucLength, and NameValueCCSID itself.)
The NameValueCCSID field may take only values from Table 10-3:
The variable portion follows the fixed portion. The variable portion contains a variable number of MQRFH2 folders. Each folder can occur multiple times in the same RFH2 header. Other folders such as mqext
, mq_usr
, mqps
and others. can also be part of the RFH2 header. For more information, refer to the IBM documentation regarding MQ RFH2 headers.
The related properties are grouped together. The MQRFH2 header can contain the following message service folders:
This contains properties that describe the shape or format of the message. For example, the Msd property identifies the message as being Text, Bytes, Stream. Map, Object, or Null. This folder is always present in JMS MQRFH2.
This is used to transport JMS header fields, and JMSX properties that cannot be fully expressed in the MQMD. This folder is always present in a JMS MQRFH2.
This is used to transport any application-defined properties associated with the message. This folder is only present if the application has set some application-defined properties.
This is used to convey publish/subscribe command messages to the broker. Only one psc folder is allowed in the NameValueData field.
This is used to contain information from the broker, in response to publish/subscribe command messages. Only one pscr folder is present in a response message.
Table 10-4 shows a full list of property names.
Table 10-4 MQRFH2 Folders and Properties Used by JMS
JMS Field Name | Java Type | MQRFH2 Folder name | Property Name | Type/values |
---|---|---|---|---|
JMSDestination |
Destination |
jms |
Dst |
string |
JMSExpiration |
long |
jms |
Exp |
i8 |
JMSPriority |
int |
jms |
Pri |
i4 |
JMSDeliveryMode |
int |
jms |
Dlv |
i4 |
JMSCorrelationID |
String |
jms |
Cid |
string |
JMSReplyTo |
Destination |
jms |
Rto |
string |
JMSTimestamp |
long |
jms |
Tms |
i8 |
JMSType |
String |
mcd |
Type, Set, Fmt |
string |
JMSXGroupID |
String |
jms |
Gid |
string |
JMSXGroupSeq |
int |
jms |
Seq |
i4 |
xxx (User Defined) |
Any |
usr |
xxx |
any |
mcd |
Msd |
jms_none jms_text jms_bytes jms_map jms_stream jms_object |
The syntax used to express the properties in the variable portion is as follows:
Length, in bytes, of the NameValueData string that immediately follows this length field. It does not include its own length. The value set into NameValueLength is always a multiple of 4. The NameValueData field is padded with space characters to achieve this.
A single character string, whose length in bytes is given by the preceding NameValueLength field. It contains a folder holding a sequence of properties. Each property is a name/type/value triplet, contained within an XML element whose name is the folder name, as follows:
<foldername> triplet1 triplet2 ..... tripletn </foldername>
Secure Sockets Layer (SSL) is a protocol for transmitting encrypted data over the Internet or an internal network. SSL works by using public and private keys to encrypt data that is transferred over the SSL connection. Data that has been encrypted with a public key can be decrypted only with the corresponding private key. Conversely, data that has been encrypted with a private key can be decrypted only with the corresponding public key.
MQ Series supports secure communication, with MQ Series clients using SSL. As a part of this functionality, the adapter would provide support to put a message on queue using SSL. To enable Oracle MQ Series Adapter for SSL, the following properties must be provided:
SSLEnable: The true/false value for this property means that the Oracle MQ Series Adapter is SSL enabled/disabled.
KeyStoreLocation: This is the keystore where Oracle MQ Series Adapter has its private keys. This property is required as the adapter must authenticate itself to the MQ Series server.
KeyStorePassword: This password is required to access keystore.
TrustStoreLocation: This is the location where the adapter keeps its trusted certificates information. This information is required when an adapter must authenticate to the MQ Series server.
Protocol: Key Management Algorithm.
KeyStoreProviderName: The name of the keystore provider.
KeyStoreType: Type of the key store.
KeyStoreAlgorithm: Algorithm used by the key store.
CipherSuite: Set CipherSuite to the name matching the CipherSpec set on the SVRCONN
channel. If set to null (default), then no SSL encryption is performed.
SSLPeerName: A distinguished name pattern. If CipherSuite is set, then you can use this variable to ensure that the correct queue manager is used. If set to null (default), then the DN of the queue manager is not checked. This variable is ignored if sslCipherSuite
is null.
Oracle MQ Series Adapter enables transaction support, which along with the inherent data processing, ensures that each modification has a clearly defined outcome, resulting in either success or failure, thus preventing potential corruption of data, executes independently from other changes, and, after completion, leaves underlying data in the same state until another transaction takes place.
The Oracle MQ Series Adapter supports both inbound and outbound XA transaction. You must set the XATransaction
property in the Oracle WebLogic Server Administration Console to enable the XA transaction. To enable XA transaction, perform the following steps:
Log in to the Oracle WebLogic Server Administration Console using your password credentials.
Under Domain Structure, in the left pane, click Deployments. The Summary of Deployments page is displayed.
Click MQSeriesAdapter. The Settings of MQSeriesAdapter page is displayed.
Click the Configuration tab. The Configuration submenu options are displayed.
Click Outbound Connection Pools. The Outbound Connection Pool Configuration Table is displayed.
Click the + icon next to javax.resource.cci.ConnectionFactory and select eis/MQ/MQAdapter. The Outbound Connection Properties page is displayed.
Note:
Click Lock & Edit to enable the options in the console.
Select the XATransaction option and click the Property Value row at the end of the XATransaction.
Enter true
in the text field, as shown in Figure 10-6, and click Save.
Figure 10-6 Outbound Connection Properties Page
Click the Transaction tab. The Settings for javax.resource.cci.ConnectionFactory
page is displayed.
Select XA Transaction from the Transaction Support list.
Click Save to save your settings. The Save Deployment Plan Assistant page is displayed.
Click OK.
You have successfully enabled XA transaction for the Oracle MQ Series Adapter.
In order to use the XA transaction feature for MQ Series with BPEL for synchronous inbound request-reply scenario, you must set the bpel.config.transaction
parameter to required. If this parameter is not set, then it causes the transaction to split at the BPEL boundary and MQ returns MQRC_SYNCPOINT_NOT_AVAILABLE
error code.
<property name="bpel.config.transaction">required
</property>
In a scenario involving fail over, such as when the prepare phase
completes successfully before a middleware fails, messages must be recovered within the adapter without restarting the MQSeries server. You must manually resolve the in-doubt transactions.
To view all in-doubt transactions for a Queue Manager, you must execute the following command at the command prompt:
dspmqtrn -m[ourQueueManager]
To backout the messages, use the following command:
rsvmqtrn -m[ourQueueManager] -b [Transaction],[Number]
To commit the messages, use the following command :
rsvmqtrn -m[ourQueueManager] -c [Transaction],[Number]
Note:
You can use the[Transaction]
and [Number]
from the output of the dspmqtrn
command.
The Oracle MQ Series Adapter supports the high availability feature for the active-active topology with Oracle BPEL Process Manager (Oracle BPEL PM) and Mediator service engines. It supports this feature for both inbound and outbound operations.
Before you configure the Oracle MQ Series Adapter for high availability, you must ensure that the following prerequisites are met:
Clustered processes must use the same queue.
Fault-policies and fault-bindings must be created for remote faults to ensure that the adapter acts correctly.
The Oracle MQ Series Adapter must ensure that it participates in the XA transaction. For more information about the XA transaction, see Section 10.3.3, "XA Transactions".
The Oracle MQ Series Adapter supports the scalability feature for inbound operations only. Oracle MQ Series Adapter provides the parameter to control the number of threads that dequeue the messages from the inbound queue.You must specify the following property in the.jca
file:
InboundThreadCoun
t='N
'
where, N is the number of threads to span to dequeue the messages from the inbound queue. The default setting is 2.
The Oracle MQ adapter creates the back-endconnections at deployment time, that is, at that time the adapter endpoint starts polling. You can have the application server prewarm the connection pool, which would provide a small marginal advantage, although connection creation does not otherwise delay the overall deployment task itself.
The example syntax for using InboundThreadCount in the .jca file is:
<adapter-config name="ExpressDeathEventListener" adapter="MQSeriesAdapter" wsdlLocation="ExpressDeathEventListener.wsdl" <xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata"> <connection-factory location="eis/MQ/MQAdapter" adapterRef=""/> <endpoint-activation portType="Dequeue_ptt" operation="Dequeue" UITransmissionPrimitive="Dequeue"> <activation-spec className="oracle.tip.adapter.mq.inbound.ActivationSpecImpl"> <property name="QueueName" value="BPMPOC_EXPCLAIMQ"/> <property name="InboundThreadCount" value="10"/> </activation-spec> </endpoint-activation> </adapter-config>
The Oracle MQ Series 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 MQ Series Adapter by using Oracle WebLogic Server container-managed sign-on.
For more information, see Section 4.2.22, "Securing Enterprise Information System Credentials".
A fault policy file defines fault conditions and their corresponding fault recovery actions. Each fault condition specifies a particular fault or group of faults, which it attempts to handle, and the corresponding action for it. A set of actions is identified by an ID in the fault policy file.
The Oracle MQ Series Adapter supports defining rejection handlers by using fault policies.
For more information about fault policies, see Section 2.21.1.1, "Configuring Rejection Handlers".
The Oracle MQ Series Adapter supports inbound message rejection handling. You can configure the message rejection handler to process translation errors, take corrective action.
For more information about rejection handlers, Section 2.21.1.1, "Configuring Rejection Handlers".
The Oracle MQ Series Adapter supports the following two mechanisms for inbound retry:
The JCA inbound retry mechanism is commonly used by all adapters, in general, whereas the message backout queue mechanism is used only by the Oracle MQ Series Adapter. If you specify the BackoutQueueName
property in the .jca file, only then the Oracle MQ Series Adapter uses the message backout queue mechanism to retry. By default, the JCA inbound retry mechanism is used for retry.
Note:
Both these methods of retry in the Oracle MQ Series Adapter are mutually exclusive operations; the adapter uses one mechanism at a time. If you specify both options, then the Backout Queue option takes precedence.
The Oracle MQ Series Adapter supports a pull model for connecting to the back-end application for receiving events. Connection-related issues are considered recoverable and most inbound adapters keep retrying until the adapters are able to establish connection with the EIS.
In case of Oracle MQ Series Adapter, a message not being able to put to a queue is also retriable.
For more information about retry mechanism, see Section 2.21, "Error Handling".
Backout Queue is a queue for putting rejected messages from an inbound queue. The inbound adapter checks for the backout count of the messages and if this count exceeds the MaximumBcakoutCount
value, then the adapter puts the messages to the specified Backout Queue. This mechanism is used by the Oracle MQ Series Adapter to handle inbound retries for the rejected messages.
If you specify the BackoutQueueName
property in the .jca
file, then Oracle MQ Series Adapter uses the message backout count for retries. You can specify the maximum retries using the MaximumBackoutCount
property. The default value for this property is infinite. If you do not specify the MaximumBackoutCount
value along with the BackoutQueueName
, then the adapter retries infinitely. The adapter does not consider JCA
retries (specified in composite.xml) when the BackOut Queue properties are specified.
The BackoutRetries
property must be set to specify the number of retries for delivering the message to the Backout Queue with retry interval set using the BackoutRetryInterval
property. The default value for BackoutRetries
is 3
and BackoutInterval
is 5
sec.
If a message gets rejected even after the MaximumBackoutCount
value is reached, then the adapter puts the message to Backout Queue. If Oracle MQ Series Adapter is cannot put the message to Backout Queue, then the adapter tries till the BackoutRetries
count with the BackoutInterval
time delay. If even after the BackoutRetries the adapter cannot put the message to Backout Queue, then the adapter deactivates the endpoint.
You must also specify the name of the Queue Manager of the Backout Queue in the BackoutQueueManagerName
property. You must not use this property if the BackoutQueue resides on the inbound queue QueueManager.
Note:
When using the Backout Queue, consider the following:
The Backout Queue options cannot be used for translation failures.
In cases where both JCA and BackOut retries are specified, the BackOut retries takes precedence.
For more information about configuring Backout Queues, see Section 10.6.6, "Configuring a Backout Queue."
The Oracle MQ Series Adapter supports performance tuning options.
For more information, see "Oracle MQ Adapter Tuning" in the Oracle Fusion Middleware Performance and Tuning Guide.
This section explains the following concepts of the Oracle MQ Series Adapter:
The Oracle MQ Series Adapter supports the following messaging scenarios:
Section 10.4.1.3, "Asynchronous Request-Response (Oracle BPEL PM As Client)"
Section 10.4.1.4, "Synchronous Request-Response (Oracle BPEL PM As Server)"
Section 10.4.1.5, "Asynchronous Request-Response (Oracle BPEL PM As Server)"
Section 10.4.1.6, "Synchronous Request-Response (Mediator As Server)"
Section 10.4.1.7, "Synchronous Request-Response (Oracle BPEL PM As Client)"
Section 10.4.1.8, "Synchronous Request-Response (Oracle Mediator as Client)"
Section 10.4.1.9, "Asynchronous Request-Response (Oracle Mediator As Client)"
In this scenario, the Oracle MQ Series Adapter connects to a specific queue managed by a queue manager and then writes the message to the queue. For outbound messages sent from Oracle BPEL PM or Mediator, the Oracle MQ Series Adapter performs the following operations:
Receives message from Oracle BPEL PM or Mediator.
Formats the XML content as specified at design time.
Sets the properties of the message, such as priority, expiry, message type, and persistence. These properties are based on the selections that you made in the Adapter Configuration Wizard.
For more information about message properties, see Section 10.4.2.1, "Messages Types".
Sends the message to the queue specified at design time in the Adapter Configuration Wizard.
Figure 10-7 displays the operation type that you must select in the Adapter Configuration Wizard.
Figure 10-7 The Adapter Configuration Wizard: Produce Message Selection
The page that appears after selecting the Put Message into MQ operation type is shown in Figure 10-8.
You can specify the following properties in this page:
Queue Name: The name of the queue on which the Oracle MQ Series Adapter enqueues the message. This is a mandatory field.
Queue Manager: The name of the queue manager to which the queue belongs. This field is optional and is necessary when enqueuing message to a remote queue.
Partial Delivery: This is applicable only when you specify multiple queues for outbound operation, which is also known as the Distribution List scenario. Partial Delivery takes either true
or false
. If assigned true
, then even if the delivery of message fails for some queues, it would still go and put the message to the rest of the queues specified in the distribution list. If assigned false
, it means even if one message fails, then the message is not put to any queue.
Message Format: The format of the message.
Note:
When enqueuing a message, ensure that the various mandatory values, required for a specific format, are specified correctly.
Priority: The priority of the message, ranging from 0 (low) to 9 (high).
Persistence: The persistence of the message. You can also specify the persistence of the message to be taken from the default persistence attribute, as defined by the destination queue.
Delivery Failure: If the delivery of message fails, then either it can be put to a dead letter queue or it can be discarded.
Allow Messages to Be Segmented When Necessary: This is applicable to a message that is big enough for the queue to accommodate. In that case, if you have specified that it has to be segmented, then the single message can be broken into that many bytes the queue can take, which results in multiple messages.
Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.
For more information about these properties, see Section 10.4.2, "Message Properties".
The next Adapter Configuration Wizard page that appears is the Messages page, as shown in Figure 10-9. This page enables you to select the XML Schema Definition (XSD) file for translation.
If native format translation is not required (for example, a JPG or GIF image is being processed), then select the Native format translation is not required check box. The file is passed through in base-64 encoding.
XSD files are required for translation. To define a new schema or convert an existing data type description (DTD) or COBOL Copybook, select Define Schema for Native Format. This starts the Native Format Builder wizard. This wizard guides you through the creation of a native schema file from file formats, such as delimited by special characters, comma-delimited value (CSV), fixed-length, DTD, and COBOL Copybook. After the native schema file is created, you are returned to this Messages page with the Schema File URL and Schema Element fields filled in.
For more information, see Section 6.1, "Creating Native Schema Files with the Native Format Builder Wizard".
In this scenario, the Oracle MQ Series Adapter connects to a specific queue managed by a queue manager and then removes the message from the queue. For inbound messages sent to Oracle BPEL PM or Mediator, the Oracle MQ Series Adapter performs the following operations:
Connects to the queue specified at design time.
Dequeues the message from the queue when a message arrives.
Reads and translates the message based on the translation logic defined at design time.
Publishes the message as an XML message to Oracle BPEL PM or Mediator.
Figure 10-10 displays the operation type that you must select in the Adapter Configuration Wizard.
Figure 10-10 The Adapter Configuration Wizard: Consume Message Selection
The page that appears after selecting the Get Message from MQ operation type is shown in Figure 10-11.
You can specify the following properties in this page:
Queue Name: The name of the queue from which the Oracle MQ Series Adapter dequeues the message. This is a mandatory field.
Schema Options: This option enables you to specify the schema for the message to be dequeued.
Choose Other Schema: This option enables you to choose your schema for the message to be dequeued.
Choose a Predefined Schema: This option enables you to choose a readymade schema that the adapter provides.
The next Adapter Configuration Wizard that appears is the Messages page, as shown in Figure 10-9. This page enables you to select the XSD schema file for translation.
As with specifying the schema for the produce message operation, you can perform the following tasks in this page:
Specify if native format translation is not required.
Select the XSD schema file for translation.
Start the Native Format Builder wizard to create an XSD file from file formats such as CSV, fixed-length, DTD, and COBOL Copybook.
For more information about the Messages page, see Section 10.4.1.1, "Enqueue Message".
In this scenario, the Oracle BPEL PM sends a request message and receives the corresponding response using a non-initiating receive activity. The invoke activity initiates the outbound invocation of the adapter to send the request. The Oracle MQ Series Adapter performs the following operations:
Receives message from Oracle BPEL PM.
Formats the XML content as specified at design time in the Adapter Configuration Wizard.
Sets properties and a correlation schema on the request message.
Sends the message to the queue specified at design time. The third-party application receives the message, processes it, generates the response, and then enqueues the response message to the replyTo
queue specified in the request message. The Correlation ID and Message ID of the response message are generated based on the correlation schema specified in the request message.
The Oracle MQ Series Adapter dequeues the message from the replyTo
queue.
Sends the response to the non-initiating receive activity of Mediator. To ensure that response is sent to the correct BPEL instance, correlation schemas are used.
Figure 10-12 displays the operation type that you must select in the Adapter Configuration Wizard.
The page that appears after selecting the Send Message to MQ and Get Reply/Reports operation type is shown in Figure 10-13.
Figure 10-13 Send Message to MQ and Get Reply/Reports Page
You can specify the following properties in this page:
Message Type: The type of the message. You can either send a normal message or a request message.
Get Reports: Select this option if you want any kind of report. You can specify the type of report in the next page, as shown in Figure 10-14.
Queue Name: The name of the queue to which the Oracle MQ Series Adapter enqueues the message. This is a mandatory field.
Queue Manager: The name of the queue manager to which the queue belongs. This field is optional.
Message Format: The format of the message.
Priority: The priority of the message ranging from 0 (low) to 9 (high).
Persistence: The persistence of the message. You can also specify the persistence of the message to be taken from the default persistence attribute, as defined by the destination queue.
Delivery Failure: If the delivery of the message fails, then either it can be put to a dead letter queue or it can be discarded.
Allow Messages to Be Segmented When Necessary: This is applicable to a message that is big enough for the queue to accommodate. In that case, if you have specified that it has to be segmented, then the single message can be broken into that many bytes the queue can take, which results in multiple messages.
Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.
For more information about these properties, see Section 10.4.2, "Message Properties" and Section 10.4.5, "Report Messages".
The page that is displayed when you click Next in the Send Message to MQ and Get Reply/Reports page can be a Reports page (shown in Figure 10-14) or a Response page (shown in Figure 10-15).
The Reports page, shown in Figure 10-14, is displayed only if you have selected the Get Reports option in the Send Message to MQ and Get Reply/Reports page, as shown in Figure 10-13.
You can select the following types of reports in this page:
Confirmation on Arrival
Confirmation on Delivery
Exception Report
Expiry Report
For information about these report types, see Section 10.4.5, "Report Messages".
The Response page shown in Figure 10-15 is displayed when you click Next in the Reports page.
You can specify the following properties in the Response page:
Reply to Queue Name: The name of the reply queue name.
Correlation Scheme: The correlation schema that is necessary for the Oracle MQ Series Adapter.
For information about correlation schemas, see Section 10.4.3, "Correlation Schemas".
Schema Options: This option enables you to specify the schema for the message to be dequeued.
Choose Other Schema: This option enables you to choose your schema for the message to be dequeued.
Choose a Predefined Schema: This option enables you to choose a readymade schema that the adapter provides.
Note:
For Oracle MQ Series Adapter in an asynchronous outbound request/reply scenario, properties are differentiated by an (Enqueue)
or (Dequeue)
label in Oracle Enterprise Manager Console. For example, QueueName(Enqueue)
is used for putting a message and QueueName(Dequeue)
is used for dequeuing the reply.
When using Oracle Enterprise Manager Console to edit Oracle MQ Series Adapter properties in this scenario, note the following:
If you change the ReplyToQueueName(Enqueue)
property, you must also change the QueueName(Dequeue)
property to the same value.
If you change the MessageId(Dequeue)
property, you must also change the MessageId(Enqueue)
property to the same value.
If you change the CorrelationId(Dequeue)
property, you must also change the CorrelationId(Enqueue)
property to the same value.
When you click Next in the Response page, a Messages page, shown in Figure 10-16, is displayed. This page enables you to select the XSD schema file for translation for request and as response message.
You can perform the following tasks in this page:
Specify if native format translation is not required.
Select the XSD schema file for translation.
Start the Native Format Builder wizard to create an XSD file from file formats such as CSV, fixed-length, DTD, and COBOL Copybook.
For more information about the Messages page, see Section 10.4.1.1, "Enqueue Message".
In the solicit-request-response scenario, the reply message is expected in the reply queue specified with some correlation scheme that is provided through the request message. This reply queue, which is used by a particular process (BPEL/Mediator), should not be used by any other process.
If the same reply queue is used by some other application, then the message might be picked, irrespective of whether the reply message had the proper correlation or not, and eventually the message becomes lost.
In this scenario, the Oracle BPEL PM receives a request, processes it, and sends the response synchronously by using a reply activity. The Oracle MQ Series Adapter performs the following operations:
Dequeues the request message from the queue when the message arrives.
Reads and translates the message based on the translation logic defined at design time.
Publishes the message as an XML message to Oracle BPEL PM. The Oracle BPEL PM processes the request and sends the response to the Oracle MQ Series Adapter.
Receives the response message from the Oracle BPEL PM.
Formats the XML content as specified at design time.
Sets the properties of the message such as priority, expiry, message type, and persistence. These properties are based on the selections that you made in the Adapter Configuration Wizard.
Sends the message to the queue specified at design time in the Adapter Configuration Wizard.
Figure 10-17 shows a sample BPEL process for this scenario.
Figure 10-17 Synchronous Request-Response Oracle BPEL PM As Server Sample
Figure 10-18 displays the operation type that you must select in the Adapter Configuration Wizard.
Figure 10-18 Operation Type Page Selection for Request-Response Synchronous Interaction
The page that appears after you select the Get Message from MQ and Send Reply/Reports operation type is shown in Figure 10-19. Specify the queue name from which the Oracle MQ Series Adapter dequeues the message in this page.
Figure 10-19 Get Message from MQ and Send Reply/Reports Page
When you click Next in the Get Message from MQ and send Reply/Reports page, the Response page shown in Figure 10-20 is displayed.
Figure 10-20 Response Page for Synchronous Request-Response
You can specify the following properties in the Response page:
Message Type: The message type of the message to be dequeued. This option affects the return message type.
Message Format: The format of the message.
Priority: The priority of the message.
Persistence: The persistence of the message. You can also specify the persistence of the message to be taken from the default persistence attribute, as defined by the destination queue.
Delivery Failure: If the delivery of the message fails, then either it can be put to a dead letter queue or it can be discarded.
Allow Messages to Be Segmented When Necessary: This is applicable to a message that is big enough for the queue to accommodate. In that case, if you have specified that it has to be segmented, then the single message can be broken into that many bytes the queue can take, which results in multiple messages.
Expiry: The expiry time of the message.
For more information about these properties, see Section 10.4.2, "Message Properties".
Click Next in the Response page, the Messages page is displayed, as shown in Figure 10-16. You can perform the following tasks in this page:
Specify if native format translation is not required.
Select the XSD schema file for translation.
Start the Native Format Builder wizard to create an XSD file from file formats such as CSV, fixed-length, DTD, and COBOL Copybook.
For more information about the Messages page, see Section 10.4.1.1, "Enqueue Message".
In Oracle BPEL PM initiated request-response interaction, a BPEL process receives a request as an inbound message, processes it, and then sends the response through an invoke activity. For asynchronous request-reply scenario, the Oracle MQ Series Adapter performs the following operations:
Dequeues the message from the queue when a message arrives.
Reads and translates the message based on the translation logic defined at design time.
Publishes the message as an XML message to Oracle BPEL PM. The Oracle BPEL PM processes the request and sends the response to the Oracle MQ Series Adapter.
Receives messages from Oracle BPEL PM.
Formats the XML content as specified at design time.
Sets the properties of the message, such as priority, expiry, message type, and persistence. These properties are based on the selections that you made in the Adapter Configuration Wizard.
Sends the message to the queue specified at design time in the Adapter Configuration Wizard.
Figure 10-21 shows a sample BPEL process for this scenario.
Figure 10-21 Asynchronous Request-Response Oracle BPEL PM As Server Sample
Figure 10-22 displays the operation type that you must select in the Adapter Configuration Wizard.
Figure 10-22 Operation Type Page Selection for Request-Response Asynchronous Interaction
The page that appears after selecting the Get Message from MQ and send Reply/Reports operation type is shown in Figure 10-19. Specify the queue name from which the Oracle MQ Series Adapter dequeues the message in this page.
When you click Next in the Get Message from MQ and send Reply/Reports page, the Response page shown in Figure 10-20 is displayed.
You can specify the following properties in the Response page:
Message Type: The message type of the message to be dequeued. This option affects the return message type.
Message Format: The format of the message.
Priority: The priority of the message.
Persistence: The persistence of the message. You can also specify the persistence of the message to be taken from the default persistence attribute, as defined by the destination queue.
Delivery Failure: If the delivery of the message fails, then either it can be put to a dead letter queue or it can be discarded.
Allow Messages to Be Segmented When Necessary: This is applicable to a message that is big enough for the queue to accommodate. In that case, if you have specified that it has to be segmented, then the single message can be broken into that many bytes the queue can take, which results in mulitple messages.
Expiry: The expiry time of the message.
For more information about these properties, see Section 10.4.2, "Message Properties".
The page that is displayed when you click Next in the Get Message to MQ and Send Reply/Reports page is a Response page (shown in Figure 10-23 and Figure 10-24) but with two different set of options.
Figure 10-23 Response Page (Request Message Type Selected)
The Response page shown in Figure 10-24 is displayed only if you have selected the Normal option in Message Type field in the Get Message to MQ and Send Reply/Reports page.
Figure 10-24 Response Page (Normal Message Type Selected)
You can specify the following properties in the Response page:
(Optional) Fallback Reply to Queue: Enter a response fallback queue name. The response message is enqueued to the queue specified with the replyToQueue property of the request message. However, if the replyToQueue property is not set on the request message, then entering a name here ensures that the process does not fail to enqueue the response.
(Optional) Fallback Reply to Queue Manager: Enter a secondary queue name. This name is used when the primary queue manager that was established when you specified the JNDI connection name cannot access the queue name entered in the Queue Name field. This is similar to the functionality described in the Fallback Reply to Queue field.
To specify the other properties in this Response page, see properties mentioned for Figure 10-23.
When you click Next in the Response page, the Messages page shown in Figure 10-25 is displayed. You can perform the following tasks in this page:
Specify if native format translation is not required.
Select the XSD schema file for translation.
Start the Native Format Builder wizard to create an XSD file from file formats such as CSV, fixed-length, DTD, and COBOL Copybook.
For more information about the Messages page, see Section 10.4.1.1, "Enqueue Message".
In asynchronous request-reply interaction, you must map the following properties from the inbound message header to the outbound message header:
MsgID
: Refers to the message ID.
CorrelID
: Refers to the correlation ID of a message.
CorrelationScheme
: Refers to a combination of both the msgid and the correlid of the request message.
For more information, see Section 10.4.3, "Correlation Schemas".
ReplyToQ
: Refers to the name of the response queue name.
ReplyToQueueManager
: Refers to the name of the response queue manager.
You can use the Assign activity to map these properties.
Create a BPEL process and double-click to open the BPEL Designer page.
In the vertical menu that appears, click the Variables icon that appears as (x) grayed out. The Variables dialog is displayed, as shown in Figure 10-26.
Capture the inbound header messages into these variables, as shown in Figure 10-27 and Figure 10-28.
Assign the variables captured in Step 2 for the Outbound Reply message, as shown in Figure 10-28 and Figure 10-23.
In this scenario, the Mediator receives a request, processes it, and sends the response synchronously. The Oracle MQ Series Adapter performs the following operations:
Dequeues the request message from the queue when the message arrives.
Reads and translates the message based on the translation logic defined at design time.
Publishes the message as an XML message to Mediator. The Mediator processes the request and sends the response to the Oracle MQ Series Adapter.
Receives the response message from the Mediator.
Formats the XML content as specified at design time.
Sets the properties of the message such as priority, expiry, message type, and persistence. These properties are based on the selections that you made in the Adapter Configuration Wizard.
Sends the message to the queue specified at design time in the Adapter Configuration Wizard.
Figure 10-19 displays the operation type that you must select in the Adapter Configuration Wizard.
From this page onwards, all the pages are similar to the pages explained in Section 10.4.1.4, "Synchronous Request-Response (Oracle BPEL PM As Server)".
Note:
The asynchronous request-response pattern is not supported for Mediator.
The Oracle MQ Series Adapter supports the outbound synchronous-solicit-request-response scenario. In this scenario, the adapter enqueues a normal/request message in a queue and expects the report/reply synchronously. The report/reply message arrives in the ReplyToQueueName
queue of the normal/request message.
Note:
Outbound synchronous-solicit-responses must be executed in non-XA modes as the request message does not get enqueued when it is participating in a global transaction.
Figure 10-29 displays the operation type that you must select in the Adapter Configuration Wizard.
The page that appears after selecting the Send Message to MQ and Get Reply/Reports operation type is shown in Figure 10-13.
You can specify the following properties in this page:
Message Type: The type of the message. You can either send a normal message or a request message.
Queue Name: The name of the queue to which the Oracle MQ Series Adapter enqueues the message. This is a mandatory field.
Queue Manager: The name of the queue manager to which the queue belongs. This field is optional and is necessary when enqueuing message to a remote queue.
Message Format: The format of the message.
Priority: The priority of the message ranging from 0 (low) to 9 (high).
Persistence: The persistence of the message. You can also specify the persistence of the message to be taken from the default persistence attribute, as defined by the destination queue.
Delivery Failure: If delivery of the message fails, then either it can be put to a dead letter queue or it can be discarded.
Allow Messages to Be Segmented When Necessary: This is applicable to a message that is big enough for the queue to accommodate. In that case, if you have specified that it has to be segmented, then the single message can be broken into that many bytes the queue can take, which results in multiple messages.
Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.
Click Next in the Send Message to MQ and Get Reply/Reports page, the Response page, as shown in Figure 10-30, is displayed.
For the Synchronous Request-Response scenario, you must also edit the following properties in the Response page:
Reply to Queue Name: The name of reply queue name.
Correlation Scheme: The correlation schema that must be used by the Oracle MQ Series Adapter.
For more information about correlation schemas, see Section 10.4.3, "Correlation Schemas".
Schema Options: This option enables you to specify the schema for the message to be dequeued.
Choose Other Schema: This option enables you to choose your schema for the message to be dequeued.
Choose a Predefined Schema: This option enables you to choose a readymade schema that the adapter provides.
Response Wait Interval: The permitted value for this property is any interval value (>= 0). This is the time in milliseconds during which the adapter waits for the report/reply to arrive in replyToQueueName
. By default, the value of this property is 0 milliseconds. You can change this value, but the value must be less than that of the timeout interval for the outbound activity. If the report/reply message does not arrive in the stipulated time, then the adapter throws an exception. This property is not mandatory.
Note:
The ResponseWaitInterval
value must be less than the timeout interval for the outbound activity. If the ResponseWaitInterval
value exceeds the outbound activity timeout, then the adapter can behave ambiguously.
The Oracle MQ Series Adapter also supports the outbound synchronous-solicit-request-response scenario. In this scenario, the adapter enqueues a normal/request message in a queue and expects the report/reply synchronously. The report/reply message arrives in the Reply to Queue Name queue of the normal/request message.
The Synchronous Request-Response scenario for Oracle Mediator as client is same as the Synchronous Request-Response for Oracle BPEL as client. For more information about the Synchronous Request-Response scenario, see Section 10.4.1.7, "Synchronous Request-Response (Oracle BPEL PM As Client)".
In this scenario, Oracle Mediator sends a request message and receives the corresponding response from the Mediator callback handler. Oracle Mediator sends an outbound invocation to send the request. The Oracle MQ Series Adapter performs the following operations:
Receives message from Oracle Mediator.
Formats the XML content as specified at design time in the Adapter Configuration Wizard.
Sets properties and a correlation schema on the request message.
Sends the message to the queue specified at design time. The third-party application receives the message, processes it, generates the response, and then enqueues the response message to the replyTo
queue specified in the request message. The Correlation ID and Message ID of the response message is generated based on the correlation schema specified in the request message.
The Oracle MQ Series Adapter dequeues the message from the replyTo
queue.
Sets the properties of the message such as priority, expiry, message type, and persistence. These properties are based on the selections that you made in the Adapter Configuration Wizard.
Sends the response to the non-initiating receive activity of the BPEL process. To ensure that response is sent to the correct BPEL instance, correlation schemas are used.
Figure 10-12 displays the operation type that you must select in the Adapter Configuration Wizard.
The page that appears after selecting the Send Message to MQ and Get Reply/Reports operation type is shown in Figure 10-13.
You can specify the following properties in this page:
Message Type: The type of the message. You can either send a normal message or a request message.
Queue Name: The name of the queue to which the Oracle MQ Series Adapter enqueues the message. This is a mandatory field.
Message Format: The format of the message.
Queue Manager: The name of the queue manager to which the queue belongs. This field is optional and is necessary when enqueuing message to a remote queue.
Priority: The priority of the message ranging from 0 (low) to 9 (high).
Persistence: The persistence of the message. You can also specify the persistence of the message to be taken from the default persistence attribute, as defined by the destination queue.
Delivery Failure: If delivery of the message fails, then either it can be put to a dead letter queue or it can be discarded.
Allow Messages to be Segmented When Necessary: This is applicable to a message that is big enough for the queue to accommodate. In that case, if you have specified that it has to be segmented, then the single message can be broken into that many bytes the queue can take, which results in mutliple messages.
Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.
For more information about these properties, see Section 10.4.2, "Message Properties" and Section 10.4.5, "Report Messages".
The page that is displayed when you click Next in the Send Message to MQ and Get Reply/Reports page can be a Reports page (shown in Figure 10-14) or a Response page (shown in Figure 10-15).
The Reports page shown in Figure 10-14 is displayed only if you have selected the Get Reports option in the Send Message to MQ and Get Reply/Reports page shown in Figure 10-13.
The Response page shown in Figure 10-15 is displayed, irrespective of whether you select the Request or Normal option. The only difference is that if you select the Request option, then REPLY
is displayed in the Message Type field of the Response page. On the other hand, if you select the Normal option, then REPORTS
is displayed in the Message Type field of the Response page.
You can select the following types of reports in Figure 10-14:
Confirmation on Arrival
Confirmation on Delivery
Exception Report
Expiry Report
For information about these report types, see Section 10.4.5, "Report Messages".
The Response page, shown in Figure 10-15, is displayed when you click Next in the Reports page.
You can specify the following properties in the Response page:
Reply to Queue Name: The name of reply queue name.
Correlation Scheme: The correlation schema that is used by the Oracle MQ Series Adapter.
For information about correlation schemas, see Section 10.4.3, "Correlation Schemas".
Schema Options: This option enables you to specify the schema for the message to be dequeued.
Choose Other Schema: This option enables you to choose your schema for the message to be dequeued.
Choose a Predefined Schema: This option enables you to choose a readymade schema that the adapter provides.
Note:
For Oracle MQ Series Adapter in an asynchronous outbound request/reply scenario, properties are differentiated by an (Enqueue)
or (Dequeue)
label in Oracle Enterprise Manager Console. For example, QueueName(Enqueue)
is used for putting a message and QueueName(Dequeue)
is used for dequeuing the reply.
When using Oracle Enterprise Manager Console to edit Oracle MQ Series Adapter properties in this scenario, note the following:
If you change the ReplyToQueueName(Enqueue)
property, you must also change the QueueName(Dequeue)
property to the same value.
If you change the MessageId(Dequeue)
property, you must also change the MessageId(Enqueue)
property to the same value.
If you change the CorrelationId(Dequeue)
property, you must also change the CorrelationId(Enqueue)
property to the same value.
When you click Next in the Response page, a Messages page shown in Figure 10-16 is displayed. This page enables you to select the XSD schema file for translation for request and as response message.
For more information about the Messages page, see Section 10.4.1.1, "Enqueue Message".
The outbound dequeue scenario dequeues a single message from a queue using the outbound Oracle MQ Series Adapter by using the Get Message from MQ option in the Operation Type page of the Adapter Configuration Wizard. To enable the outbound dequeue option, you must select the Synchronous option, as shown in Figure 10-29.
Click Next in the Send Message to MQ and Get Reply/Reports page, the Response page, as shown in Figure 10-30, is displayed. You must set the following properties in the Response page:
QueueName: This is the name of the MQ Series queue from which the message is dequeued. This property is mandatory.
Response Wait Interval: This is the time (in milliseconds) that the adapter waits if the message is not in the queue. The default value for this property is 0 milliseconds. This property is not mandatory. The permitted value for this property is any integer value (>=0). The value of this property must be less than that of the timeout for outbound activity.
Note:
The ResponseWaitInterval
value must be less than the timeout interval for the outbound activity. If the ResponseWaitInterval
value exceeds the outbound activity timeout, then the adapter can behave ambiguously.
Message Id: This property sets the message filter option based on the messageId
. This property is not mandatory. The value provided for this property must be a hexadecimal-encoded value for some messageId
.
Correlation Id: This property sets the message filter option based on the correlationId
. This property is not mandatory. The value provided for this property must be a hexadecimal-encoded value for some correlationId
.
Note:
You can filter messages based on the Message Id and Correlation Id property through headers.
The Oracle MQ Series Adapter supports the following message properties:
The Oracle MQ Series Adapter supports the following four types of messages:
A normal message is sent by one program to another program without expecting any response.
A request message is sent by one program to another program requesting a response.
A reply message is sent by a program in response to a request message.
A report message is sent by a receiving program to a sending program as confirmation of successful or unsuccessful delivery of a message. A report message can be generated for any of the message types, normal message, request message, or reply message.
For more information about acknowledgment messages supported by the Oracle MQ Series Adapter, see Section 10.4.5, "Report Messages".
You can specify the format for an outgoing message through the Adapter Configuration Wizard, as shown in Figure 10-8. The following message formats are supported:
No format name (Default)
Command server request/reply message
Type 1 command reply message
Type 2 command reply message
Dead letter header
Event message
User-defined message in programmable command format
Message consisting entirely of characters
Trigger message
Transmission queue header
You can specify the expiry time for an outgoing message by using the Adapter Configuration Wizard, as shown in Figure 10-8. The queue manager discards the message after the expiry time of a message has elapsed.
If a message has expiration notification set, then a notification is generated when the message is discarded. The notification is sent to the queue specified in the replyToQueue
parameter. By default, NEVER
is set for the expiry field.
You can specify the priority of an outgoing message through the Adapter Configuration Wizard, as shown in Figure 10-8. A priority can be in the range of 0 (low) to 9 (high). You can also specify the priority of the message to be taken from the default priority attribute, as defined by the destination queue. By default, AS_Q_DEF
is set as message priority.
You can specify the persistence of an outgoing message through the Adapter Configuration Wizard, as shown in Figure 10-8. If message persistence is not set, then a message is lost when the queue manager restarts or there is a system failure. If you set persistence for a message to true
, then it means that the message does not get lost even if there is system failure or the queue manager is restarted. You can also specify the persistence of the message to be taken from the default priority attribute, as defined by the destination queue. The Adapter writes persistent messages to log files and queue data files. If a queue manager is restarted after a failure, it recovers these persistent messages from these files.
Note:
You can specify all these message properties at run time through message headers. You can use the assign activity to assign values to these properties.
Mapping a response to a request in a request-reply interaction requires correlation. Each MQ Series request message contains a message ID and a correlation ID. When an application receives a request message from Oracle BPEL PM, it checks for the correlation schema defined for the response message. Based on the correlation schema, the application generates the message ID and correlation ID of the response message.
The response page of the Adapter Configuration Wizard shown in Figure 10-15 enables you to specify the correlation schema for the response message.
The Message ID box shown in Figure 10-15 provides the following options for the message ID of the response message:
Generate a new message ID for the response message.
Use the message ID of the request message.
Similarly, the Correlation ID box shown in Figure 10-15 provides the following options for the correlation ID of the response message:
Use the message ID of the request message
Use the correlation ID of the request message
The Oracle MQ Series Adapter enables you to enqueue a message to multiple queues.
When you select the Put Message Into MQ option in the Operation Type page and multiple queues, then the DistributionList
parameter is automatically added to the JCA file.
The Oracle MQ Series Adapter enables you to set various types of acknowledgment messages on an outgoing message. These acknowledgment messages are known as report messages. A report message is generated, only if the criteria for generating that report message is met. When enqueuing a message on a queue, you can request for more than one type of report message. When you request for a report message, you must specify the queue name to which the report message is sent. This queue is known as replyTo
queue. A report message can be generated by a queue manager, a message channel, or an application.
The Oracle MQ Series Adapter supports the following message reports:
The Confirmation on Arrival (COA) message indicates that the message has been delivered to the target queue manager. A COA message is generated by the queue manager. This message report can be selected in the Reports page of the Adapter Configuration page shown in Figure 10-14.
A Confirmation on Delivery (COD) message indicates that the message has been retrieved by the receiving application. A COD message is generated by the queue manager. This message report can be selected in the Reports page shown in Figure 10-14.
An exception report is generated when a message cannot be delivered to the specified destination queue. Exception reports are generated by the message channel. This message report can be selected in the Reports page of the Adapter Configuration page shown in Figure 10-14.
An expiry report indicates that the message was discarded because the expiry time specified for the message elapsed before the message was retrieved. An expiry report is generated by a queue manager. This message report can be selected in the Reports page of the Adapter Configuration page shown in Figure 10-14.
A Positive Action Notification (PAN) indicates that a request has been successfully processed. It means that the action requested in the message has been performed successfully. This type of report is generated by the application.
A Negative Action Notification (NAN) indicates that a request has not been successfully serviced. It means that the action requested in the message has not been performed successfully. This type of report is generated by the application.
You can specify whether all these report messages except PAN and NAN should contain the complete original message, a part of the original message, or no part of the original message. You can select any of the following options in the Adapter Configuration Wizard:
No data from the original message
The first 100 bytes of data in the original message
The entire original message
The Message Delivery Failure options are supported only for remote queues and not for normal queues. The Oracle MQ Series Adapter enables you to specify the action that should be taken in case a message could not be delivered to the destination queue. You can specify any of:
Place message on a dead letter queue
This is the default action. A message is placed on a dead-letter queue if it cannot be delivered to the destination queue. A report message is generated if requested by the sender.
Discard message
This indicates that the message should be discarded if it cannot be delivered to the destination queue. A report message is generated if requested by the sender.
You can specify these options by selecting the Put Message To MQ option in the Adapter Configuration Wizard.
The Oracle MQ Series Adapter supports message segmentation for both inbound and outbound interactions. Segmentation is required when the size of a message is greater than the message size allowed for a queue. A physical message is divided into two or more logical messages. All logical messages have the same group ID and a sequence number, and an offset.
In the inbound interaction, the segmentation is inherently supported by the Oracle MQ Series Adapter. The Oracle MQ Series Adapter dequeues all logical messages in the order of sequence number and then publishes the single message as XML to Oracle BPEL PM or Mediator.
The Allow Messages to Be Segmented When Necessary option enables you to segment messages for outbound interactions. This option appears in the Response page of the Adapter Configuration Wizard.
The message is segmented based on whether the size of the message is larger than the maximum limit set on the queue.
The Oracle MQ Series Adapter provides support for sending and receiving messages from the CICS server. In the inbound direction, an inbound message from the CICS server is dequeued in the same way as a normal message. In the outbound direction, the message should be in the CICS format. A sample schema file for the outbound CICS message format is shown in the following example:
<?xml version="1.0" ?><schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://xmlns.oracle.com/pcbpel/nxsd/cics_mqcih" elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:nxsd="http://xmlns.oracle.com/pcbpel/nxsd" nxsd:version="NXSD" nxsd:encoding="UTF8" nxsd:stream="bytes" nxsd:byteOrder="bigEndian" xmlns:nxsd_extn="http://xmlns.oracle.com/pcbpel/nxsd/extensions" <element name="MSGForMQCICSBridge"> <complexType> <sequence> <element name="MQCIH"> <complexType> <sequence> <!-- MQCHAR4 StrucId; Structure identifier --> <element name="StrucId" type="string" nxsd:style="fixedLength" nxsd:length="4" nxsd:padStyle="tail"/> <!-- MQLONG Version; Structure version number 1 or 2 --> <element name="Version" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG StrucLength; Length of MQCIH structure V1=164 V2=180 --> <element name="StrucLength" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG Encoding; Reserved --> <element name="Encoding" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG CodedCharSetId; Reserved --> <element name="CodedCharSetId" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQCHAR8 Format; MQ Format name --> <element name="Format" type="string" nxsd:style="fixedLength" nxsd:length="8" /> <!-- MQLONG Flags; Reserved --> <element name="Flags" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG ReturnCode; Return code from bridge --> <element name="ReturnCode" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG CompCode; MQ completion code or CICS EIBRESP --> <element name="CompCode" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG Reason; MQ reason or feedback code, or CICS EIBRESP2 --> <element name="Reason" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG UOWControl; Unit-of-work control --> <element name="UOWControl" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG GetWaitInterval; Wait interval for MQGET call issued by bridge --> <element name="GetWaitInterval" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="ticked" /> <!-- MQLONG LinkType; Link type --> <element name="LinkType" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG OutputDataLength; Output commarea data length --> <element name="OutputDataLength" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="ticked" /> <!-- MQLONG FacilityKeepTime; Bridge facility release time --> <element name="FacilityKeepTime" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG ADSDescriptor; Send/receive ADS descriptor --> <element name="ADSDescriptor" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG ConversationalTask; Whether task can be conversational --> <element name="ConversationalTask" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG TaskEndStatus; Status at end of task --> <element name="TaskEndStatus" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQBYTE Facility[8]; BVT token value. Initialise as required. --> <element name="Facility" type="string" nxsd:style="integer" nxsd_extn:octet="8" nxsd_extn:align="0" nxsd _extn:sign="unticked" /> <!-- MQCHAR4 Function; MQ call name or CICS EIBFN function name --> <element name="Function" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 AbendCode; Abend code --> <element name="AbendCode" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR8 Authenticator; Password or passticket --> <element name="Authenticator" type="string" nxsd:style="fixedLength" nxsd:length="8" /> <!-- MQCHAR8 Reserved1; Reserved --> <element name="Reserved1" type="string" nxsd:style="fixedLength" nxsd:length="8" /> <!-- MQCHAR8 ReplyToFormat; MQ format name of reply message --> <element name="ReplyToFormat" type="string" nxsd:style="fixedLength" nxsd:length="8" /> <!-- MQCHAR4 RemoteSysId; Remote sysid to use --> <element name="RemoteSysId" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 RemoteTransId; Remote transid to attach --> <element name="RemoteTransId" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 TransactionId; Transaction to attach --> <element name="TransactionId" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 FacilityLike; Terminal emulated attributes --> <element name="FacilityLike" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 AttentionId; AID key --> <element name="AttentionId" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 StartCode; Transaction start code --> <element name="StartCode" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 CancelCode; Abend transaction code --> <element name="CancelCode" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR4 NextTransactionId; Next transaction to attach --> <element name="NextTransactionId" type="string" nxsd:style="fixedLength" nxsd:length="4" /> <!-- MQCHAR8 Reserved2; Reserved --> <element name="Reserved2" type="string" nxsd:style="fixedLength" nxsd:length="8" /> <!-- MQCHAR8 Reserved3; Reserved --> <element name="Reserved3" type="string" nxsd:style="fixedLength" nxsd:length="8" /> <!-- MQLONG CursorPosition; Cursor position --> <element name="CursorPosition" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG ErrorOffset; Error offset --> <element name="ErrorOffset" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG InputItem; Input item --> <element name="InputItem" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> <!-- MQLONG Reserved4; Reserved --> <element name="Reserved4" type="string" nxsd:style="integer" nxsd_extn:octet="4" nxsd_extn:align="0" nxsd_extn:sign="unticked" /> </sequence> </complexType> </element> <!-- Application data --> <element name="ApplicationData" type="string" fixed="Nothing" /> </sequence> </complexType> </element> </schema>
By default, Oracle MQ Series Adapter supports a list of encodings. It displays a list of MQ Series message encodings and Java encoding, and also the mapping between the MQ Series message encoding and Java encoding. The list of supported encodings for Oracle MQ Series Adapter is as follows:
ibm037
ibm437
ibm500
ibm819
Unicode
UTF8
ibm273
ibm277
ibm278
ibm280
ibm284
ibm285
ibm297
ibm420
ibm424
ibm737
ibm775
ibm813
ibm838
ibm850
ibm852
ibm855
ibm856
ibm857
ibm860
ibm861
ibm862
ibm863
ibm864
ibm866
ibm868
ibm869
ibm870
ibm871
ibm874
ibm875
ibm912
ibm913
ibm914
ibm915
ibm916
ibm918
ibm920
ibm921
ibm922
ibm930
SJIS
ibm933
ibm935
ibm937
ibm939
ibm942
ibm948
ibm949
ibm950
EUCJIS
ibm964
ibm970
ibm1006
ibm1025
ibm1026
ibm1089
ibm1097
ibm1098
ibm1112
ibm1122
ibm1123
ibm1124
Cp1250
Cp1251
Cp1252
Cp1253
Cp1254
Cp1255
Cp1256
Cp1257
Cp1258
ibm1381
ibm1383
JIS
KSC5601
ibm33722813
GB18030
You can add support for the other standard Java encodings that are not provided in above list, as follows:
Extract the MQSeriesAdapter.jar
file from the MQSeriesAdapter.rar
file.
Extract the mq.properties
file from the MQSeriesAdapter.jar
file.
Add the entry in the mq.properties
file. For each new encoding, you must add two lines (properties) to the mq.properties
file. One line for the MQ Series encoding to the corresponding Java encoding and other line for the Java encoding to the corresponding MQ Series encoding.
For example, to add support for the following ibm037
Java encoding:ibm037 (Java encoding)<->37 (MQ Series message encoding), you must add the following two lines to the mq.properties
file:
oracle.tip.adapter.mq.encoding.37=ibm037
oracle.tip.adapter.mq.encoding.ibm037=37
Note:
For the outbound UMS Adapter, you can use the property JCA.UMS.MSG.CONTENT-TYPE
, which can be used for specifying encoding. But if you do not set the value, the outbound UMS adapter uses server encoding for email by default.
When the SOA server is started in native encoding, for example, with iso8859-1, it cannot handle ccjk characters. The content will be garbled. As a workaround, you can set the jca property for the outbound UMS adapter as:
JCA.UMS.MSG.CONTENT-TYPE = 'text/plain; charset=utf-8'
The CCDT provides several advantages when defining properties while configuring the JNDI for your MQ Series Adapter.
To understand the configuration of the Client Channel Definition Table, you should understand the following basic terms and concepts:
Channel name and Connection name: The channel name for each definition in the table should be exactly same as the server connection channel of the queue manager which has a listener running on the Connection name provided. For example, the first definition in the CCDT below, channel.ccdt_qm1
is the name of the server connection channel of a queue manager which has its listener running on localhost(1414).
Queue manager name: The queue manager name defined in the CCDT might not be the actual name of the queue manager with Channel name and Connection name defined. There can be the following possibilities:
The Queue manager name defined in the client channel is the actual queue manager name as in the third definition in the table. Hence, ccdt_qm3
is the actual name of the queue manager which has the channel.ccdt_qm3
as its server connection channel and has a listener listening on localhost(3414).
No Queue manager name is defined for a client channel definition. In the example CCDT, below, this situation can be seen for the fourth definition in the table which does not have a Queue manager name defined.
Two or more client channel entries in the CCDT have the same Queue manager name defined. This name can match with the actual queue manager name of any of the entries. The first and second definition in the below example have the same Queue manager name defined as QM
though they actually point to different queue managers.
The figure below shows a standard CCDT which has client channels defined for connections to four queue managers; that is, ccdt_qm1 to ccdt_qm4.
Once defined, this CCDT resides, by default, at the following locations:
For Windows,
<C:\Program Files\IBM\WebSphere MQ\qmgrs\QM_NAME\@ipcc\AMQCLCHL.TAB>
For Unix-based systems,
<var/mqm/qmgrs/QM_NAME/@ipcc/AMQCLCHL.TAB>
This feature simplifies what was formerly a task that involved defining the Hostname, PortNumber, ChannelName and QueueManagerName in ConnectionFactory properties while you were configuring the JNDI for your MQ Series Adapter.
You can use the Client Channel Definition Table feature (CCDT), with only the URL pointing to a CCDT file and, additionally, a QueueManagerName, as part of the configuration. The MQ Series Adapter is able to read the rest of the connection details from the CCDT to create the required connections for your MQ Series Adapter.
You can configure the MQ Series Adapter to dynamically connect to the available queue manager from a list of queue managers, a few of which might be down.
You do not have to change the JNDI used for the MQ Adapter in the composite process and then re-deploy the composite to change the queue manager on which the MQ adapter was required to connect.
Only one ConnectionFactory JNDI entry is required for the queue managers and the MQ adapter will dynamically connect to the first available queue manager.
CCDT can be used to define a list of queue managers with the same Queue Manager name property for the client channel definition. This list is used by the MQ Series Adapter to dynamically connect to the first available Queue Manager at runtime without requiring any configuration changes or redeployment.
You can gain a basic understanding of IBM Websphere MQ and MQ adapter usage and details about CCDT creation in the IBM MQ Series documentation.
IBM Websphere MQ version 6 is the minimum requirement for the CCDT feature to work.
The prerequisites for using the Oracle MQ Series Adapter are:
IBM WebSphere MQ server should be installed and running.
A queue manager and a server connection channel should be created.
Note:
You must create queues based on the requirement of the application.
To configure the Oracle MQ Series Adapter, perform the following:
The steps in this section should be performed once, before using the Oracle MQ Series Adapter.
To add correct jar properties to the classpath for the Oracle MQ Series 6 Adapter, copy the following jars to <DOMAIN_HOME>/lib folder
com.ibm.mq.jar
com.ibm.mqetclient.jar
(for use with XA)
To add correct jar properties to the classpath for the Oracle MQ Series 7 Adapter, copy the following jars to <DOMAIN_HOME>/lib folder
com.ibm.mq.commonservices.jar
com.ibm.mq.jar
com.ibm.mq.pcf.jar
com.ibm.mq.headers.jar
com.ibm.mq.jmqi.jar
com.ibm.mqetclient.jar
(for use with XA)
In addition, if you are using the Oracle MQ Series 7 Adapter , the new Sharing Conversation property of the Server Connection Channel has to be to set to zero.
The com.ibm.mqetclient.jar
is not required with the MQ Series 7.5 server.
Note:
TFor the MQAdapter to run on MQSeries 7.5 on the WebSphere Application Server Platform you need to add the required jars from MQSeries 7.0.x.
You can add a new JNDI entry in the Oracle WebLogic Server Administration Console by following these steps:
Log in to the following URL using the username/password to open the Oracle WebLogic Server Administration Console:
http://<localhost>:port/console
The Home page is displayed, as shown in Figure 10-32.
Figure 10-32 Oracle WebLogic Administration Console Home Page
Under Domain Structure, in the left pane, click Deployments. The Summary of Deployments page is displayed.
Click MQSeriesAdapter. The Settings of MQSeriesAdapter page is displayed, as shown in Figure 10-33.
Figure 10-33 Settings of MQSeriesAdapter Page
Click the Configuration tab. The Configuration submenu options are displayed, as shown in Figure 10-34.
Figure 10-34 Settings of MQSeriesAdapter Page - Configuration Submenu Options
Click Outbound Connection Pools. The Outbound Connection Pool Configuration Table is displayed, as shown in Figure 10-35.
Figure 10-35 Outbound Connection Pool Configuration Table
Click New. The Create a New Outbound Connection page is displayed, as shown in Figure 10-36.
Figure 10-36 Create a New Outbound Connection Page
Select the javax.resource.cci.ConnectionFactory option, and click Next.
Enter a value in the JNDI Name field, for example eis/MQ/MQAdapter
, as shown in Figure 10-37.
Figure 10-37 Create a New Outbound Connection Page - JNDI Name
Click Finish. The Save Deployment Plan Assistant page is displayed.
Click OK. You have successfully created a JNDI name.
You can enable binding mode for connections for the Oracle MQ Series Adapter by modifying a few properties in the Oracle WebLogic Server Administration Console:
To enable binding mode, perform the following steps:
Log in to the Oracle WebLogic Server Administration Console using your password credentials.
Under Domain Structure, in the left pane, click Deployments. The Summary of Deployments page is displayed.
Click MQSeriesAdapter. The Settings of MQSeriesAdapter page is displayed.
Click the Configuration tab. The Configuration submenu options are displayed.
Click Outbound Connection Pools. The Outbound Connection Pool Configuration Table is displayed.
Click the + icon next to javax.resource.cci.ConnectionFactory. A list of JNDIs are displayed.
Select, eis/MQ/MQAdapter, the JNDI that you created in the Section 10.5.2, "Adding JNDI Entry". The Outbound Connection Properties page is displayed, as shown in Figure 10-38, with a list of 24 properties.
Figure 10-38 Outbound Connection Properties Page
Set the following parameters as mentioned below:
hostName: This value should always be blank.
portNumber: This value should contain some unused port numbers. For example, 44888.
channelName: This value should always be blank.
queueManagerName: This value is a valid queue manager name.
You have enabled the binding mode for connections for the Oracle MQ Series Adapter.
This section contains the following topics:
Section 10.6.3, "Inbound-Outbound Synchronous Request-Reply"
Section 10.6.8, "Reading Single or Multiple RFH2 Rules and Formatting Header Version 2 Headers"
This use case is the end-to-end demonstration of how MQ Adapter dequeues a message and enqueues the same message after transformation from the MQ Series queue. This section contains the following topics:
To perform the dequeue enqueue use case, you need the following files from the artifacts.zip
file contained in the Adapters-101MQAdapterDequeueEnqueue
sample:
artifacts/schemas/address-csv.xsd
artifacts/schemas/address-fixedLength.xsd
artifacts/input/data.txt
You can obtain the Adapters-101MQAdapterDequeueEnqueue
sample by accessing the Oracle SOA Sample Code site.
You must also create the following queues:
test_in
test_out
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter De-queueEn-queue
in the Application Name field, as shown in Figure 10-39, and then click Next. The Name Your Project screen is displayed.
Figure 10-39 The Name Your Application Page
In the Project Name field, enter De-queueEn-queueComposite
and from the Available list, select SOA and click the right-arrow button, as shown in Figure 10-40.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL, as shown in Figure 10-41, and then click Finish. The Create BPEL Process dialog is displayed.
Figure 10-41 The Configure SOA Settings Page
Enter BPELdequeueenqueue
in the Name field, and select Define Service Later from the Template box, as shown in Figure 10-42.
Figure 10-42 The Create BPEL Process Dialog
Click OK. The De-queueEn-queue application and the De-queueEn-queue project appears in the design area, as shown in Figure 10-43.
Figure 10-43 The JDeveloper - Composite.xml
Copy the address-csv.xsd
and address-fixedLength.xsd
files to the xsd folder in your project (see Section 10.6.1.1, "Prerequisites" for the location of these files).
Perform the following steps to create an adapter service that dequeues the message from a queue:
Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter InboundService
in the Service Name field, as shown in Figure 10-44, and click OK. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, as shown in Figure 10-45, and click Next. The Adapter Interface page is displayed.
Figure 10-45 The MQ Series Connection Page
Select Define from operation and schema (specified later), as shown in Figure 10-46, and click Next. The Operation Type page is displayed.
Select Get Message from MQ, as shown in Figure 10-47, and click Next. The Get Message from MQ page is displayed.
Enter test_in
in the Queue Name field, as shown in Figure 10-48, and click Next. The Messages page is displayed.
Figure 10-48 The Get Message From MQ Page
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-csv.xsd, and then Root-Element, as shown in Figure 10-49.
Click OK. The address-csv.xsd file appears in the URL field in the Messages page, as shown in Figure 10-50.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-51.
Figure 10-51 The JDeveloper Page - Composite.xml Page
Perform the following steps to create an adapter service that enqueues the messages.
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter OutboundService
in the Service Name field, and click OK. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, as shown in Figure 10-45, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), as shown in Figure 10-46, and click Next. The Operation Type page is displayed.
Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.
Enter test_out
in the Queue Name field, and click Next. The Advanced Options page is displayed, as shown in Figure 10-52.
Accept the defaults and click Next. The Messages page is displayed.
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-fixedLength.xsd, and then Root-Element, and click OK. The address-fixedLength.xsd file appears in the URL field in the Messages page.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the outbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-53.
Figure 10-53 The JDeveloper Page - Composite.xml Page
You have to assemble or 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:
Drag the small triangle in the InboundService in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in OutboundService in the External References area.
The JDeveloper Composite.xml appears, as shown in Figure 10-54.
Figure 10-54 The JDeveloper - Composite.xml
Click File, Save All.
Double-click BPELdequeueenqueue. The BPELdequeueenqueue.bpel page is displayed.
Drag and drop the Receive, Transform, and Invoke activities in the order mentioned from the Component Palette to the Components area.
The JDeveloper BPELdequeueenqueue.bpel page is displayed, as shown in Figure 10-55.
Figure 10-55 The BPELdequeueenqueue.bpel Page
Drag and drop the Receive activity to InboundService. The Receive dialog is displayed.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Check the Create Instance box, and click OK.
Drag and drop the Invoke activity to OutboundService. The Invoke dialog is displayed.
Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field.
Accept the defaults, and click OK. The Invoke dialog is displayed.
Click OK.
Double-click the Transform activity. The Transform dialog is displayed.
Click the Create... (Alt+N) icon. The Source Variable dialog is displayed.
Accept the defaults, and click OK.
Select the invoke variable as target, and click OK. The Transformation_xsl page is displayed.
Drag and drop tns:Root-Element in the Sources pane to the fix:Root-Element in the Target pane. The Auto Map Preferences dialog is displayed.
Click OK. The Transformation_xsl page is displayed, as shown in Figure 10-56.
The BPELdequeueenqueue.bpel page appears, as shown in Figure 10-57.
Figure 10-57 The BPELdequeueenqueue.bpel Page
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:
Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.
In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.
Click De-queueEn-queueComposite[1.0]. The De-queueEn-queueComposite[1.0] page is displayed.
Copy the data.txt file and put it in the test_in queue.
Wait for some time and then refresh the Fusion Middleware Control Console. An instance appears on the console. This is the instance that was triggered because of the processing that occurred.
Click the Instances tab.
Click the instance associated with this deployment. The Flow Trace page is displayed.
Click the BPELdequeueenqueue component instance. The Audit Trail page is displayed.
Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.
Click an activity to view the relevant payload details.
In this use case, the inbound Oracle MQ Series Adapter dequeues the request message from MQ Series inbound queue test_in
and publishes it to the BPEL process. The Oracle MQ Series Adapter waits for the response from the BPEL process. When the Oracle MQ Series Adapter receives the response, it enqueues the response message to the MQ Series queue specified in the replyToQueueName
queue of the request message. This use case consists of the following sections:
This example assumes that you are familiar with basic BPEL constructs, such as activities and partner links, and JDeveloper environment for creating and deploying BPEL Process.
The Oracle MQ Series Adapter must be configured as specified in Section 10.5, "Configuring the Oracle MQ Series Adapter" and a queue test_in
should be created.
To perform the inbound synchronous request-reply use case, you require the following files from the artifacts.zip
file contained in the Adapters-101MQAdapterDequeueEnqueue
sample:
artifacts/schemas/address-csv.xsd
artifacts/schemas/address-fixedLength.xsd
artifacts/input/data.txt
You can obtain the Adapters-101MQAdapterDequeueEnqueue
sample by accessing the Oracle SOA Sample Code site.
You must also create the following queues:
test_in
test_reply
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter SyncReqRes
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter Sync_ReqRes
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.
The Application Navigator of JDeveloper is updated with the new application and project and the Design tab contains, a blank palette.
Enter BPELsyncreqres
in the Name field, select Define Service Later from the Template box.
Click OK. The SyncReqRes application and Sync_ReqRes project appears in the design area, as shown in Figure 10-58.
Figure 10-58 The JDeveloper - Composite.xml
Perform the following steps to create an adapter service that dequeues the message from a queue:
Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter inbound_reqres
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection JNDI name, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ and Send Reply/Reports, and select Synchronous, as shown in Figure 10-18, and click Next. The Get Message from MQ and Send Reply/Reports page is displayed.
Select Normal in the Message Type box, and enter test_in
in the Queue Name field.
Click Next. The Response page is displayed.
Accept the defaults, and click Next. The Messages page is displayed.
Select Project Schema Files, address-csv.xsd, and then Root-Element, and click OK. The address-csv.xsd file appears in the URL field in the Messages page.
In the Send Message Schema group, click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-fixedLength.xsd, and then Root-Element, and click OK. The address-fixedLength.xsd file appears in the URL field in the Messages page.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-59.
Figure 10-59 The JDeveloper Page - Composite.xml Page
Click File, Save All.
Perform the following steps to wire components:
Drag and drop the inbound_reqres
adapter service to the BPELsyncreqres
BPEL process.
Double-click BPELsyncreqres. The BPELsyncreqres.bpel page is displayed.
Drag and drop the Receive, Transform, and Reply activities in the order mentioned from the Component Palette to the Components area.
Drag and drop the Receive activity to the inbound_reqres
adapter service. The Receive dialog is displayed.
Enter ReadMsg
in the Name field.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Check the Create Instance box in the Receive dialog, and click OK.
Drag and drop the Reply activity to the inbound_reqres
adapter service. The Reply dialog is displayed.
Enter ReplyMsg
in the Name field.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK. The variable appears in the Reply dialog.
Click OK.
Double-click the Transform activity. The Transform dialog is displayed.
Click the plus icon. The Source Variable dialog is displayed.
From the Source Variable list, select ReadMsg_DequeueEnqueue_InputVariable, and click OK.
From the Target Variable list, select ReplyMsg_DequeueEnqueue_OutputVariable.
Click the Create Mappings icon. The Transformation.xsl page is displayed, as shown in Figure 10-60.
Drag the tns:Root-Element from <sources> panel to the fix:Root-Element of the <target> panel. The Auto Map Preferences dialog is displayed.
Click OK. The JDeveloper BPELsyncreqres.bpel page is displayed, as shown in Figure 10-61.
Figure 10-61 The BPELsyncreqres.bpel Page
You must deploy the application profile for the SOA project and application you created in the earlier steps.
To deploy the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:
Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.
In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.
Click Sync_ReqRes[1.0]. The Sync_ReqRes[1.0] page is displayed.
Create an MQ message with the contents of the data.txt
file and set replyToQueueName to test_reply
. Put this message in the test_in
queue.
Wait for some time and then refresh the Fusion Middleware Control Console. An instance appears on the console. This is the instance that was triggered because of the processing that occurred.
Click the Instances tab.
Click the instance associated with this deployment. The Flow Trace page is displayed.
Click the BPELsyncreqres component instance. The Audit Trail page is displayed.
Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.
Click an activity to view the relevant payload details.
This use case is the end-to-end demonstration of the Synchronous Solicit Request-Reply scenario for MQ Adapter. In this use case, the composite dequeues the message from an inbound queue. Then, it enqueues a reply message to the replyToQueue queue as specified in the inbound message. This section contains the following topics:
To perform the inbound synchronous request-reply use case, you require the following files from the artifacts.zip
file contained in the Adapters-101MQAdapterDequeueEnqueue
sample:
artifacts/schemas/address-csv.xsd
artifacts/schemas/address-fixedLength.xsd
You must also create queues named:
test_in
test1
ReplyQ
test_reply
You can obtain the Adapters-101MQAdapterDequeueEnqueue
sample by accessing the Oracle SOA Sample Code site.
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter Sync-Req-Rep
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter Sync-Req-RepComposite
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.
Enter BPELSyncreqrep
in the Name field, select Define Service Later from the Template box.
Click OK. The Sync-Req-Rep application and Sync-Req-RepComposite project appears in the design area, as shown in Figure 10-62.
Figure 10-62 The JDeveloper - Composite.xml
Perform the following steps to create an adapter service that dequeues the message from a queue:
Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter InboundReqRepService
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ and Send Reply/Reports and Synchronous in the Operation Name box, as shown in Figure 10-18, and click Next. The Get Message from MQ and Send Reply/Reports page is displayed.
Select Normal in the Message Type list and enter test_in
in the Queue Name field and select Choose Other Schema in the Schema Options box, and click Next. The Response page is displayed.
Accept the defaults and click Next. The Message page is displayed.
Click Browse in the Get Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-csv.xsd, and Root-Element, and then click OK. The Message page is populated with the address-csv.xsd file in the Get Message Schema box.
Click Browse in the Send Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-fixedLength.xsd, and Root-Element, and then click OK. The Message page is populated with the address-fixedLength.xsd file in the Send Message Schema box.
Click Next. The Finish page is displayed.
Click Finish. You have configured the InboundReqRepService adapter service, and the composite.xml page is displayed, as shown in Figure 10-63.
Figure 10-63 The JDeveloper Page - Composite.xml Page
Perform the following steps to create an adapter service that enqueues the request messages and dequeue the corresponding response messages (report) from a queue:
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter OutboundReqRepService
in the Service Name field, and click OK. The MQ Series Connection page is displayed.
Accept the defaults and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Send Message to MQ and Get Reply/Reports, select Synchronous in the Operation Name box, and click Next. The Send Message to MQ and Get Reply/Reports page is displayed.
Enter test1
in the Queue Name field and click Next. The Response page is displayed.
Enter the name of the queue in the Reply To Queue Name field such as ReplyQ
, select the Response Wait Interval option and enter a value, and select the Empty Response Message Allowed option.
Click Next. The Advanced Options page is displayed.
Accept the default values and click Next. The Messages page is displayed.
Click Browse in the Get Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-csv.xsd, and Root-Element, and then click OK. The Message page is populated with address-csv.xsd file in the Get Message Schema box.
Click Browse in the Send Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, address-fixedLength.xsd, and Root-Element, and then click OK. The Message page is populated with address-fixedLength.xsd file in the Send Message Schema box.
Click Next. The Finish page is displayed.
Click Finish. You have configured the OutboundReqRepService service, and the composite.xml page is displayed, as shown in Figure 10-64.
Figure 10-64 The JDeveloper Page - Composite.xml Page
You have to assemble or wire the three components that you have created: InboundReqRepService, BPELSyncreqrep, and OutboundReqRepService. Perform the following steps to wire the components:
Drag the small triangle in the InboundReqRepService service in the Exposed Services area to the drop zone that appears as a green triangle in BPELSyncreqrep in the Components area.
Drag the small triangle in BPELSyncreqrep in the Components area to the drop zone that appears as a green triangle in OutboundReqRepService in the External References area.
Similarly, drag the small triangle in BPELSyncreqrep in the Components area to the drop zone in OutboundReqRepService in the External References area.
The JDeveloper Composite.xml appears, as shown in Figure 10-65.
Figure 10-65 The JDeveloper - Composite.xml
Click File, Save All.
Double-click BPELSyncreqrep. The BPELSyncreqrep.bpel page is displayed.
Drag and drop the Receive, Transform, Invoke, Assign, Reply activities in the order mentioned from the Component Palette to the Components area. The JDeveloper BPELSyncreqrep.bpel page is displayed, as shown in Figure 10-66.
Figure 10-66 The BPELSyncreqrep.bpel Page
Drag and drop the Receive activity to InboundReqRepService
. The Receive dialog is displayed.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Check the Create Instance box, as shown in Figure 10-67, and click OK.
Drag and drop the Reply activity to InboundReqRepService. The Reply dialog is displayed.
Click the Auto Create Variable icon to create the variable, and then click OK. The Reply dialog is displayed, as shown in Figure 10-68.
Drag and drop the Invoke activity to the OutboundReqRepService service. The Invoke dialog is displayed.
Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field. The Create Variable dialog is displayed.
Click OK.
Similarly, create the output variable. Accept the defaults, and click OK. The Invoke dialog is displayed, as shown in Figure 10-69.
Click OK.
Double-click the Transform activity. The Transform dialog is displayed.
Click the plus icon, and select Receive_1_DequeueEnqueue_InputVariable as the source variable. Then, select Invoke_1_EnqueueDequeue_InputVariable for the target variable, as shown in Figure 10-70.
Click Create Mapping. The Transformation_1.xsl page is displayed.
Drag and drop the tns:Root-Element from the from <sources> panel to fix:Root-Element in the <target> panel. The Auto Map Preferences dialog is displayed.
Click OK. The mappings appear in the Transformation.xsl page, as shown in Figure 10-71.
Figure 10-71 The Transformation.xsl Page with Mappings
Click the BPELSyncreqrep.bpel tab.
Double-click the Assign activity. The Assign dialog is displayed.
Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.
Select the variables, as shown in Figure 10-72, and click OK.
Figure 10-72 The Create Copy Operation Dialog
Click OK in the Assign dialog. The JDeveloper BPELSyncreqrep.bpel page is displayed, as shown in Figure 10-73.
Figure 10-73 The BPELSyncreqrep.bpel Page
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:
Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.
In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.
Click Sync-Req-RepComposite[1.0]. The Sync-Req-RepComposite[1.0] page is displayed.
Create an MQ message with the contents of the data.txt
file and set replyToQueueName to test_reply
. Put this message in the test_in
queue.
Wait for some time and then refresh the Fusion Middleware Control Console. An instance appears on the console. This is the instance that was triggered because of the processing that occurred.
Click the Instances tab.
Click the instance associated with this deployment. The Flow Trace page is displayed.
Click the BPELSyncreqrep component instance. The Audit Trail page is displayed.
Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.
Click an activity to view the relevant payload details.
This use case is the end-to-end demonstration of the Asynchronous-Request-Reply scenario. In this use case, first, the composite dequeues the message from an inbound queue. Then, it enqueues a request message and dequeues the reply message. Finally, the composite enqueues the reply message to the other queue. This section contains the following topics:
Section 10.6.4.4, "Creating an Asynchronous Outbound Request Reply Adapter Service Outbound"
Section 10.6.4.8, "Monitoring Using the Fusion Middleware Control Console"
The Oracle MQ Series Adapter must be configured as specified in Section 10.5, "Configuring the Oracle MQ Series Adapter" and create the following queues: test_in, test_out, and test_demo queues.
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter AsynchronousRequestReply
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter Async-Req-RepComposite
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.
Enter BPELAsyncreqrep
in the Name field, select Define Service Later from the Template box.
Click OK. The AsynchronousRequestReply application and the Async-Req-RepComposite project appear in the design area, as shown in Figure 10-74.
Figure 10-74 The JDeveloper - Composite.xml
Perform the following steps to create an adapter service that dequeues the message from a queue:
Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter InboundService
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ and click Next. The Get Message from MQ page is displayed.
Enter test_in
in the Queue Name field and click Next. The Messages page is displayed.
Select Native Format Translation is not required (Schema is Opaque) and click Next. The Finish page is displayed.
Click Finish. You have configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-75.
Figure 10-75 The JDeveloper Page - Composite.xml Page
Perform the following steps to create an adapter service that enqueues the request messages and dequeue the corresponding response messages (report) from a queue:
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter asyn-Req-Res
in the Service Name field, and click OK. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Send Message to MQ and Get Reply/Reports and select Asynchronous in the Operation Name box, and then click Next. The Send Message to MQ and Get Reply/Reports page is displayed.
Select Normal in the Message Type box and enter test_out
in the Queue Name field, and then select the Get Reports check box, and click Next. The Reports page is displayed.
Select Confirmation on Arrival, as shown in Figure 10-76, and click Next. The Response page is displayed.
Figure 10-76 The Adapter Configuration Wizard Reports Page
Enter test_out
in the Reply To Queue Name field, and click Next. The Advanced Options page is displayed.
Accept the default values, and click Next. The Messages page is displayed.
Select Native Format Translation is not Required(Schema is Opaque) in both the Get Message Schema and Send Message Schema boxes, and click Next. The Finish page is displayed.
Click Finish. You have configured the async-Req-Res service, and the composite.xml page is displayed, as shown in Figure 10-77.
Figure 10-77 The JDeveloper Page - Composite.xml Page
Perform the following steps to create an adapter service that enqueues the response (report) messages.
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter OutboundService
in the Service Name field, and click OK. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.
Enter test_demo
in the Queue Name field, and click Next. The Advanced Options page is displayed.
Accept the default values, and click Next. The Messages page is displayed.
Select Native Format Translation is not required(Schema is Opaque), and click Next. The Finish page is displayed.
Click Finish. You have configured the OutboundService service, and the composite.xml page is displayed, as shown in Figure 10-78.
Figure 10-78 The JDeveloper Page - Composite.xml Page
You have to assemble or wire the four components that you have created: Inbound adapter service, BPEL process, async-Req-Res, and Outbound adapter reference. Perform the following steps to wire the components:
Drag the small triangle in the InboundService service in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in async-Req-Res in the External References area.
Similarly, drag the small triangle in the BPEL process in the Components area to the drop zone in OutboundService in the External References area.
The JDeveloper Composite.xml appears, as shown in Figure 10-79.
Figure 10-79 The JDeveloper - Composite.xml
Click File, Save All.
Double-click BPELAsyncreqrep. TheDequeueEnqueueRFH2.bpel page is displayed.
Drag and drop the Receive, Assign, Invoke, Receive, Assign, Invoke activities in the order mentioned from the Component Palette to the Components area. The JDeveloper BPELAsyncreqrep.bpel page is displayed, as shown in Figure 10-80.
Figure 10-80 The BPELAsyncreqrep.bpel Page
Drag and drop the first Receive activity to the InboundService adapter service. The Receive dialog is displayed.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Check the Create Instance box, and click OK.
Drag and drop the first Invoke activity to the async-Req-Res service. The Invoke dialog is displayed.
Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field.
Accept the defaults, and click OK. The Invoke dialog is displayed.
Click OK.
Drag and drop the second Receive activity to the async-Req-Rep service. The Receive dialog is displayed.
Click the Auto Create Variable icon to create variable.
Note:
Do not check the Create Instance box.
Click OK in the Receive dialog.
Drag and drop the second Invoke activity to OutboundService. The Invoke dialog is displayed.
Click the Automatically Create Input Variable icon to create a variable.
Click OK in the Invoke dialog.
Double-click the first Assign activity. The Assign dialog is displayed.
Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.
Select the variables, as shown in Figure 10-81, and click OK.
Figure 10-81 The Create Copy Operation Dialog
Click OK in the Assign dialog.
Double-click the second Assign activity. The Assign dialog is displayed.
Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.
Select the variables, as shown in Figure 10-82, and click OK.
Figure 10-82 The Create Copy Operation Dialog
Click OK in the Assign dialog. The JDeveloper BPELAsyncreqrep.bpel page is displayed, as shown in Figure 10-83.
Figure 10-83 The BPELAsyncreqrep.bpel Page
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:
Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.
In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.
Click Async-Req-RepComposite[1.0]. The Async-Req-RepComposite[1.0] page is displayed.
Put a message that has the content that conforms to the address-csv.xsd and also contains the Reply Queue as the header in the test_in queue.
Wait for some time and then refresh the Fusion Middleware Control Console. An instance appears on the console. This is the instance that was triggered because of the processing that occurred.
Click the Instances tab.
Click the instance associated with this deployment. The Flow Trace page is displayed.
Click the BPELAsyncreqrep component instance. The Audit Trail page is displayed.
Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.
Click an activity to view the relevant payload details.
This use case is the end-to-end demonstration of how MQ Adapter dequeues a single message at a time. This section contains the following topics:
Section 10.6.5.3, "Creating an Outbound Dequeue Adapter Service"
Section 10.6.5.6, "Monitoring Using the Fusion Middleware Control Console"
To perform the outbound dequeue use case, you require the following files from the Adapters-101MQAdapterDequeueEnqueue
sample:
De-queueEn-queue/De-queueEn-queueComposite/xsd/singleString.xsd
You also require the following files from the artifacts.zip
file contained in the Adapters-101MQAdapterDequeueEnqueue
sample:
artifacts/input/data.txt
You can onbtain the Adapters-101MQAdapterDequeueEnqueue
sample by accessing the Oracle SOA Sample Code site.
You must also create a queue named test_out
.
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter OutboundDequeue
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter OutboundDequeueComposite
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.
Enter BPELOutboundDequeue
in the Name field, select Synchronous BPEL Process in the Template box.
Click Browse at the end of the Input field. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, singleString, and then click OK.
Click Browse at the end of the Output field. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, singleString, and then click OK.
Click OK. The OutboundDequeue application and OutboundDequeueComposite project appears in the design area, as shown in Figure 10-84.
Figure 10-84 The JDeveloper - Composite.xml
Perform the following steps to create an adapter service that dequeues the message to a queue:
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter OutboundDequeueService
in the Service Name field, and click OK. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ and Synchronous, and click Next. The Get Message from MQ page is displayed.
Enter test_out
in the Queue Name field and enter 10
in the Wait Interval field, and then click Next. The Messages page is displayed.
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, and then singleString, and click OK. The singleString.xsd file appears in the URL field in the Messages page.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-85.
Figure 10-85 The JDeveloper Page - Composite.xml Page
Click File, Save All.
You have to assemble or wire the three components that you have created: Client, BPEL process, and Outbound adapter reference. Perform the following steps to wire the components:
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in OutboundDequeueService in the External References area.
Double-click BPELOutboundDequeue. The BPELOutboundDequeue.bpel page is displayed.
Drag and drop the Invoke and Assign activities in the order mentioned from the Component Palette to the Components area in between the receiveInput and replyOutput activities.
The composite.xml page is displayed, as shown in Figure 10-86.
Figure 10-86 The JDeveloper - Composite.xml Page
The JDeveloper BPELOutboundDequeue.bpel page is displayed, as shown in Figure 10-87.
Figure 10-87 The BPELOutboundDequeue.bpel Page
Drag and drop the Invoke activity to the OutboundDequeueService adapter reference. The Invoke dialog is displayed.
Click the Auto Create Variable icon that appears at the end of the Input Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Repeat the same for the output variable and click OK.
Double-click the Assign activity. The Assign dialog is displayed.
Click the plus icon and select Copy Operation. The Create Copy Operation dialog is displayed.
Select the variables, as shown in Figure 10-88, and then click OK.
Figure 10-88 Create Copy Operation Dialog
Click OK in the Assign dialog.
The BPELOutboundDequeue.bpel page appears, as shown in Figure 10-89.
Figure 10-89 The BPELOutboundDequeue.bpel Page
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:
Log in to http://servername:portnumber/em using your username/password.
In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.
Click OutboundDequeueComposite[1.0]. The OutboundDequeueComposite[1.0] page is displayed.
Click the Test button. The Test Web Service page is displayed.
Click the Request tab, and scroll to the Input Arguments pane.
Enter Test Outbound Dequeue
in the Input field, and then click the Test Web Service button.
Wait for some time and then click the Response tab. The message in the singleString xsd that you provided appears in the Response tab.
Click the Instances tab.
Click the instance associated with this deployment. The Flow Trace page is displayed.
Click the BPELOutboundDequeue component instance. The Audit Trail page is displayed, as shown in Figure 10-90.
Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.
Click an activity to view the relevant payload details.
This use case demonstrates how a backout queue must be configured for Oracle MQ Series Adapter. Oracle MQ Series Adapter dequeues a message and enqueues the same message after transformation from the MQ Series queue. During this process, a failure can occur either during an invoke activity or when a response is being sent. You must configure a Backout Queue to send the rejected messages to a Backout Queue instead of the default rejected messages folder. This section contains the following topics:
To perform the use case for configuring a backout queue, you must ensure that the adapter JNDI is configured for XA. Also, you require the singleString.xsd
file, which you can create using the following code:
<schema attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/singleString" xmlns="http://www.w3.org/2001/XMLSchema"> <element name="singleString"> <complexType> <sequence> <element name="input" type="string"/> </sequence> </complexType> </element> </schema>
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter MQ_BackoutQ_Retry
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter SOA_BackoutQ_Retry
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL, and then click Finish. The Create BPEL Process dialog is displayed.
Enter BPELProcess_BackoutQ_Retry
in the Name field, and select Define Service Later from the Template box.
Click OK. The MQ_BackoutQ_Retry application and the SOA_BackoutQ_Retry project appears in the design area.
Perform the following steps to create an adapter service that dequeues the message and put the message to a queue:
Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter InboundService
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ and Send Reply/Reports (Synchronous), and click Next. The Get Message from MQ and Send Rep page is displayed.
Enter INBOUND_QUEUE
in the Queue Name field, and click Next. The Response page is displayed.
Accept the defaults, and click Next. The Messages page is displayed.
Click Browse at the end of the URL fields. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, and then singleString.
Click OK. The singleString.xsd file appears in the URL fields in the Messages page.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed with an inbound adapter added.
Add the Backout Queue properties to the corresponding JCA
file (ReqReply_mq.jca
), as shown in the following sample:
<property name="BackoutQueueName" value="BACKOUT.QUEUE"/> <property name="MaximumBackoutCount" value="5"/> <property name="BackoutRetries" value="3"/>
Perform the following steps to create an adapter service that enqueues the messages.
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter EQ
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.
Enter a test_out
in the Queue Name field, and click Next. The Advanced Options page is displayed.
Accept the defaults and click Next. The Messages page is displayed.
Click Browse at the end of the URL field. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, and then singleString, and click OK. The singleString.xsd file appears in the URL field in the Messages page.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the outbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-91.
Figure 10-91 The JDeveloper Page - Composite.xml Page
You have to assemble or 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:
Drag the small triangle in the InboundService in the Exposed Services area to the drop zone that appears as a green triangle in the BPEL process in the Components area.
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in OutboundService in the External References area.
The JDeveloper Composite.xml appears, as shown in Figure 10-92.
Figure 10-92 The JDeveloper - Composite.xml
Click File, Save All.
Double-click BPELProcess_BackoutQ_Retry. The BPELProcess_backoutQ_Retry.bpel page is displayed.
Drag and drop the Receive, Assign, Invoke, and Reply activities in the order mentioned from the Component Palette to the Components area.
Drag and drop the Receive activity to ReqReply. The Receive dialog is displayed.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Check the Create Instance box, and click OK.
Drag and drop the Reply activity to ReqReply. The Reply dialog is displayed.
Enter ReplyOutput
in the Name field.
Click the Browse Variables icon that appears at the end of the Variable field. The Variable Chooser dialog is displayed.
Select replyOutput_DequeueEnqueue_OutputVariable, and click OK. The variable appears in the Reply dialog.
Click OK.
Drag and drop the Invoke activity to EQ. The Invoke dialog is displayed.
Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field.
Accept the defaults, and click OK. The Invoke dialog is displayed.
Click OK.
Double-click the Assign activity. The Assign dialog is displayed.
Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.
In the Create Copy Operation dialog, select receiveInput_DequeueEnqueue_InputVariable
as the From Type and select the variable in the To pane to which the copy operation is being created.
The following is a code snippet from the BPELProcess_BackoutQ_Retry.bpel file, with the copy operation defined:
<assign name="Assign_1"> <copy> <from variable="receiveInput_DequeueEnqueue_InputVariable" part="singleString" query="/ns3:singleString/ns3:input"/> <to variable="Invoke_1_Enqueue_InputVariable" part="body" query="/ns3:singleString/ns3:input"/> </copy> <copy> <from variable="receiveInput_DequeueEnqueue_InputVariable" part="singleString" query="/ns3:singleString/ns3:input"/> <to variable="replyOutput_DequeueEnqueue_OutputVariable" part="singleString" query="/ns3:singleString/ns3:input"/> </copy> </assign>
Click OK. The BPELdequeueenqueue.bpel page appears, as shown in Figure 10-93.
Figure 10-93 The BPELProcess_BackoutQ_Retry.bpel Page
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:
Navigate to http://
servername:portnumber
/em
. The composite you deployed appears in the application navigator.
Disable (Put Inhibit) the test_out queue or the reply queue that is provided with the Inbound message and then put a message to the INBOUND_QUEUE
.
Wait for some time and then refresh the Fusion Middleware Control Console. Instances that are triggered because of the processing appear on the console.
Note:
The number of instances that are triggered must be equal to BackoutRetries + 1
.
Click the Instances tab.
Click an instance associated with this deployment. The Flow Trace page is displayed.
Click the BPELProcess_BackoutQ_Retry component instance. The Audit Trail page is displayed.
Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.
Click an activity to view the relevant payload details.
You can configure the MQ Series Adapter to use CCDT for connection details; you can use the CCDT to connect to the first available queue manager from a list of queue managers.
For example, in this use case, there are three queue managers QM1, QM2 and QM3 with the basic properties as indicated in the table bekow.
The MQ adapter can, dynamically at runtime, connect to any of the three queue managers, depending on the one that is available (that is, if QM1 is down, the MQ adapter automatically connects to QM2; and if QM2 is also down, then the MQ Adapter must connect to QM3).
Example queue manager properties are provided in the table below.
Queue Manager Name | QM1 | QM2 | QM3 |
---|---|---|---|
Hostname |
localhost |
localhost |
10.177.255.25 |
PortName |
1414 |
2414 |
1414 |
Server Connection Channel Name |
channel.QM1 |
channel.QM2 |
channel.QM3 |
To achieve this, the CCDT needs to configured as follows :
Channel name | Queue manager name | Connection name |
---|---|---|
channel.QM1 |
MyQM_group |
localhost(1414) |
channel.QM2 |
MyQM_group |
localhost(2414) |
channel.QM3 |
MyQM_group |
10.177.255.25(1414) |
Once you have created a CCDT, a single ConnectionFactory JNDI needs to be configured to use this CCDT. The following ConnectionFactory properties need to configured in that JNDI:
CCDTurl
QueueManagerName
The CCDTurl must point to the URL of the CCDT file that is used by the MQ Series Adapter to supply client connection details. For example, the values provided can be either of:
file:/scratch/username/ccdt/AMQCLCHL.TAB
ftp://userName:password@myServer/definitionPath/AMQCLCHL.TAB
In the use case above, the value of the QueueManagerName property must be set to MyQM_group
.
This name indicates that MQ Series Adapter should connect to the first available queue manager which has a client definition entry in the CCDT having Queue manager name as MyQM_group
.
The property QueueManagerName is matched against the queue manager name defined in the CCDT and not the actual queue manager name. In general, the QueueManagerName should be provided appropriate values, using the considerations listed below:
If you only specify a queue manager name, for example QM_default
, the CCDT will be searched in alphabetical order for a client channel that contains in its definition a QueueManager name that matches exactly (and is case sensitive) to the one specified
If an asterisk is included at the beginning of the specified queue manager name, for example QM_default
, then the CCDTis searched in alphabetical order of channel name, for an entry that matches the queue manager name with or without the asterisk. If two or more client channel definitions have the queue manager names defined as QM_default, then the first available queue manager is connected to.
If the queue manager name is not specified in the CCDT, then the Queue Manager name in the JNDI should be a "*".
These two properties are the only required configuration for informing the MQ Series Adapter to use CCDT for connection details. The use of CCDT does not affect the configuration required for other MQ adapter features such as support for SSL, Exits or XA
If other ConnectionFactory properties such as Hostname, PortNumber, ChannelName are configured and the CCDT is also configured, the CCDT will take precedence over the those properties.
Once these ConnectionFactory properties are set, and this JNDI is used in any composite process, the MQ Adapter connects to the first available queue manager from QM1, QM2 and QM3.
You can dequeue and read MQ messages that contain single or multiple RFH2 headers, in addition to enqueueing messages with multiple RFH2 headers. Ths feature includes the following functionality:
Reading and writing the properties from the fixed portion of the RFH2 headers.
Reading and writing multiple occurrences of any individual folder within any RFH2 header.
Reading and writing multiple RFH2 header occurrences in a single message.
The RFH2 header enables the message producer to add more header properties to the payload and to provide other additional information.
By providing the MQ adapter the ability to read and write this information as header properties, you can perform specific processing of the message payload depending on the RFH2 header properties.
The following use cases provide examples of two types of scenarios.
This sample demonstrates the use of the MQ Adapter for processing MQ messages containing one or more RFH2 headers.
An MQ message containing two RFH2 headers is dequeued from a queue and a new message with the same payload, but with updated RFH2 headers is enqueued to another queue.
The steps for creating this use case sample include:
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter DequeueEnqueueRFH2
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter DequeueEnqueueRFH2
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL, and then click Finish. The Create BPEL Process dialog is displayed.
Enter DequeueEnqueueRFH2
in the Name field, and select Define Service Later from the Template box.
Click OK. The DequeueEnqueueRFH2
application and the DequeueEnqueueRFH2
project appears in the design area.
Perform the following steps to create an adapter service that dequeues the message and put the message to a queue:
Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter InboundMQ
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ (do not check Synchronous), and click Next. The Get Message from MQ page is displayed.
Enter queue1
in the Queue Name field, select Choose Other Schema, click Next. The Messages page is displayed.
Select Native Format is not required (Schema is opaque), and click Next. The Finish page is displayed.
Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed with an inbound adapter added.
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter OutboundMQ
in the Service Name field, and click Next. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Put Message into MQ. Click Next. The Put Message into MQ page is displayed.
Enter queue2
in the Queue Name field. Click Next. The Advanced Options page is displayed.
Accept the defaults and click Next. The Messages page is displayed.
Select Native Format Translation is Not Required (Schema is Opaque)
and click Next. The Finish page is displayed.
Click Finish. You have now configured the outbound adapter service, and the composite.xml
page is displayed, as shown in Figure 10-91.
Figure 10-94 The JDeveloper Page - Composite.xml Page
You have to assemble or 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:
Drag the small triangle in the InboundMQ in the ExposedServices area to the drop zone that appears as a green triangle in DequeueEnqueueRFH2 in the Components area.
Drag the small triangle in DequeuEnqueueRFH2 in the Components area to the drop zone that appears as a green triangle in OutboundMQ in the External Refereences area.
The composite.xml page is displayed, as shown in Figure 10-86.
Figure 10-95 The JDeveloper - Composite.xml Page
Click File, Save All.
Double-click DequeueEnqueueRFH2. The DequeueEnqueueRFH2.bpel page is displayed.
Drag and drop the Receive, Assign and Invoke activities in the order mentioned from the Component Palette to the Components area.
The JDeveloper DequeueEnqueueRFH2.bpel page is displayed.
Drag and drop the Receive activity to the Inbound Service. The Receive dialog is displayed.
Click the AutoCreate Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Click the Create Instance box, and click OK.
Drag and drop the Invoke activity to the Outbound Service. The Invoke dialog is displayed.
Click the Automatically Create Input Input Variable icon that appears at the end of the Input Variable field.
Accept the defaults, and click OK. The Invoke dialog is displayed.
Click OK.
Double-click the Assign activity. The Assign dialog is displayed.
Select the variables, and click the Plus icon.
Click OK in the Assign dialog. The JDeveloper DequeueEnqueueRFH2.bpel.html
is displayed.
Figure 10-98 The DequeueEnqueueRFH2.bpel page
Create temporary variables to store the RFH2 header portions.
Open the Source tab of the DequeueEnqueueRFH2.bpel
page.
Under the <variables> tab add the following new variables:
<variable name="RFH2.StructId" type="xsd:string"/> <variable name="RFH2.Version" type="xsd:string"/> <variable name="RFH2.Encoding" type="xsd:string"/> <variable name="RFH2.CodedCharSetId" type="xsd:string"/> <variable name="RFH2.Format" type="xsd:string"/> <variable name="RFH2.Flags" type="xsd:string"/> <variable name="RFH2.NameValueCCSID" type="xsd:string"/> <variable name="RFH2.JMSFolder" type="xsd:string"/> <variable name="RFH2.MCDFolder" type="xsd:string"/> <variable name="RFH2.USRFolder" type="xsd:string"/> <variable name="RFH2.USRFolder_2" type="xsd:string"/> <variable name="RFH2.PSCFolder" type="xsd:string"/> <variable name="RFH2extrafolder" type="xsd:string"/> <variable name="RFH2_2.StructId" type="xsd:string"/> <variable name="RFH2_2.Version" type="xsd:string"/> <variable name="RFH2_2.Encoding" type="xsd:string"/> <variable name="RFH2_2.CodedCharSetId" type="xsd:string"/> <variable name="RFH2_2.Format" type="xsd:string"/> <variable name="RFH2_2.Flags" type="xsd:string"/> <variable name="RFH2_2.NameValueCCSID" type="xsd:string"/> <variable name="RFH2_2.JMSFolder" type="xsd:string"/> <variable name="RFH2_2.JMSFolder_2" type="xsd:string"/> <variable name="RFH2_2.MCDFolder" type="xsd:string"/> <variable name="RFH2_2.USRFolder" type="xsd:string"/> <variable name="RFH2_2.USRFolder_2" type="xsd:string"/> <variable name="RFH2_2.PSCFolder" type="xsd:string"/> <variable name="TotalRFH2" type="xsd:string"/>
Configure the Receive Activity to receive RFH2 header properties in the temporary variables created above.
Open the Source tab of the DequeueEnqueueRFH2.bpel
page.
Under the <receive> tag add the following entries.
<bpelx:property name="jca.mq.RFH2.StructId" variable="RFH2.StructId"/> <bpelx:property name="jca.mq.RFH2.Version" variable="RFH2.Version"/> <bpelx:property name="jca.mq.RFH2.Encoding" variable="RFH2.Encoding"/> <bpelx:property name="jca.mq.RFH2.CodedCharSetId" variable="RFH2.CodedCharSetId"/> <bpelx:property name="jca.mq.RFH2.Format" variable="RFH2.Format"/> <bpelx:property name="jca.mq.RFH2.Flags" variable="RFH2.Flags"/> <bpelx:property name="jca.mq.RFH2.NameValueCCSID" variable="RFH2.NameValueCCSID"/> <bpelx:property name="jca.mq.RFH2.JMSFolder" variable="RFH2.JMSFolder"/> <bpelx:property name="jca.mq.RFH2.MCDFolder" variable="RFH2.MCDFolder"/> <bpelx:property name="jca.mq.RFH2.USRFolder" variable="RFH2.USRFolder"/> <bpelx:property name="jca.mq.RFH2.USRFolder_2" variable="RFH2.USRFolder_2"/> <bpelx:property name="jca.mq.RFH2.PSCFolder" variable="RFH2.PSCFolder"/> <bpelx:property name="jca.mq.RFH2.mq_usr" variable="RFH2extrafolder"/> <bpelx:property name="jca.mq.RFH2_2.StructId" variable="RFH2_2.StructId"/> <bpelx:property name="jca.mq.RFH2_2.Version" variable="RFH2_2.Version"/> <bpelx:property name="jca.mq.RFH2_2.Encoding" variable="RFH2_2.Encoding"/> <bpelx:property name="jca.mq.RFH2_2.CodedCharSetId" variable="RFH2_2.CodedCharSetId"/> <bpelx:property name="jca.mq.RFH2_2.Format" variable="RFH2_2.Format"/> <bpelx:property name="jca.mq.RFH2_2.Flags" variable="RFH2_2.Flags"/> <bpelx:property name="jca.mq.RFH2_2.NameValueCCSID" variable="RFH2_2.NameValueCCSID"/> <bpelx:property name="jca.mq.RFH2_2.JMSFolder" variable="RFH2_2.JMSFolder"/> <bpelx:property name="jca.mq.RFH2_2.JMSFolder_2" variable="RFH2_2.JMSFolder_2"/> <bpelx:property name="jca.mq.RFH2_2.MCDFolder" variable="RFH2_2.MCDFolder"/> <bpelx:property name="jca.mq.RFH2_2.USRFolder" variable="RFH2_2.USRFolder"/> <bpelx:property name="jca.mq.RFH2_2.PSCFolder" variable="RFH2_2.PSCFolder"/> <bpelx:property name="jca.mq.RFH2_2.USRFolder_2" variable="RFH2_2.USRFolder_2"/> <bpelx:property name="jca.mq.RFH2.Total.Headers" variable="TotalRFH2"/>
Configure the Invoke activity to push modified RFH2 header properties to the outbound message.
Open the Source tab of the DequeueEnqueueRFH2.bpel page
Under the <invoke> tag add the following entries
<bpelx:inputProperty name="jca.mq.MQMD.Format" expression="'RF_HDR_2'"/> <bpelx:inputProperty name="jca.mq.RFH2.StructId" variable="RFH2.StructId"/> <bpelx:inputProperty name="jca.mq.RFH2.Version" variable="RFH2.Version"/> <bpelx:inputProperty name="jca.mq.RFH2.CodedCharSetId" variable="RFH2.CodedCharSetId"/> <bpelx:inputProperty name="jca.mq.RFH2.Encoding" variable="RFH2.Encoding"/> <bpelx:inputProperty name="jca.mq.RFH2.Flags" variable="RFH2.Flags"/> <bpelx:inputProperty name="jca.mq.RFH2.Format" expression="'MQHRF2 '"/> <bpelx:inputProperty name="jca.mq.RFH2.NameValueCCSID" variable="RFH2.NameValueCCSID"/> <bpelx:inputProperty name="jca.mq.RFH2.JMSFolder" variable="RFH2.JMSFolder"/> <bpelx:inputProperty name="jca.mq.RFH2.MCDFolder" variable="RFH2.MCDFolder"/> <bpelx:inputProperty name="jca.mq.RFH2.USRFolder" variable="RFH2.USRFolder"/> <bpelx:inputProperty name="jca.mq.RFH2.mq_usr" variable="RFH2extrafolder"/> <bpelx:inputProperty name="jca.mq.RFH2_2.StructId" expression="'RFH '"/> <bpelx:inputProperty name="jca.mq.RFH2_2.Version" expression="'2'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.CodedCharSetId" expression="'819'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.Encoding" expression="'273'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.Flags" expression="'0'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.Format" expression="'MQSTR '"/> <bpelx:inputProperty name="jca.mq.RFH2_2.NameValueCCSID" expression="'1208'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.JMSFolder" expression="'<jms><Dst>MYTOPIC</Dst><Exp>2000</Exp><Pri>4</Pri><Cid>22344</Cid><Rto>REPLY.QUEUE</Rto><Gid>3334</Gid><Seq>2</Seq><Dlv>1</Dlv><xxx>UserSpace</xxx></jms>'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.JMSFolder_2" variable="RFH2_2.JMSFolder_2"/> <bpelx:inputProperty name="jca.mq.RFH2_2.MCDFolder" expression="'<mcd><Msd>jms_object</Msd></mcd>'"/> <bpelx:inputProperty name="jca.mq.RFH2_2.USRFolder" variable="RFH2_2.USRFolder"/> <bpelx:inputProperty name="jca.mq.RFH2_2.USRFolder_2" variable="RFH2_2.USRFolder_2"/>
Click File, Save All.
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
You must place the MQ message with the correct RFH2 headers in the inbound queue.
The sample is configured to obtain two RFH2 headers from the inbound message (this can be changed by configuring the BPEL process as required). The test input MQ message should have the following:
Payload: Any message (any format will be acceptable becaise we are using Opaque)
RFH2 header 1: Should contain 2 USR folders, 1 JMS folder, 1 PSC folder, 1 MCD folder and 1 mq_usr folder.
RFH2 header 2: Should contain 2 USR folders, 2 JMS folders, 1 PSC folder and 1 MCD folder.
Deploy the sample and put the above message to the inbound queue. Check the outbound queue for a new message having modified RFH2 headers (as configured in the BPEL invoke activity)
This sample demonstrates the use of the MQ Adapter for obtaining MQ messages containing one or more RFH2 headers in an outbound dequeue scenario.
In this sample, an MQ message containing two RFH2 headers is dequeued from a queue in the outbound queue scenario.
The steps for creating this use case sample include:
You must create a JDeveloper application to contain the SOA composite. To create an application and a project for the use case, perform the following:
In JDeveloper, click File and select New.
The New Gallery dialog is displayed.
Expand the General node, and select the Applications category.
In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.
In the Name Your Application screen, enter OutboundDequeueRFH2
in the Application Name field, and then click Next. The Name Your Project screen is displayed.
In the Project Name field, enter OutboundDequeueRFH2
and from the Available list, select SOA and click the right-arrow button.
Click Next. The Configure SOA Settings screen is displayed.
In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.
Enter OutboundDequeueRFH2
in the Name field, select Synchronous BPEL Process in the Template box.
Click Browse at the end of the Input field. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, singleString, and then click OK.
Click Browse at the end of the Output field. The Type Chooser dialog is displayed.
Select Project Schema Files, singleString.xsd, singleString, and then click OK.
Click OK. The OutboundDequeueRFH2 application and OutboundDequeueRFH2 Composite project appear in the design area.
Perform the following steps to create an adapter service that dequeues the message to a queue:
Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.
Click Next. The Service Name page is displayed.
Enter OutboundDQ
in the Service Name field, and click OK. The MQ Series Connection page is displayed.
Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.
Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.
Select Get Message from MQ and Synchronous, and click Next. The Get Message from MQ page is displayed.
Enter queue1
in the Queue Name field and enter 10 seconds
in the Wait Interval field, and then click Next. The Messages page is displayed.
Select Native Form at Translation is not required (Schema is Opaque) and click OK.
Click Next. The Finish page is displayed.
Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-99.
Figure 10-99 The JDeveloper-composite.xml
Click File, Save All.
You must assemble or wire the three components that you have created: Client, BPEL process, and OutboundDQ adapter reference.
Perform the following steps to wire the components:
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in the OutboundDequeueService in the External References area.
Double-click the OutboundDequeueRFH2 bpel process. The OutboundDequeueRFH2.bpel page is displayed.
The JDeveloper Composite.xml appears, as shown in Figure 10-92.
Click File, Save All.
Double-click OutboundDequeueRFH2.bpel. The OutboundDequeueRFH2.bpel page is displayed.
Drag and drop the Invoke and Assign activities in the order mentioned from the Component Palette to the Components area in between the receiveInput and replyOutput activities.
Drag and drop the Invoke activity to the OutboundDQ adapter reference. The Invoke dialog is displayed.
Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.
Accept the defaults, and click OK.
Repeat the same for the output variable and click OK.
Double-click the Assign activity. The Assign dialog is displayed.
Select the variables, and click the Plus icon.
.Click OK in the Assign dialog. The JDeveloper BPELOutboundDequeue.bpel
page is displayed.
Create temporary variables to store the RFH2 header portions.
Open the Source tab of the DequeueEnqueueRFH2.bpel page.
Under the <variables> tab add the following new variables.
<variable name="RFH2.StructId" type="xsd:string"/> <variable name="RFH2.Version" type="xsd:string"/> <variable name="RFH2.Encoding" type="xsd:string"/> <variable name="RFH2.CodedCharSetId" type="xsd:string"/> <variable name="RFH2.Format" type="xsd:string"/> <variable name="RFH2.Flags" type="xsd:string"/> <variable name="RFH2.NameValueCCSID" type="xsd:string"/> <variable name="RFH2.JMSFolder" type="xsd:string"/> <variable name="RFH2.MCDFolder" type="xsd:string"/> <variable name="RFH2.USRFolder" type="xsd:string"/> <variable name="RFH2.USRFolder_2" type="xsd:string"/> <variable name="RFH2.PSCFolder" type="xsd:string"/> <variable name="RFH2extrafolder" type="xsd:string"/> <variable name="RFH2_2.StructId" type="xsd:string"/> <variable name="RFH2_2.Version" type="xsd:string"/> <variable name="RFH2_2.Encoding" type="xsd:string"/> <variable name="RFH2_2.CodedCharSetId" type="xsd:string"/> <variable name="RFH2_2.Format" type="xsd:string"/> <variable name="RFH2_2.Flags" type="xsd:string"/> <variable name="RFH2_2.NameValueCCSID" type="xsd:string"/> <variable name="RFH2_2.JMSFolder" type="xsd:string"/> <variable name="RFH2_2.JMSFolder_2" type="xsd:string"/> <variable name="RFH2_2.MCDFolder" type="xsd:string"/> <variable name="RFH2_2.USRFolder" type="xsd:string"/> <variable name="RFH2_2.USRFolder_2" type="xsd:string"/> <variable name="RFH2_2.PSCFolder" type="xsd:string"/> <variable name="TotalRFH2" type="xsd:string"/>
Configure the Invoke Activity to receive the RFH2 header properties from the outbound dequeue message.
Open the Source tab of the DequeueEnqueueRFH2.bpel page.
Under the <invoke> tag add the following entries.
<bpelx:outputProperty name="jca.mq.RFH2.StructId" variable="RFH2.StructId"/> <bpelx:outputProperty name="jca.mq.RFH2.Version" variable="RFH2.Version"/> <bpelx:outputProperty name="jca.mq.RFH2.Encoding" variable="RFH2.Encoding"/> <bpelx:outputProperty name="jca.mq.RFH2.CodedCharSetId" variable="RFH2.CodedCharSetId"/> <bpelx:outputProperty name="jca.mq.RFH2.Format" variable="RFH2.Format"/> <bpelx:outputProperty name="jca.mq.RFH2.Flags" variable="RFH2.Flags"/> <bpelx:outputProperty name="jca.mq.RFH2.NameValueCCSID" variable="RFH2.NameValueCCSID"/> <bpelx:outputProperty name="jca.mq.RFH2.JMSFolder" variable="RFH2.JMSFolder"/> <bpelx:outputProperty name="jca.mq.RFH2.MCDFolder" variable="RFH2.MCDFolder"/> <bpelx:outputProperty name="jca.mq.RFH2.USRFolder" variable="RFH2.USRFolder"/> <bpelx:outputProperty name="jca.mq.RFH2.USRFolder_2" variable="RFH2.USRFolder_2"/> <bpelx:outputProperty name="jca.mq.RFH2.PSCFolder" variable="RFH2.PSCFolder"/> <bpelx:outputProperty name="jca.mq.RFH2.mq_usr" variable="RFH2extrafolder"/> <bpelx:outputProperty name="jca.mq.RFH2_2.StructId" variable="RFH2_2.StructId"/> <bpelx:outputProperty name="jca.mq.RFH2_2.Version" variable="RFH2_2.Version"/> <bpelx:outputProperty name="jca.mq.RFH2_2.Encoding" variable="RFH2_2.Encoding"/> <bpelx:outputProperty name="jca.mq.RFH2_2.CodedCharSetId" variable="RFH2_2.CodedCharSetId"/> <bpelx:outputProperty name="jca.mq.RFH2_2.Format" variable="RFH2_2.Format"/> <bpelx:outputProperty name="jca.mq.RFH2_2.Flags" variable="RFH2_2.Flags"/> <bpelx:outputProperty name="jca.mq.RFH2_2.NameValueCCSID" variable="RFH2_2.NameValueCCSID"/> <bpelx:outputProperty name="jca.mq.RFH2_2.JMSFolder" variable="RFH2_2.JMSFolder"/> <bpelx:outputProperty name="jca.mq.RFH2_2.JMSFolder_2" variable="RFH2_2.JMSFolder_2"/> <bpelx:outputProperty name="jca.mq.RFH2_2.MCDFolder" variable="RFH2_2.MCDFolder"/> <bpelx:outputProperty name="jca.mq.RFH2_2.USRFolder" variable="RFH2_2.USRFolder"/> <bpelx:outputProperty name="jca.mq.RFH2_2.PSCFolder" variable="RFH2_2.PSCFolder"/> <bpelx:outputProperty name="jca.mq.RFH2_2.USRFolder_2" variable="RFH2_2.USRFolder_2"/> <bpelx:outputProperty name="jca.mq.RFH2.Total.Headers" variable="TotalRFH2"/>
Click File, Save All.
You must deploy the application profile for the SOA project and application you created in the earlier steps.
For more information about deploying the application profile using JDeveloper, see Section 2.7, "Deploying Oracle JCA Adapter Applications from JDeveloper".
You must also create an application server connection. For more information about creating an application server connection, see Section 2.6, "Creating an Application Server Connection for Oracle JCA Adapters".
The MQ message with the correct RFH2 headers must be put to the outbound dequeue queue. The sample is configured to obtain two RFH2 headers from the message (this can be changed by configuring the bpel process as required). The test MQ message should have the following:
Payload: Any message (any format will do since Opaque is being employed)
RFH2 header 1: Should contain 2 USR folders, 1 JMS folder, 1 PSC folder, 1 MCD folder and 1 mq_usr folder.
RFH2 header 2: Should contain 2 USR folders, 2 JMS folders, 1 PSC folder and 1 MCD folder.
Deploy the sample and put the above message to the outbound dequeue queue. Open the Enterprise Manager console and invoke the sample using the Test utility. Wait for a time and examine the instance audit trail.