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.
Oracle Streams 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 “Introduction to Oracle Streams AQ" in the Oracle Streams Advanced Queuing User's Guide.
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 Components .
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 pre-dates Mediator and most of this guide and the samples 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.
Get an overview of Oracle AQ Adapter features in this section.
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.
You can obtain the Oracle AQ Adapter samples by accessing the Oracle SOA Sample Code site.
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.
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:
Multi consumer Queue
The Oracle AQ Adapter can retrieve messages from a multi consumer 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).
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 multi subscriber 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 15 if you select a multi subscriber 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 is used for adding subscriber when there is no subscriber and DequeueCondition is used for dequeuing from a queue as it supports nested query in rule. This is done as addSubscriber does not support nested query.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.
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.
Follow these steps to use the AQ Adapter Configuration Wizard to configure an AQ Adapter for synchronous request-response.
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.
You can configure an outbound Synchronous Dequeue for an AQ Adapter by selecting the Synchronous Dequeue operation type on the AQ Operation Type page.
Follow these steps to use the AQ Adapter Configuration Wizard to configure AQ for synchronous dequeue.
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>
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>
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
JDeveloper BPEL Designer 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 .
To obtain sample code that demonstrates usage of the Native Format Builder access the latest SOA Sample code under Middleware & Tools from Sample Code for Developers and Adminspage.
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 |
---|---|
|
User-provided schema or opaque schema. |
Whole |
Must use a schema generated by the Adapter Configuration Wizard, which is based on the queue structure. |
|
User-provided schema or opaque schema. |
|
User-provided schema or opaque schema. |
|
Opaque schema. |
|
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.
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.
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.
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.
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.
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>
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
.
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>
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;
Oracle AQ Adapter supports performance tuning features.
For more information, see Oracle JCA Adapter Tuning Guide and Oracle JCA Adapter Properties.
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-13.
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
:
Search fmwhome
/ for AqAdapter.rar
.
Unzip the file.
Edit META-INF
/weblogic-ra.xml
(and possibly ra.xml
.)
Jar the file again.
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.
The section includes the following use cases related to Oracle AQ Adapter.
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:
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:
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 require the following files from the artifacts.zip
file contained in the adapters-aq-103-adtclobpayload
sample:
artifacts/sql/setup_user.sql
artifacts/sql/create_type_service.sql
artifacts/sql/create_queues.sql
artifacts/sql/dequeue_service.sql
artifacts/sql/enqueue_service.sql
To obtain the adapters-aq-103-adtclobpayload
sample, access the Oracle Sample SOA Code site.
You must create a JDeveloper application to contain the SOA composite. Perform the following steps to create an application, a SOA project:
The next step is to define an Oracle AQ Adapter service. Perform the following steps to create an Oracle AQ Adapter service:
In the Components window, select SOA.
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.
Click Next.
The Adapter Configuration Wizard Service Name page is displayed, as shown in Figure 7-12.
Figure 7-12 The Adapter Configuration Wizard Service Name Page
Specify a service name, and then click Next.
The Adapter Configuration Wizard Service Connection page is displayed, as shown in Figure 7-13.
Figure 7-13 Adapter Configuration Wizard Service Connection Page
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.
Enter the following information:
For Create Connection In, choose Application Resources.
In the Connection Name field, specify a unique name for the database connection.
In this example, type DBConnection1.
From the Connection Type box, select Oracle (JDBC).
In the UserName field, specify the user name to be authorized for access to the database.
In this example, type scott
.
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.
In the Password field, specify the password to be associated with the specified user name.
In this example, type tiger
.
Select Save Password and Deploy Password.
From the Driver list, select Thin.
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
.
In the JDBC Port field, enter a value to identify the TCP/IP port. The default is 1521
.
In the SID field, enter a value for the unique system identifier (SID) of an Oracle database instance.
The default is XE
.
Click Test Connection to determine whether the specified information establishes a connection with the database.
A Success message is displayed.
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
.
Click Next.
The Adapter Configuration Wizard Adapter Interface page is displayed, as shown in Figure 7-14.
In the Adapter Interface page, choose Define from operation and schema (specified later).
Figure 7-14 The Adapter Configuration Wizard Adapter Interface Page
Click Next.
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, as shown in Figure 7-15.
The operation is automatically named after the operation that you selected. However, you can edit the Operation Name field.
Figure 7-15 The Adapter Configuration Wizard Operation Page
Note:
When creating a SOA composite that uses an inbound Oracle AQ Adapter dequeuing from a queue based on an ADT (Oracle Object) data type - if the SchemaValidation property in the .jca config file is set to true
, any empty (NULL) members of the ADT payload in the dequeued message results in the AQ_INVALID_PAYLOAD
error being raised and further resulting in the message being rejected. To avoid the message being rejected, you must set the SchemaValidation property to false
.
Click Next.
The Adapter Configuration Wizard Queue Name page is displayed, as shown in Figure 7-16.
Figure 7-16 The Adapter Configuration Wizard Queue Name Page
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, as shown in Figure 7-17.
Select the required queue, and then click OK.
In this example, select SERVICE_IN_QUEUE. The Queue Name page is displayed again with the Queue Name field populated with SERVICE_IN_QUEUE, as shown in Figure 7-18.
Figure 7-18 The Adapter Configuration Wizard Queue Name Page
Click Next.
The Adapter Configuration Wizard Queue Parameters page is displayed, as shown in Figure 7-19.
Figure 7-19 The Adapter Configuration Wizard Queue Parameters Page
Enter values for the parameters, and then click Next.
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.
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 multi consumer queues.
Click Next.
The Adapter Configuration Wizard Object Payload page is displayed, as shown in Figure 7-20.
Figure 7-20 The Adapter Configuration Wizard Object Payload Page
In Business Payload, select Field within the Object.
Click Browse in the Payload Fields Options section to select a field that contains the business payload.
The Select Payload Field dialog is displayed, as shown in Figure 7-21.
Figure 7-21 The Select Payload Field Dialog
Select a field, and then click OK.
In this example, select PAYLOAD (CLOB).
The Object Payload field is displayed with all the payload details filled up, as shown in Figure 7-22.
Figure 7-22 The Adapter Configuration Wizard Object payload Page
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.
Define Schema for Native Format: Click this to start the Native Format Builder wizard, which guides you through the process of defining the native format.
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.
In this example, click the Browse for schema file icon to browse for the schema file URL.
The Type Chooser dialog is displayed, as shown in Figure 7-23.
Select SERVICE from the list, as shown in Figure 7-23, and then click OK.
The Messages page reappears, with the Schema Location and Schema Element fields populated, as shown in Figure 7-24.
Figure 7-24 The Adapter Configuration Wizard Messages Page
Click Next.
The Finish screen is displayed. This page shows the path and name of the adapter file that the wizard creates.
Click Finish.
You have created an AQ Adapter service with dequeue operation.
Click OK.
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>
Dequeuing and enqueuing is covered in ADT Queue.
To enqueue or dequeue the entire object as the payload, perform the following:
For a working example of an ADT payload use case, refer to any of the following samples:
adapters-aq-102-adt
adapters-aq-110-supportedadttypes
You can obtain these samples by accessing the Oracle SOA Sample Code site.
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.
The walkthrough 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, you must perform the following steps in the Adapter Configuration Wizard Object Payload page:
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>
For a working example of an ADT CLOB
use case where one field or column within an object payload is dequeued, refer to the following samples:
adapters-aq-103-adtclobpayload
adapters-aq-105-adtclobopaquepayload
You can obtain these samples by accessing the Oracle SOA Sample Code site.
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:
To perform this use case, you must have access to a database with the SCOTT schema. Also, you require the following files from the artifacts.zip
file contained in the adapters-aq-104-requestreply
sample:
create_queues.sql
drop_queues.sql
enqueue.sql
SendReply.sql
setup_user.sql
To obtain the adapters-aq-104-requestreply sample code, access the Oracle SOA Sample Code site.
You must create a JDeveloper application to contain the SOA composite. Follow the steps documented in Creating an Application and an SOA Project to create an application, and an SOA project.
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:
In the Components window, select SOA.
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.
Click Next.
The Adapter Configuration Wizard Service Name page is displayed, as shown in Figure 7-12.
Specify a service name, and then click Next.
The Adapter Configuration Wizard Service Connection page is displayed.
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.
Enter the following information:
For Create Connection In, choose Application Resources.
In the Connection Name field, specify a unique name for the database connection.
From the Connection Type box, select Oracle (JDBC).
In the UserName field, specify the user name to be authorized for access to the database.
In this example, type scott
.
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.
In the Password field, specify the password to be associated with the specified user name.
In this example, type tiger
.
Select Save Password and Deploy Password.
From the Driver list, select thin.
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
.
In the JDBC Port field, enter a value to identify the TCP/IP port. The default is 1521
.
In the SID field, enter a value for the unique system identifier (SID) of an Oracle database instance.
The default is XE
.
Click Test Connection to determine whether the specified information establishes a connection with the database.
A Success message is displayed.
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
.
Click Next.
The Adapter Configuration Wizard Adapter Interface page is displayed.
In the Adapter Interface page, choose Define from operation and schema (specified later).
Click Next.
The Operation page is displayed.
Select Enqueue/Dequeue, as shown in Figure 7-15.
Figure 7-26 The Adapter Configuration Wizard Operation Page
Click Next.
The Adapter Configuration Wizard Queue Name page is displayed, as shown in Figure 7-16.
Figure 7-27 The Adapter Configuration Wizard Queue Name Page
Click Browse to browse for a request queue.
The Select Queue dialog is displayed, as shown in Figure 7-28.
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-29.
Repeat Step 12 and 13 for the enqueue queue information.
The Queue Name page is displayed, as shown in Figure 7-29.
Figure 7-29 The Adapter Configuration Wizard Queue Name Page
Click Next.
The Adapter Configuration Wizard Queue Parameters page is displayed, as shown in Figure 7-30.
Figure 7-30 The Adapter Configuration Wizard Queue Parameters Page
Click Next.
The Adapter Configuration Wizard Object Payload page is displayed, as shown in Figure 7-31.
Figure 7-31 The Adapter Configuration Wizard Object Payload Page
Select the Business Payload options, Whole Object CORRELATIONREQUEST_TYPE and Whole Object CORRELATIONREPLY_TYPE.
Click Next.
The Finish screen is displayed. This page shows the path and name of the adapter file that the wizard creates.
Click Finish.
You have created an AQ Adapter service for synchronous enqueue/dequeue operations.
Click OK.
You must assemble or wire the BPEL process and the Outbound adapter reference. Perform the following steps to wire the components:
Drag the small triangle in the BPEL process in the Components area to the drop zone that appears as a green triangle in RequestReply in the External References area.
The JDeveloper Composite.xml appears, as shown in Figure 7-32.
Figure 7-32 The JDeveloper - Composite.xml
Click File, Save All.
Add Invoke Activity
Double-click BPELProcess1. The BPELProcess1.bpel page is displayed.
Drag and drop an Invoke activity from the Components window to the design area.
Double-click the Invoke activity. The Invoke dialog is displayed.
Enter a name for the invoke activity in the Name field.
Click Browse Partner Links at the end of the Partner Link field. The Partner Link Chooser dialog is displayed, as shown in Figure 7-33.
Figure 7-33 The Partner Link Chooser Dialog
Select RequestReply, and click OK.
Click the Automatically Create Input Variable icon to the right of the Input variable field in the Invoke dialog, as shown in Figure 7-34. The Create Variable dialog is displayed.
Select the default variable name and click OK. The Variable field is populated with the default variable name.
Click OK. The JDeveloper BPELProcess1.bpel page appears, as shown in Figure 7-35.
Figure 7-35 The JDeveloper - BPELProcess1.bpel Page
Add an Assign Activity
Drag and drop an Assign activity from the Components window to the design area.
Double-click the Assign activity. The Assign dialog is displayed.
Enter a name for the Assign activity in the Name field.
Click the Copy Operation tab.
Select Copy Operation. The Create Copy Operation dialog is displayed.
Create a copy operation from inputVariable to outputVariable, as shown in Figure 7-36.
Figure 7-36 The Create Copy Operation Dialog
Click OK in the Create Copy Operation dialog.
Create another copy operation from inputVariable to Invoke_1_Enqueue_InputVariable, as shown in Figure 7-37.
Figure 7-37 The Create Copy Operation Dialog
Click OK in the Create Copy Operation dialog.
Click OK to return to the JDeveloper BPELProcess1.bpel page, as shown in Figure 7-38.
Figure 7-38 The JDeveloper - BPELProcess1.bpel
Click File, Save All.
Add a Receive Activity
You must deploy the application profile for the SOA project and the application you created in the preceding steps.
The following are the steps to deploy the application profile by using JDeveloper:
You can monitor the deployed composite by using the Fusion Middleware Control Console. Perform the following steps:
http://
servername
:
portnumber
/em
. The composite you deployed is displayed in the Application Navigator.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>
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.
For a working example of this use case where an Oracle AQ Adapter dequeues messages enqueued with that same correlation ID, refer to the following samples:
adapters-aq-106-messagerejection
adapters-aq-109-nativecorrelation
adapters-aq-112-prioritymessageselector
adapters-aq-113-payloadbasedmessageselector
You can obtain these samples by accessing the Oracle SOA Sample Code site.
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 15, 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>
For a working example of this use case which demonstrates enqueuing and dequeuing from multisubscriber queues, refer to the following samples:
adapters-aq-114-multiconsumeroutbound
You can obtain these samples by accessing the Oracle SOA Sample Code site.
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:
You must have access to a database with the SCOTT schema.
To perform this use case, you require the following SQL files from the artifacts.zip
file contained in the adapters-aq-102-adt
sample. These files are located in the artifacts/sql
subdirectory of the artifacts.zip
file. Execute the SQL files in the order shown below:
setup_user.sql
create_type_customer.sql
create_queues.sql
enqueue_customer.sql
dequeue_customer.sql
To obtain the adapters-aq-102-adt sample code, access the Oracle SOA Sample Code site
You must create an JDeveloper application to contain the SOA composite. Use the following steps to create an application and an SOA project:
The following are the steps to create an inbound Oracle AQ Adapter service:
In the Components window, select SOA.
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.
Click Next.
The Service Name page is displayed.
Specify a name for the service in the Service Name page. In this example, type dequeue
.
Click Next.
The Service Connection page is displayed. A database connection is required to configure an Oracle AQ Adapter. You can either create a new connection or select an existing database connection.
Click the Create a new database connection icon to create a database connection.
The Create Database Connection page is displayed.
Create a database connection, as mentioned in Step 6 of Defining an Service.
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.
Click Next.
The Adapter Interface page is displayed.
In the Adapter Interface page, select Define from operation and schema (specified later).
Click Next.
The Operation page is displayed.
Select Dequeue.
Accept the default operation name, and then click Next.
The Queue Name page is displayed.
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.
In the Select Queue dialog, perform the following steps:
For Queue Type, select all types.
For Database Schema, select Scott.
Retain the default values for the other fields.
Under Queues, select CUSTOMER_IN_QUEUE.
Figure 7-41 shows the Select Queue dialog.
Figure 7-41 Selecting a Queue for the Inbound Operation
Click OK.
The Queue Name dialog with all the fields populated is displayed, as shown in Figure 7-42.
Click Next.
The Queue Parameters page is displayed.
In the Queue Parameters page, leave the fields empty, and then click Next.
The Object Payload page is displayed.
Select a business payload: either the entire object, or just one field within the object.
In this example, select Whole Object CUSTOMER_TYPE.
Click Next.
The Finish screen is displayed. This page shows the path and name of the adapter file that the wizard creates.
Click Finish.
You have defined an inbound Oracle AQ Adapter
The following are the steps to create an outbound Oracle AQ Adapter service:
In the Components window, select SOA.
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.
Click Next.
The Service Name page is displayed.
In the Service Name field, enter enqueue
and click Next.
The Service Connection page is displayed.
For Connection, select MyConnection, and then click Next.
The Adapter Interface page is displayed.
In the Adapter Interface page, select Define from operation and schema (specified later), and then click Next.
The Operation page is displayed.
In the Operation page, select Enqueue, and accept the default operation name.
Click Next.
The Queue Name page is displayed.
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.
In the Select Queue dialog, perform the following steps:
For Queue Type, select all types.
For Database Schema, select Scott.
Retain the default values for the other fields.
Under Queues, select CUSTOMER_OUT_QUEUE, as shown in Figure 7-43.
Figure 7-43 Selecting a Queue for the Outbound Operation
Click OK.
The Queue Name page with all the fields populated is displayed, as shown in Figure 7-44.
Click Next.
The Queue Parameters page is displayed.
In the Queue Parameters page, leave the fields empty, and then click Next.
The Object Payload page is displayed.
Select a business payload, either the entire object, or just one field within the object. In this example, select Whole Object CUSTOMER_TYPE.
Click Next.
The Finish screen is displayed. This page shows the path and name of the adapter file that the wizard creates.
In the Finish window, click Finish.
You have defined an outbound Oracle AQ Adapter.
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:
You must deploy the application profile for the SOA project and the application you created in the preceding steps.
The following are the steps to deploy the application profile by using JDeveloper:
You can monitor the deployed composite by using the Fusion Middleware Control Console. Perform the following steps:
http://
servername
:
portnumber
/em
. The composite you deployed is displayed in the Application Navigator.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:
You must have access to a database with the SCOTT
schema.
To perform this use case, you require the following SQL files from the artifacts.zip
file contained in the adapters-aq-101-raw
sample. These files are located in the artifacts/sql
subdirectory of the artifacts.zip
file. Execute the SQL files in the order shown below:
setup_user.sql
create_queues.sql
enqueue_raw.sql
dequeue_raw.sql
artifacts/schemas/emp.xsd
To obtain the artifacts.zip
contained in the adapters-aq-101-raw
sample code, access the Oracle SOA Sample Code site.
To obtain the adapters-aq-101-raw
sample code, access the Oracle SOA Sample Code site.
You must create an JDeveloper application to contain the SOA composite. To create an application and an SOA project, perform the following steps:
Perform the following steps to create an inbound Oracle AQ Adapter service that dequeues the message to a queue:
Perform the following steps to create an adapter service that enqueues the request messages and dequeue the corresponding response messages (report) from a queue:
You must 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:
You must deploy the application profile for the SOA project and the application you created in the preceding steps.
The following are the steps to deploy the application profile using JDeveloper: