1. Understanding Technology Adapters
  2. Oracle Technology Adapters
  3. Oracle JCA Adapter for AQ

7 Oracle JCA Adapter for AQ

Use the Oracle JCA Adapter for AQ (Oracle AQ Adapter) to enable an Oracle BPEL Process Manager (Oracle BPEL PM) or an Oracle Mediator to interact with a single consumer or a multi consumer queue.

7.1 Introduction to the Oracle AQ Adapter

Oracle Advanced Queuing (AQ) provides a flexible mechanism for bidirectional, asynchronous communication between participating applications.

Advanced queues are an Oracle database feature, and are therefore scalable and reliable. Other features of Oracle database, such as backup and recovery (including any-point-in-time recovery), logging, transactional services, and system management, are also inherited by advanced queues. Multiple queues can also service a single application, partitioning messages in a variety of ways and providing another level of scalability through load balancing.

For more information on Oracle AQ, see Oracle Database Advanced Queuing User's Guide .

7.1.1 Oracle AQ Adapter Integration with Oracle BPEL Process Manager and Oracle Mediator

JCA Binding Component is used for the bidirectional integration of the JCA 1.5 resource adapters with Oracle BPEL Process Manager and Oracle Mediator. JCA Binding Component is based on standards and employs the Web service Invocation Framework (WSIF) technology for exposing the underlying JCA interactions as Web services.

For more information about Oracle AQ Adapter architecture, adapter integration with Oracle BPEL Process Manager and Oracle Mediator, and adapter deployments, see Adapter Integration with Oracle Application Server Components.

7.1.2 Oracle AQ Adapter Integration with Oracle Mediator

The Mediator Server supports Oracle AQ Adapter and enables you to define inbound and outbound adapter services for each. An inbound adapter service receives data from an Oracle AQ Adapter and transforms it into an XML message. An outbound adapter service sends data to a target application by transforming an XML message into the native format of the given adapter.

Using the Mediator Server, you can send or receive messages from Oracle Advanced Queuing single or multi consumer queues.

Note:

Oracle BPEL PM predates Mediator and most of this guide implicitly assume use with Oracle BPEL PM. However, the Oracle AQ Adapter works equally well with either Oracle BPEL PM or Mediator. For any mention of Oracle BPEL PM here, you may substitute Mediator, instead.

7.2 Oracle AQ Adapter Features

The Oracle AQ Adapter is both a producer and a consumer of AQ messages. The enqueue operation is exposed as a JCA outbound interaction. The dequeue operation is exposed as a JCA inbound interaction.

The Oracle AQ Adapter supports ADT (Oracle object type), XMLType, and RAW queues as payloads. It also supports extracting a payload from one ADT member column.

The Oracle AQ Adapter supports normalized properties for enqueue and dequeue operations.

For more information about the properties supported by Oracle AQ Adapter, see Oracle AQ Adapter Properties.

7.2.1 Enqueue-Specific Features (Message Production)

The Oracle AQ Adapter supports the following features of Oracle Streams AQ:

  • Correlation Identifier

    In the Adapter Configuration Wizard, you can specify a correlation identifier when defining an enqueue operation, which you use to retrieve specific messages.

  • Multi consumer Queue

    In Oracle Streams AQ, multiple consumers can process and consume a single message. To use this feature, you must create multi consumer queues and enqueue the messages into these queues. In this configuration, a single message can be consumed by multiple AQ consumer (dequeue operation), either through the default subscription list or with an override recipient list. Under this scenario, a message remains in the queue until it is consumed by all of its intended consumer agents. The Oracle AQ Adapter enqueue header property (jca.aq.RecipientList) enables you to specify the override recipient list (string values separated by commas) that can retrieve messages from a queue. All consumers that are added as subscribers to a multi consumer queue must have unique values for the Recipient parameter. Two subscribers cannot have the same values for the NAME, ADDRESS, and PROTOCOL attributes.

  • Message Priority

    If you specify the priority of enqueued messages, then the messages are dequeued in priority order. If two messages have the same priority, then the order in which they are dequeued is determined by the enqueue time. You can also create a first-in, first-out (FIFO) priority queue by specifying the enqueue time priority as the sort order of the messages. This priority is a property of the Oracle AQ Adapter enqueue header. The enqueue time is set automatically by the underlying AQ application.

    Here is an example of how to create the FIFO queue:

    EXECUTE DBMS_AQADM.CREATE_QUEUE_TABLE( \
queue_table => 'OE_orders_pr_mqtab', \
sort_list =>'priority,enq_time', \
comment => 'Order Entry Priority \
MultiConsumer Orders queue table',\
multiple_consumers => TRUE, \
queue_payload_type => 'BOLADM.order_typ', \
compatible => '8.1', \
primary_instance => 2, \
secondary_instance => 1);
EXECUTE DBMS_AQADM.CREATE_QUEUE ( \
queue_name => 'OE_bookedorders_que', \
queue_table => 'OE_orders_pr_mqtab');

  • Time Specification and Scheduling

    In Oracle Streams AQ, you can specify a delay interval and an expiration interval. The delay interval determines when an enqueued message is marked as available to the dequeuers after the message is enqueued. When a message is enqueued with a delay time set, the message is marked in a WAIT state. Messages in a WAIT state are masked from the default dequeue calls. The expiration time property is used to specify an expiration time, and the message is automatically moved to an exception queue if the message is not consumed before its expiration.

7.2.2 Dequeue and Enqueue Features

Oracle Streams AQ provides the following dequeuing options:

  • Poll option

  • Notification option

The poll option involves processing the messages as they arrive and polling repeatedly for messages. The Oracle AQ Adapter supports a polling mechanism for consuming AQ messages.

The Oracle AQ Adapter supports the following features of Oracle Streams AQ:

  • Multiconsumer Queue

    The Oracle AQ Adapter can retrieve messages from a multiconsumer queue.

  • Navigation of Messages for Dequeuing

    Messages do not have to be dequeued in the same order in which they were enqueued. You can use a correlation identifier to specify dequeue order. The Adapter Configuration Wizard defines the correlation ID for the dequeue operation.

  • Retries with Delays

    The number of retries is a property of the Oracle AQ Adapter dequeue header. If the number of retries exceeds the limit, then the message is moved to an exception queue that you specify. The exception queue is a property of the Oracle AQ Adapter enqueue header.

  • Rule-Based Subscription

    Oracle Streams AQ provides content-based message filtering and subject-based message filtering. A rule defines one or more consumers' interest in subscribing to messages that conform to that rule. For a subject-based rule, you specify a Boolean expression using syntax similar to the WHERE clause of a SQL query. This Boolean expression can include conditions on message properties (current priority and correlation ID), user data properties (object payloads only), and functions (as specified in the WHERE clause of a SQL query).

    For an example of creating rule-based subscriptions to a multiconsumer queue, see Using Message Selector Rule for Filtering Messages During Dequeue.

  • Oracle AQ Adapter Header Properties

    For more information about Oracle AQ Adapter header properties, see Oracle AQ Adapter Properties.

  • Dequeue Condition

    The Dequeue condition is an advanced queuing product feature that Oracle AQ Adapter uses. If a dequeue condition is specified and no messages meet the specified condition, then no dequeue happens.

    A dequeue condition element is a Boolean expression using syntax similar to the WHERE clause of a SQL query. This Boolean expression can include conditions on message properties, user object payload data properties, and PL/SQL or SQL functions. Message properties include priority, corrid, and other columns in the queue table.

    When a dequeue is performed from a multisubscriber queue, it is sometimes necessary to screen the messages and accept only those that meet certain conditions. These conditions may concern header information, such as in selecting messages of only priority 1, or some aspect of the message payload, such as in selecting only loan applications above $100,000.

    The Message Selector Rule field is displayed in Step 11 in Defining an Oracle AQ Adapter Service if you select a multisubscriber queue. Enter a subscription rule in the form of a Boolean expression using syntax similar to a SQL WHERE clause, such as priority = 1, or TAB.USER_DATA.amount > 1000. The adapter dequeues only those messages for which this Boolean expression is true.

    Note:

    MessageSelectorRule can be used in combination with DequeueCondition to support nested queries. For an example of creating rule-based subscriptions to a multiconsumer queue, see Using Message Selector Rule for Filtering Messages During Dequeue.

    You must select the Access to non-payload fields also needed check box to access header information.

    When this check box is selected, the generated WSDL file has additional code in the type section: 

    <?xml version = '1.0' encoding = 'UTF-8'?>
<?binding.jca Inbound_aq.jca?>
<definitions name="Inbound"   targetNamespace="http://xmlns.oracle.
   com/pcbpel/adapter/aq/Inbound/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT" xmlns:imp1="http://www.oracle.com/ipdemo">
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/" xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT">
            <import namespace="http://xmlns.oracle.com/xdb/SCOTT" schemaLocation="xsd/SCOTT_MAGAZINE_TYPE.xsd"/>
            <import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/" schemaLocation="xsd/aqAdapterInboundHeader.xsd"/>
            <complexType name="HeaderCType">
                <sequence>
                    <element name="QueueHeader" 
                             type="hdr:HeaderType"/>
                    <element name="PayloadHeader" 
                        type="obj1:MAGAZINE_TYPE"/>
                </sequence>
            </complexType>
            <element name="Header" type="tns:HeaderCType"/>
        </schema>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://www.oracle.com/ipdemo" schemaLocation="xsd/simpleMagazine.xsd"/>
        </schema>
    </types>
    <message name="simpleMagazine_msg">
        <part name="simpleMagazine" 
                    element="imp1:simpleMagazine"/>
    </message>
    <message name="Header_msg">
        <part name="Header" element="tns:Header"/>
    </message>
    <portType name="Dequeue_ptt">
        <operation name="Dequeue">
            <input message="tns:simpleMagazine_msg"/>
        </operation>
    </portType>
    <plt:partnerLinkType name="Dequeue_plt">
        <plt:role name="Dequeue_role">
            <plt:portType name="tns:Dequeue_ptt"/>
        </plt:role>
    </plt:partnerLinkType>
</definitions>

    Note that PayloadHeader is the type for the whole ADT of the queue. The payload contains only the chosen payload field. If you selected Access to non-payload fields also needed, then the PayloadHeader (. jca.aq.HeaderDocument) contains the whole ADT (including the payload field, which is also present in the header, but ignored by the adapter.)

For more information about Oracle AQ Adapter architecture, adapter integration with Oracle BPEL Process Manager and Oracle Mediator, and adapter deployments, see Introduction to Oracle JCA Adapters.

7.2.3 Synchronous Request-Response

You can employ the AQ Adapter Configuration Wizard to model a process that enables the Oracle AQ Adapter to be used in a synchronous request-response interaction pattern.

In this scenario, the Oracle AQ Adapter sends a request to the request queue and waits for a response from the reply queue before further execution continues. Internally, the Oracle AQ Adapter uses a new interaction pattern, AQRequestReplyInteractionSpec. This interaction spec enables you to configure a request and reply destination name.

A variation enables you to use a temporary destination as part of the reply queue. In turn, the Adapter sets the AQReplyTo header to the reply destination.

7.2.3.1 Configuration Wizard Flow for AQ Synchronous Request-Response Interaction Pattern

Follow these steps to use the AQ Adapter Configuration Wizard to configure an AQ Adapter for synchronous request-response.

  1. Open the AQ Adapter Configuration Wizard and proceed through the initial steps. On the AQ Adapter Operation Page, select Enqueue/Dequeue. The Operation Name section on the page is enabled.

    Select Synchronous, and either use the supplied Operation Name Enqueue_Dequeue, or change the name to one of your own.

    Figure 7-1 AQ Adapter Configuration Wizard Operation Screen with Enqueue/Dequeue and Synchronous Operation Selected

    Description of Figure 7-1 follows
    Description of "Figure 7-1 AQ Adapter Configuration Wizard Operation Screen with Enqueue/Dequeue and Synchronous Operation Selected"
  2. On the Queue Name screen, provide Outbound Queue Information and Inbound Queue Information. You can browse for a Database Schema and select the appropriate Queue Name, or use the Default Schema and select a Queue Name from the list available with the Default Schema selected.
  3. The Queue Parameters screen appears. Provide the following, and then select Next. Note that

    • In the Consumer field, provide the consumer name for a multi-consumer queue.

    • In the Message Selector Rule field, provide a Message Selector Rule. Refer to Dequeue and Enqueue Features for more information on using Message Selector Rules.

    • In the Dequeue Condition, provide conditions on messages. Refer to Dequeue and Enqueue Features for more information on using Dequeue Condition.

  4. The AQ Adapter Configuration Wizard Object Payload Screen appears. This screen enables you to enter information about the object payloads for both inbound and outbound Queues.

    Figure 7-2 AQ Adapter Configuration Wizard Object Payload Screen

    Description of Figure 7-2 follows
    Description of "Figure 7-2 AQ Adapter Configuration Wizard Object Payload Screen"

    • Text at the top specifies the name of a structured object payload. The rest of the text provides additional information about the payload. For the Business Payload either the Whole object or the Field within the Object.

    • If you specified Field within the Object, the Payload Field Options section is enabled. There you can enter directly or Browse to enter the field name.

      If you select Browse, the Select Payload Field Browser opens. Select the field or fields that contains the business payload and click OK to populate the field name on the Object Payload screen.

      You can also select Validate Payload to validate the payload for the dequeue operation. When this option is selected, the resulting XML payload is validated against the schema before further processing. In case of failure, the message is rejected.

      Figure 7-3 The AQ Adapter Configuration Wizard Select Payload Field Browser

      Description of Figure 7-3 follows
      Description of "Figure 7-3 The AQ Adapter Configuration Wizard Select Payload Field Browser"

      Select the checkbox Access to non-payload fields needed if you also need the schema generated for these fields. Select this checkbox if you would want ADT object attributes to be available as header properties. For example, your payload may be a JPG image. You might want to specify a person's name in the non payload field. This selection generates an additional header schema file (object_name.xsd, where object_name is the structured payload object used by the queue. The xsd name is additionally prefixed by the schema; if you are connected to schema scott, the name would be SCOTT_object_name.xsd. If you select ADT fields on the Object page or if Whole ADT payload is selected, the Messages page is displayed for you to specify schemas.If you specify a ADT Field within the structured object, the outbound ADT field name must be same as the inbound ADT Field name.

    • Fill in the information in a similar manner for the Outbound Queue in the second half of the AQ Adapter Configuration Wizard Object Payload Screen.

    • Click Next.

  5. The AQ Adapter Configuration Wizard Messages Screen appears.

    • On this screen, you are prompted to define the message that is contained in the fields of both queues you have specified. As with other message screens for this and other adapters, you can indicate if the message is opaque and native format translation is required, or you can specify a schema by providing the schema and the URL and the schema element.

    • Click Next to finish configuring the AQ Adapter in a Synchronous Request-Response interaction pattern.

    Figure 7-4 The AQ Adapter Configuration Wizard Messages Screen

    Description of Figure 7-4 follows
    Description of "Figure 7-4 The AQ Adapter Configuration Wizard Messages Screen"
