10 Oracle JCA Adapter for MQ Series

This chapter describes how to use the Oracle JCA Adapter for MQ Series (Oracle MQ Series Adapter), which works in conjunction with Oracle BPEL Process Manager (Oracle BPEL PM) and Oracle Mediator (Mediator) as an external service.

This chapter includes the following sections:

MQ Series Message Queuing Concepts

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 are running at different times or are temporarily unavailable.

The basic concepts of message queuing are described in the following list:

  • Messaging

    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.

  • Message

    Messages are structured data sent by one program and intended for another program.

  • Message Queue

    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.

  • 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.

  • Message Channel

    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.

  • Transmission Queue

    A transmission queue is used to temporarily store messages that are destined for a remote queue manager.

  • Message Segment

    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.

  • Message Group

    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.

  • Cluster

    A cluster is a group of queue managers that are logically associated.

  • Enqueue/Dequeue

    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.

    Figure 10-1 Enqueue/Dequeue

    Description of Figure 10-1 follows
    Description of "Figure 10-1 Enqueue/Dequeue"

  • Request/Response

    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.

    Figure 10-2 Request/Response Interaction

    Description of Figure 10-2 follows
    Description of "Figure 10-2 Request/Response Interaction"

    For more information about the interaction scenarios supported by the Oracle MQ Series Adapter, see Dequeue Message.

MQ Series Concepts

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.0.

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

Description of Figure 10-3 follows
Description of "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.

Figure 10-4 MQ Series Message

Description of Figure 10-4 follows
Description of "Figure 10-4 MQ Series Message"

An MQ Series message consists of the following parts, as shown in Figure 10-4:

  • Message Header

    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.

  • Optional Header

    The optional header is required for communication with specific applications, such as the CICS application.

    For more information, see Integration with CICS.

  • Application Data

    This contains the actual data, for example, a record from an indexed or flat file or a row or column from a DB2 table.

Introduction to Native Oracle MQ Series Adapter

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:

The Need for Oracle MQ Series Adapter

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:

MQ Series version that the Oracle MQ Series Adapter is certified is 6.0.0.0 version, both on Windows and Linux.

Oracle MQ Series Adapter Integration with Oracle BPEL Process Manager

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 3-8. 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.

Oracle MQ Series Adapter Integration with Mediator

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, as shown in Figure 3-6.

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

Enqueue Message

Dequeue Message

Dequeue Message

Request-Response

Synchronous Request-Response (Mediator As Server)

Synchronous Request-Response (Oracle Mediator as Client)

Asynchronous Request-Response (Oracle Mediator As Client)

Outbound Dequeue

Outbound Dequeue Scenario


Oracle MQ Series Adapter Features

This section explains the following features of the Oracle MQ Series Adapter:

RFH Version 2 (RFH2) Header

The RFH2 header is an extensible header. The RFH2 header allows 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.

Fixed Portion

The fixed portion is modeled on the standard WebSphere MQ header pattern and consists of the following fields:

StrucId (MQCHAR4)

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.

Version (MQLONG)

Structure version number.

Must be MQRFH_VERSION_2 (value: 2) (initial value).

StrucLength (MQLONG)

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).

Encoding (MQLONG)

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).

CodedCharSetId (MQLONG)

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 (MQCHAR8)

Format name.

Format name for the portion of the message following MQRFH2.

Flags (MQLONG)

Flags.

MQRFH_NO_FLAGS =0. No flags set.

NameValueCCSID (MQLONG)

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:

Table 10-3 Possible Values for NameValueCCSID Field

Value Meaning

1200

UCS2 open-ended

1208

UTF8

13488

UCS2 2.0 subset

17584

UCS2 2.1 subset (includes the Euro symbol)


Variable Portion

The variable portion follows the fixed portion. The variable portion contains a variable number of MQRFH2 folders. Each folder contains a variable number of elements or properties. The related properties are grouped together. The MQRFH2 header can contain the following message service folders:

The <mcd> folder

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.

The <jms> folder

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.

The <usr> folder

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.

The <psc> folder

This is used to convey publish/subscribe command messages to the broker. Only one psc folder is allowed in the NameValueData field.

The <pscr> folder

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:

NameValueLength (MQLONG)

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.

NameValueData (MQCHARn)

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>

SSL Enabling

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 will have its private keys. This is required when an adapter needs to 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 needs to 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 this variable can be used 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.

XA Transactions

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, once completed, 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:

  1. Log in to the Oracle WebLogic Server Administration Console using your password credentials.

  2. Under Domain Structure, in the left pane, click Deployments. The Summary of Deployments page is displayed.

  3. Click MQSeriesAdapter. The Settings of MQSeriesAdapter page is displayed.

  4. Click the Configuration tab. The Configuration sub-menu options are displayed.

  5. Click Outbound Connection Pools. The Outbound Connection Pool Configuration Table is displayed.

  6. 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.
  7. Select the XATransaction option and click the Property Value row at the end of the XATransaction.

  8. Enter true in the text field, as shown in Figure 10-5, and click Save.

    Figure 10-5 Outbound Connection Properties Page

    Description of Figure 10-5 follows
    Description of "Figure 10-5 Outbound Connection Properties Page"

  9. Click the Transaction tab. The Settings for javax.resource.cci.ConnectionFactory page is displayed.

  10. Select XA Transaction from the Transaction Support list.

  11. Click Save to save your settings. The Save Deployment Plan Assistant page is displayed.

  12. 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>

XA Recovery

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.

High Availability

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.

Prerequisites for High Availability

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.

High Availability in Inbound/Outbound Operations

The Oracle MQ Series Adapter must ensure that it participates in the XA transaction. For more information about the XA transaction, see XA Transactions.

Scalability

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:

InboundThreadCount='N'

where, N is the number of threads that you want to span to dequeue the messages from the inbound queue.

Securing Enterprise Information System Credentials

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 Securing Enterprise Information System Credentials.

Fault Policy

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 Configuring Rejection Handlers.

Inbound Rejection Handler

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, Rejected Message Handlers.

Retry Mechanism

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 will use 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. This means that the adapter can use only one mechanism at a time. In case both of the options are specified, then the Backout Queue option takes precedence.

JCA Inbound Retry Mechanism

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, message not being able to put to a queue is also retriable.

For more information about retry mechanism, see Handling Connection Errors.

Message Backout Queue

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 unable to 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 Configuring a Backout Queue.

Performance Tuning

The Oracle MQ Series Adapter supports performance tuning options.

For more information, see "Oracle MQ Adapter Tuning" in the Oracle Fusion Middleware Performance Guide.

Oracle MQ Series Adapter Concepts

This section explains the following concepts of the Oracle MQ Series Adapter:

Messaging Scenarios

The Oracle MQ Series Adapter supports the following messaging scenarios:

Enqueue Message

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:

  1. Receives message from Oracle BPEL PM or Mediator.

  2. Formats the XML content as specified at design time.

  3. 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 Messages Types.

  4. Sends the message to the queue specified at design time in the Adapter Configuration Wizard.

Figure 10-6 displays the operation type that you must select in the Adapter Configuration Wizard.

Figure 10-6 The Adapter Configuration Wizard: Produce Message Selection

Description of Figure 10-6 follows
Description of "Figure 10-6 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-7.

Figure 10-7 Put Message Options

Description of Figure 10-7 follows
Description of "Figure 10-7 Put Message Options"

You can specify the following properties in this page:

  • Queue Name: The name of the queue on which the Oracle MQ Series Adapter will enqueue 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 should be used when enqueuing message to a remote queue.

  • Partial Delivery: This is applicable only when you specify more than one queue 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 more than one message.

  • Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.

For more information about these properties, see Message Properties.

The next Adapter Configuration Wizard page that appears is the Messages page, as shown in Figure 10-8. This page enables you to select the XML Schema Definition (XSD) file for translation.

Figure 10-8 Messages Page

Description of Figure 10-8 follows
Description of "Figure 10-8 Messages Page"

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. If you want to define a new schema or convert an existing data type description (DTD) or COBOL Copybook, then 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-separated 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 Creating Native Schema Files with the Native Format Builder Wizard.

Note:

Ensure that the schema you specify includes a namespace. If your schema does not have a namespace, an error message appears.

Dequeue Message

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:

  1. Connects to the queue specified at design time.

  2. Dequeues the message from the queue when a message arrives.

  3. Reads and translates the message based on the translation logic defined at design time.

  4. Publishes the message as an XML message to Oracle BPEL PM or Mediator.

    Figure 10-9 displays the operation type that you must select in the Adapter Configuration Wizard.

    Figure 10-9 The Adapter Configuration Wizard: Consume Message Selection

    Description of Figure 10-9 follows
    Description of "Figure 10-9 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-10.

    Figure 10-10 Get Message from MQ Page

    Description of Figure 10-10 follows
    Description of "Figure 10-10 Get Message from MQ Page"

    You can specify the following properties in this page:

    • Queue Name: The name of the queue from which the Oracle MQ Series Adapter will dequeue the message. This is a mandatory field.

    • Schema Options: This option allows you to specify the schema for the message to be dequeued.

      • Choose Other Schema: This option allows you to choose your schema for the message to be dequeued.

      • Choose a Predefined Schema: This option allows 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-8. 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 Enqueue Message.

Asynchronous Request-Response (Oracle BPEL PM As Client)

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:

  1. Receives message from Oracle BPEL PM.

  2. Formats the XML content as specified at design time in the Adapter Configuration Wizard.

  3. Sets properties and a correlation schema on the request message.

  4. 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 on the basis of the correlation schema specified in the request message.

  5. The Oracle MQ Series Adapter dequeues the message from the replyTo queue.

  6. 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-11 displays the operation type that you must select in the Adapter Configuration Wizard.

Figure 10-11 Selecting an Operation Type

Description of Figure 10-11 follows
Description of "Figure 10-11 Selecting an Operation Type"

The page that appears after selecting the Send Message to MQ and Get Reply/Reports operation type is shown in Figure 10-12.

Figure 10-12 Send Message to MQ and Get Reply/Reports Page

Description of Figure 10-12 follows
Description of "Figure 10-12 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-13.

  • 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 more than one message.

  • Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.

For more information about these properties, see Message Properties and 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-13) or a Response page (shown in Figure 10-14).

The Reports page, shown in Figure 10-13, 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-12.

Figure 10-13 Reports Page

Description of Figure 10-13 follows
Description of "Figure 10-13 Reports Page"

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 Report Messages.

The Response page shown in Figure 10-14 is displayed when you click Next in the Reports page.

Figure 10-14 Response Page

Description of Figure 10-14 follows
Description of "Figure 10-14 Response 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 should be used by the Oracle MQ Series Adapter.

    For information about correlation schemas, see Correlation Schemas.

  • Schema Options: This option allows you to specify the schema for the message to be dequeued.

    • Choose Other Schema: This option allows you to choose your schema for the message to be dequeued.

    • Choose a Predefined Schema: This option allows 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-15, is displayed. This page enables you to select the XSD schema file for translation for request as well as response message.

Figure 10-15 Messages Page

Description of Figure 10-15 follows
Description of "Figure 10-15 Messages Page"

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 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 will get lost.

Synchronous Request-Response (Oracle BPEL PM As Server)

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:

  1. Dequeues the request message from the queue when the message arrives.

  2. Reads and translates the message based on the translation logic defined at design time.

  3. 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.

  4. Receives the response message from the Oracle BPEL PM.

  5. Formats the XML content as specified at design time.

  6. 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.

  7. Sends the message to the queue specified at design time in the Adapter Configuration Wizard.

Figure 10-16 shows a sample BPEL process for this scenario.

Figure 10-16 Synchronous Request-Response Oracle BPEL PM As Server Sample

Description of Figure 10-16 follows
Description of "Figure 10-16 Synchronous Request-Response Oracle BPEL PM As Server Sample"

Figure 10-17 displays the operation type that you must select in the Adapter Configuration Wizard.

Figure 10-17 Operation Type Page Selection for Request-Response Synchronous Interaction

Description of Figure 10-17 follows
Description of "Figure 10-17 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-18. Specify the queue name from which the Oracle MQ Series Adapter will dequeue the message in this page.

Figure 10-18 Get Message from MQ and Send Reply/Reports Page

Description of Figure 10-18 follows
Description of "Figure 10-18 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-19 is displayed.

Figure 10-19 Response Page for Synchronous Request-Response

Description of Figure 10-19 follows
Description of "Figure 10-19 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 will have an effect on 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 more than one message.

  • Expiry: The expiry time of the message.

For more information about these properties, see Message Properties.

Click Next in the Response page, the Messages page is displayed, as shown in Figure 10-15. 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 Enqueue Message.

Asynchronous Request-Response (Oracle BPEL PM As Server)

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:

  1. Dequeues the message from the queue when a message arrives.

  2. Reads and translates the message based on the translation logic defined at design time.

  3. 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.

  4. Receives messages from Oracle BPEL PM.

  5. Formats the XML content as specified at design time.

  6. 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.

  7. Sends the message to the queue specified at design time in the Adapter Configuration Wizard.

Figure 10-20 shows a sample BPEL process for this scenario.

Figure 10-20 Asynchronous Request-Response Oracle BPEL PM As Server Sample

Description of Figure 10-20 follows
Description of "Figure 10-20 Asynchronous Request-Response Oracle BPEL PM As Server Sample"

Figure 10-21 displays the operation type that you must select in the Adapter Configuration Wizard.

Figure 10-21 Operation Type Page Selection for Request-Response Asynchronous Interaction

Description of Figure 10-21 follows
Description of "Figure 10-21 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-18. Specify the queue name from which the Oracle MQ Series Adapter will dequeue 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-19 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 will have an effect on 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 more than one message.

  • Expiry: The expiry time of the message.

For more information about these properties, see 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-22 and Figure 10-23) but with two different set of options.

Figure 10-22 Response Page (Request Message Type Selected)

Description of Figure 10-22 follows
Description of "Figure 10-22 Response Page (Request Message Type Selected)"

The Response page shown in Figure 10-23 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-23 Response Page (Normal Message Type Selected)

Description of Figure 10-23 follows
Description of "Figure 10-23 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-22.

When you click Next in the Response page, the Messages page shown in Figure 10-24 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.

Figure 10-24 Messages Page

Description of Figure 10-24 follows
Description of "Figure 10-24 Messages Page"

For more information about the Messages page, see 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 Correlation Schemas.

  • ReplyToQ : Refers to the name of the response queue name.

  • ReplyToQueueManager: Refers to the name of the response queue manager.

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.

You can use the Assign activity to map these properties.

  1. Create a BPEL process and double-click to open the BPEL Designer page.

  2. 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-25.

    Figure 10-25 The Variables Dialog

    Description of Figure 10-25 follows
    Description of "Figure 10-25 The Variables Dialog"

  3. Capture the inbound header messages into these variables, as shown in Figure 10-26 and Figure 10-27.

    Figure 10-26 The Receive Dialog

    Description of Figure 10-26 follows
    Description of "Figure 10-26 The Receive Dialog "

  4. Assign the variables captured in Step 2 for the Outbound Reply message, as shown in Figure 10-27 and Figure 10-22.

    Figure 10-27 The Invoke Dialog

    Description of Figure 10-27 follows
    Description of "Figure 10-27 The Invoke Dialog"

Synchronous Request-Response (Mediator As Server)

In this scenario, the Mediator receives a request, processes it, and sends the response synchronously. The Oracle MQ Series Adapter performs the following operations:

  1. Dequeues the request message from the queue when the message arrives.

  2. Reads and translates the message based on the translation logic defined at design time.

  3. Publishes the message as an XML message to Mediator. The Mediator processes the request and sends the response to the Oracle MQ Series Adapter.

  4. Receives the response message from the Mediator.

  5. Formats the XML content as specified at design time.

  6. 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.

  7. Sends the message to the queue specified at design time in the Adapter Configuration Wizard.

Figure 10-18 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 Synchronous Request-Response (Oracle BPEL PM As Server).

Note:

The asynchronous request-response pattern is not supported for Mediator.

Synchronous Request-Response (Oracle BPEL PM As Client)

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.

Figure 10-28 displays the operation type that you must select in the Adapter Configuration Wizard.

Figure 10-28 The Operation Type Dialog

Description of Figure 10-28 follows
Description of "Figure 10-28 The Operation Type Dialog"

The page that appears after selecting the Send Message to MQ and Get Reply/Reports operation type is shown in Figure 10-12.

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 should be used 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 the 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 more than one message.

  • 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-29, is displayed.

Figure 10-29 The Response Page

