6 Internet Access to Oracle Streams AQ

6.1.1 Oracle Streams AQ Internet Operations Architecture

Figure 6-1 shows the architecture for performing Oracle Streams AQ operations over HTTP. The major components are:

• Oracle Streams AQ client program

• Web server/servlet runner hosting the Oracle Streams AQ servlet

• Oracle Database server

A Web browser or any other HTTP client can serve as an Oracle Streams AQ client program, sending XML messages conforming to IDAP to the Oracle Streams AQ servlet, which interprets the incoming XML messages. The Oracle Streams AQ servlet connects to the Oracle Database server and performs operations on user queues.

Figure 6-1 Architecture for Performing Oracle Streams AQ Operations Using HTTP

Description of the illustration adque430.gif

6.1.2 Internet Message Payloads

Oracle Streams AQ supports messages of three types: RAW, Oracle object, and Java Message Service (JMS). All these message types can be accessed using SOAP and Web services. If the queue holds messages in RAW, Oracle object, or JMS format, then XML payloads are transformed to the appropriate internal format during enqueue and stored in the queue. During dequeue, when messages are obtained from queues containing messages in any of the preceding formats, they are converted to XML before being sent to the client.

The message payload type depends on the queue type on which the operation is being performed:

RAW Queues

The contents of RAW queues are raw bytes. You must supply the hex representation of the message payload in the XML message. For example, <raw>023f4523</raw>.

Oracle Object Type Queues

For Oracle object type queues that are not JMS queues (that is, they are not type AQ$_JMS_*), the type of the payload depends on the type specified while creating the queue table that holds the queue. The content of the XML elements must map to the attributes of the object type of the queue table.

JMS Type Queues/Topics

For queues with JMS types (that is, those with payloads of type AQ$_JMS_*), there are four XML elements, depending on the JMS type. IDAP supports queues or topics with the following JMS types:

• TextMessage

• MapMessage

• BytesMessage

• ObjectMessage

JMS queues with payload type StreamMessage are not supported through IDAP.

6.1.3 Configuring the Web Server to Authenticate Users Sending POST Requests

After the servlet is installed, the Web server must be configured to authenticate all users that send POST requests to the Oracle Streams AQ servlet. The Oracle Streams AQ servlet allows only authenticated users to access the servlet. If the user is not authenticated, then an error is returned by the servlet.

The Web server can be configured in multiple ways to restrict access. Some of the common techniques are basic authentication (username/password) over SSL and client certificates. Consult your Web server documentation to see how you can restrict access to servlets.

In the context of the Oracle Streams AQ servlet, the username that is used to connect to the Web server is known as the Oracle Streams AQ HTTP agent or Oracle Streams AQ Internet user.

6.1.4 Client Requests Using HTTP

An Oracle Streams AQ client begins a request to the Oracle Streams AQ servlet using HTTP by opening a connection to the server. The client logs in to the server using HTTP basic authentication (with or without SSL) or SSL certificate-based client authentication. The client constructs an XML message representing the send, publish, receive or register request.

The client sends an HTTP POST to the servlet at the remote server.

6.1.5 Oracle Streams AQ Servlet Responses Using HTTP

The server accepts the client HTTP(S) connection and authenticates the user (Oracle Streams AQ agent) specified by the client. The server receives the POST request and invokes the Oracle Streams AQ servlet.

If this is the first request from this client, then a new HTTP session is created. The XML message is parsed and its contents are validated. If a session ID is passed by the client in the HTTP headers, then this operation is performed in the context of that session.

The servlet determines which object (queue/topic) the agent is trying to perform operations on. The servlet looks through the list of database users that map to this Oracle Streams AQ agent. If any one of these users has privileges to access the queue/topic specified in the request, then the Oracle Streams AQ servlet superuser creates a session on behalf of this user.

If no transaction is active in the HTTP session, then a new database transaction is started. Subsequent requests in the session are part of the same transaction until an explicit COMMIT or ROLLBACK request is made. The effects of the transaction are visible only after it is committed. If the transaction remains inactive for 120 seconds, then it is automatically terminated.

