Skip Headers
Oracle® Application Server Adapters for Files, FTP, Databases, and Enterprise Messaging User's Guide
10g Release 2 (10.1.2.)
B25307-01
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

3 Oracle Application Server Adapter for Advanced Queuing

This chapter describes how to use the Oracle Application Server Adapter for Advanced Queuing (AQ adapter), which enables a BPEL process to interact with a queue.

This chapter contains the following topics:

Introduction to the AQ Adapter

Oracle Streams Advanced Queuing (AQ) provides a flexible mechanism for bidirectional, asynchronous communication between participating applications. Because advanced queues are an Oracle database feature, they are scalable and reliable. Backup and recovery (including any-point-in-time recovery), logging, transactional services, and system management are all inherent features of the database and, therefore, 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. See Oracle Streams Advanced Queuing User's Guide and Reference for more information.

AQ Adapter Features

The AQ adapter is both a producer and 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 AQ adapter supports both ADT (Oracle object type) and RAW queues as payloads. It also supports extracting a payload from one ADT member column. The AQ adapter does not support the AQ XML type.

The AQ adapter supports headers for enqueue and dequeue options. Headers are comprised of an AQ header and a payload header. The AQ header consists of the standard message properties that are present in every queue.

You access the AQ adapter from the Adapter Configuration Wizard, which you use to browse queues and expose the underlying metadata as a WSDL with JCA extensions.

For AQ adapter samples, go to

Oracle_Home\integration\orabpel\samples\tutorials\124.AQAdapter

Enqueue-Specific Features (Message Production)

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

  • Multiconsumer queue

    In Oracle Streams AQ, more than one consumer can process and consume a single message. To use this feature, you must create multiconsumer queues and enqueue the messages into these queues. In this configuration, a single message can be consumed by more than one 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 AQ adapter enqueue header 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 multiconsumer queue must have unique values for the Recipient parameter. This means that 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, 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 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. The delay interval, expiration time, and exception queue property are properties of the AQ adapter enqueue header.

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 AQ adapter supports a polling mechanism for consuming AQ messages.

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

  • Multiconsumer queue

    The 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 AQ adapter dequeue header. If the number of retries exceeds the limit, the message is moved to an exception queue that you specify. The exception queue is a property of the 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 (currently priority and correlation ID), user data properties (object payloads only), and functions (as specified in the WHERE clause of a SQL query).

  • AQ headers

    Table 3-1 summarizes the AQ header properties for the enqueue and dequeue operations.

    Table 3-1 AQ Header Message Properties

    Message Property Datatype Default If Not Specified Description Include in Message Header for Enqueue Include in Message Header for Dequeue

    Priority

    Integer

    1

    Priority of the message.

    A smaller number indicates a higher priority.

    Yes

    Yes

    Delay

    Integer

    0

    The number of seconds after which the message is available for dequeuing

    Yes

    No

    Expiration

    Integer

    -1 (never expires)

    The number of seconds before the message expires. This parameter is an offset from the delay.

    Yes

    No

    Correlation

    String

    -

    User-assigned correlation ID

    Yes

    Yes

    RecipientList

    String

    -

    The list of recipients for this message, separated by commas. This overrides RecipientList in the InteractionSpec

    Yes

    No

    ExceptionQueue

    String

    -

    The exception queue name

    Yes

    No

    EnqueueTime

    String

    -

    The time at which the message was enqueued

    No

    Yes

    MessageID

    String

    -

    The hexadecimal representation of the message ID

    No

    Yes

    OrigMessageId

    String

    -

    The hexadecimal representation of the original message ID

    No

    Yes

    Attempts

    Integer

    -

    The number of failed attempts at dequeuing the message

    No

    Yes


See Oracle Application Server Adapter Concepts for information on AQ adapter architecture, adapter integration with Oracle BPEL Process Manager, and adapter deployments.

Supported ADT Payload Types