Description of Figure 10-29 follows
Description of "Figure 10-29 The Response Page"

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 should be used by the Oracle MQ Series Adapter.

    For more information about correlation schemas, see Correlation Schemas.

  • Schema Options: This option allows you to specify the schema for the message to be dequeued.

    • Choose Other Schema: This option allows you to choose your schema for the message to be dequeued.

    • Choose a Predefined Schema: This option allows 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.

Synchronous Request-Response (Oracle Mediator as Client)

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 Synchronous Request-Response (Oracle BPEL PM As Client).

Asynchronous Request-Response (Oracle Mediator 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:

  1. Receives message from Oracle Mediator.

  2. Formats the XML content as specified at design time in the Adapter Configuration Wizard.

  3. Sets properties and a correlation schema on the request message.

  4. 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 on the basis of the correlation schema specified in the request message.

  5. The Oracle MQ Series Adapter dequeues the message from the replyTo queue.

  6. 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.

  7. 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-11 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-12.

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 should be used 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 more than one message.

  • Expiry: The expiry time of the message. The message is discarded after the expiry time has elapsed.

For more information about these properties, see Message Properties and 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-13) or a Response page (shown in Figure 10-14).

The Reports page shown in Figure 10-13 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-12.

The Response page shown in Figure 10-14 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-13:

  • Confirmation on Arrival

  • Confirmation on Delivery

  • Exception Report

  • Expiry Report

For information about these report types, see Report Messages.

The Response page, shown in Figure 10-14, 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 should be used by the Oracle MQ Series Adapter.

    For information about correlation schemas, see Correlation Schemas.

  • Schema Options: This option allows you to specify the schema for the message to be dequeued.

    • Choose Other Schema: This option allows you to choose your schema for the message to be dequeued.

    • Choose a Predefined Schema: This option allows 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-15 is displayed. This page enables you to select the XSD schema file for translation for request as well as response message.

For more information about the Messages page, see Enqueue Message.

Outbound Dequeue Scenario

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-28.

Click Next in the Send Message to MQ and Get Reply/Reports page, the Response page, as shown in Figure 10-29, 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). Note that 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.

Message Properties

The Oracle MQ Series Adapter supports the following message properties:

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.

Messages Types

The Oracle MQ Series Adapter supports the following four types of messages:

  • Normal Message

    A normal message is sent by one program to another program without expecting any response.

  • Request Message

    A request message is sent by one program to another program requesting a response.

  • Reply Message

    A reply message is sent by a program in response to a request message.

  • Report 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 Report Messages.

Message Format

You can specify the format for an outgoing message through the Adapter Configuration Wizard, as shown in Figure 10-7. 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

Message Expiry

You can specify the expiry time for an outgoing message by using the Adapter Configuration Wizard, as shown in Figure 10-7. 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.

Message Priority

You can specify the priority of an outgoing message through the Adapter Configuration Wizard, as shown in Figure 10-7. 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.

Message Persistence

You can specify the persistence of an outgoing message through the Adapter Configuration Wizard, as shown in Figure 10-7. 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 will not be 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. Persistent messages are written 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.

Correlation Schemas

Correlation is required for mapping a response to a request in a request-reply interaction. 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-14 enables you to specify the correlation schema for the response message.

The Message ID box shown in Figure 10-14 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-14 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

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 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.

Distribution List Support

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 more than one queues, then the DistributionList parameter is automatically added to the JCA file.

Report Messages

The Oracle MQ Series Adapter enables you to set various types of acknowledgement messages on an outgoing message. These acknowledgement 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 will be 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:

  • Confirmation on Arrival

    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-13.

  • Confirmation on Delivery

    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-13.

  • Exception Report

    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-13.

  • Expiry Report

    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-13.

  • Positive Action Notification

    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.

  • Negative Action Notification

    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 one 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

Message Delivery Failure Options

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 one of the following actions:

  • 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.

Message Segmentation

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 allows you to segment messages for outbound interactions. This option appears in the Response page of the Adapter Configuration Wizard.

The message will be segmented based on whether the size of the message is larger than the maximum limit set on the queue.

Integration with CICS

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>

Supported Encodings

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:

  1. Extract the MQSeriesAdapter.jar file from the MQSeriesAdapter.rar file.

  2. Extract the mq.properties file from the MQSeriesAdapter.jar file.

  3. 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

Configuring the Oracle MQ Series Adapter

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:

Adding com.ibm.mq.jar to the Oracle MQ Series Adapter Classpath

The steps in this section should be performed only once, before using the Oracle MQ Series Adapter. To add the com.ibm.mq.jar property to the classpath for the Oracle MQ Series Adapter, copy the com.ibm.mq.jar file to the <DOMAIN_HOME>/lib folder.

Adding JNDI Entry

You can add a new jndi entry in the Oracle WebLogic Server Administration Console by following these steps:

  1. 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-30.

    Figure 10-30 Oracle WebLogic Administration Console Home Page

    Description of Figure 10-30 follows
    Description of "Figure 10-30 Oracle WebLogic Administration Console Home Page"

  2. Under Domain Structure, in the left pane, click Deployments. The Summary of Deployments page is displayed.

  3. Click MQSeriesAdapter. The Settings of MQSeriesAdapter page is displayed, as shown in Figure 10-31.

    Figure 10-31 Settings of MQSeriesAdapter Page

    Description of Figure 10-31 follows
    Description of "Figure 10-31 Settings of MQSeriesAdapter Page"

  4. Click the Configuration tab. The Configuration sub-menu options are displayed, as shown in Figure 10-32.

    Figure 10-32 Settings of MQSeriesAdapter Page - Configuration Sub-Menu Options

    Description of Figure 10-32 follows
    Description of "Figure 10-32 Settings of MQSeriesAdapter Page - Configuration Sub-Menu Options"

  5. Click Outbound Connection Pools. The Outbound Connection Pool Configuration Table is displayed, as shown in Figure 10-33.

    Figure 10-33 Outbound Connection Pool Configuration Table

    Description of Figure 10-33 follows
    Description of "Figure 10-33 Outbound Connection Pool Configuration Table"

  6. Click New. The Create a New Outbound Connection page is displayed, as shown in Figure 10-34.

    Figure 10-34 Create a New Outbound Connection Page

    Description of Figure 10-34 follows
    Description of "Figure 10-34 Create a New Outbound Connection Page"

  7. Select the javax.resource.cci.ConnectionFactory option, and click Next.

  8. Enter a value in the JNDI Name field, for example eis/MQ/MQAdapter, as shown in Figure 10-35.

    Figure 10-35 Create a New Outbound Connection Page - JNDI Name

    Description of Figure 10-35 follows
    Description of "Figure 10-35 Create a New Outbound Connection Page - JNDI Name"

  9. Click Finish. The Save Deployment Plan Assistant page is displayed.

  10. Click OK. You have successfully created a JNDI name.

Enabling Binding Mode for Connections

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:

  1. Log in to the Oracle WebLogic Server Administration Console using your password credentials.

  2. Under Domain Structure, in the left pane, click Deployments. The Summary of Deployments page is displayed.

  3. Click MQSeriesAdapter. The Settings of MQSeriesAdapter page is displayed.

  4. Click the Configuration tab. The Configuration sub-menu options are displayed.

  5. Click Outbound Connection Pools. The Outbound Connection Pool Configuration Table is displayed.

  6. Click the + icon next to javax.resource.cci.ConnectionFactory. A list of JNDIs are displayed.

  7. Select, eis/MQ/MQAdapter, the JNDI that you created in the Adding JNDI Entry. The Outbound Connection Properties page is displayed, as shown in Figure 10-36, with a list of 24 properties.

    Figure 10-36 Outbound Connection Properties Page

    Description of Figure 10-36 follows
    Description of "Figure 10-36 Outbound Connection Properties Page"

  8. 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.

Oracle MQ Series Adapter Use Cases

This section contains the following topics:

Dequeue Enqueue

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:

Prerequisites

To perform the dequeue enqueue 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

The Adapters-101MQAdapterDequeueEnqueue sample is available at the following location:

http://www.oracle.com/technology/sample_code/products/adapters