The requested operation is performed. The response is formatted as an XML message and sent back the client. The response also includes the session ID in the HTTP headers as a cookie.

6.1.6 Oracle Streams AQ Propagation Using HTTP and HTTPS

You can propagate over HTTP and HTTPS (HTTP over SSL) instead of Oracle Net Services. HTTP, unlike Oracle Net Services, is easy to configure for firewalls. The background process doing propagation pushes messages to an Oracle Streams AQ servlet that enqueues them into the destination database, as shown in Figure 6-2.

Figure 6-2 HTTP Oracle Streams AQ Propagation

Description of the illustration adque445.gif

You can set up any application to use Oracle Streams AQ HTTP propagation without any change to the existing code. An application using Oracle Streams AQ HTTP propagation can easily switch back to Net Services propagation just by re-creating the database link with a Net Services connection string, without any other changes.

6.3.1 SOAP Message Structure

SOAP structures a message request or response as follows:

• SOAP Envelope

• SOAP Header

• SOAP Body

6.3.2 SOAP Method Invocation

A method invocation is performed by creating the request header and body and processing the returned response header and body. The request and response headers can consist of standard transport protocol-specific and extended headers.

SOAPMethodName: http://ns.oracle.com/AQ/schemas/access#AQXmlSend

6.4.1 IDAP Client Requests for Enqueue

Client send and publish requests use AQXmlSend to enqueue to a single-consumer queue and AQXmlPublish to enqueue to multiconsumer queues/topics

AQXmlSend and AQXmlPublish contain the following elements:

• producer_options

• message_set

• message_header

• message_payload

• AQXmlCommit

producer_options

This is a required element. It contains the following child elements:

• destination

  This element is required. It specifies the queue/topic to which messages are to be sent. It has an optional lookup_type attribute, which determines how the destination value is interpreted. If lookup_type is DATABASE, which is the default, then the destination is interpreted as schema.queue_name. If lookup_type is LDAP, then the LDAP server is used to resolve the destination.

• visibility

  This element is optional. It determines when an enqueue becomes visible. The default is ON_COMMIT, which makes the enqueue visible when the current transaction commits. If IMMEDIATE is specified, then the effects of the enqueue are visible immediately after the request is completed. The enqueue is not part of the current transaction. The operation constitutes a transaction on its own.

• transformation

  This element is optional. It specifies the PL/SQL transformation to be invoked before the message is enqueued.

message_set

This is a required element and contains one or more messages. Each message consists of a message_header and a message_payload.

message_header

This element is optional. It contains the following child elements:

• sender_id

  If a message_header element is included, then it must contain a sender_id element, which specifies an application-specific identifier. The sender_id element can contain agent_name, address, protocol, and agent_alias elements. The agent_alias element resolves to a name, address, and protocol using LDAP.

• message_id

  This element is optional. It is a unique identifier of the message, supplied during dequeue.

• correlation

  This element is optional. It is the correlation identifier of the message.

• delay

  This element is optional. It specifies the duration in seconds after which a message is available for processing.

• expiration

  This element is optional. It specifies the duration in seconds that a message is available for dequeuing. This parameter is an offset from the delay. By default messages never expire. If a message is not dequeued before it expires, then it is moved to an exception queue in the EXPIRED state.

• priority

  This element is optional. It specifies the priority of the message. The priority can be any number, including negative numbers. A smaller number indicates higher priority.

• recipient_list

  This element is optional. It is a list of recipients which overrides the default subscriber list. Each recipient is represented in recipient_list by a recipient element, which can contain agent_name, address, protocol, and agent_alias elements. The agent_alias element resolves to a name, address, and protocol using LDAP.

• message_state

  This element is optional. It specifies the state of the message. It is filled in automatically during dequeue. If message_state is 0, then the message is ready to be processed. If it is 1, then the message delay has not yet been reached. If it is 2, then the message has been processed and is retained. If it is 3, then the message has been moved to an exception queue.