7.2.3.1.1 Editing an AQ Adapter using the Synchronous Request-Reply Interaction Pattern

Note that you can also select a previously-configured AQ Adapter using the SOA Composite Editor and invoking the AQ Adapter wizard in edit mode. However, using this method, you cannot modify the operation type, which you have already defined, but you can modify the selected queue and queue parameters, and modify the payload schema.

7.2.4 Synchronous Dequeue

You can configure an outbound Synchronous Dequeue for an AQ Adapter by selecting the Synchronous Dequeue operation type on the AQ Operation Type page.

7.2.4.1 Configuration Wizard Flow for AQ Synchronous Dequeue

Follow these steps to use the AQ Adapter Configuration Wizard to configure AQ for synchronous dequeue.

  1. Select Synchronous Dequeue as the operation type. The operation named for the Synchronous Dequeue is defaulted to Sync_Dequeue. However, you can overwrite this name if you wish.

    Figure 7-5 AQ Adapter Configuration Wizard Operation Screen with Synchronous Dequeue Operation Selected and Operation Name Sync_Dequeue Shown

    Description of Figure 7-5 follows
    Description of "Figure 7-5 AQ Adapter Configuration Wizard Operation Screen with Synchronous Dequeue Operation Selected and Operation Name Sync_Dequeue Shown"
  2. Click Next. The AQ Adapter Configuration Wizard Queue Name screen appears. On this screen, you can specify the database schema and the inbound and outbound queue to be used for this service. Click Next.

    Figure 7-6 AQ Adapter Configuration Wizard Queue Name Screen with Database Schema Defaulted and a Queue Name Selected

    Description of Figure 7-6 follows
    Description of "Figure 7-6 AQ Adapter Configuration Wizard Queue Name Screen with Database Schema Defaulted and a Queue Name Selected "
  3. On the Queue Parameters Screen, indicate the parameters for the Dequeue operator: the Consumer, the Message Selector Rule and the Dequeue Condition, and click Next. (Note that you get this screen only if you select a multiconsumer queue. If you select a single-consumer queue, you get a screen with just two fields: Correlation Id and Dequeue Condition. In that case, you do not get Consumer and Message Selector Rule in the Configuration Wizard.

    • Consumer: Specify the consumer name for a multiconsumer queue.

    • Correlation ID: Enter an optional correlation ID from 1 to 30 characters in length.

    • Message Selector Rule: Provide a Message Selector Rule. Refer to Dequeue and Enqueue Features for more information on using Message Selector Rules.

    • Dequeue Condition: Displayed only when you select dequeue in the Operation page, this enables you to provide conditions on messages. Refer to Dequeue and Enqueue Features for more information on using Dequeue Condition.

    Figure 7-7 The AQ Adapter Configuration Wizard Queue Parameters Screen

    Description of Figure 7-7 follows
    Description of "Figure 7-7 The AQ Adapter Configuration Wizard Queue Parameters Screen"
7.2.4.2 JCA File for Synchronous Request-Reply

The next sections provide file artifacts for both synchronous request-reply and synchronous dequeue. The following example shows the jca file for synchronous request-reply scenario:

<adapter-config name="AQService" adapter="AQ" wsdlLocation="../WSDLs/AQRequestReply.wsdl" xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  <connection-factory location="eis/AQ/slc01gid" UIConnectionName="slc01gid"/>
  <endpoint-interaction portType="Enqueue_Dequeue_ptt" operation="Enqueue_Dequeue" UITransmissionPrimitive="Request-response">
    <interaction-spec className="oracle.tip.adapter.aq.v2.jca.AQRequestReplyInteractionSpec">
     <property name="EnqueueQueue" value="EDN_OAOO_QUEUE"/>
      <property name="RecipientList" value="recp1"/>
      <property name="DequueQueue" value="EDN_EVENT_QUEUE"/>
      <property name="ObjectFieldName" value="PAYLOAD"/>
     <property name="Consumer" value="cons1"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>
7.2.4.3 JCA File for Synchronous Dequeue

The following example shows the jca file for the Synchronous Dequeue scenario:

<adapter-config name="AQSyncDequeue" adapter="AQ" wsdlLocation="../WSDLs/AQSyncDequeue.wsdl" xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  <connection-factory location="eis/AQ/slc01gid" UIConnectionName="slc01gid"/>
  <endpoint-interaction portType="Sync_Dequeue_ptt" operation="Sync_Dequeue">
    <interaction-spec className="oracle.tip.adapter.aq.v2.jca.AQReceiveNoWaitInteractionSpec">
      <property name="Consumer" value="cons1"/>
      <property name="SchemaValidation" value="false"/>
      <property name="QueueName" value="EDN_OAOO_QUEUE"/>
      <property name="ObjectFieldName" value="PAYLOAD"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

7.2.5 Supported ADT Payload Types

The Oracle AQ Adapter supports the following RAW types:

  • BLOB

  • CHAR

  • CLOB

  • DATE

  • DECIMAL

  • DOUBLE PRECISION

  • FLOAT

  • INTEGER

  • NUMBER

  • REAL

  • SMALLINT

  • TIMESTAMP

  • VARCHAR2

In addition to the RAW types mentioned in the preceding list, the Oracle AQ Adapter supports primitive types and arrays of objects.

Note:

The Oracle AQ Adapter does not currently support the following data types for ADT columns: TIMESTAMP WITH LOCAL TIMEZONE and TIMESTAMP WITH TIMEZONE.

If you choose a payload field instead of the whole ADT, then choose one of the following data types as the payload field:

  • CLOB, either XSD or opaque schema

  • VARCHAR2, either XSD or opaque schema

  • BLOB, opaque schema only

  • XMLTYPE, either XSD or opaque schema

7.2.6 Native Format Builder Wizard

Oracle JDeveloper provides the Native Format Builder Wizard to define XSD files of various formats, including for the AQ RAW payload.

For more information about the Native Format Builder wizard, see Native Format Builder Wizard.

Payload Schema

The payload schemas depend on the payload type. In the whole ADT case, the schema is completely generated by the Adapter Configuration Wizard. In an ADT case where the payload case selected is BLOB, an opaque schema as defined in the following example must be used:

<element name="opaqueElement" type="base64Binary" />

In all other cases, you can either provide a schema or use an opaque schema, as shown in Table 7-1.

Table 7-1 Payload Schema

Payload Type Supported Schema

RAW

User-provided schema or opaque schema.

Whole ADT

Must use a schema generated by the Adapter Configuration Wizard, which is based on the queue structure.

ADT with VARCHAR2 picked as payload

User-provided schema or opaque schema.

ADT with CLOB picked as payload user-provided schema or opaque schema

User-provided schema or opaque schema.

ADT with BLOB picked as payload opaque schema

Opaque schema.

XMLTYPE

User-provided schema or opaque schema.

If you do not have an XSD file but the payload data is formatted (for example, in a comma-delimited value (CSV) format), you can use the Native Format Builder wizard to generate an appropriate XSD. The Adapter Configuration Wizard is integrated with the Native Format Builder wizard. In the Adapter Configuration Wizard Messages window, click Define Schema for Native Format to access the Native Format Builder wizard.

7.2.7 Normalized Message Support

Header manipulation and propagation is a key business integration messaging requirement. Oracle BPEL PM, Mediator, Oracle JCA, and B2B rely extensively on header support to solve customers' integration needs. For example, you can preserve a file name from the source directory to the target directory by propagating it through message headers. In Oracle BPEL PM and Mediator, you can access, manipulate, and set headers with varying degrees of UI support.

Note:

AQ Adapter inbound and outbound headers supported in the 10.1.3 release are supported in 11g through normalized message properties.

For more information, see Correlation Support Within Adapters.

Propagating Headers in a Normalized Message:

A normalized message is simplified to have only two parts, properties and payload. Typically, properties are name-value pairs of scalar types. To fit the existing complex headers into properties, properties are flattened into scalar types.

Manipulating Headers in Design Time:

The user experience is simplified while manipulating headers in design time, because the complex properties are predetermined. In the Mediator or BPEL designer, you can manipulate the headers with some reserved key words. For example, currently in Mediator, you can access an inbound File adapter fileName header using the following expression: 

$nmproperty.InboundFileHeaderType.fileName

However, this method does not address the properties that are dynamically generated based on your input. For example, in the AQ Adapter Wizard, you can propagate some fields from an AQ object as headers. Based on your choice, the header definitions are defined. These definitions are not predetermined and hence cannot be accounted for in the list of predetermined property definitions. You cannot design header manipulation of the dynamic properties before they are defined. To address this limitation, you must generate all the necessary services (composite entry points) and references. This restriction applies to services that are expected to generate dynamic properties. Once dynamic properties are generated, they must be stored for each composite. Only then you can manipulate the dynamic properties in Mediator or BPEL designer.

Identifying Properties That Must Be Propagated over the Life Cycle of the Normalized Message:

Some properties must be propagated across the life cycle of the message, whereas some must not be propagated. The properties that must be propagated are referred to as propagatable properties, whereas properties that must not be propagated are referred to as non-propagatable properties.

7.2.8 Is DOM 2 Compliant

Oracle AQ Adapter is Document Object Model Level 2 (DOM 2) compliant, that is, the AQ adapter can generate document objects that are compliant with DOM2 specification.

7.2.9 Is Message-Size Aware

Oracle AQ Adapter is message-size aware, that is, Oracle AQ Adapter calculates the message size and reports the size back to JCA Binding Component. The API, related to size, exposed by JCA Binding Component can be used for reporting purposes.

7.2.10 Multiple Receiver Threads

Oracle AQ Adapter supports an activation endpoint property, adapter.aq.dequeue.threads. Setting this property is a preferred way to spawn multiple threads for the inbound message flow between the adapter and the Enterprise Information System (EIS). Earlier versions of the Oracle AQ Adapter relied on the activationInstances endpoint property, which was used by JCA Binding Component to initiate multiple endpoints.

7.2.11 DequeueTimeout Property

The DequeueTimeOut property supports multiple inbound dequeue threads. The value for this property determines how many seconds the dequeue() API waits for messages before it returns and the next polling cycle begins.

Add this property to the composite.xml file, as shown in the following example: 

<service name="Inbound" ui:wsdlLocation="Inbound.wsdl">
<interface.wsdl interface="http://xmlns.oracle.com/pcbpel/adapter/aq/AQ_InboundRetry_Mediator/AQ2JMSInboundRetry/Inbound%2F#wsdl.interface(Dequeue_ptt)"/>
<binding.jca config="Inbound_aq.jca">
<property name="DequeueTimeOut" type="xs:integer" many="false"override="may">10
</property>
</binding.jca>
</service>

7.2.12 Control Dequeue Timeout and Multiple Inbound Polling Threads

Oracle AQ Adapter provides system properties to control dequeue timeout and multiple inbound polling threads for each Java Virtual Machine (JVM), systemwide, instead of for each process.

The system property provided by Oracle AQ Adapter to control dequeue timeout is oracle.adapter.aq.wait, and the property that controls inbound polling threads is adapter.aq.dequeue.threads.

7.2.13 Stream Payload Support

Oracle AQ Adapter provides support to stream payload. When you enable this feature, the payload is streamed to a database instead of getting manipulated in SOA runtime as in a memory DOM. You use this feature while handling large payloads. To enable support to stream payload, you must select the Enable Streaming check box while defining the dequeue operation parameters in Oracle JDeveloper (JDeveloper). When you select the Enable Streaming check box, a corresponding Boolean property EnableStreaming is appended to the ActivationSpec properties defined in the respective .jca file, as shown in the following example. If the EnableStreaming property does not exist, then the default value false is assumed. The property is applicable when processing Raw messages, XMLType messages, and ADT type messages for which a payload is specified though an ADT attribute. 

<activation-spec className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
      <property name="QueueName" value="RAW_IN_QUEUE"/>
      <property name="DatabaseSchema" value="SCOTT"/>
      <property name="EnableStreaming" value="true"/>
</activation-spec>

7.2.14 Oracle AQ Adapter Inbound Retries

If you configure the Oracle AQ Adapter inbound retries to retry for more than 5 times by using the jca.retry.count service binding property for a retriable exception, then ensure that the queue is created with max_retries value that is greater then the value used for jca.retry.count. If nothing is specified, then the queue is created with a max_retries value of 5 which would mean that the message ends up in the exception queue after 5 retries and is not be delivered to adapter for further processing. If jca.retry.count is specified with a value of 5 or less, then you do not have to change the queue max_retries property.

Use the following code to change the max_retries property when creating a queue: 

begin
DBMS_AQADM.CREATE_QUEUE_TABLE ( queue_table => 'RAW_IN_QUEUE_TABLE',queue_payload_type => 'RAW');
DBMS_AQADM.CREATE_QUEUE ( queue_name => 'RAW_IN_QUEUE',queue_table=> 'RAW_IN_QUEUE_TABLE', max_retries=>1500);
DBMS_AQADM.START_QUEUE ( queue_name => 'RAW_IN_QUEUE');
DBMS_AQADM.CREATE_QUEUE_TABLE ( queue_table => 'RAW_OUT_QUEUE_TABLE', queue_payload_type => 'RAW');
DBMS_AQADM.CREATE_QUEUE ( queue_name  => 'RAW_OUT_QUEUE', queue_table => 'RAW_OUT_QUEUE_TABLE');
DBMS_AQADM.START_QUEUE ( queue_name => 'RAW_OUT_QUEUE');
end;

7.2.15 Error Handling Support

For information about error handling, see Error Handling.

7.2.16 Performance Tuning

Oracle AQ Adapter supports performance tuning features.

For more information, see Oracle JCA Adapter Tuning Guide and Oracle JCA Adapter Properties.

7.3 Oracle AQ Adapter Deployment

The Oracle AQ Adapter comes deployed to the application server as part of the install. It contains a single adapter instance entry eis/AQ/aqSample, which points to the data source jdbc/aqSample. The data source is not created as part of install and must be created manually. The connection information to the database is inside the data source definition.

When deploying a SOA project that uses the Oracle AQ Adapter instance eis/AQ/aqSample that exists at the time of installation, you must first create a data source at jdbc/aqSample. On the other hand, if a new adapter instance is preferred, then you must add a new adapter instance and restart the application server. This is because you want to point to a data source other than the one referred in the existing adapter instance jdbc/aqSample, or because you chose a name for the adapter instance that does not yet exist. For instance, if you create a connection in JDeveloper named DBConnection1, then by default the AQ Adapter service points to eis/AQ/DBConnection1, as shown in Figure 7-12.

You can also check which adapter instance the service is pointing to by looking at the .jca file, as shown in the following code snippet: 

<connection-factory location="eis/AQ/aqSample" … />

In the preceding example, the location is the JNDI name of the adapter instance at runtime.

You can create a new AQ Adapter instance through the Oracle WebLogic Administration Console, as mentioned in Adding an Adapter Connection Factory or by directly editing the weblogic-ra.xml file. The following are the steps to edit weblogic-ra.xml:

  1. Search fmwhome/ for AqAdapter.rar.

  2. Unzip the file.

  3. Edit META-INF/weblogic-ra.xml (and possibly ra.xml.)

  4. Jar the file again.

  5. Restart the application server.

The following is a sample AQ adapter instance in weblogic-ra.xml:

Example - Sample AQ Adapter Instance in weblogic-ra.xml

<connection-instance>
  <jndi-name>eis/AQ/aqSample</jndi-name>
  <connection-properties>
    <properties>
      <property>
         <name>XADataSourceName</name>
         <value>jdbc/aqSample</value>
      </property>
      <property>
    <name>DataSourceName</name>
    <value></value>
      </property>
      <property>
    <name>ConnectionString</name>
    <value></value>
      </property>
      <property>
    <name>UserName</name>
    <value></value>
      </property>
      <property>
    <name>Password</name>
    <value></value>
      </property>
      <property>
    <name>DefaultNChar</name>
    <value>false</value>
      </property>
      <property>
    <name>UseDefaultConnectionManager</name>
    <value>false</value>
      </property>
    </properties>
  </connection-properties>
</connection-instance>

The mandatory properties are: jndi-name, XADataSourceName or DataSourceName. The jndi-name property must match the location attribute in the .jca file, and is the name of the adapter instance. The XADataSourceName or DataSourceName property is the name of the underlying data source (which has the connection information). Specify one of the properties XADataSourceName or DataSourceName. The usage depends on if the scenario involves and would require adapter to participate in global transaction or if local transaction semantics are sufficient. In the former case XADataSourceName must be specified while in the latter case DataSourceName must be specified. When specifying XADataSourceName property ensure that the physical data source it refers to is XA enabled while when specifying DataSourceName property the physical data source it refers to might or might not be XA enabled.

Most Common Mistakes

The following are the two most common mistakes with deployment:

  • Not creating an adapter instance entry that matches the location attribute in your .jca file (or not creating a instance at all.)

  • Setting the location attribute in the .jca file to the name of the data source directly.

For the latter, there is a level of indirection in that you give the name of the adapter instance (eis/AQ/...), which itself points to the data source pool (jdbc/...). It is a common mistake to miss this indirection and give the name jdbc/... directly in the location attribute.

Additional Adapter Instance Properties

There are additional properties in the AQ Adapter instance beyond xADataSourceName, dataSourceName.

For information about the Oracle AQ Adapter instance properties, see Oracle AQ Adapter Properties.

7.4 Oracle AQ Adapter Use Cases

The section includes the following use cases related to Oracle AQ Adapter.

7.4.1 Generic Use Cases

The following use cases include a general walkthrough of the Adapter Configuration Wizard, followed by examples of how you can modify the general procedure in different situations. Each example shows relevant parts of the generated WSDL and JCA files.

This section includes the following topics:

7.4.1.1 The Adapter Configuration Wizard Walkthrough

In this example, you create an Oracle AQ Adapter service that dequeues messages to the service_in_queue queue, with a payload that is one field within the service_type object, and with a user-defined schema.

This section describes the tasks required to configure Oracle AQ Adapter by using the Adapter Configuration Wizard in JDeveloper.

This section includes the following topics:

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

You must have access to a database with the SCOTT schema.

To perform this use case, you must first create the following files and execute them in the following order:

  • setup_user.sql

  • create_type_service.sql

  • create_queues.sql

  • dequeue_service.sql

  • enqueue_service.sql

Contents of setup_user.sql

grant connect, resource to scott;
;
grant aq_administrator_role to scott;
;

Contents of create_type_service.sql

create type SERVICE_TYPE as OBJECT (
        MSG_ID                                          VARCHAR2(128),
        INREPLYTO_MSG_ID                                VARCHAR2(128),
	    FROM_PARTY                                      VARCHAR2(512),
	    TO_PARTY                                        VARCHAR2(512),
        ACTION_NAME                                     VARCHAR2(512),
        DOCTYPE_NAME                                    VARCHAR2(512),
        DOCTYPE_REVISION                                VARCHAR2(512),
        MSG_TYPE                                        INT,
        PAYLOAD                                         CLOB
)
/

Contents of create_queues.sql

begin
  dbms_aqadm.create_queue_table('service_in_table', 'service_type');   
  dbms_aqadm.create_queue('service_in_queue', 'service_in_table');
  dbms_aqadm.start_queue('service_in_queue');
  dbms_aqadm.create_queue_table('service_out_table', 'service_type');   
  dbms_aqadm.create_queue('service_out_queue', 'service_out_table');
  dbms_aqadm.start_queue('service_out_queue');
end;
/

Contents of dequeue_service.sql

set serveroutput on;
DECLARE
   enqueue_options     dbms_aq.enqueue_options_t;
   dequeue_options     dbms_aq.dequeue_options_t;
   message_properties  dbms_aq.message_properties_t;
   message_handle      RAW(16);
   msg_varchar         varchar2(4000);
   service1           service_type;
BEGIN
   dequeue_options.wait:=180;
   DBMS_AQ.DEQUEUE(
      queue_name          =>     'SERVICE_OUT_QUEUE',
      dequeue_options      =>    dequeue_options,
      message_properties  =>     message_properties,
      payload             =>     service1,
      msgid               =>     message_handle);
	 dbms_output.put_line('SERVICE.MSG_ID="' || SERVICE1.MSG_ID || '"');
	 dbms_output.put_line('SERVICE.INREPLYTO_MSG_ID="' || SERVICE1.INREPLYTO_MSG_ID || '"');		
	 dbms_output.put_line('SERVICE.FROM_PARTY="' || SERVICE1.FROM_PARTY || '"');		
	 dbms_output.put_line('SERVICE.TO_PARTY="' || SERVICE1.TO_PARTY || '"');				
	 dbms_output.put_line('SERVICE.ACTION_NAME="' || SERVICE1.ACTION_NAME || '"');				
	 dbms_output.put_line('SERVICE.DOCTYPE_NAME ="' || SERVICE1.DOCTYPE_NAME  || '"');	
	 dbms_output.put_line('SERVICE.DOCTYPE_REVISION ="' || SERVICE1.DOCTYPE_REVISION  || '"');
	 dbms_output.put_line('SERVICE.MSG_TYPE="' || SERVICE1.MSG_TYPE || '"');				
	 dbms_output.put_line('SERVICE.PAYLOAD="' || SERVICE1.PAYLOAD|| '"');				
END;
/

Contents of enqueue_service.sql

DECLARE
  enqueue_options     dbms_aq.enqueue_options_t;
  message_properties  dbms_aq.message_properties_t;
  msgid               RAW(16);
  qname                VARCHAR2(100);
  service                service_type;
BEGIN
  qname := 'service_in_queue';
  service := service_type('reply123', 'request123', 'seller', 'buyer', 'ack','b2bDoc', '1.1', 1, '<?xml version="1.0" encoding="UTF-8"?><SERVICE xmlns="http://www.oracle.com/service/contract"><DESCRIPTION>ADT with CLOB payload testcase</DESCRIPTION><RATE>100.00</RATE></SERVICE>');  
      dbms_aq.enqueue(queue_name         => qname,           
                      enqueue_options    => enqueue_options,       
                      message_properties => message_properties,     
                      payload            => service,               
                      msgid              => msgid);
  commit;
END;
/
7.4.1.1.2 Creating an Application and a SOA Project

You must create a JDeveloper application to contain the SOA composite. To create an application and a SOA project, perform the following steps:

  1. Open JDeveloper.
  2. In the Application Navigator, click New Application. The Create Generic Application Name your application page is displayed, as shown in Figure 7-8.
  3. Enter a name for the application in the Application Name field.
  4. In the Application Template list, choose Generic Application.

    Figure 7-8 The Create Generic Application Name your application Page

    Description of Figure 7-8 follows
    Description of "Figure 7-8 The Create Generic Application Name your application Page"
  5. Click Next.

    The Create Generic Application Name your project page is displayed, as shown in Figure 7-9.

  6. In the Project Name field, enter a descriptive name.

    For example, SOAComposite.

  7. In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.

    Figure 7-9 The Create Generic Application Name your Generic project Page

    Description of Figure 7-9 follows
    Description of "Figure 7-9 The Create Generic Application Name your Generic project Page"
  8. Click Next.

    The Create Generic Application Configure SOA settings page is displayed, as shown in Figure 7-10.

    Figure 7-10 The Create Generic Application Configure SOA settings Page

    Description of Figure 7-10 follows
    Description of "Figure 7-10 The Create Generic Application Configure SOA settings Page"
  9. Select Composite With BPEL from the Composite Template list, and then click Finish.

    You have created a new application and a SOA project. This automatically creates a SOA composite.

    The Create BPEL Process page is displayed, as shown in Figure 7-11.

    Figure 7-11 The Create BPEL Process Page

    Description of Figure 7-11 follows
    Description of "Figure 7-11 The Create BPEL Process Page"
  10. Enter a name for the BPEL process in the Name field. For example, CustomerDetails.
  11. Select Define Service Later in the Template list, and then click OK.

    You have created the CustomerDetails BPEL process.

7.4.1.1.3 Defining an Oracle AQ Adapter Service

The next step is to define an Oracle AQ Adapter service. Perform the following steps to create an Oracle AQ Adapter service:

  1. Drag and drop AQ Adapter from the Components to the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Specify a service name, and then click Next.

    The Service Connection page is displayed.

    Figure 7-12 Adapter Configuration Wizard Service Connection Page

    Description of Figure 7-12 follows
    Description of "Figure 7-12 Adapter Configuration Wizard Service Connection Page"

  3. Click the plus icon to create a database connection.

    The Create Database Connection page is displayed.

    Note:

    You must connect to the database where Oracle Applications is running.

  4. Enter the following information:

    1. For Create Connection In, choose Application Resources.

    2. In the Connection Name field, specify a unique name for the database connection.

      In this example, type DBConnection1.

    3. From the Connection Type box, select Oracle (JDBC).

    4. In the UserName field, specify the user name to be authorized for access to the database.

      In this example, type scott.

    5. In the Role field, enter a role, if applicable.

      This must be a specific database role, such as SYSDBA, as defined in the database. This field is optional. In this example, leave the Role field blank.

    6. In the Password field, specify the password to be associated with the specified user name.

      In this example, type tiger.

    7. Select Save Password and Deploy Password.

    8. From the Driver list, select Thin.

    9. In the Host Name field, enter a value to identify the computer running the Oracle server.

      Use an IP address or a host name that can be resolved by TCP/IP, for example, myserver. The default value is localhost.

    10. In the JDBC Port field, enter a value to identify the TCP/IP port. The default is 1521.

    11. In the SID field, enter a value for the unique system identifier (SID) of an Oracle database instance.

      The default is XE.

    12. Click Test Connection to determine whether the specified information establishes a connection with the database.

      A Success message is displayed.

    13. Click OK.

      The Connection you created is displayed in the Connection field in the Service Name page.

      Notice that the Java Naming and Directory Interface (JNDI) name in the JNDI Name field is populated after you have created the database connection. The JNDI name acts as a placeholder for the connection used when your service is deployed to the BPEL server. Using JNDI as a placeholder enables you to use different databases for development and later production.

      The value specified in the JNDI name must exist in the Oracle AQ Adapter weblogic-ra.xml file to ensure that the adapter runs in managed mode. A default connection instance eis/AQ/aqSample is shipped and can be used as the default value for this field. To use this connection instance, it would still require that a data source is created with the JNDI name jdbc/aqSample.

  5. Click Next and the Adapter Interface page is displayed.

  6. Choose Define from operation and schema (specified later) and click Next.

  7. The Operation page is displayed. Oracle AQ Adapter supports three operations:

    • Dequeue: Polls for incoming messages from a queue.

    • Enqueue: Puts outgoing messages in a queue.

    • Enqueue/Dequeue: Puts outgoing messages in a queue and expects response messages in a queue.

    In this example, select Dequeue. The operation is automatically named after the operation that you selected. However, you can edit the Operation Name field.

    Note:

    When creating a SOA composite that uses an inbound Oracle AQ Adapter to dequeue from a queue based on an ADT (Abstract Data Type), if the SchemaValidation property in the .jca config file is set to true then a field that does not have any data is returned as <FIELD_NAME xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns=""/>.

    If SchemaValidation is set to false, then the same field is returned as <FILED_NAME NULL="TRUE"/>

    The former is a valid XML and the latter is an invalid XML. The latter is returned for backward compatibility with 11g and no schema validation is done on the returned XML. The following is an example of an ADT type CREATE OR REPLACE TYPE persons_address AS OBJECT 
    ( 
  streetNumber NUMBER, 
  streetName   VARCHAR2(30), 
  citySuburb   VARCHAR2(30), 
  state        VARCHAR2(4), 
  postCode     NUMBER 
);

  8. Click Next and the Queue Name page is displayed.

  9. Select a database schema from the Database Schema list, or click Browse to browse for the schema. In this example, click Browse The Select Queue dialog is displayed.

    Figure 7-13 The Select Queue Dialog

    Description of Figure 7-13 follows
    Description of "Figure 7-13 The Select Queue Dialog"

  10. Select the required queue, and then click OK and click Next. The Queue Parameters page is displayed.

  11. Enter values for the parameters, and then click Next.

    • Consumer: Use the Consumer section of the AQ Adapter Queue Parameters Page to specify the name of the agent subscribing to the queue. This field appears for inbound multiconsumer queues.

    • Correlation ID: Enter an optional correlation ID from 1 to 30 characters in length. This is used to identify messages that can be retrieved at a later time by a dequeue activity using the same correlation ID.

      The value to enter is agreed upon between the enqueuing sender and the dequeuing receiver for asynchronous conversations. The correlation ID maps to an AQ header property. Correlation IDs in the inbound direction enable you to be selective about the message to dequeue. This field is optional. If you do not enter a value, then all the messages in the queue are processed.

      If you enter a value for the Correlation ID in the outbound direction, then all outbound messages have the correct ID set to the value entered. You can override this value on a per message basis in the correlation field of the outbound header.

    • Message Selector Rule: Use the Message Selector Rule of the AQ Adapter Queue Parameters Page to specify an agent using the consumer name only if you are using the Advanced Queue Adapter Wizard with multiconsumer queue for dequeue operation.If this field is filled in, an agent using the consumer name and the rule are created in the queue. The consumer name must be a new agent name, because the adapter does not change the rule of a previously created agent. No validation is performed on the logic you enter.This field appears for inbound multiconsumer queues.

      Refer to Dequeue and Enqueue Features for more information on using Message Selector Rules.

    • Dequeue Condition: Displayed only when you select dequeue in the Operation page.

      Enter a Boolean expression similar to the WHERE clause of a SQL query. This expression can include conditions on message properties, user data properties (object payloads only), and PL/SQL or SQL functions. If more than one message satisfies the dequeue condition, then the order of dequeuing is indeterminate, and the sort order of the queue is not honored.

      This field is displayed for inbound single consumer and multiconsumer queues.

  12. Click Next. The Object Payload page is displayed

    Figure 7-14 The Adapter Configuration Wizard Object payload Page

    Description of Figure 7-14 follows
    Description of "Figure 7-14 The Adapter Configuration Wizard Object payload Page"

    1. In Business Payload, select Field within the Object.

    2. Click Browse in the Payload Fields Options section to select a field that contains the business payload.

      Figure 7-15 The Select Payload Field Dialog

      Description of Figure 7-15 follows
      Description of "Figure 7-15 The Select Payload Field Dialog"

  13. Select a field, and then click OK.

    In this example, select PAYLOAD (CLOB).

  14. Select Access to non-payload fields also needed, and then click Next. The Messages page is displayed.

    The Message page has the following options:

    • Native format translation is not required (Schema is Opaque): Select this option if you do not want to specify a schema. Selecting this option disables all the other fields under Message Schema.

    • URL: You can enter the path for the schema file URL or click Browse to browse for the path.

    • Schema Element: The name of the schema element.

  15. In this example, click the Browse for schema file icon to browse for the schema file URL.

    The Type Chooser dialog is displayed.

    Figure 7-16 The Type Chooser Dialog

    Description of Figure 7-16 follows
    Description of "Figure 7-16 The Type Chooser Dialog"

  16. Select SERVICE from the list, click OK and click Next.

    Figure 7-17 The Adapter Configuration Wizard Messages Page

    Description of Figure 7-17 follows
    Description of "Figure 7-17 The Adapter Configuration Wizard Messages Page"

  17. Click Next in the JCA Endpoint Properties screen.

  18. Click Finish in the Finish Screen.

7.4.1.1.4 Generated WSDL and JCA Files

The adapter service generates a WSDL and a JCA file to serve as the defined adapter interface.

The following is the WSDL file generated for the dequeue operation:

<definitions name="Inbound" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT" xmlns:imp1="http://www.oracle.com/service/contract">
    <types>
    <schema attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/" xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT">
       <import namespace="http://xmlns.oracle.com/xdb/SCOTT" schemaLocation="xsd/SCOTT_SERVICE_TYPE.xsd"/>
        <import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/" schemaLocation="xsd/aqAdapterInboundHeader.xsd"/>
            <complexType name="HeaderCType">
                <sequence>
                    <element name="QueueHeader" type="hdr:HeaderType"/>
                    <element name="PayloadHeader" type="obj1:SERVICE_TYPE"/>
                </sequence>
            </complexType>
            <element name="Header" type="tns:HeaderCType"/>
        </schema>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://www.oracle.com/service/contract" schemaLocation="xsd/service.xsd"/>
        </schema>
    </types>
    <message name="SERVICE_msg">
        <part name="SERVICE" element="imp1:SERVICE"/>
    </message>
    <message name="Header_msg">
        <part name="Header" element="tns:Header"/>
    </message>
    <portType name="Dequeue_ptt">
        <operation name="Dequeue">
            <input message="tns:SERVICE_msg"/>
        </operation>
    </portType>
    <plt:partnerLinkType name="Dequeue_plt">
        <plt:role name="Dequeue_role">
            <plt:portType name="tns:Dequeue_ptt"/>
        </plt:role>
    </plt:partnerLinkType>
</definitions>
7.4.1.2 Dequeuing and Enqueuing Object and ADT Payloads

Dequeuing and enqueuing is covered in ADT Queue.

To enqueue or dequeue the entire object as the payload, perform the following steps:

Note:

If you modify an ADT type using evolution commands such as ALTER OBJECT, the AQ Adapter throws an ORA-25215 SQL exception.

The workaround to this exception is to use only CREATE OBJECT (without issuing evolution commands such as ALTER OBJECT) to add attributes to the ADT types.

7.4.1.3 Dequeuing One Column of the Object Payload

This is an example of dequeuing one field or column within an object payload.

To create an Oracle AQ Adapter that dequeues one field in an object, perform the following steps in the Adapter Configuration Wizard Object Payload page:

  1. Select Field within the Object.
  2. Click Browse at the end of the Field Name field.

    The Select Payload Field dialog is displayed.

  3. Select a field that contains the business payload, and then click OK.

    The Adapter Configuration Wizard Object Payload page with Field Name field populated with the field that you selected is displayed, as shown in Figure 7-18.

    Figure 7-18 The Adapter Configuration Wizard Object Payload Page

    Description of Figure 7-18 follows
    Description of "Figure 7-18 The Adapter Configuration Wizard Object Payload Page"
  4. Select Access to non-payload fields also needed, and then click Next.

The following segment of the generated JCA file specifies that one field, in this case the field named PAYLOAD, is dequeued in addition to payload header fields. 

<adapter-config name="Inbound" adapter="AQ Adapter" xmlns="http://platform.integration.oracle/blocks
    /adapter/fw/metadata">
    <connection-factory location="eis/AQ/aqSample" 
       UIConnectionName="Connection1" adapterRef=""/>
  <endpoint-activation portType="Dequeue_ptt" operation="Dequeue">
    <activation-spec    className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
      <property name="QueueName" value="SERVICE_IN_QUEUE"/>
      <property name="ObjectFieldName" value="PAYLOAD"/>
      <property name="PayloadHeaderRequired" value="true"/>
      <property name="SchemaValidation" value="false"/>
    </activation-spec>
  </endpoint-activation>
</adapter-config>
7.4.1.4 Configuring the Enqueue/Dequeue Operation Type

This use case walks you through the procedure for configuring the Enqueue/Dequeue operation type of the Oracle AQ Adapter, which lets the Oracle AQ Adapter put outgoing messages on a queue and expect response messages on a different queue.

This section includes the following topics:

7.4.1.4.1 Creating an Application and a SOA Project

You must create a JDeveloper application to contain the SOA composite. Follow the steps documented in Creating an Application and a SOA Project to create an application, and a SOA project.

7.4.1.4.2 Defining an Oracle AQ Adapter Service

Perform the following steps to create an Oracle AQ Adapter service to put outgoing messages on a queue and expect response messages on a queue:

  1. Drag and drop AQ Adapter from the Service Adapters list to the Exposed Services swim lane in the composite.xml page. The Adapter Configuration Wizard Welcome page is displayed.

  2. Specify a service name, and then click Next. The Service Connection page is displayed.

  3. Click the plus icon to create a database connection. The Create Database Connection page is displayed.

    Note:

    You must connect to the database where Oracle Applications is running.

  4. Enter the following information:

    1. For Create Connection In, choose Application Resources.

    2. In the Connection Name field, specify a unique name for the database connection.

    3. From the Connection Type box, select Oracle (JDBC).

    4. In the UserName field, specify the user name to be authorized for access to the database.

      In this example, type scott.

    5. In the Role field, enter a role, if applicable.

      This must be a specific database role, such as SYSDBA, as defined in the database. This field is optional. In this example, leave the Role field blank.

    6. In the Password field, specify the password to be associated with the specified user name.

      In this example, type tiger.

    7. Select Save Password and Deploy Password.

    8. From the Driver list, select thin.

    9. In the Host Name field, enter a value to identify the computer running the Oracle server.

      Use an IP address or a host name that can be resolved by TCP/IP, for example, myserver. The default value is localhost.

    10. In the JDBC Port field, enter a value to identify the TCP/IP port. The default is 1521.

    11. In the SID field, enter a value for the unique system identifier (SID) of an Oracle database instance.

      The default is XE.

    12. Click Test Connection to determine whether the specified information establishes a connection with the database.

      A Success message is displayed.

    13. Click OK.

      The Connection you created is displayed in the Connection field in the Service Connection page.

      Also, the JNDI Name field is populated after you created the database connection.

      The value specified in the JNDI name must exist in the Oracle AQ Adapter weblogic-ra.xml file to ensure that the adapter runs in managed mode. A default connection instance eis/AQ/aqSample is shipped and can be used as the default value for this field. To use this connection instance, it would still require that a data source is created with the JNDI name jdbc/aqSample.

  5. Click Next.

    The Adapter Configuration Wizard Adapter Interface page is displayed.

  6. In the Adapter Interface page, choose Define from operation and schema (specified later).

  7. Click Next.

    The Operation page is displayed.

  8. Select Enqueue/Dequeue.

  9. Click Next. The Queue Name page is displayed

    Figure 7-19 The Adapter Configuration Wizard Queue Name Page

    Description of Figure 7-19 follows
    Description of "Figure 7-19 The Adapter Configuration Wizard Queue Name Page"

  10. Click Browse to browse for a request queue. The Select Queue dialog is displayed

    Figure 7-20 The Select Queue Dialog

    Description of Figure 7-20 follows
    Description of "Figure 7-20 The Select Queue Dialog"

  11. Select the required queue, and then click OK.

    In this example, select CORRELATION_REQUEST. The Queue Name page is displayed with the Queue Name field populated with CORRELATION_REQUEST, as shown in Figure 7-21.

  12. Repeat Step 12 and 13 for the enqueue queue information.

    The Queue Name page is displayed.

    Figure 7-21 The Adapter Configuration Wizard Queue Name Page

    Description of Figure 7-21 follows
    Description of "Figure 7-21 The Adapter Configuration Wizard Queue Name Page"

  13. Click Next. The Queue Parameters page is displayed

    Figure 7-22 The Adapter Configuration Wizard Queue Parameters Page

    Description of Figure 7-22 follows
    Description of "Figure 7-22 The Adapter Configuration Wizard Queue Parameters Page"

  14. Click Next. The Object Payload page is displayed

    Figure 7-23 The Adapter Configuration Wizard Object Payload Page

    Description of Figure 7-23 follows
    Description of "Figure 7-23 The Adapter Configuration Wizard Object Payload Page"

  15. Select the Business Payload options, Whole Object CORRELATIONREQUEST_TYPE and Whole Object CORRELATIONREPLY_TYPE.

  16. Click Next.

    The Finish screen is displayed. This page shows the path and name of the adapter file that the wizard creates.

  17. Click Finish.

    You have created an AQ Adapter service for synchronous enqueue/dequeue operations.

7.4.1.4.3 Wiring Services and Activities

You must assemble or wire the BPEL process and the Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in RequestReply in the External References area.

    The JDeveloper Composite.xml appears, as shown in Figure 7-24.

    Figure 7-24 The JDeveloper - Composite.xml

    Description of Figure 7-24 follows
    Description of "Figure 7-24 The JDeveloper - Composite.xml"

  2. Click File, Save All.

Add Invoke Activity

  1. Double-click BPELProcess1. The BPELProcess1.bpel page is displayed.

  2. Drag and drop an Invoke activity from the Components window to the design area.

  3. Double-click the Invoke activity. The Invoke dialog is displayed.

  4. Enter a name for the invoke activity in the Name field.

  5. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed, as shown in Figure 7-25.

    Figure 7-25 The Partner Link Chooser Dialog

    Description of Figure 7-25 follows
    Description of "Figure 7-25 The Partner Link Chooser Dialog"

  6. Select RequestReply, and click OK.

  7. Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog, as shown in Figure 7-26. The Create Variable dialog is displayed.

    Figure 7-26 The Invoke Dialog

    Description of Figure 7-26 follows
    Description of "Figure 7-26 The Invoke Dialog"

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

  9. Click OK. The JDeveloper BPELProcess1.bpel page appears, as shown in Figure 7-27.

    Figure 7-27 The JDeveloper - BPELProcess1.bpel Page

    Description of Figure 7-27 follows
    Description of "Figure 7-27 The JDeveloper - BPELProcess1.bpel Page"

Add an Assign Activity

  1. Drag and drop an Assign activity from the Components window to the design area.

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

  3. Enter a name for the Assign activity in the Name field.

  4. Click the Copy Operation tab.

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

  6. Create a copy operation from inputVariable to outputVariable, as shown in Figure 7-28.

    Figure 7-28 The Create Copy Operation Dialog

    Description of Figure 7-28 follows
    Description of "Figure 7-28 The Create Copy Operation Dialog"

  7. Click OK in the Create Copy Operation dialog.

  8. Create another copy operation from inputVariable to Invoke_1_Enqueue_InputVariable, as shown in Figure 7-29.

    Figure 7-29 The Create Copy Operation Dialog

    Description of Figure 7-29 follows
    Description of "Figure 7-29 The Create Copy Operation Dialog"

  9. Click OK in the Create Copy Operation dialog.

  10. Click OK to return to the JDeveloper BPELProcess1.bpel page, as shown in Figure 7-30.

    Figure 7-30 The JDeveloper - BPELProcess1.bpel

    Description of Figure 7-30 follows
    Description of "Figure 7-30 The JDeveloper - BPELProcess1.bpel"

  11. Click File, Save All.

Add a Receive Activity

  1. Drag and drop a Receive activity from the Components window to the design area.
  2. Double-click the Receive activity. The Receive dialog is displayed.
  3. Enter a name for the Receive activity in the Name field.
  4. Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed.
  5. Select RequestReply, and click OK.
  6. Click the Auto-Create Variable icon to the right of the Variable field in the Receive dialog. The Create Variable dialog is displayed.
  7. Select the default variable name and click OK. The Variable field is populated with the default variable name.
  8. Check Create Instance, and click OK. The JDeveloper BPELProcess1.bpel page appears, as shown in Figure 7-31.

    Figure 7-31 The JDeveloper - BPELProcess1.bpel

    Description of Figure 7-31 follows
    Description of "Figure 7-31 The JDeveloper - BPELProcess1.bpel"
7.4.1.4.4 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
7.4.1.4.5 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed 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. Click an instance. The Flow Trace page is displayed.
  3. Click the BPEL component instance. The Audit page is displayed.
  4. Click the Flow-Debug tab to debug the instance.
7.4.1.4.6 Generated WSDL and JCA Files

The following WSDL file is generated for the Enqueue/Dequeue operation:

<?xml version = '1.0' encoding = 'UTF-8'?>
<?binding.jca Inbound_aq.jca?>
<definitions name="Inbound" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/" xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT" xmlns:imp1="http://www.oracle.com/ipdemo">
    <types>
        <schema attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/" xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/" xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT">
            <import namespace="http://xmlns.oracle.com/xdb/SCOTT" schemaLocation="xsd/SCOTT_MAGAZINE_TYPE.xsd"/>
            <import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/" schemaLocation="xsd/aqAdapterInboundHeader.xsd"/>
            <complexType name="HeaderCType">
                <sequence>
                    <element name="QueueHeader" type="hdr:HeaderType"/>
                    <element name="PayloadHeader" type="obj1:MAGAZINE_TYPE"/>
                </sequence>
            </complexType>
            <element name="Header" type="tns:HeaderCType"/>
        </schema>
        <schema xmlns="http://www.w3.org/2001/XMLSchema">
            <import namespace="http://www.oracle.com/ipdemo"   	schemaLocation="xsd/simpleMagazine.xsd"/>
        </schema>
<?xml version = '1.0' encoding = 'UTF-8'?>
   <?binding.jca Inbound_aq.jca?>
    <definitions name="Inbound"
    targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/
     xmlns="http://schemas.xmlsoap.org/wsdl/"
      xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/"
      xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
      xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT"
     xmlns:imp1="http://www.oracle.com/ipdemo">
     <types>
 <schema attributeFormDefault="qualified" elementFormDefault="qualified"
    targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/"
    xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/Inbound/"
xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/"

xmlns:obj1="http://xmlns.oracle.com/xdb/SCOTT">
<import namespace="http://xmlns.oracle.com/xdb/SCOTT"
schemaLocation="xsd/SCOTT_MAGAZINE_TYPE.xsd"/>
<import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/inbound/"

     schemaLocation="xsd/aqAdapterInboundHeader.xsd"/>
<complexType name="HeaderCType">
 <sequence>
<element name="QueueHeader" type="hdr:HeaderType"/>
<element name="PayloadHeader" type="obj1:MAGAZINE_TYPE"/>
 </sequence>
</complexType>

   <element name="Header" type="tns:HeaderCType"/>
</schema>

        <schema xmlns="http://www.w3.org/2001/XMLSchema">
       <import namespace="http://www.oracle.com/ipdemo"
        schemaLocation="xsd/simpleMagazine.xsd"/>
</schema>
</types>
<message name="simpleMagazine_msg">

   <part name="simpleMagazine" element="imp1:simpleMagazine"/>
</message>
     <message name="Header_msg">
     <part name="Header" element="tns:Header"/>
</message>
<portType name="Dequeue_ptt">
    <operation name="Dequeue">
       <input message="tns:simpleMagazine_msg"/>
    </operation>
</portType>
    <plt:partnerLinkType name="Dequeue_plt">
        <plt:role name="Dequeue_role">
            <plt:portType name="tns:Dequeue_ptt"/>
        </plt:role>
   </plt:partnerLinkType>
</definitions>

The following JCA file is generated for the Enqueue/Dequeue operation:

<adapter-config name="RequestReply" adapter="AQ Adapter" wsdlLocation="RequestReply.wsdl" xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  
  <connection-factory location="eis/AQ/aqSample" UIConnectionName="aqSample" adapterRef=""/>
  <endpoint-activation portType="Dequeue_ptt" operation="Dequeue" UITransmissionPrimitive="Request-response">
    <activation-spec className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
      <property name="QueueName" value="CORRELATION_REPLY"/>
    </activation-spec>
  </endpoint-activation>
 
  <endpoint-interaction portType="Enqueue_ptt" operation="Enqueue" UITransmissionPrimitive="Request-response">
    <interaction-spec className="oracle.tip.adapter.aq.outbound.AQEnqueueInteractionSpec">
      <property name="QueueName" value="CORRELATION_REQUEST"/>
    </interaction-spec>
  </endpoint-interaction>
 
</adapter-config>
7.4.1.5 Using Correlation ID for Filtering Messages During Dequeue

Perform the following steps to set up an adapter that dequeues messages with a certain correlation ID only:

The adapter dequeues messages enqueued with that same correlation ID only.

7.4.1.6 Enqueuing and Dequeuing from Multisubscriber Queues

Multisubscriber queues are accessible by multiple users, and sometimes, those users are concerned only with certain types of messages within the queue. For example, you may have a multiuser queue for loan applications where loans below $100,000 can be approved by regular loan-approval staff, whereas loans over $100,000 must be approved by a supervisor. In this case, the BPEL process can use one adapter to enqueue loan applications for big loans for supervisors, and another adapter to enqueue loan applications for smaller loans for regular staff in the same multisubscriber queue.

Specify an adapter that enqueues to a multisubscriber queue, and include queue parameters in the Recipients field.

In Step 11 in Defining an Oracle AQ Adapter Service, specify Bob in the Recipients field.

The following code is from a JCA file generated by defining an Oracle AQ Adapter that enqueues with a recipient list of Bob: 

<adapter-config name="Inbound" adapter="AQ Adapter" xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
    <connection-factory location="eis/AQ/aqSample" UIConnectionName="aqSample" adapterRef=""/>
  <endpoint-interaction portType="Enqueue_ptt" operation="Enqueue">
    <interaction-spec className="oracle.tip.adapter.aq.outbound.AQEnqueueInteractionSpec">
      <property name="QueueName" value="PURCHASEORDER_APPROVAL"/>
      <property name="RecipientList" value="Bob"/>
    </interaction-spec>
  </endpoint-interaction>
</adapter-config>

When dequeuing from a multisubscriber queue, the Queue Parameters window is displayed.

The Consumer field is where you specify the consumer name, or the name of the queue subscriber. This must match the Recipient entry on the enqueue process for the message to be dequeued. When subscribing to a multiconsumer queue, this field is required.

The following code is from a JCA file generated by defining an Oracle AQ Adapter with a consumer name: 

<adapter-config name="Dequer_Bob" adapter="AQ Adapter" xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
    <connection-factory location="eis/AQ/manas" UIConnectionName="aqSample" adapterRef=""/>
  <endpoint-activation portType="Dequeue_ptt" operation="Dequeue">
    <activation-spec className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
      <property name="QueueName" value="PURCHASEORDER_APPROVAL"/>
      <property name="Consumer" value="Bob"/>
      <property name="SchemaValidation" value="false"/>
    </activation-spec>
  </endpoint-activation>
</adapter-config>
7.4.1.7 Using Message Selector Rule for Filtering Messages During Dequeue

The following is an example for creating rule-based subscriptions to a multiconsumer queue. In this example, two subscribers are created to subscribe to messages in the same queue. In this scenario, messages are filtered by the subscriber's subscription rule.

  1. Create a service type, multiconsumer queue table, queue, and start the queue using a SQL command. This example connects to the Oracle database using the same schema that will be used by the SOA composite(s) to be deployed:
    create type SERVICE_TYPE as OBJECT (
        MSG_ID             VARCHAR2(128),
        INREPLYTO_MSG_ID   VARCHAR2(128),
        FROM_PARTY         VARCHAR2(512),
        TO_PARTY           VARCHAR2(512),
        ACTION_NAME        VARCHAR2(512),
        DOCTYPE_NAME       VARCHAR2(512),
        DOCTYPE_REVISION   VARCHAR2(512),
        MSG_TYPE           INT,
        PAYLOAD            CLOB
)
/

BEGIN
   DBMS_AQADM.CREATE_QUEUE_TABLE (queue_table => 'service_in_table', queue_payload_type => 'service_type', multiple_consumers => TRUE);
END;
/
begin
   dbms_aqadm.create_queue('service_in_queue', 'service_in_table');  
   dbms_aqadm.start_queue('service_in_queue');
end;
/
  2. Use the JDeveloper AQ Adapter Wizard to create an AQ Adapter consumer_1 with a rule. The generated AQ Adapter JCA file will look like this after it is created:
    <adapter-config name="aqService" adapter="aq"
      wsdlLocation="../WSDLs/aqService.wsdl"
      xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  
  <connection-factory UIConnectionName="Oracle" location="eis/AQ/aqSample"/>
  <endpoint-activation portType="Dequeue_ptt" operation="Dequeue">
    <activation-spec className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
      <property name="MessageSelectorRule" value="tab.user_data.MSG_ID='reply123'"/>
      <property name="Consumer" value="consumer_1"/>
      <property name="QueueName" value="SERVICE_IN_QUEUE"/>
      <property name="SchemaValidation" value="false"/>
    </activation-spec>
  </endpoint-activation>

</adapter-config>
  3. Use the JDeveloper AQ Adapter Wizard to create an AQ Adapter consumer_2 with a rule. The generated AQ Adapter JCA file will look like this after it is created:
    <adapter-config name="aqService" adapter="aq"
      wsdlLocation="../WSDLs/aqService.wsdl"
      xmlns="http://platform.integration.oracle/blocks/adapter/fw/metadata">
  
  <connection-factory UIConnectionName="Oracle" location="eis/AQ/aqSample"/>
  <endpoint-activation portType="Dequeue_ptt" operation="Dequeue">
    <activation-spec className="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec">
      <property name="MessageSelectorRule" value="tab.user_data.MSG_ID='reply124'"/>
      <property name="Consumer" value="consumer_2"/>
      <property name="QueueName" value="SERVICE_IN_QUEUE"/>
      <property name="SchemaValidation" value="false"/>
    </activation-spec>
  </endpoint-activation>

</adapter-config>

    Note that the consumer name must be different each time you create a new subscriber. For consumer_1, it only receives messages with MSG_ID='reply123'. For consumer_2, it only receives messages with MSG_ID='reply124'. Since we are accessing the MSG_ID field of the message body in the rule, we must prepend the tab.user_data. prefix to the MSG_ID field.

  4. Subscribers are registered during SOA composite deployment. You can find the subscribers after the SOA composite is deployed using the SQL command:
    select * from AQ$service_in_table_r;

    The general form of the command is:

    select * from user_schema_name.AQ$queue_table_name_r;

    where user_schema_name and queue_table_name are the appropriate schema name and table name. If the schema name is omitted, the current schema name used to connect to the database is used.

    This command returns a result similar to:

    SERVICE_IN_QUEUE CONSUMER_1 0 tab.user_data.MSG_ID='reply123'
SERVICE_IN_QUEUE$21
SERVICE_IN_QUEUE CONSUMER_2 0 tab.user_data.MSG_ID='reply124'
SERVICE_IN_QUEUE$22

  5. Enqueue messages.

    Message for consumer_1: 

    DECLARE
  enqueue_options     dbms_aq.enqueue_options_t;
  message_properties  dbms_aq.message_properties_t;
  msgid               RAW(16);
  qname               VARCHAR2(100);
  service             service_type;

BEGIN
  qname := 'service_in_queue';
  service := service_type('reply123', 'request124', 'seller', 'buyer',
'ack','b2bDoc', '1.1', 1, '<?xml version="1.0" encoding="UTF-8"?><SERVICE
xmlns="http://www.oracle.com/service/contract"><DESCRIPTION>ADT with CLOB
payload testcase</DESCRIPTION><RATE>100.00</RATE></SERVICE>');

      dbms_aq.enqueue(queue_name         => qname,          
                      enqueue_options    => enqueue_options,      
                      message_properties => message_properties,    
                      payload            => service,              
                      msgid              => msgid);
  commit;
END;
/

    Message for consumer_2: 

    DECLARE
  enqueue_options     dbms_aq.enqueue_options_t;
  message_properties  dbms_aq.message_properties_t;
  msgid               RAW(16);
  qname               VARCHAR2(100);
  service             service_type;

BEGIN
  qname := 'service_in_queue';
  service := service_type('reply124', 'request124', 'seller', 'buyer',
'ack','b2bDoc', '1.1', 1, '<?xml version="1.0" encoding="UTF-8"?><SERVICE
xmlns="http://www.oracle.com/service/contract"><DESCRIPTION>ADT with CLOB
payload testcase</DESCRIPTION><RATE>100.00</RATE></SERVICE>');

      dbms_aq.enqueue(queue_name         => qname,          
                      enqueue_options    => enqueue_options,      
                      message_properties => message_properties,    
                      payload            => service,              
                      msgid              => msgid);
  commit;
END;
/
  6. If you want to remove everything you have created, perform the following steps.
    1. To stop and drop a queue and queue table:
      BEGIN
  DBMS_AQADM.stop_queue('service_in_queue');
  DBMS_AQADM.drop_queue('service_in_queue');
  dbms_aqadm.drop_queue_table('service_in_table');

END;
/
    2. To remove the type you have created:
      drop type SERVICE_TYPE;
    3. To remove a subscriber:
      DECLARE
   subscriber       sys.aq$_agent;
BEGIN
   subscriber := sys.aq$_agent ('consumer_1', null, null);
   DBMS_AQADM.REMOVE_SUBSCRIBER(
      queue_name => 'service_in_queue',
      subscriber => subscriber);
END;
/
For more details on how to manage Oracle AQ, see the following chapters in Transactional Event Queues and Advanced Queuing User's Guide:

7.4.2 Oracle AQ Adapter ADT Queue

In this sample, the business process receives a message from the AQ Adapter, copies the payload to an outbound message, and invokes the AQ Adapter with the outbound message.The queues involved are ADT queues. In this scenario, where the user has chosen to use whole ADT as the payload, the AQ Adapter Wizard has generated the schema in SCOTT_CUSTOMER_TYPE.xsd, according to the queue structure. During runtime, an XML file that matches the schema is created by the adapter for each message.

This section includes the following topics:

7.4.2.1 Prerequisites

You must have access to a database with the SCOTT schema.

To perform this use case, you must first create the following files and execute them in the following order:

  • setup_user.sql

  • create_type_customer.sql

  • create_queues.sql

  • enqueue_customer.sql

  • dequeue_customer.sql

Contents of setup_user.sql

grant connect to scott;
grant aq_administrator_role to scott;

Contents of create_type_customer.sql

create or replace type suite_arr as varray (5) of number;
/
create or replace type street_info as object (    street_name varchar2(100),    street_num  number,    suites      suite_arr );
/
create or replace type address_type as object (  street    street_info,  city      varchar2(100),  zip       number,  state     varchar2(2),  country   varchar2(100) );
/
create or replace type phone as object (  country_code  number,  area_code     number,  dial          number,  last_dialed   date );
/
create or replace type phone_arr as varray (10) of phone;
/
create or replace type contact_info as object (  phones  phone_arr,  email  varchar2(100),  web_address  varchar2(256) );
/
create or replace type customer_type as object (      name   varchar2(100),      location  address_type,  sex char, age float,height DOUBLE PRECISION ,mark decimal  ,  contacts  contact_info,      contract  CLOB,tstamp TIMESTAMP );
/

Contents of create_queues.sql

begin 
dbms_aqadm.create_queue_table('customer_in_table', 'customer_type');      dbms_aqadm.create_queue('customer_in_queue', 'customer_in_table');  
dbms_aqadm.start_queue('customer_in_queue'); 
dbms_aqadm.create_queue_table('customer_out_table', 'customer_type');      dbms_aqadm.create_queue('customer_out_queue', 'customer_out_table'); 
dbms_aqadm.start_queue('customer_out_queue'); 
end;
/

Contents of enqueue_customer.sql

DECLARE
  qname               VARCHAR2(100);
  enqueue_options     dbms_aq.enqueue_options_t;
  message_properties  dbms_aq.message_properties_t;
  msgid               RAW(16);
  contract_msg        VARCHAR2(1000);
  suites suite_arr;
  str street_info;
  addr address_type;
  ph1 phone;
  ph2 phone;
  phs phone_arr;
  ci contact_info;
  cus customer_type;
BEGIN
  qname := 'customer_in_queue';
  suites := suite_arr(800, 900);
  str := street_info('Oracle Parkway', 500, suites);
  addr := address_type(str, 'Redwood Shores',94065, 'CA', 'USA');
  ph1 := phone(1, 503, 5253190,to_date ('2004/04/02', 'yyyy/mm/dd'));
  ph2 := phone(1, 503, 3297507,to_date ('040905', 'MMDDYY'));
  phs := phone_arr(ph1,ph2);
  ci  := contact_info(phs, 'shashi@oracle.com', 'http://oracle.com');
  cus := customer_type('Shashi', addr,'M',27.5,5.90,86.2, ci, 'my contract 12345678','20-JUL-05 04.11.58.000000 PM');  
  dbms_aq.enqueue(queue_name         => qname,           
    enqueue_options    => enqueue_options,       
    message_properties => message_properties,     
    payload            => cus,               
    msgid              => msgid);
commit;
END;
/

Contents of dequeue_customer.sql

set serveroutput on;
DECLARE
   enqueue_options     dbms_aq.enqueue_options_t;
   dequeue_options     dbms_aq.dequeue_options_t;
   message_properties  dbms_aq.message_properties_t;
   message_handle      RAW(16);
   msg_varchar         varchar2(4000);
   customer1           customer_type;
   tempstr             varchar2(200);
BEGIN
   dequeue_options.wait:=180;
   DBMS_AQ.DEQUEUE(
      queue_name          =>     'CUSTOMER_OUT_QUEUE',
      dequeue_options      =>    dequeue_options,
      message_properties  =>     message_properties,
      payload             =>     customer1,
      msgid               =>     message_handle);
   tempstr:=to_char(customer1.tstamp,'YYYY/MM/DD HH:MI:SS');
   dbms_output.put_line('customer.name = "' || customer1.NAME || '"');
   dbms_output.put_line('customer.location.street.street_name = "' || customer1.LOCATION.STREET.STREET_NAME || '"');
   dbms_output.put_line('customer.location.street.street_num = "' || customer1.LOCATION.STREET.STREET_NUM|| '"');
   dbms_output.put_line('customer1.LOCATION.CITY = "' || customer1.LOCATION.CITY|| '"');
   dbms_output.put_line('customer1.LOCATION.ZIP = "' || customer1.LOCATION.ZIP|| '"');
   dbms_output.put_line('customer1.LOCATION.STATE = "' || customer1.LOCATION.STATE|| '"');
   dbms_output.put_line('customer1.LOCATION.COUNTRY = "' || customer1.LOCATION.COUNTRY|| '"');
   dbms_output.put_line('customer.location.country = "' || customer1.location.country  || '"');
   dbms_output.put_line('customer.contract = "' || customer1.CONTRACT|| '"');
   dbms_output.put_line('customer.name = "' || customer1.NAME || '"');
   dbms_output.put_line('customer.location.street.street_name = "' || customer1.LOCATION.STREET.STREET_NAME || '"');
   dbms_output.put_line('customer.location.street.street_num = "' || customer1.LOCATION.STREET.STREET_NUM|| '"');
   dbms_output.put_line('customer.location.country = "' || customer1.location.country  || '"');
   dbms_output.put_line('customer.contract = "' || customer1.CONTRACT|| '"');
   dbms_output.put_line('customer1.SEX = "' || customer1.SEX|| '"');
   dbms_output.put_line('customer1.AGE = "' || customer1.AGE|| '"');
   dbms_output.put_line('customer1.HEIGHT = "' || customer1.HEIGHT|| '"');
   dbms_output.put_line('customer1.MARK = "' || customer1.MARK|| '"');
   dbms_output.put_line('customer1.contract = "' || customer1.CONTRACT|| '"');
   dbms_output.put_line('customer1.CONTACTS.EMAIL = "' || customer1.CONTACTS.EMAIL|| '"');
   dbms_output.put_line('customer1.CONTACTS.WEB_ADDRESS = "' || customer1.CONTACTS.WEB_ADDRESS|| '"');
   dbms_output.put_line('customer1.LOCATION.STREET.SUITES[1]  = "' || customer1.LOCATION.STREET.SUITES(1) || '"');
   dbms_output.put_line('customer1.LOCATION.STREET.SUITES[2]  = "' || customer1.LOCATION.STREET.SUITES(2) || '"');
   dbms_output.put_line('customer1.CONTACTS.PHONES(1).country_codE = "' || customer1.CONTACTS.PHONES(1).country_code|| '"');
   dbms_output.put_line('customer1.CONTACTS.PHONES(1).area_code = "' || customer1.CONTACTS.PHONES(1).area_code || '"');
   dbms_output.put_line('customer1.CONTACTS.PHONES(1).dial = "' || customer1.CONTACTS.PHONES(1).dial || '"');
   dbms_output.put_line('customer1.CONTACTS.PHONES(1).last_dialed = "' || customer1.CONTACTS.PHONES(1).last_dialed || '"');
   COMMIT;
END;
/
7.4.2.2 Creating an Application and a SOA Project

You must create an JDeveloper application to contain the SOA composite. To create an application and a SOA project, perform the following steps:

  1. In the Application Navigator of JDeveloper, click New Application.

    The Create Generic Application Name your application page is displayed.

  2. Enter ADT in the Application Name field, and click Next.

    The Create Generic Application Name your project page is displayed.

  3. Enter ADT in the Project Name field.
  4. In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.
  5. Click Next.

    The Create Generic Application Configure SOA settings page is displayed.

  6. Select Composite With Mediator from the Composite Template list, and then click Finish.

    You have created a new application and a SOA project.

    The Create Mediator page is displayed, as shown in Figure 7-32.

    Figure 7-32 The Create Mediator Page

    Description of Figure 7-32 follows
    Description of "Figure 7-32 The Create Mediator Page"
  7. Enter a name for the Mediator component in the Name field. In this example, retain the default name Mediator1.
  8. Select Define Interface Later in the Template list, and then click OK.

    You have created a Mediator component.

7.4.2.3 Creating an Inbound Oracle AQ Adapter

The following are the steps to create an inbound Oracle AQ Adapter service:

  1. Drag and drop AQ Adapter from the Components window into the Exposed Services swim lane. The Adapter Configuration Wizard Welcome page is displayed.

  2. Enter the Service Name and click Next. The Service Connection page is displayed.

  3. A database connection is required to configure an Oracle AQ Adapter. You can either create a new connection or select an existing database connection.

  4. Click the Create a new database connection icon to create a database connection. The Create Database Connection page is displayed.

  5. Create a database connection, as described in Step 4 in Defining an Oracle AQ Adapter Service.

  6. Click OK to complete the process of creating a new database connection. The Service Connection page is displayed, providing a summary of the database connection.

  7. Click Next. The Adapter Interface page is displayed.

  8. In the Adapter Interface page, select Define from operation and schema (specified later).

  9. Click Next. The Operation page is displayed.

  10. Select Dequeue.

  11. Accept the default operation name, and then click Next.

    The Queue Name page is displayed.

  12. Select a database schema from the list, or click Browse to browse for the schema. In this example, click Browse.

    The Select Queue dialog is displayed.

  13. In the Select Queue dialog, perform the following steps:

    1. For Queue Type, select all types.

    2. For Database Schema, select Scott.

    3. Retain the default values for the other fields.

    4. Under Queues, select CUSTOMER_IN_QUEUE.

    Figure 7-33 shows the Select Queue dialog.

    Figure 7-33 Selecting a Queue for the Inbound Operation

    Description of Figure 7-33 follows
    Description of "Figure 7-33 Selecting a Queue for the Inbound Operation"

  14. Click OK.

    The Queue Name dialog with all the fields populated is displayed.

    Figure 7-34 The Queue Name Page

    Description of Figure 7-34 follows
    Description of "Figure 7-34 The Queue Name Page"

  15. Click Next. The Queue Parameters page is displayed.

  16. In the Queue Parameters page, leave the fields empty, and then click Next. The Object Payload page is displayed.

  17. Select a business payload: either the entire object, or just one field within the object.

    In this example, select Whole Object CUSTOMER_TYPE.

  18. Click Next. The JCA Endpoint Properties page is displayed.

    The JCA Endpoint Properties screen appears if you have selected the Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.

  19. Click Next. The Finish Page is displayed and it shows the path and name of the adapter file that the wizard creates.

  20. Click Finish.

    You have defined an inbound Oracle AQ Adapter.

7.4.2.4 Creating an Outbound Oracle AQ Adapter

The following are the steps to create an outbound Oracle AQ Adapter service:

  1. Drag and drop AQ Adapter from the Service Adapters list in the Components window to the Exposed Services swim lane in the composite.xml page. The Adapter Configuration Wizard is displayed.

  2. In the Service Name field, enter enqueue and click Next.

    The Service Connection page is displayed.

  3. For Connection, select MyConnection, and then click Next.

    The Adapter Interface page is displayed.

  4. In the Adapter Interface page, select Define from operation and schema (specified later), and then click Next.

    The Operation page is displayed.

  5. In the Operation page, select Enqueue, and accept the default operation name.

  6. Click Next.

    The Queue Name page is displayed.

  7. In the Queue Name page, select a database schema from the list, or click Browse to browse for the schema. In this example, click Browse.

    The Select Queue dialog is displayed.

  8. In the Select Queue dialog, perform the following steps:

    1. For Queue Type, select all types.

    2. For Database Schema, select Scott.

    3. Retain the default values for the other fields.

    4. Under Queues, select CUSTOMER_OUT_QUEUE.

    Figure 7-35 Selecting a Queue for the Outbound Operation

    Description of Figure 7-35 follows
    Description of "Figure 7-35 Selecting a Queue for the Outbound Operation"

  9. Click OK.

    The Queue Name page with all the fields populated is displayed.

    Figure 7-36 The Queue Name Page

    Description of Figure 7-36 follows
    Description of "Figure 7-36 The Queue Name Page"

  10. Click Next.

    The Queue Parameters page is displayed.

  11. In the Queue Parameters page, leave the fields empty, and then click Next.

    The Object Payload page is displayed.

  12. Select a business payload, either the entire object, or just one field within the object. In this example, select Whole Object CUSTOMER_TYPE.

  13. Click Next.

    The Finish screen is displayed. This page shows the path and name of the adapter file that the wizard creates.

  14. In the Finish window, click Finish.

    You have defined an outbound Oracle AQ Adapter.

7.4.2.5 Wiring Services and Activities

You must assemble or wire the three components that you have created: Inbound adapter service, Mediator component, and Outbound adapter reference. Perform the following steps to wire the components:

  1. Drag the small triangle in the Inbound adapter in the Exposed Services area to the drop zone that appears as a green triangle in the Mediator component in the Components area.
  2. Drag the small triangle in the Mediator component in the Components area to the drop zone that appears as a green triangle in the Outbound adapter in the External References area.

    The JDeveloper composite.xml is displayed, as shown in Figure 7-37.

    Figure 7-37 The JDeveloper composite.xml

    Description of Figure 7-37 follows
    Description of "Figure 7-37 The JDeveloper composite.xml"
  3. Click File, Save All.
7.4.2.6 Configuring Routing Service

The following are the steps to configure the routing service:

  1. Double-click Mediator1.

    The Mediator1.mplan window is displayed.

  2. Click the Select an existing mapper file or create a new one... icon that is displayed at the end of the Transform Using field.

    The Request Transformation Map dialog is displayed, as shown in Figure 7-38.

    Figure 7-38 The Request Transformation Map Dialog

    Description of Figure 7-38 follows
    Description of "Figure 7-38 The Request Transformation Map Dialog"
  3. Select Create New Mapper File, and then click OK.

    The Transformation window is displayed, as shown in Figure 7-39.

    Figure 7-39 The Transformation Window

    Description of Figure 7-39 follows
    Description of "Figure 7-39 The Transformation Window"
  4. Select the source root elements on the left-hand side of the mapper and drag them over to the destination root elements on the right-hand side to set the map preferences.

    The Auto Map Preferences dialog is displayed, as shown in Figure 7-40.

    Figure 7-40 The Auto Map Preferences Dialog

    Description of Figure 7-40 follows
    Description of "Figure 7-40 The Auto Map Preferences Dialog"
  5. Click OK.

    The middle pane of the application window appears as shown in Figure 7-41.

    Figure 7-41 The Application Window After Setting the Map Preferences

    Description of Figure 7-41 follows
    Description of "Figure 7-41 The Application Window After Setting the Map Preferences"
  6. Save and close the tab for the mapper.
  7. Save and close the tab for the routing service.
7.4.2.7 Configuring the Data Sources in the Oracle WebLogic Server Administration Console
  1. Navigate to http://servername:portnumber/console.
  2. Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.

    The Home page of the Oracle WebLogic Server Administration Console is displayed, as shown in Figure 7-42.

    Figure 7-42 Oracle WebLogic Server Administration Console Home Page

    Description of Figure 7-42 follows
    Description of "Figure 7-42 Oracle WebLogic Server Administration Console Home Page"
  3. Under Domain Structure, select Services, JBDC, and then click DataSources.

    The Summary of JDBC Data Sources page is displayed, as shown Figure 7-43.

    Figure 7-43 The Summary of JDBC Data Sources Page

    Description of Figure 7-43 follows
    Description of "Figure 7-43 The Summary of JDBC Data Sources Page"
  4. Click New. The Create a New JDBC Data Source page is displayed.
  5. Enter the values for the properties to be used to identify your new JDBC data source, as shown in Figure 7-44.

    Figure 7-44 The Create a New JDBC Data Source Page

    Description of Figure 7-44 follows
    Description of "Figure 7-44 The Create a New JDBC Data Source Page"
  6. Click Next. The Create a New JDBC Data Source Transaction Options page is displayed, as shown in Figure 7-45.

    Figure 7-45 The Create a New JDBC Data Source Transaction Options Page

    Description of Figure 7-45 follows
    Description of "Figure 7-45 The Create a New JDBC Data Source Transaction Options Page"
  7. Click Next. The Create a New JDBC Data Source Connection Properties page is displayed, as shown in Figure 7-46.

    Figure 7-46 The Create a New JDBC Data Source Connection Properties Page

    Description of Figure 7-46 follows
    Description of "Figure 7-46 The Create a New JDBC Data Source Connection Properties Page"
  8. Enter the connection properties in the Connection Properties page.
  9. Click Next. The Create a New JDBC Data Source Test Database Connection page is displayed, as shown in Figure 7-47.

    Figure 7-47 The Create a New JDBC Data Source Test Database Connection Page

    Description of Figure 7-47 follows
    Description of "Figure 7-47 The Create a New JDBC Data Source Test Database Connection Page"
  10. Click Test Configuration to test the database availability and the connection properties you provided. A message stating that the connection test succeeded is displayed at the top of the Create a New JDBC Data Source Test Database Connection page.
  11. Click Next. The Create a New JDBC Data Source Select Targets page is displayed, as shown in Figure 7-48.

    Figure 7-48 The Create a New JDBC Data Source Select Targets Page

    Description of Figure 7-48 follows
    Description of "Figure 7-48 The Create a New JDBC Data Source Select Targets Page"
  12. Select a target, and then click Finish.

    The Summary of JDBC Data Sources page is displayed, as shown in Figure 7-49. This page summarizes the JDBC data source objects that have been created in this domain. The data source that you created appears in this list.

    Figure 7-49 The Summary of JDBC Data Sources Page

    Description of Figure 7-49 follows
    Description of "Figure 7-49 The Summary of JDBC Data Sources Page"
  13. Close the Oracle WebLogic Server Administration Console.
7.4.2.8 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
7.4.2.9 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed 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. In the Last 5 Instances pane, there is an entry of a new instance. This new instance is the instance that was triggered when you enqueued a message.
  3. Click an instance. The Flow Trace page is displayed.
  4. Click the Mediator1 component instance. The Audit page is displayed.
  5. Click the Flow-Debug tab to debug the instance.

7.4.3 Oracle AQ Adapter RAW Queue

This use case demonstrates how to use Oracle AQ Adapter to dequeue from and enqueue to an AQ RAW queue.

This section includes the following topics:

7.4.3.1 Prerequisites

You must have access to a database with the SCOTT schema.

To perform this use case, you must first create the following files and execute the .sql files in the following order:

  • setup_user.sql

  • create_queues.sql

  • enqueue_raw.sql

  • dequeue_raw.sql

  • emp.xsd

Contents of setup_user.sql

grant connect, resource to scott;
grant aq_administrator_role to scott;

Contents of create_queues.sql

begin  
   DBMS_AQADM.CREATE_QUEUE_TABLE ( queue_table => 'RAW_IN_QUEUE_TABLE', queue_payload_type => 'RAW');  
   DBMS_AQADM.CREATE_QUEUE ( queue_name => 'RAW_IN_QUEUE', queue_table => 'RAW_IN_QUEUE_TABLE');
   DBMS_AQADM.START_QUEUE ( queue_name => 'RAW_IN_QUEUE');
   DBMS_AQADM.CREATE_QUEUE_TABLE ( queue_table => 'RAW_OUT_QUEUE_TABLE', queue_payload_type => 'RAW');
   DBMS_AQADM.CREATE_QUEUE ( queue_name  => 'RAW_OUT_QUEUE', queue_table => 'RAW_OUT_QUEUE_TABLE');  
   DBMS_AQADM.START_QUEUE ( queue_name => 'RAW_OUT_QUEUE');
end;
/

Contents of enqueue_raw.sql

DECLARE
   enqueue_options     dbms_aq.enqueue_options_t;
   message_properties  dbms_aq.message_properties_t;
   message_handle      RAW(16);
   msg_in              raw(2000);
   msg_varchar         varchar2(4000);
BEGIN
   msg_varchar := '<AqRaw_End2End xmlns="http://www.oracle.com/aqSample/Raw">
<EMPS>
  <ID>34</ID>
  <EMP>
    <YEARS>21</YEARS>
    <NAME>john doe</NAME>
  </EMP>
</EMPS></AqRaw_End2End>';
   msg_in := utl_raw.cast_to_raw(msg_varchar);
   dbms_aq.enqueue(queue_name => 'raw_in_queue', enqueue_options      => enqueue_options,    message_properties   => message_properties,      payload              => msg_in,    msgid                => message_handle);
commit;
END;
/

Contents of dequeue_raw.sql

DECLARE
   enqueue_options     dbms_aq.enqueue_options_t;
   dequeue_options     dbms_aq.dequeue_options_t;
   message_properties  dbms_aq.message_properties_t;
   message_handle      RAW(16);
   msg_in              raw(2000);
   msg_out             raw(2000);
   msg_varchar         varchar2(4000);
BEGIN
   dequeue_options.wait:=180;
   DBMS_AQ.DEQUEUE(
      queue_name          =>     'RAW_OUT_QUEUE',
      dequeue_options      =>    dequeue_options,
      message_properties  =>     message_properties,
      payload             =>     msg_out,
      msgid               =>     message_handle);
   msg_varchar := utl_raw.cast_to_varchar2(msg_out);
   dbms_output.put_line('Payload = "' || msg_varchar || '"');
   insert into temp_raw values(msg_varchar);
   COMMIT;
END;
/

Contents of emp.xsd

<?xml version= '1.0' encoding= 'UTF-8' ?>
<schema attributeFormDefault="qualified" elementFormDefault="qualified" targetNamespace="http://www.oracle.com/aqSample/Raw"
     xmlns="http://www.w3.org/2001/XMLSchema" xmlns:AQAPP="http://www.oracle.com/aqSample/Raw">
    <complexType name="EMPS">
        <sequence>
            <element minOccurs="0" name="ID" type="double"/>
            <element minOccurs="0" name="EMP" type="AQAPP:EMP_TYPE"/>
        </sequence>
    </complexType>
    <complexType name="EMP_TYPE">
        <sequence>
            <element minOccurs="0" name="YEARS" type="double"/>
            <element minOccurs="0" name="NAME" type="string"/>
        </sequence>
    </complexType>
    <element name="AqRaw_End2End">
        <complexType>
            <sequence>
                <element name="EMPS" type="AQAPP:EMPS"/>
            </sequence>
        </complexType>
    </element>
</schema>
7.4.3.2 Creating an Application and a SOA Project

You must create an JDeveloper application to contain the SOA composite. To create an application and a SOA project, perform the following steps:

  1. Open JDeveloper.
  2. In the Application Navigator, click New Application.

    The Create Generic Application Name your Application page is displayed.

  3. Enter Rawqueue in the Application Name field.
  4. In the Application Template list, select Generic Application.
  5. Click Next.

    The Create Generic Application Name your project page is displayed.

  6. In the Project Name field, enter a descriptive name. For example, Raw.
  7. In the Available list in the Project Technologies tab, double-click SOA to move it to the Selected list.
  8. Click Next.

    The Create Generic Application Configure SOA settings page is displayed.

  9. Select Composite With BPEL from the Composite Template list, and then click Finish.

    You have created a new application and a SOA project. This automatically creates a SOA composite.

    The Create BPEL Process page is displayed.

  10. Enter a name for the BPEL process in the Name field. For example, BPELRawqueue.
  11. Select Define Service Later in the Template list, and then click OK.

    The Rawqueue application and the Raw project appear in the design area.

  12. Copy the emp.xsd file that you created (see Prerequisites) to the xsd directory in your project.
7.4.3.3 Creating an Inbound Adapter Service

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

  1. Drag and drop AQ Adapter from the Components window into the Exposed Services swim lane.
    The Adapter Configuration Wizard Welcome page is displayed.
  2. Click Next.

    The Service Name page is displayed.

  3. In the Service Name field, enter Raw-Dequeuer, and then click Next.

    The Service Connection page is displayed.

  4. Create a database connection, as described in Step 4 in Defining an Oracle AQ Adapter Service.
  5. Click Next.

    The Adapter Interface page is displayed.

  6. In the Adapter Interface page, select Define from operation and schema (specified later), and then click Next.

    The Operation page is displayed.

  7. In the Operation page, select Dequeue.

    Figure 7-50 The Adapter Configuration Wizard Operation Page

    Description of Figure 7-50 follows
    Description of "Figure 7-50 The Adapter Configuration Wizard Operation Page"
  8. Accept the default operation name, and click Next.

    The Queue Name page is displayed.

  9. In the Queue Name page, select SCOTT as Database Schema and RAW_IN_QUEUE as Queue Name.

    Figure 7-51 The Adapter Configuration Wizard Queue Name Page

    Description of Figure 7-51 follows
    Description of "Figure 7-51 The Adapter Configuration Wizard Queue Name Page"
  10. Click Next.

    The Queue Parameters page is displayed.

  11. Enter the Correlation ID and a Dequeue condition, and then click Next.

    The Messages page is displayed.

  12. Click Browse at the end of the URL field.

    The Type Chooser dialog is displayed.

  13. Select Project Schema Files, emp.xsd, and then AQRaw_End2End.

    Figure 7-52 The Type Chooser Dialog

    Description of Figure 7-52 follows
    Description of "Figure 7-52 The Type Chooser Dialog"
  14. Click OK.

    The emp.xsd schema file is displayed in the URL field in the Message dialog.

    Figure 7-53 The Adapter Configuration Wizard Messages Page

    Description of Figure 7-53 follows
    Description of "Figure 7-53 The Adapter Configuration Wizard Messages Page"
  15. Click Next.
    The JCA Endpoint Properties screen appears for inbound if you have selected the Reference Configuration option. For more information, see JCA Endpoint Properties in the Adapter Configuration Wizard.
  16. Click Finish. You have configured the Oracle AQ Adapter service, and the composite.xml page is displayed.

    Figure 7-54 The JDeveloper Window Composite.xml Page

    Description of Figure 7-54 follows
    Description of "Figure 7-54 The JDeveloper Window Composite.xml Page"
7.4.3.4 Creating an Outbound Adapter Service

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

  1. Drag and drop AQ Adapter from the Service Adapters list in the Components window to the Exposed Services swim lane in the composite.xml page.

    The Adapter Configuration Wizard Welcome page is displayed.

  2. Enter Raw-Enqueuer in the Service Name field, and click OK.

    The Service Connection page is displayed.

  3. Select XA Datasource, and then click Next.

    The Operation page is displayed.

  4. Select Enqueue.
  5. Accept the default operation name, and click Next.

    The Queue Name page is displayed.

  6. Select SCOTT as Database Schema and RAW_OUT_QUEUE as Queue Name.

    Figure 7-55 The Adapter Configuration Wizard Queue Name Page

    Description of Figure 7-55 follows
    Description of "Figure 7-55 The Adapter Configuration Wizard Queue Name Page"
  7. Click Next.

    The Queue Parameters page is displayed.

  8. Enter the Correlation ID, and then click Next.

    The Messages page is displayed.

  9. Click Browse for schema file at the end of the URL field.

    The Type Chooser dialog is displayed.

  10. Select Project Schema Files, emp.xsd, and AQRaw_End2End, as shown in Figure 7-52.
  11. Click Next.

    The emp.xsd schema file is displayed in the URL field in the Message dialog, as shown in Figure 7-53.

  12. Click Next.

    The Finish page is displayed.

  13. Click Finish.

    You have configured the Oracle AQ Adapter service, and the composite.xml page is displayed.

    Figure 7-56 The JDeveloper Window Composite.xml Page

    Description of Figure 7-56 follows
    Description of "Figure 7-56 The JDeveloper Window Composite.xml Page"
7.4.3.5 Wiring Services and Activities

You must 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:

  1. Drag the small triangle in the Raw-Dequeuer 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 Raw-Enqueuer in the External References area.

    Similarly, drag the small triangle in the BPEL process in the Components area to the drop zone in OutboundService in the External References.

    The JDeveloper composite.xml file is displayed, as shown in Figure 7-57.

    Figure 7-57 The JDeveloper- Composite.xml

    Description of Figure 7-57 follows
    Description of "Figure 7-57 The JDeveloper- Composite.xml"
  3. Click File, Save All.
  4. Double-click BPELRawqueue.

    The BPELRawqueue.bpel page is displayed.

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

    The JDeveloper BPELRawqueue.bpel page is displayed, as shown in Figure 7-58.

    Figure 7-58 The BPELRawqueue.bpel Page

    Description of Figure 7-58 follows
    Description of "Figure 7-58 The BPELRawqueue.bpel Page"
  6. Double-click the Receive activity.

    The Receive dialog is displayed.

  7. Click the Browse Partner Links icon at the end of the Partner Link field.

    The Partner Link Chooser dialog is displayed.

  8. Select Raw-Dequeuer, and then click OK.

    The Receive dialog is displayed with the Partner Link field populated with the value Raw-Dequeuer.

  9. Click the Auto-Create Variable icon that is displayed at the end of the Variable field.

    The Create Variable dialog is displayed.

  10. Accept the default values, and click OK.
  11. Check the Create Instance box, as shown in Figure 7-59, and click OK.

    Figure 7-59 The Receive Dialog

    Description of Figure 7-59 follows
    Description of "Figure 7-59 The Receive Dialog"
  12. Double-click the Invoke activity.

    The Invoke dialog is displayed.

  13. Click the Browse Partner Links icon at the end of the Partner Link field.

    The Partner Link Chooser dialog is displayed.

  14. Select Raw-Enqueuer, and then click OK.

    The Invoke dialog is displayed with the Partner Link field populated with the value Raw-Enqueuer.

  15. Click the Automatically Create Input Variable icon that is displayed at the end of the Input Variable field.
  16. Accept the default values, and click OK.

    The Invoke dialog is displayed, as shown in Figure 7-60.

    Figure 7-60 The Invoke Dialog

    Description of Figure 7-60 follows
    Description of "Figure 7-60 The Invoke Dialog"
  17. Click OK.
  18. Double-click the Assign activity.

    The Assign dialog is displayed.

  19. Click the plus icon, and select Copy Operation.

    The Create Copy Operation dialog is displayed.

  20. Select the variables, as shown in Figure 7-61, and click OK.

    Figure 7-61 The Create Copy Operation Dialog

    Description of Figure 7-61 follows
    Description of "Figure 7-61 The Create Copy Operation Dialog"
  21. Click OK in the Assign dialog.

    The JDeveloper BPELRawqueue.bpel page is displayed, as shown in Figure 7-62.

    Figure 7-62 The BPELRawqueue.bpel Page

    Description of Figure 7-62 follows
    Description of "Figure 7-62 The BPELRawqueue.bpel Page"
  22. Click File, Save All.
7.4.3.6 Configuring the Data Sources in the Oracle WebLogic Server Administration Console
  1. Navigate to http://servername:portnumber/console.
  2. Use the required credentials to open the Home page of the Oracle WebLogic Server Administration Console.
  3. In the Home page, under Domain Structure, select Services, JBDC, and then click DataSources.

    The Summary of JDBC Data Sources page is displayed.

  4. Click New. The Create a New JDBC Data Source page is displayed.
  5. Enter the values for the properties to be used to identify your new JDBC data source.
  6. Click Next. The Create a New JDBC Data Source Transaction Options page is displayed.
  7. Click Next. The Create a New JDBC Data Source Connection Properties page is displayed.
  8. Enter the connection properties in the Connection Properties page.
  9. Click Next. The Create a New JDBC Data Source Test Database Connection page is displayed.
  10. Click Test Configuration to test the database availability and the connection properties you provided. A message stating that the connection test succeeded is displayed at the top of the Create a New JDBC Data Source Test Database Connection page.
  11. Click Next. The Create a New JDBC Data Source Select Targets page is displayed.
  12. Select a target, and then click Finish.

    The Summary of JDBC Data Sources page is displayed. This page summarizes the JDBC data source objects that have been created in this domain. The Data Source that you created is displayed in this list.

  13. Close the Oracle WebLogic Server Administration Console.
7.4.3.7 Deploying with JDeveloper

You must deploy the application profile for the SOA project and the application you created in the preceding steps. To deploy the application profile using JDeveloper, perform the following steps:

  1. Create an application server connection. For more information, see Creating an Application Server Connection for Oracle JCA Adapters.
  2. Deploy the application. For more information, see Deploying Oracle JCA Adapter Applications from JDeveloper.
7.4.3.8 Monitoring Using the Oracle Fusion Middleware Control Console

You can monitor the deployed 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. In the Last 5 Instances pane, there is an entry of a new instance.

    This is the instance that triggered when you enqueued a message.

  3. Click an instance.

    The Flow Trace page is displayed.

  4. Click the BPELRawqueue component instance.

    The Audit page is displayed.

  5. Click the Flow-Debug tab to debug the instance.