You must also create the following queues:

  • test_in

  • test_out

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. In the Name Your Application screen, enter De-queueEn-queue in the Application Name field, as shown in Figure 10-37, and then click Next. The Name Your Project screen is displayed.

    Figure 10-37 The Name Your Application Page

    Description of Figure 10-37 follows
    Description of "Figure 10-37 The Name Your Application Page"

  5. 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-38.

    Figure 10-38 The Name Your Project Page

    Description of Figure 10-38 follows
    Description of "Figure 10-38 The Name Your Project Page"

  6. Click Next. The Configure SOA Settings screen is displayed.

  7. In the Composite Template list, select Composite With BPEL, as shown in Figure 10-39, and then click Finish. The Create BPEL Process dialog is displayed.

    Figure 10-39 The Configure SOA Settings Page

    Description of Figure 10-39 follows
    Description of "Figure 10-39 The Configure SOA Settings Page"

  8. Enter BPELdequeueenqueue in the Name field, and select Define Service Later from the Template box, as shown in Figure 10-40.

    Figure 10-40 The Create BPEL Process Dialog

    Description of Figure 10-40 follows
    Description of "Figure 10-40 The Create BPEL Process Dialog"

  9. Click OK. The De-queueEn-queue application and the De-queueEn-queue project appears in the design area, as shown in Figure 10-41.

    Figure 10-41 The JDeveloper - Composite.xml

    Description of Figure 10-41 follows
    Description of "Figure 10-41 The JDeveloper - Composite.xml"

  10. Copy the address-csv.xsd and address-fixedLength.xsd files to the xsd folder in your project (see Prerequisites for the location of these files).

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter InboundService in the Service Name field, as shown in Figure 10-42, and click OK. The MQ Series Connection page is displayed.

    Figure 10-42 The Service Name Page

    Description of Figure 10-42 follows
    Description of "Figure 10-42 The Service Name Page"

  4. Accept the default JNDI name for the MQ Series connection, as shown in Figure 10-43, and click Next. The Adapter Interface page is displayed.

    Figure 10-43 The MQ Series Connection Page

    Description of Figure 10-43 follows
    Description of "Figure 10-43 The MQ Series Connection Page"

  5. Select Define from operation and schema (specified later), as shown in Figure 10-44, and click Next. The Operation Type page is displayed.

    Figure 10-44 The Adapter Interface Page

    Description of Figure 10-44 follows
    Description of "Figure 10-44 The Adapter Interface Page"

  6. Select Get Message from MQ, as shown in Figure 10-45, and click Next. The Get Message from MQ page is displayed.

    Figure 10-45 The Operation Type Page

    Description of Figure 10-45 follows
    Description of "Figure 10-45 The Operation Type Page"

  7. Enter test_in in the Queue Name field, as shown in Figure 10-46, and click Next. The Messages page is displayed.

    Figure 10-46 The Get Message From MQ Page

    Description of Figure 10-46 follows
    Description of "Figure 10-46 The Get Message From MQ Page"

  8. Click Browse at the end of the URL field. The Type Chooser dialog is displayed.

  9. Select Project Schema Files, address-csv.xsd, and then Root-Element, as shown in Figure 10-47.

    Figure 10-47 The Type Chooser Dialog

    Description of Figure 10-47 follows
    Description of "Figure 10-47 The Type Chooser Dialog"

  10. Click OK. The address-csv.xsd file appears in the URL field in the Messages page, as shown in Figure 10-48.

    Figure 10-48 The Messages Page

    Description of Figure 10-48 follows
    Description of "Figure 10-48 The Messages Page"

  11. Click Next. The Finish page is displayed.

  12. Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-49.

    Figure 10-49 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-49 follows
    Description of "Figure 10-49 The JDeveloper Page - Composite.xml Page"

Creating an Outbound Adapter Service

Perform the following steps to create an adapter service that will enqueue the messages.

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter OutboundService in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, as shown in Figure 10-43, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), as shown in Figure 10-44, and click Next. The Operation Type page is displayed.

  6. Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.

  7. Enter test_out in the Queue Name field, and click Next. The Advanced Options page is displayed, as shown in Figure 10-50.

    Figure 10-50 The Advanced Options Page

    Description of Figure 10-50 follows
    Description of "Figure 10-50 The Advanced Options Page"

  8. Accept the defaults and click Next. The Messages page is displayed.

  9. Click Browse at the end of the URL field. The Type Chooser dialog is displayed.

  10. 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.

  11. Click Next. The Finish page is displayed.

  12. Click Finish. You have now configured the outbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-51.

    Figure 10-51 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-51 follows
    Description of "Figure 10-51 The JDeveloper Page - Composite.xml Page"

Wiring Services and Activities

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 together:

  1. 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.

  2. 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-52.

    Figure 10-52 The JDeveloper - Composite.xml

    Description of Figure 10-52 follows
    Description of "Figure 10-52 The JDeveloper - Composite.xml"

  3. Click File, Save All.

  4. Double-click BPELdequeueenqueue. The BPELdequeueenqueue.bpel page is displayed.

  5. 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-53.

    Figure 10-53 The BPELdequeueenqueue.bpel Page

    Description of Figure 10-53 follows
    Description of "Figure 10-53 The BPELdequeueenqueue.bpel Page"

  6. Drag and drop the Receive activity to InboundService. The Receive dialog is displayed.

  7. Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.

  8. Accept the defaults, and click OK.

  9. Check the Create Instance box, and click OK.

  10. Drag and drop the Invoke activity to OutboundService. The Invoke dialog is displayed.

  11. Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field.

  12. Accept the defaults, and click OK. The Invoke dialog is displayed.

  13. Click OK.

  14. Double-click the Transform activity. The Transform dialog is displayed.

  15. Click the Create... (Alt+N) icon. The Source Variable dialog is displayed.

  16. Accept the defaults, and click OK.

  17. Select the invoke variable as target, and click OK. The Transformation_xsl page is displayed.

  18. 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.

  19. Click OK. The Transformation_xsl page is displayed, as shown in Figure 10-54.

    Figure 10-54 The Trasformation_xsl Page

    Description of Figure 10-54 follows
    Description of "Figure 10-54 The Trasformation_xsl Page "

    The BPELdequeueenqueue.bpel page appears, as shown in Figure 10-55.

    Figure 10-55 The BPELdequeueenqueue.bpel Page

    Description of Figure 10-55 follows
    Description of "Figure 10-55 The BPELdequeueenqueue.bpel Page "

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Monitoring Using the Oracle Enterprise Manager Fusion Middleware Control Console (Fusion Middleware Control Console)

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.

  2. In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.

  3. Click De-queueEn-queueComposite[1.0]. The De-queueEn-queueComposite[1.0] page is displayed.

  4. Copy the data.txt file and put it in the test_in queue.

  5. Wait for some time and then refresh the Fusion Middleware Control Console. An instance will show up on the console. This is the instance that was triggered as a result of the processing.

  6. Click the Instances tab.

  7. Click the instance associated with this deployment. The Flow Trace page is displayed.

  8. Click the BPELdequeueenqueue component instance. The Audit Trail page is displayed.

  9. Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.

  10. Click an activity to view the relevant payload details.

Inbound Synchronous Request-Reply

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:

Prerequisites

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 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

The Adapters-101MQAdapterDequeueEnqueue sample is available at the following location:

http://www.oracle.com/technology/sample_code/products/adapters

You must also create the following queues:

  • test_in

  • test_reply

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. In the Name Your Application screen, enter SyncReqRes in the Application Name field, and then click Next. The Name Your Project screen is displayed.

  5. In the Project Name field, enter Sync_ReqRes and from the Available list, select SOA and click the right-arrow button.

  6. Click Next. The Configure SOA Settings screen is displayed.

  7. 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.

  8. Enter BPELsyncreqres in the Name field, select Define Service Later from the Template box.

  9. Click OK. The SyncReqRes application and Sync_ReqRes project appears in the design area, as shown in Figure 10-56.

    Figure 10-56 The JDeveloper - Composite.xml

    Description of Figure 10-56 follows
    Description of "Figure 10-56 The JDeveloper - Composite.xml"

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter inbound_reqres in the Service Name field, and click Next. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection JNDI name, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Get Message from MQ and Send Reply/Reports, and select Synchronous, as shown in Figure 10-17, and click Next. The Get Message from MQ and Send Reply/Reports page is displayed.

  7. Select Normal in the Message Type box, and enter test_in in the Queue Name field.

  8. Click Next. The Response page is displayed.

  9. Accept the defaults, and click Next. The Messages page is displayed.

  10. 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.

  11. In the Send Message Schema group, click Browse at the end of the URL field. The Type Chooser dialog is displayed.

  12. 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.

  13. Click Next. The Finish page is displayed.

  14. Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-57.

    Figure 10-57 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-57 follows
    Description of "Figure 10-57 The JDeveloper Page - Composite.xml Page"

  15. Click File, Save All.

