In this section: Reference: |
Oracle Advanced Queuing (AQ) is the message queuing function of the Oracle database system. With Oracle AQ, you can perform message queuing operations in a manner similar to that of SQL operations.
The message queuing function of AQ enables asynchronous communication, using queues, between applications and users on Oracle databases. It offers:
AQ offers ways to prioritize the messages and offers time properties for messages such as expiration and delays. Notifications also are provided for immediate attention.
With AQ, message queuing operations benefit from the reliability, integrity, high availability, security, and scalability of a database. All of the message queuing operations are transactional. After messages are committed, they are guaranteed to be delivered. You can perform multiple message queuing and database operations in the same transaction. A database offers disaster protection for the messages. You also can use the advanced security features of the Oracle database.
The integration of message queuing with a database also offers unique benefits. Message queuing can use the management functions of a database. All the AQ operations are automatically audited, and you can look up the messaging information using an SQL view. You can use these SQL views to extract additional intelligence about the messaging environment.
Message queuing can take advantage of the system type of the Oracle database. Each message can be of an Oracle object type. Queuing brings the structure to the messaging system, which brings benefits such as better querying and content-based subscriptions.
AQ is used extensively in application integration, e-Businesses for online operations, and B2B exchanges.
iWay Service Manager can monitor AQ queues and read messages as they appear on the queue. The message is then processed and deleted after processing is complete. Before using the AQ adapter, you must add the Oracle-provided AQ JAR files to the class path.
For instructions on registering JAR files, see Registering Library Files and Setting JVM Options.
The Oracle AQ listener requires that you register jar files as follows:
|
Queue |
JAR Files |
|---|---|
|
RAW |
These Java AQ API JAR files are located in the following directory: %ORACLE_HOME%/rdbms/jlib/where:
|
|
CLOB |
|
|
RAC |
|
For instructions on registering JAR files, see Registering Library Files and Setting JVM Options.
The following tables list and describe the Oracle AQ listener properties. The individual tables correspond to the basic, AQ, JMS, and Advanced sections of the configuration window. For instructions on creating a listener, see How to Create a Listener.
|
Property Name |
Property Description |
|---|---|
|
SID (required) |
The name of the Oracle database service. |
|
Host (required) |
The IP address or DNS name where the Oracle Service ID is installed. |
|
Port (required) |
The Oracle listener port. The default value, if not changed at Oracle installation time, is 1521. |
|
Driver (required) |
The type of driver to use for server connection. Select OCI or Thin. |
|
User (required) |
A valid Oracle user ID that has AQ_USER_ROLE granted by the AQ administrator and executes a privilege on DBMS_AQ. |
|
Password (required) |
A valid password for the Oracle user ID previously specified. |
|
Table Owner/Schema (required) |
The schema name. Usually the same name as the login name. |
|
Table Name |
The named repository for a set of queues and their messages. A queue table may contain numerous queues, each of which may have many messages. However, a given queue and its messages may exist in only one queue table. This queue table resides in the previously specified Oracle Service ID. |
|
Receiver Name (required) |
The name of the queue on which input documents will be received for processing by Service Manager. |
|
Connection Type (required) |
You can select Oracle JMS or Oracle AQ. |
AQ
|
Property Name |
Property Description |
|---|---|
|
Message Type |
Select CLOB or RAW type of message to send or create type if creating dynamic message queue on listener. |
|
Payload Class |
When using custom defined objects, specify a class that is in the classpath. |
|
Payload Object |
When using custom defined objects, specify the Oracle object to which the class will map. The owner of the schema will be prepended. |
|
Object Owner |
Usually the same as the login value. |
RAC
|
Property Name |
Property Description |
|---|---|
|
RAC Hosts |
Enter additional hosts for RAC failover/load balancing using the following format: host1:port,host2:port,host3:port |
|
RAC Failover |
Select true if you want to use a RAC connection for failover. By default, false is selected. |
|
RAC Loadbalance |
Select true if you want to use a RAC connection for load balancing. By default, false is selected. |
|
ONS Hosts |
Hosts emitting ONS information. For example: host:port,host:port |
|
Cache Minimum |
The minimum number of connections in the queue to be held in the cache. |
|
Cache Maximum |
The maximum number of connections in the queue to be held in the cache. |
|
Cache Initial |
The initial number of connections to create in the cache. |
|
Cache Inactive Timeout |
The maximum time a cached physical connection can remain idle. |
|
Cache Abandoned Timeout |
The maximum time that a connection can remain unused before the connection is closed and returned to the cache. |
|
Cache Maximum Statements |
The maximum number of statements that a connection keeps open. |
|
Cache Property Interval |
Sets the time interval at which the cache manager inspects and enforces all specified cache properties. |
JMS
|
Property Name |
Property Description |
|---|---|
|
Form of Input |
Select a topic or a queue listener. |
|
Form of Acknowledgment |
Select auto acknowledge, client provides, or duplicates permitted to choose how the listener acknowledges received messages. |
|
Set Reply Correlation Id |
If set to a value, this is used as the correlation ID of the response. |
|
Default Output Form |
Select a topic or a queue target. |
|
Message Type |
Select bytes or text type of message to send or create type if creating dynamic queue on listener. |
|
JMSReplyTo |
Queue or Topic (used for JNDI lookup). |
Advanced
|
Property Name |
Property Description |
|---|---|
|
Retry |
The interval between retrying pending requests contained in a message. |
|
Accepts non-XML (flat) only |
Select true if non-XML input is expected. If enabled, XML input still can be passed to the listener. Preparsers do not run. |
|
Optimize Favoring |
Use this option to customize listener performance. For smaller transactions, select performance. For large payloads that could monopolize the amount of memory used by Service Manager, select memory. |
|
Multithreading |
The number of documents that can be processed in parallel. |
|
Maximum Threads |
The parallel threads can grow to this count automatically on demand. |
|
Execution Time Limit |
The maximum time a request can take to complete. A request that takes longer to complete terminates. Prevents runaway requests. |
|
Polling Interval |
The interval (in seconds) after which the listener returns control to Service Manager to determine if there is new input or a stop listener is requested. The listener is constantly connected to the queue to retrieve incoming messages. The default value is 2.0. |
|
Whitespace Normalization |
Specifies how the parser treats whitespace in Element content. Choose preserve to turn off all normalization as prescribed by the XML Specification. Choose condense to remove extra whitespace in pretty printed documents and for compatibility with earlier versions. |
|
Default Java File Encoding |
The default encoding if incoming message is not self-declaring (that is, XML). |
|
Agent Precedence |
Sets the order by which Service Manager selects agents. Service Manager usually looks for a document entry in the configuration library and when a match is found, the agent specified in that entry is selected. If no matching document is found or no agent specified, the engine looks in the input protocol configuration (listener). For the processing agent to be taken directly from the listener (thus ignoring the document entry), use <listener> overrides <document>. <document> overrides <listener> is the default value, which is used to manage EDA documents. |
|
Always reply to listener default |
If set to true, the default reply definition is used in addition to defined destinations. |
|
Error Documents treated normally |
If set to true, error documents are processed by configured preemitters. |
|
Listener is Transaction Manager |
If set to true, agents run in a local transaction. Agents can roll back uncompleted transactions. |
|
Record in Activity Log(s) |
If set to true, activity on this channel will be recorded in the activity logs. If set to false, the activity will not be recorded. |
Messages are sent to the destinations at the completion of a workflow. The state of the document determines which destination is used. The order in which the destinations are used cannot be predicted. Destinations cannot accept responses. These configurations also are used to send a message over a different protocol.
Note: Configuring an Oracle AQ emitter is not required if the emitter protocol used in the outlet of the channel is the same as the listener protocol used in the inlet of the channel. For more information on inlets and outlets, see Defining an Inlet and Defining an Outlet.
To route an output document or error message to a protocol other than that of the listener, you must configure an emitter. For example, an application may send input over TCP, but want to route the output to an Oracle AQ queue.
The following tables list and describe the Oracle AQ emitter properties. The individual tables correspond to the basic, AQ, and JMS sections of the configuration window. For instructions on creating an emitter, see How to Create an Emitter.
|
Property Name |
Property Description |
|---|---|
|
Destination (required) |
Type queue@host. When using RAC, leave the host section blank. |
|
Host |
The host name of the server connection. |
|
SID (required) |
The Oracle database service ID. |
|
Port (required) |
The Oracle listener port. The default value, if not changed at Oracle installation time, is 1521. |
|
Driver (required) |
The type of driver to use for the server connection. Select OCI or Thin. |
|
User (required) |
A valid Oracle user ID that has AQ_USER_ROLE granted by the AQ administrator and executes a privilege on DBMS_AQ. |
|
Password (required) |
A valid password for the Oracle user ID previously specified. |
|
Table Owner/Schema (required) |
The schema name. Usually the same name as the login name. |
|
Table Name |
A named repository for a set of queues and their messages. A queue table may contain numerous queues, each of which may have many messages. However, a given queue and its messages may exist in only one queue table. This queue table resides in the previously specified Oracle Service ID. |
|
Connection Type (required) |
You can select the Oracle JMS or Oracle AQ. |
AQ
|
Property Name |
Property Description |
|---|---|
|
Message Type |
You can select either a CLOB or RAW type of message to send. You can also create a type if creating dynamic message queue on listener. |
|
Payload Class |
When using custom defined objects, specify a class that is in the classpath. |
|
Payload Object |
When using custom defined objects, specify the Oracle object that the class will map to. The owner of the schema will be prepended. |
|
Object Owner |
This property value is usually the same as the login value. |
RAC
|
Property Name |
Property Description |
|---|---|
|
RAC Hosts |
Enter additional hosts for RAC failover/load balancing using the following format: host1:port,host2:port,host3:port |
|
RAC Failover |
If set to true , the RAC connection is used for failover. By default, false is selected. |
|
RAC Loadbalance |
If set to true, the RAC connection is used for load balancing. By default, false is selected. |
|
ONS Hosts |
Hosts emitting ONS information. For example: host:port,host:port |
|
Cache Minimum |
The minimum number of connections in the queue to be held in the cache. |
|
Cache Maximum |
The maximum number of connections in the queue to be held in the cache. |
|
Cache Initial |
The initial number of connections to create in the cache. |
|
Cache Inactive Timeout |
The maximum time a cached physical connection can remain idle. |
|
Cache Abandoned Timeout |
The maximum time that a connection can remain unused before the connection is closed and returned to the cache. |
|
Cache Maximum Statements |
The maximum number of statements that a connection keeps open. |
|
Cache Property Interval |
Sets the time interval at which the cache manager inspects and enforces all specified cache properties. |
JMS
|
Property Name |
Property Description |
|---|---|
|
Message Priority |
The outgoing message priority (if omitted, uses incoming priority) as integer. |
|
Message Type |
Select bytes or text type of message to send or create type if creating dynamic queue on listener. |
|
Set Reply Correlation Id |
If set to a value, this value is used as the correlation ID of the response. |
|
Delivery Mode |
Select Non-Persistent or Persistent. Retention of a message at the destination until its receipt is acknowledged is not guaranteed by a Persistent delivery mode. |
|
JMSReplyTo |
Select Queue or Topic (used for JNDI lookup). |
|
Time to Live |
The lifetime of the message (in milliseconds) as float. The default will live forever. |
The following table lists and describes the special registers (SREGs) available on the Oracle AQ listener.
|
Name |
Level |
Type |
Description |
|---|---|---|---|
|
correlid |
Document |
String |
The correlation ID. |
|
destination |
Document |
String |
The default destination for reply (from message). |
|
iwayconfig |
System |
String |
The current active configuration name. |
|
msgid |
Document |
String |
The message ID. |
|
msgsize |
Document |
Integer |
The physical length of the message payload. |
|
name |
System |
String |
The assigned name of the master (listener). |
|
priority |
Document |
String |
The priority of this message. |
|
protocol |
System |
String |
The protocol on which this message was received. |
|
source |
Document |
String |
The queue or topic on which message was received. |
|
tid |
Document |
String |
Unique transaction ID. |
The following table lists and describes errors that you may encounter when using an Oracle AQ listener.
| Error | Reason | Solution |
|---|---|---|
fetching message errorcode[174] and errormsg[JMS-174: Class must be specified for queues with object payloads Use dequeue(deq_option, payload_fact) or dequeue(deq_option, sql_data_cl)] |
Queue specified was configured for a user-defined message type. Currently, the listener can only accommodate the RAW message type. |
Redefine the message queue as payload_type of RAW. For additional information, see the Oracle AQ documentation. |
Exception: java.sql.SQLException: ORA-00600: internal error code, arguments: [kpotcprc: depth exceeded], [16], [], [], [], [], [], []: [ |
Server is unable to find the receive queue specified during configuration. Possible cause is a typographical error during configuration. |
Verify that the message queue exists in the queue table. |
java.sql.SQLException: Io exception: The Network Adapter could not establish the connection: |
If the Oracle instance is not running, this error can appear at the start up (or restart) of Service Manager. |
Check with your Oracle DBA to ensure that your Oracle system is running. |
OracleDriver.class not found |
The JDBC driver for Oracle is release specific. |
Verify that the correct JDBC driver is included in your class path. To ensure that the correct classes12.zip is being used, check the Service Manager class path. |
| iWay Software |