• exception_queue

  This element is optional. It specifies the name of the queue to which the message is moved if the number of unsuccessful dequeue attempts has exceeded max_retries or the message has expired. All messages in the exception queue are in the EXPIRED state.

  If the exception queue specified does not exist at the time of the move, then the message is moved to the default exception queue associated with the queue table, and a warning is logged in the alert log. If the default exception queue is used, then the parameter returns a NULL value at dequeue time.

message_payload

This is a required element. It can contain different elements based on the payload type of the destination queue/topic. The different payload types are described in "IDAP Client Requests for Dequeue".

AQXmlCommit

This is an optional empty element. If it is included, then the transaction is committed at the end of the request.

6.4.2 IDAP Client Requests for Dequeue

Client requests for dequeue use AQXmlReceive, which contains the following elements:

• consumer_options

• AQXmlCommit

consumer_options

This is a required element. It contains the following child elements:

• destination

  This element is required. It specifies the queue/topic from which messages are to be received. The destination element has an optional lookup_type attribute, which determines how the destination value is interpreted. If lookup_type is DATABASE, which is the default, then the destination is interpreted as schema.queue_name. If lookup_type is LDAP, then the LDAP server is used to resolve the destination.

• consumer_name

  This element is optional. It specifies the name of the consumer. Only those messages matching the consumer name are accessed. If a queue is not set up for multiple consumers, then this field should not be specified.

• wait_time

  This element is optional. It specifies the number of seconds to wait if there is no message currently available which matches the search criteria.

• selector

  This element is optional. It specifies criteria used to select the message. It can contain child elements correlation, message_id, or condition.

  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.

  To specify dequeue conditions on a message payload, use attributes of the object type in clauses. You must prefix each attribute with tab.user_data as a qualifier to indicate the specific column of the queue table that stores the payload.

  A dequeue condition element cannot exceed 4000 characters.

  Note:

  When a dequeue condition or correlation identifier is used, the order of the messages dequeued is indeterminate, and the sort order of the queue is not honored.

• visibility

  This element is optional. It determines when a dequeue becomes visible. The default is ON_COMMIT, which makes the dequeue visible when the current transaction commits. If IMMEDIATE is specified, then the effects of the dequeue are visible immediately after the request is completed. The dequeue is not part of the current transaction. The operation constitutes a transaction on its own.

• dequeue_mode

  This element is optional. It specifies the locking action associated with the dequeue. The possible values are REMOVE, BROWSE, and LOCKED.

  REMOVE is the default and causes the message to be read and deleted. The message can be retained in the queue table based on the retention properties. BROWSE reads the message without acquiring any lock on it. This is equivalent to a select statement. LOCKED reads the message and obtains a write lock on it. The lock lasts for the duration of the transaction. This is equivalent to a select for update statement.

• navigation_mode

  This element is optional. It specifies the position of the message that is retrieved. First, the position is determined. Second, the search criterion is applied. Finally, the message is retrieved. Possible values are FIRST_MESSAGE, NEXT_MESSAGE, and NEXT_TRANSACTION.

  FIRST_MESSAGE retrieves the first message which is available and which matches the search criteria. This resets the position to the beginning of the queue. NEXT_MESSAGE is the default and retrieves the next message which is available and which matches the search criteria. If the previous message belongs to a message group, then Oracle Streams AQ retrieves the next available message which matches the search criteria and which belongs to the message group.NEXT_TRANSACTION skips the remainder of the current transaction group and retrieves the first message of the next transaction group. This option can only be used if message grouping is enabled for the current queue.

• transformation

  This element is optional. It specifies the PL/SQL transformation to be invoked after the message is dequeued.

AQXmlCommit

This is an optional empty element. If it is included, then the transaction is committed at the end of the request.

6.4.3 IDAP Client Requests for Registration

Client requests for registration use AQXmlRegister, which must contain a register_options element. The register_options element contains the following child elements:

• destination

  This element is required. It specifies the queue/topic on which notifications are registered. The destination element has an optional lookup_type attribute, which determines how the destination value is interpreted. If lookup_type is DATABASE, which is the default, then the destination is interpreted as schema.queue_name. If lookup_type is LDAP, then the LDAP server is used to resolve the destination.