Wiring Services and Activities

Perform the following steps to wire components together:

  1. Drag and drop the inbound_reqres adapter service to the BPELsyncreqres BPEL process.

  2. Double-click BPELsyncreqres. The BPELsyncreqres.bpel page is displayed.

  3. Drag and drop the Receive, Transform, and Reply activities in the order mentioned from the Component Palette to the Components area.

  4. Drag and drop the Receive activity to the inbound_reqres adapter service. The Receive dialog is displayed.

  5. Enter ReadMsg in the Name field.

  6. Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.

  7. Accept the defaults, and click OK.

  8. Check the Create Instance box in the Receive dialog, and click OK.

  9. Drag and drop the Reply activity to the inbound_reqres adapter service. The Reply dialog is displayed.

  10. Enter ReplyMsg in the Name field.

  11. Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.

  12. Accept the defaults, and click OK. The variable appears in the Reply dialog.

  13. Click OK.

  14. Double-click the Transform activity. The Transform dialog is displayed.

  15. Click the plus icon. The Source Variable dialog is displayed.

  16. From the Source Variable list, select ReadMsg_DequeueEnqueue_InputVariable, and click OK.

  17. From the Target Variable list, select ReplyMsg_DequeueEnqueue_OutputVariable.

  18. Click the Create Mappings icon. The Transformation.xsl page is displayed, as shown in Figure 10-58.

    Figure 10-58 The Transformation.xsl Page

    Figure
    Description of "Figure 10-58 The Transformation.xsl Page"

  19. Drag the tns:Root-Element from <sources> panel to the fix:Root-Element of the <target> panel. The Auto Map Preferences dialog is displayed.

  20. Click OK. The JDeveloper BPELsyncreqres.bpel page is displayed, as shown in Figure 10-59.

    Figure 10-59 The BPELsyncreqres.bpel Page

    Description of Figure 10-59 follows
    Description of "Figure 10-59 The BPELsyncreqres.bpel Page "

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.

  2. In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.

  3. Click Sync_ReqRes[1.0]. The Sync_ReqRes[1.0] page is displayed.

  4. 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.

  5. Wait for some time and then refresh the Fusion Middleware Control Console. An instance will show up on the console. This is the instance that was triggered as a result of the processing.

  6. Click the Instances tab.

  7. Click the instance associated with this deployment. The Flow Trace page is displayed.

  8. Click the BPELsyncreqres component instance. The Audit Trail page is displayed.

  9. Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.

  10. Click an activity to view the relevant payload details.

Inbound-Outbound Synchronous Request-Reply

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:

Prerequisites

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

The Adapters-101MQAdapterDequeueEnqueue sample is available at the following location:

http://www.oracle.com/technology/sample_code/products/adapters

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. 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.

  5. In the Project Name field, enter Sync-Req-RepComposite and from the Available list, select SOA and click the right-arrow button.

  6. Click Next. The Configure SOA Settings screen is displayed.

  7. In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.

  8. Enter BPELSyncreqrep in the Name field, select Define Service Later from the Template box.

  9. Click OK. The Sync-Req-Rep application and Sync-Req-RepComposite project appears in the design area, as shown in Figure 10-60.

    Figure 10-60 The JDeveloper - Composite.xml

    Description of Figure 10-60 follows
    Description of "Figure 10-60 The JDeveloper - Composite.xml"

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter InboundReqRepService in the Service Name field, and click Next. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Get Message from MQ and Send Reply/Reports and Synchronous in the Operation Name box, as shown in Figure 10-17, and click Next. The Get Message from MQ and Send Reply/Reports page is displayed.

  7. 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.

  8. Accept the defaults and click Next. The Message page is displayed.

  9. Click Browse in the Get Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.

  10. 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.

  11. Click Browse in the Send Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.

  12. 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.

  13. Click Next. The Finish page is displayed.

  14. Click Finish. You have configured the InboundReqRepService adapter service, and the composite.xml page is displayed, as shown in Figure 10-61.

    Figure 10-61 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-61 follows
    Description of "Figure 10-61 The JDeveloper Page - Composite.xml Page"

Creating an Outbound Adapter Service

Perform the following steps to create an adapter service that will enqueue the request messages and dequeue the corresponding response messages (report) from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter OutboundReqRepService in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the defaults and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. 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.

  7. Enter test1 in the Queue Name field and click Next. The Response page is displayed.

  8. 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.

  9. Click Next. The Advanced Options page is displayed.

  10. Accept the default values and click Next. The Messages page is displayed.

  11. Click Browse in the Get Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.

  12. 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.

  13. Click Browse in the Send Message Schema box that appears at the end of the URL field. The Type Chooser dialog is displayed.

  14. 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.

  15. Click Next. The Finish page is displayed.

  16. Click Finish. You have configured the OutboundReqRepService service, and the composite.xml page is displayed, as shown in Figure 10-62.

    Figure 10-62 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-62 follows
    Description of "Figure 10-62 The JDeveloper Page - Composite.xml Page"

Wiring Services and Activities

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 together:

  1. 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.

  2. 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.

  3. 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-63.

    Figure 10-63 The JDeveloper - Composite.xml

    Description of Figure 10-63 follows
    Description of "Figure 10-63 The JDeveloper - Composite.xml"

  4. Click File, Save All.

  5. Double-click BPELSyncreqrep. The BPELSyncreqrep.bpel page is displayed.

  6. 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-64.

    Figure 10-64 The BPELSyncreqrep.bpel Page

    Description of Figure 10-64 follows
    Description of "Figure 10-64 The BPELSyncreqrep.bpel Page"

  7. Drag and drop the Receive activity to InboundReqRepService. The Receive dialog is displayed.

  8. Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.

  9. Accept the defaults, and click OK.

  10. Check the Create Instance box, as shown in Figure 10-65, and click OK.

    Figure 10-65 The Receive Dialog

    Sync use case Receive dialog
    Description of "Figure 10-65 The Receive Dialog"

  11. Drag and drop the Reply activity to InboundReqRepService. The Reply dialog is displayed.

  12. Click the Auto Create Variable icon to create the variable, and then click OK. The Reply dialog is displayed, as shown in Figure 10-66.

    Figure 10-66 The Reply Dialog

    Figure
    Description of "Figure 10-66 The Reply Dialog"

  13. Drag and drop the Invoke activity to the OutboundReqRepService service. The Invoke dialog is displayed.

  14. Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field. The Create Variable dialog is displayed.

  15. Click OK.

  16. Similarly, create the output variable. Accept the defaults, and click OK. The Invoke dialog is displayed, as shown in Figure 10-67.

    Figure 10-67 The Invoke Dialog

    Figure
    Description of "Figure 10-67 The Invoke Dialog"

  17. Click OK.

  18. Double-click the Transform activity. The Transform dialog is displayed.

  19. 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-68.

    Figure 10-68 The Transform Dialog

    Figure
    Description of "Figure 10-68 The Transform Dialog"

  20. Click Create Mapping. The Transformation_1.xsl page is displayed.

  21. 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.

  22. Click OK. The mappings appear in the Transformation.xsl page, as shown in Figure 10-69.

    Figure 10-69 The Transformation.xsl Page with Mappings

    Figure
    Description of "Figure 10-69 The Transformation.xsl Page with Mappings"

  23. Click the BPELSyncreqrep.bpel tab.

  24. Double-click the Assign activity. The Assign dialog is displayed.

  25. Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.

  26. Select the variables, as shown in Figure 10-70, and click OK.

    Figure 10-70 The Create Copy Operation Dialog

    Figure
    Description of "Figure 10-70 The Create Copy Operation Dialog"

  27. Click OK in the Assign dialog. The JDeveloper BPELSyncreqrep.bpel page is displayed, as shown in Figure 10-71.

    Figure 10-71 The BPELSyncreqrep.bpel Page

    Figure
    Description of "Figure 10-71 The BPELSyncreqrep.bpel Page"

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.

  2. In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.

  3. Click Sync-Req-RepComposite[1.0]. The Sync-Req-RepComposite[1.0] page is displayed.

  4. 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.

  5. Wait for some time and then refresh the Fusion Middleware Control Console. An instance will show up on the console. This is the instance that was triggered as a result of the processing.

  6. Click the Instances tab.

  7. Click the instance associated with this deployment. The Flow Trace page is displayed.

  8. Click the BPELSyncreqrep component instance. The Audit Trail page is displayed.

  9. Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.

  10. Click an activity to view the relevant payload details.