The AQ adapter supports the following RAW types:

  • BLOB

  • CHAR

  • CLOB

  • DATE

  • DECIMAL

  • DOUBLE PRECISON

  • FLOAT

  • INTEGER

  • NUMBER

  • REAL

  • SMALLINT

  • TIMESTAMP

  • VARCHAR2

In addition, the primitive types, varrays of objects, or primitives are also supported.

If choosing a payload field instead of the whole ADT, choose only one of the following datatypes as the payload field:

  • CLOB, either XSD or opaque schema

  • VARCHAR2, either XSD or opaque schema

  • BLOB, opaque schema only

Native Format Builder Wizard

JDeveloper BPEL Designer provides the Native Format Builder Wizard to define XSD files of various formats, including for the AQ RAW payload. See Chapter 6, "Native Format Builder Wizard" for more information. For Native Format Builder examples, go to

Oracle_Home\integration\orabpel\samples\tutorials\124.AQAdapter\
RawQueuePayloadUsingNativeFormat

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 the ADT with BLOB selected as the payload case, an opaque schema must be used, which is defined as:

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

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

Table 3-2 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


If you do not have an XSD, but the payload data is formatted in some way (for example, in a comma-separated value (CSV) format), then the Native Format Builder Wizard can be used 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.

Use Cases for the AQ Adapter

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

Adapter Configuration Wizard Walkthrough