• consumer_name

  This element is optional. It specifies the consumer name for multiconsumer queues or topics. This parameter must not be specified for single-consumer queues.

• notify_url

  This element is required. It specifies where notification is sent when a message is enqueued. The form can be http://url, mailto://email address or plsql://pl/sql procedure.

6.4.4 IDAP Client Requests to Commit a Transaction

A request to commit all actions performed by the user in a session uses AQXmlCommit. A commit request has the following format:

<?xml version="1.0"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
      <AQXmlCommit xmlns="http://ns.oracle.com/AQ/schemas/access"/>
   </Body>
</Envelope>

6.4.5 IDAP Client Requests to Roll Back a Transaction

A request to roll back all actions performed by the user in a session uses AQXmlRollback. Actions performed with IMMEDIATE visibility are not rolled back. An IDAP client rollback request has the following format:

<?xml version="1.0"?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
      <AQXmlRollback xmlns="http://ns.oracle.com/AQ/schemas/access"/>
   </Body>
</Envelope>

6.4.6 IDAP Server Response to an Enqueue Request

The response to an enqueue request to a single-consumer queue uses AQXmlSendResponse. It contains the following elements:

• status_response

  This element contains child elements status_code, error_code, and error_message. The status_code element takes value 0 for success or -1 for failure. The error_code element contains an Oracle error code. The error_message element contains a description of the error.

• send_result

  This element contains child elements destination and message_id. The destination element specifies where the message was sent. The message_id element uniquely identifies every message sent.

The response to an enqueue request to a multiconsumer queue or topic uses AQXmlPublishResponse. It contains the following elements:

• status_response

  This element contains child elements status_code, error_code, and error_message. The status_code element takes value 0 for success or -1 for failure. The error_code element contains an Oracle error code. The error_message element contains a description of the error.

• publish_result

  This element contains child elements destination and message_id. The destination element specifies where the message was sent. The message_id element uniquely identifies every message sent.

6.4.7 IDAP Server Response to a Dequeue Request

The response to a dequeue request uses AQXmlReceiveResponse. It contains the following elements:

• status_response

  This element contains child elements status_code, error_code, and error_message. The status_code element takes value 0 for success or -1 for failure. The error_code element contains an Oracle error code. The error_message element contains a description of the error.

• receive_result

  This element contains child elements destination and message_set. The destination element specifies where the message was sent. The message_set element specifies the set of messages dequeued.

6.4.8 IDAP Server Response to a Register Request

The response to a register request uses AQXmlRegisterResponse. It contains the status_response element described in "IDAP Server Response to a Dequeue Request".

6.4.9 IDAP Commit Response

The response to a commit request uses AQXmlCommitResponse. It contains the status_response element described in "IDAP Server Response to a Dequeue Request". The response to a commit request has the following format:

<?xml version = '1.0'?>
<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
   <Body>
      <AQXmlCommitResponse xmlns="http://ns.oracle.com/AQ/schemas/access">
         <status_response>
            <status_code>0</status_code>
         </status_response>
      </AQXmlCommitResponse>
   </Body>
</Envelope>

6.4.10 IDAP Rollback Response

The response to a rollback request uses AQXmlRollbackResponse. It contains the status_response element described in "IDAP Server Response to a Dequeue Request".

6.4.11 IDAP Notification

When an event for which a client has registered occurs, a notification is sent to the client at the URL specified in the REGISTER request using AQXmlNotification. It contains the following elements:

• notification_options

  This element has child elements destination and consumer_name. The destination element specifies the destination queue/topic on which the event occurred. The consumer_name element specifies the consumer name for which the even occurred. It applies only to multiconsumer queues/topics.

• message_set

  This element specifies the set of message properties.

6.4.12 IDAP Response in Case of Error

In case of an error in any of the preceding requests, a FAULT is generated. The FAULT element contains the following elements:

• faultcode

  This element specifies the error code for the fault.

• faultstring

  This element indicates a client error or a server error. A client error means that the request is not valid. A server error indicates that the Oracle Streams AQ servlet has not been set up correctly.

• detail

  This element contains the status_response element, which is described in "IDAP Server Response to a Dequeue Request".