Asynchronous-Request-Reply

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:

Prerequisites

The Oracle MQ Series Adapter must be configured as specified in Configuring the Oracle MQ Series Adapter and create the following queues: test_in, test_out, and test_demo queues.

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. In the Name Your Application screen, enter AsynchronousRequestReply in the Application Name field, and then click Next. The Name Your Project screen is displayed.

  5. In the Project Name field, enter Async-Req-RepComposite and from the Available list, select SOA and click the right-arrow button.

  6. Click Next. The Configure SOA Settings screen is displayed.

  7. In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.

  8. Enter BPELAsyncreqrep in the Name field, select Define Service Later from the Template box.

  9. Click OK. The AsynchronousRequestReply application and the Async-Req-RepComposite project appear in the design area, as shown in Figure 10-72.

    Figure 10-72 The JDeveloper - Composite.xml

    Description of Figure 10-72 follows
    Description of "Figure 10-72 The JDeveloper - Composite.xml"

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter InboundService in the Service Name field, and click Next. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Get Message from MQ and click Next. The Get Message from MQ page is displayed.

  7. Enter test_in in the Queue Name field and click Next. The Messages page is displayed.

  8. Select Native Format Translation is not required (Schema is Opaque) and click Next. The Finish page is displayed.

  9. Click Finish. You have configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-73.

    Figure 10-73 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-73 follows
    Description of "Figure 10-73 The JDeveloper Page - Composite.xml Page"

Creating an Asynchronous Outbound Request Reply Adapter Service Outbound

Perform the following steps to create an adapter service that will enqueue the request messages and dequeue the corresponding response messages (report) from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter asyn-Req-Res in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. 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.

  7. 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.

  8. Select Confirmation on Arrival, as shown in Figure 10-74, and click Next. The Response page is displayed.

    Figure 10-74 The Adapter Configuration Wizard Reports Page

    Description of Figure 10-74 follows
    Description of "Figure 10-74 The Adapter Configuration Wizard Reports Page"

  9. Enter test_out in the Reply To Queue Name field, and click Next. The Advanced Options page is displayed.

  10. Accept the default values, and click Next. The Messages page is displayed.

  11. 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.

  12. Click Finish. You have configured the async-Req-Res service, and the composite.xml page is displayed, as shown in Figure 10-75.

Figure 10-75 The JDeveloper Page - Composite.xml Page

Description of Figure 10-75 follows
Description of "Figure 10-75 The JDeveloper Page - Composite.xml Page"

Creating Another Outbound Adapter Service

Perform the following steps to create an adapter service that will enqueue the response (report) messages.

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter OutboundService in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.

  7. Enter test_demo in the Queue Name field, and click Next. The Advanced Options page is displayed.

  8. Accept the default values, and click Next. The Messages page is displayed.

  9. Select Native Format Translation is not required(Schema is Opaque), and click Next. The Finish page is displayed.

  10. Click Finish. You have configured the OutboundService service, and the composite.xml page is displayed, as shown in Figure 10-76.

    Figure 10-76 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-76 follows
    Description of "Figure 10-76 The JDeveloper Page - Composite.xml Page"

Wiring Services and Activities

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 together:

  1. 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.

  2. 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.

  3. 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-77.

    Figure 10-77 The JDeveloper - Composite.xml

    Description of Figure 10-77 follows
    Description of "Figure 10-77 The JDeveloper - Composite.xml"

  4. Click File, Save All.

  5. Double-click BPELAsyncreqrep. The BPELAsyncreqrep.bpel page is displayed.

  6. 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-78.

    Figure 10-78 The BPELAsyncreqrep.bpel Page

    Description of Figure 10-78 follows
    Description of "Figure 10-78 The BPELAsyncreqrep.bpel Page"

  7. Drag and drop the first Receive activity to the InboundService adapter service. The Receive dialog is displayed.

  8. Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.

  9. Accept the defaults, and click OK.

  10. Check the Create Instance box, and click OK.

  11. Drag and drop the first Invoke activity to the async-Req-Res service. The Invoke dialog is displayed.

  12. Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field.

  13. Accept the defaults, and click OK. The Invoke dialog is displayed.

  14. Click OK.

  15. Drag and drop the second Receive activity to the async-Req-Rep service. The Receive dialog is displayed.

  16. Click the Auto Create Variable icon to create variable.

    Note:

    Do not check the Create Instance box.
  17. Click OK in the Receive dialog.

  18. Drag and drop the second Invoke activity to OutboundService. The Invoke dialog is displayed.

  19. Click the Automatically Create Input Variable icon to create a variable.

  20. Click OK in the Invoke dialog.

  21. Double-click the first Assign activity. The Assign dialog is displayed.

  22. Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.

  23. Select the variables, as shown in Figure 10-79, and click OK.

    Figure 10-79 The Create Copy Operation Dialog

    Description of Figure 10-79 follows
    Description of "Figure 10-79 The Create Copy Operation Dialog"

  24. Click OK in the Assign dialog.

  25. Double-click the second Assign activity. The Assign dialog is displayed.

  26. Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.

  27. Select the variables, as shown in Figure 10-80, and click OK.

    Figure 10-80 The Create Copy Operation Dialog

    Description of Figure 10-80 follows
    Description of "Figure 10-80 The Create Copy Operation Dialog"

  28. Click OK in the Assign dialog. The JDeveloper BPELAsyncreqrep.bpel page is displayed, as shown in Figure 10-81.

    Figure 10-81 The BPELAsyncreqrep.bpel Page

    Description of Figure 10-81 follows
    Description of "Figure 10-81 The BPELAsyncreqrep.bpel Page"

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Log in to http://servername:portnumber/em using your username/password. The Oracle Enterprise Manager Fusion Middleware Control page is displayed.

  2. In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.

  3. Click Async-Req-RepComposite[1.0]. The Async-Req-RepComposite[1.0] page is displayed.

  4. 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.

  5. Wait for some time and then refresh the Fusion Middleware Control Console. An instance will show up on the console. This is the instance that was triggered as a result of the processing.

  6. Click the Instances tab.

  7. Click the instance associated with this deployment. The Flow Trace page is displayed.

  8. Click the BPELAsyncreqrep component instance. The Audit Trail page is displayed.

  9. Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.

  10. Click an activity to view the relevant payload details.

Outbound Dequeue

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:

Prerequisites

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

The Adapters-101MQAdapterDequeueEnqueue sample is available at the following location:

http://www.oracle.com/technology/sample_code/products/adapters

You must also create a queue named test_out.

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. In the Name Your Application screen, enter OutboundDequeue in the Application Name field, and then click Next. The Name Your Project screen is displayed.

  5. In the Project Name field, enter OutboundDequeueComposite and from the Available list, select SOA and click the right-arrow button.

  6. Click Next. The Configure SOA Settings screen is displayed.

  7. In the Composite Template list, select Composite With BPEL and then click Finish. The Create BPEL Process dialog is displayed.

  8. Enter BPELOutboundDequeue in the Name field, select Synchronous BPEL Process in the Template box.

  9. Click Browse at the end of the Input field. The Type Chooser dialog is displayed.

  10. Select Project Schema Files, singleString.xsd, singleString, and then click OK.

  11. Click Browse at the end of the Output field. The Type Chooser dialog is displayed.

  12. Select Project Schema Files, singleString.xsd, singleString, and then click OK.

  13. Click OK. The OutboundDequeue application and OutboundDequeueComposite project appears in the design area, as shown in Figure 10-82.

    Figure 10-82 The JDeveloper - Composite.xml

    Description of Figure 10-82 follows
    Description of "Figure 10-82 The JDeveloper - Composite.xml"

Creating an Outbound Dequeue Adapter Service

Perform the following steps to create an adapter service that will dequeue the message to a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter OutboundDequeueService in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Get Message from MQ and Synchronous, and click Next. The Get Message from MQ page is displayed.

  7. 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.

  8. Click Browse at the end of the URL field. The Type Chooser dialog is displayed.

  9. 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.

  10. Click Next. The Finish page is displayed.

  11. Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-83.

    Figure 10-83 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-83 follows
    Description of "Figure 10-83 The JDeveloper Page - Composite.xml Page"

  12. Click File, Save All.