This procedure shows how to use the Adapter Configuration Wizard. The example creates an adapter service that enqueues messages to the CUSTOMER_IN_QUEUE queue, with a payload that is one field within the CUSTOMER_TYPE object (the customer's e-mail address), and with a user-defined schema.

  1. Drag and drop a PartnerLink activity onto the right side of the designer window.

  2. Select Define Adapter Service (third icon) in the Create Partner Link window.

    Create Partner Link Window
    Description of the illustration jms1.gif

  3. Select AQ Adapter from the Adapter Type window and click Next.

    Adapter Type Window
    Description of the illustration aq1.gif

  4. Enter a service name (this name can be anything) and click Next.

    Service Name Window
    Description of the illustration aq2.gif

  5. Select a database connection and click Next. This name must typically match with your connector-factory location setting in the oc4j-ra.xml file. Ensure that you restart Oracle BPEL Server after changing the oc4j-ra.xml file.

    Service Connection Window
    Description of the illustration aq3.gif

  6. Select Enqueue, to send messages to a queue, or Dequeue, to receive messages from a queue. Click Next.

    Operation Window
    Description of the illustration aq4.gif

  7. Select a database schema or click Browse to browse for the correct schema. The <Default Schema> selection is the schema owned by the connection user. For example, if you connect as scott/tiger, then the <Default Schema> is scott; you see all of the queues of scott. In general, you only see schemas and queues that the connection user has the privileges to see. For this example, Browse is selected.

    Queue Name Window
    Description of the illustration aq5.gif

    The Select Queue window appears. Note that all types is selected. This means that all available types display: RAW, OBJECT, and special OBJECT (XML Gateway, Business Event System, and B2B Integration) queues.

    Description of aq6.gif follows
    Description of the illustration aq6.gif

  8. Select the correct queue and click OK.

    Selecting a Queue
    Description of the illustration aq7.gif

  9. Verify that you have selected the database schema and click Next.

    Completed Queue Name Window
    Description of the illustration aq8.gif

  10. Enter an optional correlation ID from 1 to 30 characters in length and click Next. 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. 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, all messages in the queue are processed.

    If you enter a value for the Correlation ID in the outbound direction, 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.

    Queue Parameters Window
    Description of the illustration aq9.gif

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

    • If you select Whole Object CUSTOMER_TYPE, click Next and go to Step 14. The message schema is automatically generated.

    • If you select Field within the Object, the business payload is contained in a single field in the object. Specify the correct file name, either by entering the name or by browsing for it using the Browse button. The field containing the payload you select must be a CLOB, BLOB, or VARCHAR2.

      The Access to non-payload fields also needed check box is available as an option. Select this check box if you need to specify additional information in a header field that is separate from the object payload. This selection generates the additional header schema but does not automatically create the header variable. Header variable is an optional field used to pass the header to and from the partnerlink. This header variable is created in the adapter tab of corresponding receive or invoke activity. See section "Header Variables in JDeveloper BPEL Designer" for more information.

      For example, your payload may be a JPG image. You may want to specify a person's name in the nonpayload field. This selection generates an additional header schema file (object_name.xsd, where object_name is the structured payload object used by the queue). Using this information is discussed in more detail in "Rule-Based Subscription for Multiconsumer Queues".

    Object Payload Window
    Description of the illustration aq10.gif

  12. If you select the Browse button, the Select Payload Field window appears. Select the correct field name and click OK.

    Figure 3-1 Select Payload Field Window

    Description of Figure 3-1  follows
    Description of "Figure 3-1 Select Payload Field Window"

  13. Click Next.

    Completed Object Payload Window
    Description of the illustration aq13.gif

    The Messages window appears. These settings define the correct schema for the message payload.

  14. Perform one of the following tasks:

    • Check Native format translation is not required (Schema is Opaque), which disables the rest of the fields.

    • Click Define Schema for Native Format to start the Native Format Builder Wizard, if the schema you want to use is not a native schema file. This wizard guides you through the creation of a native schema file from file formats such as comma-separated value (CSV), fixed-length, data type description (DTD), and COBOL Copybook.

    • Enter the path for the schema file URL (or browse for the path).

    The following steps demonstrate the last option, browsing for the schema file URL. Click the Browse button.

    Messages Window
    Description of the illustration aq14.gif

    The Type Chooser window appears, with the Type Explorer navigation tree.

  15. Browse the tree and select the appropriate schema type. Click OK. Type Chooser Window
    Description of the illustration aq15.gif

    The Messages window reappears, with the Schema File URL field completed.

    Completed Messages Window
    Description of the illustration aq16.gif

  16. Click Next.

    The Finish window appears. This box shows the path and name of the adapter file that the wizard creates.

    Finish Window
    Description of the illustration aq17.gif

  17. Click Finish.

    The Create Partner Link window appears with the fields completed.

    Completed Create Partner Link Window
    Description of the illustration aq18.gif

  18. Click OK.

Generated WSDL file

The adapter service generates a WSDL file to serve as the defined adapter interface. Here is the WSDL file generated by the walkthrough example.

This part of the code segment defines the name of the adapter, and the locations of various necessary schemas and other definition files.

<definitions
     name="AQ_Example"
     targetNamespace="http://xmlns.oracle.com/pcbpel/adapter/aq/AQ_Example/"
     xmlns="http://schemas.xmlsoap.org/wsdl/"
     xmlns:tns="http://xmlns.oracle.com/pcbpel/adapter/aq/AQ_Example/"
     xmlns:plt="http://schemas.xmlsoap.org/ws/2003/05/partner-link/"
     xmlns:jca="http://xmlns.oracle.com/pcbpel/wsdl/jca/"
     xmlns:imp1="http://xmlns.oracle.com/BPELProcess"
     xmlns:hdr="http://xmlns.oracle.com/pcbpel/adapter/aq/outbound/"
    >

This code segment imports the necessary namespaces.

    <import namespace="http://xmlns.oracle.com/pcbpel/adapter/aq/outbound/" location="aqAdapterOutboundHeader.wsdl"/>
    <import namespace="http://xmlns.oracle.com/BPELProcess" location="bpelprocess.wsdl"/>

This code segment defines the message name and port type for the partner link.

    <message name="BPELProcessProcessRequest_msg">
        <part name="BPELProcessProcessRequest" element="imp1:BPELProcessProcessRequest"/>
    </message>
    <portType name="Enqueue_ptt">
        <operation name="Enqueue">
            <input message="tns:BPELProcessProcessRequest_msg"/>
        </operation>
    </portType>

This code segment defines the necessary bindings for the enqueue operation and the target queue, and identifies the message header.

    <binding name="Enqueue_binding" type="tns:Enqueue_ptt">
    <jca:binding />
        <operation name="Enqueue">
      <jca:operation
          InteractionSpec="oracle.tip.adapter.aq.outbound.AQEnqueueInteractionSpec"
          QueueName="CUSTOMER_IN_QUEUE"
          ObjectFieldName="CONTACTS.EMAIL"
          OpaqueSchema="false" >
      </jca:operation>
      <input>
        <jca:header message="hdr:Header" part="Header"/>
      </input>
        </operation>
    </binding>
    <service name="AQ_Example">
        <port name="Enqueue_pt" binding="tns:Enqueue_binding">

This last part defines the database connection, the connection factory (as defined in the oc4j-ra.xml file), and the name and role of the partnerLinkType and portType.

<!--Your runtime connection is declared in 
J2EE_HOME/application-deployments/default/DbAdapter/oc4j-ra.xml 
These mcf properties here are from your design time connection and 
save you from having to edit that file and restart the application server 
if eis/AQ/DBConnection2 is missing.

These mcf properties are safe to remove.-->
      <jca:address location="eis/AQ/DBConnection2" UIConnectionName="DBConnection2"
          ManagedConnectionFactory="oracle.tip.adapter.aq.AQManagedConnectionFactory"
          mcf.ConnectionString="jdbc:oracle:thin:@144.25.143.7:1521:shashipc"
          mcf.UserName="system"
          mcf.Password="47E570316F19A1CFFD2E2104BF5CA8FE" />
        </port>
    </service>
  <plt:partnerLinkType name="Enqueue_plt" >
    <plt:role name="Enqueue_role" >
      <plt:portType name="tns:Enqueue_ptt" />
    </plt:role>
  </plt:partnerLinkType>
</definitions>

Dequeuing and Enqueuing Object and ADT Payloads

The Adapter Configuration Wizard walkthrough shows how to enqueue one field in an object. To enqueue or dequeue the entire object as the payload, do the following:

  • Select Enqueue or Dequeue in Step 6.

  • Select Whole Object CUSTOMER_TYPE in Step 11, and skip to Step 16.

The Adapter Configuration Wizard walkthrough provided an enqueue operation example. For a dequeue operation, the resulting WSDL file differs by including dequeue information instead of enqueue information, and by lacking an ObjectFieldName in the jca:Operation section of the code. See the following code sample for a dequeue operation and compare it to the WSDL file from the general walkthrough to see these differences:

    <portType name="Dequeue_ptt">
        <operation name="Dequeue">
            <input message="tns:CUSTOMER_TYPE_msg"/>
        </operation>
    </portType>
    <binding name="Dequeue_binding" type="tns:Dequeue_ptt">
    <pc:inbound_binding />
        <operation name="Dequeue">
      <jca:operation
          ActivationSpec="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec"
          QueueName="CUSTOMER_OUT_QUEUE
          OpaqueSchema="false" >
      </jca:operation>
      <input>
        <jca:header message="hdr:Header" part="Header"/>
      </input>
        </operation>

Dequeuing One Column of the Object/ADT Payload

The walkthrough is an example of enqueuing one field or column within an object payload. To create an adapter that dequeues the one field in an object, the steps are the same, except that in Step 6, select Dequeue.

The following segment of the generated WSDL file specifies that one field, in this case CONTACTS.EMAIL, is dequeued.

      <jca:operation
          ActivationSpec="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec"
          QueueName="CUSTOMER_IN_QUEUE"
          ObjectFieldName="CONTACTS.EMAIL"
          OpaqueSchema="true" >
      </jca:operation>

Processing Large Numbers of Messages

If you want to process large numbers of messages with the AQ adapter, ensure that you set the cacheWSIFOperation property to true in the bpel.xml file:

<BPELSuitcase> 
 <BPELProcess id="HelloWorld" src="HelloWorld.bpel"> 
    <partnerLinkBindings> 
       <partnerLinkBinding name="Dequeue"> 
          <property name="wsdlLocation">fileService.wsdl</property> 
       </partnerLinkBinding> 
       <partnerLinkBinding name="Enqueue"> 
          <property name="wsdlLocation">fileWriteService.wsdl</property> 
          *<property name="cacheWSIFOperation">true</property>* 
       </partnerLinkBinding> 
    </partnerLinkBindings>

Set this property through the Property tab of the Create Partner Link or Edit Partner Link window for the partner link.

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.

  • Select Dequeue operation in Step 6.

  • Enter the correlation ID in Step 10.

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

The resulting WSDL file contains the correlation ID:

<jca:operation
   ActivationSpec="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec"
   QueueName="CUSTOMER_OUT_QUEUE"
   Correlation="147"
   OpaqueSchema="false" >
</jca:operation>

Enqueuing and Dequeuing from Multisubscriber Queues

Multisubscriber queues are accessible by multiple users, and sometimes those users are only concerned 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.

If you specify an adapter that enqueues to a multisubscriber queue in Step 8, then the Queue Parameters window also includes a Recipients field with the Correlation Id field, as shown in .

Figure 3-2 Queue Parameters Window with Correlation Id Field

Description of Figure 3-2  follows
Description of "Figure 3-2 Queue Parameters Window with Correlation Id Field"

Enter the consumer name or names separated by commas that are the intended recipients for the messages enqueued by the adapter. The message remains in the queue until all recipients have dequeued the message. If the Recipients field is left empty, then all currently active consumers are recipients. This field can be overridden on a per message basis by setting the RecipientList field described in Table 3-1 in the outbound header.

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

      <jca:operation
         InteractionSpec="oracle.tip.adapter.aq.outbound.AQEnqueueInteractionSpec"
          QueueName="IP_IN_QUEUE"
          DatabaseSchema="SCOTT"
          ObjectFieldName="PAYLOAD"
          PayloadHeaderRequired="true"
          RecipientList="Bob"
          OpaqueSchema="true" >
      </jca:operation>

When dequeuing from a multisubscriber queue, the Queue Parameters window appears, as shown in .

Figure 3-3 Queue Parameters Window with Consumer Field

Description of Figure 3-3  follows
Description of "Figure 3-3 Queue Parameters Window with Consumer Field"

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 WSDL file generated by defining an AQ adapter with a consumer name:

      <jca:operation
          ActivationSpec="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec"
          QueueName="IP_IN_QUEUE"
          DatabaseSchema="SCOTT"
          ObjectFieldName="PAYLOAD"
          PayloadHeaderRequired="true"
          Consumer="Bob"
          OpaqueSchema="true" >
      </jca:operation>
      <input>
        <jca:header message="tns:Header_msg" part="Header"/>
      </input>
        </operation>

The Message Selector Rule field enables you to enter rules for accepting messages. This is discussed in more detail in the following section.

Correlation Id is a number assigned to a message to identify it to specific dequeuers, as mentioned in Step 10. This differs from a subscription rule in that the queue stores messages with a correlation ID for later use when a subscriber using that correlation ID comes online.

Rule-Based Subscription for Multiconsumer Queues

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. This condition may concern header information, as in selecting messages of only priority 1, or some aspect of the message payload, as in selecting only loan applications above $100,000.

The Message Selector Rule field appears in Step 10 if the selected queue is multisubscriber. 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 only dequeues messages for which this Boolean expression is true.

In Step 11, Access to non-payload fields also needed must be checked in order to access header information.

When this field is checked, the generated WSDL has additional code in the type section:

     <complexType name="HeaderCType" >
       <sequence>
         <!-- static header -->
         <element name="QueueHeader" type="hdr:HeaderType" />
         <!-- payload header -->
         <element name="PayloadHeader" type="obj1:SERVICE_TYPE" />
       </sequence>
     </complexType>
     <element name="Header" type="tns:HeaderCType" />
<element name="Header" type="tns:HeaderCType" />and the message:
   <message name="Header_msg">
       <part name="Header" element="tns:Header"/>
   </message>

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

For working examples of rule-based subscription using header and payload information, go to

Oracle_Home\integration\orabpel\samples\tutorials\124.AQAdapter\
RuleBasedSubscription_Header

Oracle_Home\integration\orabpel\samples\tutorials\124.AQAdapter\
RuleBasedSubscription_Payload

Using AQ Headers in a BPEL Process

The entries included in AQ headers are described in "Dequeue and Enqueue Features" . These header entries are available for composing subscription rules.

Header information can also be translated into BPEL variables using the Adapter tab when defining BPEL activities that send or receive messages. This tab enables you to create header variables for use with the adapters.

You create header variables in invoke, receive, reply, and pick - OnMessage branch activities. Information passing through header variables is protocol specific.

Note that header information for messages coming from the AQ adapter is different from header information for corresponding messages flowing into the AQ adapter. You must use headers if you need to get or set any of these protocol-specific properties. The following examples describe when you must use headers:

  • The AQ adapter enables you to get and set the priority of the message. For example, you want two different flows in your business process: one for high priority flows and one for low priority flows. This is possible if you use the inbound AQ header of the message flowing into the business process. In a similar fashion, you can set the priority of an outbound message through the outbound AQ headers.

  • In a file propagation scenario, files are being moved from one file system to another using the file adapter. In this case, it is imperative that you maintain file names across the two systems. Use file headers in both directions and set the file name in the outbound file header to use the file name in the inbound file header.

Header Variables in JDeveloper BPEL Designer

The following example describes how to create a special header variable in a receive activity in the outbound direction for the file adapter. You are not restricted to this direction or adapter type. You can also create this variable in either direction (inbound or outbound) with other adapter types that include headers (AQ, JMS, and FTP).

  1. Click the flashlight icon to display the Variable Chooser window.

  2. Select the second Variables folder, and click Create to display the Create Variable window.

  3. Enter a unique and recognizable name in the Name field (for this example, Variable_Header).

  4. Select Message Type and click the flashlight icon to display the Type Chooser window.

  5. Expand Message Types, then Project WSDL Files, then service_name.wsdl, and then Message Types, where service_name is the name you specified for the service name when you ran the Adapter Configuration Wizard.

    A header message named OutboundHeader_msg (or a similar name that includes Header_msg as part of the name) appears.

  6. If this name appears here, select it and go to Step 8.

  7. If this name does not appear, perform the following additional steps.

    1. Expand Imported WSDL, then fileAdapterOutboundHeader.wsdl (or a similar name for the direction and adapter type you are using), and then Message Types.

    2. Select OutboundHeader_msg and go to Step 8.


      Note:

      The name that displays here for the AQ adapter may only be Header. Select this name. This indicates that the header is static, because you did not need to select the Access to non-payload fields check box when configuring the AQ adapter.

  8. Click OK to close the Type Chooser window, Create Variable window, and Variable Chooser window.

  9. Complete the setup of the Receive activity.

  10. Open the source view of the BPEL process file to view the header variable you created:

    bpelx:headerVariable="Variable_Header"/>
    

Configuring a Message Rejection Handler for Data Errors

Rejected messages (that is, messages with data errors) can be directed to a rejected messages queue, and can also be logged in a directory on the system for later review.

An example of a rejection handler can be found at

Oracle_Home\integration\orabpel\samples\tutorials\124.AQAdapter\
AQMessageRejectionHandler

The readme.txt file in this directory describes a procedure for testing the message rejection handler.

The Dequeue.wsdl file in this directory includes the following code:

    <pc:inbound_binding />
        <operation name="Dequeue">
      <jca:operation
          ActivationSpec="oracle.tip.adapter.aq.inbound.AQDequeueActivationSpec"
          QueueName="REJECTION_TEST_IN"
          DatabaseSchema="SCOTT"
          OpaqueSchema="false" >
      </jca:operation>
      <input>
        <jca:header message="hdr:Header" part="Header"/>
      </input>
        </operation>
    </binding>

This part of the code directs the errored message to the REJECTION_TEST_IN queue.

Summary

This chapter discusses Oracle Streams AQ concepts and how to configure various types of AQ adapters. It also discusses different ways of filtering messages received from multisubscriber queues, and copying header information into BPEL variables for decision making.