Wiring Services and Activities

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 together:

  1. 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.

  2. Double-click BPELOutboundDequeue. The BPELOutboundDequeue.bpel page is displayed.

  3. 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-84.

    Figure 10-84 The JDeveloper - Composite.xml Page

    Description of Figure 10-84 follows
    Description of "Figure 10-84 The JDeveloper - Composite.xml Page"

    The JDeveloper BPELOutboundDequeue.bpel page is displayed, as shown in Figure 10-85.

    Figure 10-85 The BPELOutboundDequeue.bpel Page

    Description of Figure 10-85 follows
    Description of "Figure 10-85 The BPELOutboundDequeue.bpel Page"

  4. Drag and drop the Invoke activity to the OutboundDequeueService adapter reference. The Invoke dialog is displayed.

  5. Click the Auto Create Variable icon that appears at the end of the Input Variable field. The Create Variable dialog is displayed.

  6. Accept the defaults, and click OK.

  7. Repeat the same for the output variable and click OK.

  8. Double-click the Assign activity. The Assign dialog is displayed.

  9. Click the plus icon and select Copy Operation. The Create Copy Operation dialog is displayed.

  10. Select the variables, as shown in Figure 10-86, and then click OK.

    Figure 10-86 Create Copy Operation Dialog

    Description of Figure 10-86 follows
    Description of "Figure 10-86 Create Copy Operation Dialog"

  11. Click OK in the Assign dialog.

    The BPELOutboundDequeue.bpel page appears, as shown in Figure 10-87.

    Figure 10-87 The BPELOutboundDequeue.bpel Page

    Description of Figure 10-87 follows
    Description of "Figure 10-87 The BPELOutboundDequeue.bpel Page "

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Log in to http://servername:portnumber/em using your username/password.

  2. In the left pane, navigate to SOA, soa-infra (soa_server1). A list of all the composites that are deployed appears.

  3. Click OutboundDequeueComposite[1.0]. The OutboundDequeueComposite[1.0] page is displayed.

  4. Click the Test button. The Test Web Service page is displayed.

  5. Click the Request tab, and scroll to the Input Arguments pane.

  6. Enter Test Outbound Dequeue in the Input field, and then click the Test Web Service button.

  7. Wait for some time and then click the Response tab. The message in the singleString xsd that you provided appears in the Response tab.

  8. Click the Instances tab.

  9. Click the instance associated with this deployment. The Flow Trace page is displayed.

  10. Click the BPELOutboundDequeue component instance. The Audit Trail page is displayed, as shown in Figure 10-88.

    Figure 10-88 Audit Trail Page

    Description of Figure 10-88 follows
    Description of "Figure 10-88 Audit Trail Page"

  11. Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.

  12. Click an activity to view the relevant payload details.

Using RFH2 Headers

This use case demonstrates how to set the RFH2 header properties for a message to be added to a MQ Series queue. This is applicable only for outbound references. You must ensure that the format of the message is RFH2 and also set the fixed portions of the header properties. This section contains the following topics:

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. In the Name your application screen, enter the name of your application in the Application Name field, and then click Next. The Name your project page is displayed.

  5. In the Project Name field, enter the project name and from the Available list, select SOA and click the right-arrow button.

  6. Click Next. The Configure SOA Settings page is displayed.

  7. In the Composite Template list, select Composite With BPEL, and then click Finish. The Create BPEL Process page is displayed.

  8. Enter a name for your BPEL process in the Name field, and select One Way BPEL Process from the Template box.

  9. Click OK. Your application and project appears in the design area, as shown in Figure 10-41.

    Figure 10-89 The JDeveloper - Composite.xml

    Description of Figure 10-89 follows
    Description of "Figure 10-89 The JDeveloper - Composite.xml"

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message from a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter a service name in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Get Message from MQ, and click Next. The Get Message from MQ page is displayed.

  7. Enter a queue name in the Queue Name field, and click Next. The Messages page is displayed.

  8. Select Native format translation is not required (Schema is Opaque), and click Next. The Finish page is displayed.

  9. Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-90.

    Figure 10-90 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-90 follows
    Description of "Figure 10-90 The JDeveloper Page - Composite.xml Page"

Creating an Outbound Adapter Service

Perform the following steps to create an adapter service that will enqueue the messages.

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter the service name in the Service Name field, and click OK. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.

  7. Enter a queue name in the Queue Name field, and click Next. The Advanced Options page is displayed.

  8. Accept the defaults and click Next. The Messages page is displayed.

  9. Select Native format translation is not required (Schema is Opaque), and click Next. The Finish page is displayed.

    Note:

    You can also specify a sample schema that you must use if native format translation is required.
  10. 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

    Description of Figure 10-91 follows
    Description of "Figure 10-91 The JDeveloper Page - Composite.xml Page"

Wiring Services and Activities

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 together:

  1. 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.

  2. 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

    Description of Figure 10-92 follows
    Description of "Figure 10-92 The JDeveloper - Composite.xml"

  3. Click File, Save All.

  4. Double-click the BPEL process. The BPELprocess.bpel page is displayed.

  5. Drag and drop the Assign, and Invoke activities in the order mentioned from the Component Palette to the Components area.

    The JDeveloper BPELprocess.bpel page is displayed, as shown in Figure 10-53.

    Figure 10-93 The BPELprocess.bpel Page

    Description of Figure 10-93 follows
    Description of "Figure 10-93 The BPELprocess.bpel Page"

  6. Create temporary variables to store the RFH2 header portions. Additionally, you must create a messageFormat variable, a JMSFolder variable, and an MCDFolder variable.

    1. Click the Variables... icon represented by (x). The Variables dialog is displayed.

    2. Click the Create... (Alt+N) icon. The Create Variable dialog is displayed.

    3. Enter a variable name in the Name field.

    4. Select Simple Type as the variable type.

    5. Click Browse XML Schema Types icon at the end of Simple Type field. The Type Chooser dialog is displayed.

    6. Choose string type.

    7. Click OK. A variable of type Simple Type is added to the Variables list in the variable dialog, as shown in Figure 10-94.

      Figure 10-94 The Variable Dialog

      Description of Figure 10-94 follows
      Description of "Figure 10-94 The Variable Dialog"

    8. Repeat Step a to g until all the required variables have been created.

  7. Assign values to variables created in Step 6 by performing the following steps:

    1. Double-click the assign activity. The Assign dialog is displayed.

    2. Click the Copy Operation tab. The Assign dialog is displayed.

    3. Select Copy Operation. The Create Copy Operation dialog is displayed.

    4. In the Create Copy Operation dialog, select Expression from Type and specify the value and select the variable in the To pane to which the copy operation is being created, as shown in Figure 10-95.

      Figure 10-95 The Create Copy Operation Dialog

      Description of Figure 10-95 follows
      Description of "Figure 10-95 The Create Copy Operation Dialog"

      The following is a code snippet from the BPELProcess_JMSFolder.bpel file, with the copy operation defined:

        <sequence name="main">
          <receive name="Receive_1" createInstance="yes"
                   variable="Receive_1_Dequeue_InputVariable" partnerLink="DQ"
                   portType="ns1:Dequeue_ptt" operation="Dequeue"/>
          <assign name="Assign_1">
            <copy>
              <from variable="Receive_1_Dequeue_InputVariable" part="opaque"
                    query="/ns3:opaqueElement"/>
              <to variable="Invoke_1_Enqueue_InputVariable" part="opaque"
                  query="/ns3:opaqueElement"/>
            </copy>
            <copy>
              <from expression="'RFH '"/>
              <to variable="StructId"/>
            </copy>
            <copy>
              <from expression="'2'"/>
              <to variable="Version"/>
            </copy>
            <copy>
              <from expression="'273'"/>
              <to variable="Encoding"/>
            </copy>
            <copy>
              <from expression="'-2'"/>
              <to variable="CodedCharSetId"/>
            </copy>
            <copy>
              <from expression="'MQSTR   '"/>
              <to variable="Format"/>
            </copy>
            <copy>
              <from expression="'0'"/>
              <to variable="Flags"/>
            </copy>
            <copy>
              <from expression="'819'"/>
              <to variable="NameValueCCSID"/>
            </copy>
            <copy>
              <from expression="'RF_HDR_2'"/>
              <to variable="messageFormat"/>
            </copy>
            <copy>
              <from expression="'&lt;jms>&lt;Dst>MYTOPIC&lt;/Dst>&lt;Exp>2000&lt;/Exp>&lt;Pri>4&lt;/Pri>&lt;Cid>22344&lt;/Cid>&lt;Rto>REPLY.QUEUE&lt;/Rto>&lt;Gid>3334&lt;/Gid>&lt;Seq>2&lt;/Seq>&lt;Dlv>1&lt;/Dlv>&lt;xxx>User Space&lt;/xxx>&lt;/jms>'"/>
              <to variable="JMSFolder"/>
            </copy>
            <copy>
              <from expression="'&lt;mcd>&lt;Msd>jms_object&lt;/Msd>&lt;/mcd>'"/>
              <to variable="MCDFolder"/>
            </copy>
          </assign>
      

      Note:

      The values for StructId and Version are fixed, as specified in the preceding code snippet. You can set the values for the other variables according to your requirements.
    5. Repeat step b to d, until the copy operation is created for all the variables.

    6. Click OK in the Create Copy Operation dialog. The Assign dialog is displayed as shown in Figure 10-96.

      Figure 10-96 The Assign Dialog

      Description of Figure 10-96 follows
      Description of "Figure 10-96 The Assign Dialog"

    7. Click OK. The BPELProcess.bpel page is displayed.

  8. Set the header properties by using the following steps:

    1. Double-click the invoke activity. The Invoke dialog is displayed.

    2. Click the Browse Partner Links icon to the right of the Partner Link field. The Partner Link Chooser page is displayed.

    3. Select the outbound service and click OK.

    4. Click the Auto-Create Variable icon to the right of the Variable field under the General tab. The Create Variable dialog is displayed.

    5. Select the default variable name and click OK. The Variable field is populated with the default variable name.

    6. Click the Properties tab.

    7. Select a property from the Properties column and set the Value accordingly.

      For example, select the jca.mq.MQMD.Format property from the Properties column and set the Value as MessageFormat. Ensure that the Type column is set to input, as shown in Figure 10-97.

      Note:

      if you want to create a user folder, then you must first assign the value to a String variable, then go to Properties in the Invoke activity and then map this String value to the property jca.mq.RFH2.USRFolder.

      Figure 10-97 The Invoke Dialog

      Description of Figure 10-97 follows
      Description of "Figure 10-97 The Invoke Dialog"

    8. Click OK. The BPELProcess.bpel page is displayed.

    9. Click the Properties tab. The BPELProcess.bpel page is displayed.

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Configuring a Backout Queue

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:

Prerequisites

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>

Designing the SOA Composite

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:

  1. In JDeveloper, click File and select New.

    The New Gallery dialog is displayed.

  2. Expand the General node, and select the Applications category.

  3. In the Items list, select Generic Application and click OK. The Create Generic Application Wizard is displayed.

  4. 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.

  5. In the Project Name field, enter SOA_BackoutQ_Retry and from the Available list, select SOA and click the right-arrow button.

  6. Click Next. The Configure SOA Settings screen is displayed.

  7. In the Composite Template list, select Composite With BPEL, and then click Finish. The Create BPEL Process dialog is displayed.

  8. Enter BPELProcess_BackoutQ_Retry in the Name field, and select Define Service Later from the Template box.

  9. Click OK. The MQ_BackoutQ_Retry application and the SOA_BackoutQ_Retry project appears in the design area.

Creating an Inbound Adapter Service

Perform the following steps to create an adapter service that will dequeue the message and put the message to a queue:

  1. Drag and drop MQ Adapter from the Component Palette into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter InboundService in the Service Name field, and click Next. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Get Message from MQ and Send Reply/Reports (Synchronous), and click Next. The Get Message from MQ and Send Rep page is displayed.

  7. Enter INBOUND_QUEUE in the Queue Name field, and click Next. The Response page is displayed.

  8. Accept the defaults, and click Next. The Messages page is displayed.

  9. Click Browse at the end of the URL fields. The Type Chooser dialog is displayed.

  10. Select Project Schema Files, singleString.xsd, and then singleString.

  11. Click OK. The singleString.xsd file appears in the URL fields in the Messages page.

  12. Click Next. The Finish page is displayed.

  13. Click Finish. You have now configured the inbound adapter service, and the composite.xml page is displayed with an inbound adapter added.

  14. 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"/>    
    

Creating an Outbound Adapter Service

Perform the following steps to create an adapter service that will enqueue the messages.

  1. Drag and drop MQ Adapter from the Component Palette into the External References swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Click Next. The Service Name page is displayed.

  3. Enter EQ in the Service Name field, and click Next. The MQ Series Connection page is displayed.

  4. Accept the default JNDI name for the MQ Series connection, and click Next. The Adapter Interface page is displayed.

  5. Select Define from operation and schema (specified later), and click Next. The Operation Type page is displayed.

  6. Select Put Message into MQ, and click Next. The Put Message into MQ page is displayed.

  7. Enter a test_out in the Queue Name field, and click Next. The Advanced Options page is displayed.

  8. Accept the defaults and click Next. The Messages page is displayed.

  9. Click Browse at the end of the URL field. The Type Chooser dialog is displayed.

  10. 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.

  11. Click Next. The Finish page is displayed.

  12. Click Finish. You have now configured the outbound adapter service, and the composite.xml page is displayed, as shown in Figure 10-98.

    Figure 10-98 The JDeveloper Page - Composite.xml Page

    Description of Figure 10-98 follows
    Description of "Figure 10-98 The JDeveloper Page - Composite.xml Page"

Wiring Services and Activities

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 together:

  1. 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.

  2. 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-99.

    Figure 10-99 The JDeveloper - Composite.xml

    Description of Figure 10-99 follows
    Description of "Figure 10-99 The JDeveloper - Composite.xml"

  3. Click File, Save All.

  4. Double-click BPELProcess_BackoutQ_Retry. The BPELProcess_backoutQ_Retry.bpel page is displayed.

  5. Drag and drop the Receive, Assign, Invoke, and Reply activities in the order mentioned from the Component Palette to the Components area.

  6. Drag and drop the Receive activity to ReqReply. The Receive dialog is displayed.

  7. Click the Auto Create Variable icon that appears at the end of the Variable field. The Create Variable dialog is displayed.

  8. Accept the defaults, and click OK.

  9. Check the Create Instance box, and click OK.

  10. Drag and drop the Reply activity to ReqReply. The Reply dialog is displayed.

  11. Enter ReplyOutput in the Name field.

  12. Click the Browse Variables icon that appears at the end of the Variable field. The Variable Chooser dialog is displayed.

  13. Select replyOutput_DequeueEnqueue_OutputVariable, and click OK. The variable appears in the Reply dialog.

  14. Click OK.

  15. Drag and drop the Invoke activity to EQ. The Invoke dialog is displayed.

  16. Click the Automatically Create Input Variable icon that appears at the end of the Input Variable field.

  17. Accept the defaults, and click OK. The Invoke dialog is displayed.

  18. Click OK.

  19. Double-click the Assign activity. The Assign dialog is displayed.

  20. Click the plus icon, and select Copy Operation. The Create Copy Operation dialog is displayed.

  21. 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>
    
  22. Click OK. The BPELdequeueenqueue.bpel page appears, as shown in Figure 10-100.

    Figure 10-100 The BPELProcess_BackoutQ_Retry.bpel Page

    Description of Figure 10-100 follows
    Description of "Figure 10-100 The BPELProcess_BackoutQ_Retry.bpel Page "

Deploying with JDeveloper

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 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 Creating an Application Server Connection for Oracle JCA Adapters.

Monitoring Using the Fusion Middleware Control Console

You can monitor the deployed SOA composite using the Fusion Middleware Control Console. Perform the following steps:

  1. Navigate to http://servername:portnumber/em. The composite you deployed appears in the application navigator.

  2. 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.

  3. Wait for some time and then refresh the Fusion Middleware Control Console. Instances that are triggered as a result of the processing show up on the console.

    Note:

    The number of instances that are triggered must be equal to BackoutRetries + 1.
  4. Click the Instances tab.

  5. Click an instance associated with this deployment. The Flow Trace page is displayed.

  6. Click the BPELProcess_BackoutQ_Retry component instance. The Audit Trail page is displayed.

  7. Click the Flow tab to debug the instance. The BPEL process instance flow is displayed.

  8. Click an activity to view the relevant payload details.