This chapter describes new features of the Oracle Database 11g Release 1 (11.1) and provides pointers to additional information. There are no new features for 11g Release 2 (11.2).
The following notification enhancements are introduced:
AQ Event Notification Infrastructure provides asynchronous communication of database events from the suppliers/publishers of their events to the consumers/registrations. The event monitor sends these notifications. In order to meet the demands of increased notification use, the notification server in 11g is enhanced to a parallel notification server consisting of a coordinator and a set of subordinate processes. The parallel notification server offers a capability to process a greater volume of notifications, faster notification processing and lower shared memory use for staging notification events.
Sometimes a very large number of events occur in the database and it is important that applications not be overwhelmed with notifications. The preferred strategy is for notifications to be grouped and delivered at application-specified intervals and in application-specified formats. Oracle Streams AQ provides the infrastructure for notification grouping by time for AQ and DBCHANGE namespaces. Users have the option of specifying the grouping time interval and the predefined format in which to be notified at the end of those grouping intervals. Users can also specify when to start sending grouping notifications and how many times to send grouping notifications.
The following sections describe diagnosability:
This release adds new performance views for persistent messaging statistics and notification statistics. The Automatic Workload Repository (AWR) has also been enhanced for displaying queues with the most persistent messaging operations, allowing for easier diagnosability of AQ performance problems.
New dictionary views are provided to simplify subscription management for Oracle Streams Advanced Queuing. DBA_SUBSCR_REGISTRATIONS and USER_SUBSCR_REGISTRATIONS identify registered subscriptions, as well as detail information on the subscriptions. Runtime statistics for notifications are available with the V$SUBSCR_REGISTRATION_STATS view.
Export import of queues is now fully supported at queue table level granularity. The user only needs to export the queue table. All the queues in the queue table, primary object grants, related objects like views, IOTs, rules are automatically exported.
EMON PL/SQL notifications are executed by background jobs. In this release these jobs are DBMS_SCHEDULER jobs and are no longer conducted by DBMS_JOBS.
The init.ora parameter job_queue_processes does not need to be set for PL/SQL notifications or AQ propagations.
AQ propagation is now likewise handled by DBMS_SCHEDULER jobs rather than DBMS_JOBS. Additionally, propagation takes advantage of the event based scheduling features of DBMS_SCHEDULER for better scalability.
The following Messaging Gateway enhancements are introduced:
The Oracle Scheduler will be used to start Messaging Gateway agents. Messaging Gateway will leverage the Oracle Scheduler RAC service feature so that a Messaging Gateway agent is associated with a database service. If the instance on which a Messaging Gateway agent is running fails or is shutdown, the Oracle Scheduler will automatically restart the agent on another instance supporting that service.
Messaging Gateway is enhanced to enable multiple agents per instance and database. With this enhancement, you can now statically partition propagation jobs based on functionality, organizations, or workload and assign them to different MGW agents hosted by different database instances on different machines. This not only enables MGW to scale, but also enables propagation job grouping and isolation, which is important when MGW is used in a complicated application integration environment.
An enhanced PL/SQL API consolidates the propagation subscriber and the propagation schedule into a new propagation job. It is now easier to create and schedule a propagation job for the messaging gateway.
A list of error messages is provided to aid you in troubleshooting problems.
This chapter describes the components of the Oracle Streams Advanced Queuing (AQ) Java Message Service (JMS) operational interface that are specific to publish/subscribe operations. Components that are shared by point-to-point and publish/subscribe are described in Chapter 15, "Oracle JMS Shared Interfaces".
This chapter contains these topics:
Creating a Connection with Default ConnectionFactory Parameters
Creating a TopicConnection with an Open OracleOCIConnectionPool
Publishing Messages Specifying Delivery Mode, Priority and TimeToLive
Creating a DurableSubscriber for a JMS Topic Without Selector
Creating a DurableSubscriber for an Oracle Object Type Topic Without Selector
Creating a DurableSubscriber for an Oracle Object Type Topic With Selector
Creating a Remote Subscriber for Oracle Object Type Messages
Unsubscribing a Durable Subscription for a Remote Subscriber
Creating a TopicReceiver for a Topic of Standard JMS Type Messages
Creating a TopicReceiver for a Topic of Oracle Object Type Messages
Creating a TopicBrowser for Standard JMS Messages, Locking Messages
Creating a TopicBrowser for Oracle Object Type Messages, Locking Messages
public javax.jms.Connection createConnection(
java.lang.String username,
java.lang.String password)
throws JMSException
This method creates a connection supporting both point-to-point and publish/subscribe operations with the specified username and password. This method is new and supports JMS version 1.1 specifications. It has the following parameters:
| Parameter | Description |
|---|---|
username | Name of the user connecting to the database for queuing |
password | Password for creating the connection to the server |
public javax.jms.Connection createConnection()
throws JMSException
This method creates a connection supporting both point-to-point and publish/subscribe operations with default ConnectionFactory parameters. This method is new and supports JMS version 1.1 specifications. If the ConnectionFactory properties do not contain a default username and password, then it throws a JMSException.
public javax.jms.TopicConnection createTopicConnection(
java.lang.String username,
java.lang.String password)
throws JMSException
This method creates a TopicConnection with the specified username/password. It has the following parameters:
| Parameter | Description |
|---|---|
username | Name of the user connecting to the database for queuing |
password | Password for creating the connection to the server |
Example 14-1 Creating a TopicConnection with Username/Password
TopicConnectionFactory tc_fact = AQjmsFactory.getTopicConnectionFactory("sun123", "oratest", 5521, "thin");
/* Create a TopicConnection using a username/password */
TopicConnection tc_conn = tc_fact.createTopicConnection("jmsuser", "jmsuser");
public static javax.jms.TopicConnection createTopicConnection(
java.sql.Connection jdbc_connection)
throws JMSException
This method creates a TopicConnection with open JDBC connection. It has the following parameter:
| Parameter | Description |
|---|---|
jdbc_connection | Valid open connection to database |
public static javax.jms.TopicConnection createTopicConnection(
oracle.jdbc.pool.OracleOCIConnectionPool cpool)
throws JMSException
This method creates a TopicConnection with an open OracleOCIConnectionPool. It is static and has the following parameter:
| Parameter | Description |
|---|---|
cpool | Valid open OCI connection pool to the database |
public javax.jms.Session createSession(boolean transacted,
int ack_mode)
throws JMSException
This method creates a Session supporting both point-to-point and publish/subscribe operations. It is new and supports JMS version 1.1 specifications. It has the following parameters:
| Parameter | Description |
|---|---|
transacted | If set to true, then the session is transactional |
ack_mode | Indicates whether the consumer or the client will acknowledge any messages it receives. It is ignored if the session is transactional. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE. |
public javax.jms.TopicSession createTopicSession(boolean transacted,
int ack_mode)
throws JMSException
This method creates a TopicSession. It has the following parameters:
| Parameter | Description |
|---|---|
transacted | If set to true, then the session is transactional |
ack_mode | Indicates whether the consumer or the client will acknowledge any messages it receives. It is ignored if the session is transactional. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE. |
public javax.jms.TopicPublisher createPublisher(javax.jms.Topic topic)
throws JMSException
This method creates a TopicPublisher. It has the following parameter:
| Parameter | Description |
|---|---|
topic | Topic to publish to, or null if this is an unidentified producer |
public void publish(javax.jms.Message message)
throws JMSException
This method publishes a message with minimal specification. It has the following parameter:
| Parameter | Description |
|---|---|
message | Message to send |
The TopicPublisher uses the default values for message priority (1) and timeToLive (infinite).
Example 14-6 Publishing Without Specifying Topic
/* Publish without specifying topic */
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicPublisher publisher1;
Topic shipped_orders;
int myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME",
"MYSID",
myport,
"oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
/* create TopicSession */
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
/* get shipped orders topic */
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE",
"Shipped_Orders_Topic");
publisher1 = jms_sess.createPublisher(shipped_orders);
/* create TextMessage */
TextMessage jms_sess.createTextMessage();
/* publish without specifying the topic */
publisher1.publish(text_message);
Example 14-7 Publishing Specifying Correlation and Delay
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicPublisher publisher1;
Topic shipped_orders;
int myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME",
"MYSID",
myport,
"oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE",
"Shipped_Orders_Topic");
publisher1 = jms_sess.createPublisher(shipped_orders);
/* Create TextMessage */
TextMessage jms_sess.createTextMessage();
/* Set correlation and delay */
/* Set correlation */
jms_sess.setJMSCorrelationID("FOO");
/* Set delay of 30 seconds */
jms_sess.setLongProperty("JMS_OracleDelay", 30);
/* Publish */
publisher1.publish(text_message);
public void publish(javax.jms.Topic topic, javax.jms.Message message)
throws JMSException
This method publishes a message specifying the topic. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to publish to |
message | Message to send |
If the TopicPublisher has been created with a default topic, then the topic parameter may not be specified in the publish() call. If a topic is specified, then that value overrides the default in the TopicPublisher. If the TopicPublisher has been created without a default topic, then the topic must be specified with the publish() call.
Example 14-8 Publishing Specifying Topic
/* Publish specifying topic */
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicPublisher publisher1;
Topic shipped_orders;
int myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
'MYHOSTNAME', 'MYSID', myport, 'oci8');
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
/* create TopicPublisher */
publisher1 = jms_sess.createPublisher(null);
/* get topic object */
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
'WS', 'Shipped_Orders_Topic');
/* create text message */
TextMessage jms_sess.createTextMessage();
/* publish specifying the topic */
publisher1.publish(shipped_orders, text_message);
public void publish(javax.jms.Topic topic,
javax.jms.Message message,
oracle.jms.AQjmsAgent[] recipient_list,
int deliveryMode,
int priority,
long timeToLive)
throws JMSException
This method publishes a message specifying delivery mode, priority and TimeToLive. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to which to publish the message (overrides the default topic of the MessageProducer) |
message | Message to publish |
recipient_list | List of recipients to which the message is published. Recipients are of type AQjmsAgent. |
deliveryMode | PERSISTENT or NON_PERSISTENT (only PERSISTENT is supported in this release) |
priority | Priority for this message |
timeToLive | Message lifetime in milliseconds (zero is unlimited) |
Example 14-9 Publishing Specifying Priority and TimeToLive
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicPublisher publisher1;
Topic shipped_orders;
int myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
publisher1 = jms_sess.createPublisher(shipped_orders);
/* Create TextMessage */
TextMessage jms_sess.createTextMessage();
/* Publish message with priority 1 and time to live 200 seconds */
publisher1.publish(text_message, DeliveryMode.PERSISTENT, 1, 200000);
public void publish(javax.jms.Message message,
oracle.jms.AQjmsAgent[] recipient_list)
throws JMSException
This method publishes a message specifying a recipient list overriding topic subscribers. It has the following parameters:
| Parameter | Description |
|---|---|
message | Message to publish |
recipient_list | List of recipients to which the message is published. Recipients are of type AQjmsAgent. |
Example 14-10 Publishing Specifying a Recipient List Overriding Topic Subscribers
/* Publish specifying priority and timeToLive */
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicPublisher publisher1;
Topic shipped_orders;
int myport = 5521;
AQjmsAgent[] recipList;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection(" jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
publisher1 = jms_sess.createPublisher(shipped_orders);
/* create TextMessage */
TextMessage jms_sess.createTextMessage();
/* create two receivers */
recipList = new AQjmsAgent[2];
recipList[0] = new AQjmsAgent(
"ES", "ES.shipped_orders_topic", AQAgent.DEFAULT_AGENT_PROTOCOL);
recipList[1] = new AQjmsAgent(
"WS", "WS.shipped_orders_topic", AQAgent.DEFAULT_AGENT_PROTOCOL);
/* publish message specifying a recipient list */
publisher1.publish(text_message, recipList);
public javax.jms.TopicSubscriber createDurableSubscriber(
javax.jms.Topic topic,
java.lang.String subs_name)
throws JMSException
This method creates a DurableSubscriber for a JMS topic without selector. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Non-temporary topic to subscribe to |
subs_name | Name used to identify this subscription |
Exclusive Access to Topics
CreateDurableSubscriber() and Unsubscribe() both require exclusive access to their target topics. If there are pending JMS send(), publish(), or receive() operations on the same topic when these calls are applied, then exception ORA - 4020 is raised. There are two solutions to the problem:
Limit calls to createDurableSubscriber() and Unsubscribe() to the setup or cleanup phase when there are no other JMS operations pending on the topic. That makes sure that the required resources are not held by other JMS operational calls.
Call TopicSession.commit before calling createDurableSubscriber() or Unsubscribe().
Example 14-11 Creating a Durable Subscriber for a JMS Topic Without Selector
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int myport = 5521;
AQjmsAgent[] recipList;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME",
"MYSID",
myport,
"oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE",
"Shipped_Orders_Topic");
/* create a durable subscriber on the shipped_orders topic*/
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders,
'WesternShipping');
public javax.jms.TopicSubscriber createDurableSubscriber(
javax.jms.Topic topic,
java.lang.String subs_name,
java.lang.String messageSelector,
boolean noLocal)
throws JMSException
This method creates a durable subscriber for a JMS topic with selector. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Non-temporary topic to subscribe to |
subs_name | Name used to identify this subscription |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
noLocal | If set to true, then it inhibits the delivery of messages published by its own connection |
A client can change an existing durable subscription by creating a durable TopicSubscriber with the same name and a different messageSelector. An unsubscribe call is needed to end the subscription to the topic.
Example 14-12 Creating a Durable Subscriber for a JMS Topic With Selector
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int myport = 5521;
AQjmsAgent[] recipList;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
/* create a subscriber */
/* with condition on JMSPriority and user property 'Region' */
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders, 'WesternShipping',
"JMSPriority > 2 and Region like 'Western%'", false);
public javax.jms.TopicSubscriber createDurableSubscriber(
javax.jms.Topic topic,
java.lang.String subs_name,
java.lang.Object payload_factory)
throws JMSException
This method creates a durable subscriber for an Oracle object type topic without selector. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Non-temporary topic to subscribe to |
subs_name | Name used to identify this subscription |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
Example 14-13 Creating a Durable Subscriber for an Oracle Object Type Topic Without Selector
/* Subscribe to an ADT queue */
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int my[port = 5521;
AQjmsAgent[] recipList;
/* the java mapping of the oracle object type created by J Publisher */
ADTMessage message;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
/* create a subscriber, specifying the correct CustomDatumFactory */
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders, 'WesternShipping', AQjmsAgent.getFactory());
public javax.jms.TopicSubscriber createDurableSubscriber(
javax.jms.Topic topic,
java.lang.String subs_name,
java.lang.String messageSelector,
boolean noLocal,
java.lang.Object payload_factory)
throws JMSException
This method creates a durable subscriber for an Oracle object type topic with selector. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Non-temporary topic to subscribe to |
subs_name | Name used to identify this subscription |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
noLocal | If set to true, then it inhibits the delivery of messages published by its own connection |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
Example 14-14 Creating a Durable Subscriber for an Oracle Object Type Topic With Selector
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int myport = 5521;
AQjmsAgent[] recipList;
/* the java mapping of the oracle object type created by J Publisher */
ADTMessage message;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
/* create a subscriber, specifying correct CustomDatumFactory and selector */
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders, "WesternShipping",
"priority > 1 and tab.user_data.region like 'WESTERN %'", false,
ADTMessage.getFactory());
A transformation can be supplied when sending/publishing a message to a queue/topic. The transformation is applied before putting the message into the queue/topic.
The application can specify a transformation using the setTransformation interface in the AQjmsQueueSender and AQjmsTopicPublisher interfaces.
Example 14-15 Sending Messages to a Destination Using a Transformation
Suppose that the orders that are processed by the order entry application should be published to WS_bookedorders_topic. The transformation OE2WS (defined in the previous section) is supplied so that the messages are inserted into the topic in the correct format.
public void ship_bookedorders(
TopicSession jms_session,
AQjmsADTMessage adt_message)
{
TopicPublisher publisher;
Topic topic;
try
{
/* get a handle to the WS_bookedorders_topic */
topic = ((AQjmsSession)jms_session).getTopic("WS", "WS_bookedorders_topic");
publisher = jms_session.createPublisher(topic);
/* set the transformation in the publisher */
((AQjmsTopicPublisher)publisher).setTransformation("OE2WS");
publisher.publish(topic, adt_message);
}
catch (JMSException ex)
{
System.out.println("Exception :" ex);
}
}
A transformation can also be specified when creating topic subscribers using the CreateDurableSubscriber() call. The transformation is applied to the retrieved message before returning it to the subscriber. If the subscriber specified in the CreateDurableSubscriber() call already exists, then its transformation is set to the specified transformation.
Example 14-16 Specifying Transformations for Topic Subscribers
The Western Shipping application subscribes to the OE_bookedorders_topic with the transformation OE2WS. This transformation is applied to the messages and the returned message is of Oracle object type WS.WS_orders.
Suppose that the WSOrder java class has been generated by Jpublisher to map to the Oracle object WS.WS_order:
public AQjmsAdtMessage retrieve_bookedorders(TopicSession jms_session)
{
TopicSubscriber subscriber;
Topic topic;
AQjmsAdtMessage msg = null;
try
{
/* get a handle to the OE_bookedorders_topic */
topic = ((AQjmsSession)jms_session).getTopic("OE", "OE_bookedorders_topic");
/* create a subscriber with the transformation OE2WS */
subs = ((AQjmsSession)jms_session).createDurableSubscriber(
topic, 'WShip', null, false, WSOrder.getFactory(), "OE2WS");
msg = subscriber.receive(10);
}
catch (JMSException ex)
{
System.out.println("Exception :" ex);
}
return (AQjmsAdtMessage)msg;
}
public void createRemoteSubscriber(javax.jms.Topic topic,
oracle.jms.AQjmsAgent remote_subscriber,
java.lang.String messageSelector)
throws JMSException
This method creates a remote subscriber for topics of JMS messages. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to subscribe to |
remote_subscriber | AQjmsAgent that refers to the remote subscriber |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
Oracle Streams Advanced Queuing allows topics to have remote subscribers, for example, subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the local and remote topic.
Remote subscribers can be a specific consumer at the remote topic or all subscribers at the remote topic. A remote subscriber is defined using the AQjmsAgent structure. An AQjmsAgent consists of a name and address. The name refers to the consumer_name at the remote topic. The address refers to the remote topic. Its syntax is schema.topic_name[@dblink].
To publish messages to a particular consumer at the remote topic, the subscription_name of the recipient at the remote topic must be specified in the name field of AQjmsAgent, and the remote topic must be specified in the address field. To publish messages to all subscribers of the remote topic, the name field of AQjmsAgent must be set to null.
Example 14-17 Creating a Remote Subscriber for Topics of JMS Messages
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int my[port = 5521;
AQjmsAgent remoteAgent;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
remoteAgent = new AQjmsAgent("WesternRegion", "WS.shipped_orders_topic", null);
/* create a remote subscriber (selector is null )*/
subscriber1 = ((AQjmsSession)jms_sess).createRemoteSubscriber(
shipped_orders, remoteAgent, null);
public void createRemoteSubscriber(javax.jms.Topic topic,
oracle.jms.AQjmsAgent remote_subscriber,
java.lang.String messageSelector,
java.lang.Object payload_factory)
throws JMSException
This method creates a remote subscriber for topics of Oracle object type messages. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to subscribe to |
remote_subscriber | AQjmsAgent that refers to the remote subscriber |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
Oracle Streams Advanced Queuing allows topics to have remote subscribers, for example, subscribers at other topics in the same or different database. In order to use remote subscribers, you must set up propagation between the local and remote topic.
Remote subscribers can be a specific consumer at the remote topic or all subscribers at the remote topic. A remote subscriber is defined using the AQjmsAgent structure. An AQjmsAgent consists of a name and address. The name refers to the consumer_name at the remote topic. The address refers to the remote topic. Its syntax is schema.topic_name[@dblink].
To publish messages to a particular consumer at the remote topic, the subscription_name of the recipient at the remote topic must be specified in the name field of AQjmsAgent, and the remote topic must be specified in the address field. To publish messages to all subscribers of the remote topic, the name field of AQjmsAgent must be set to null.
Example 14-18 Creating a Remote Subscriber for Topics of Oracle Object Type Messages
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int my[port = 5521;
AQjmsAgent remoteAgent;
ADTMessage message;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
/* create TopicSession */
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
/* get the Shipped order topic */
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
/* create a remote agent */
remoteAgent = new AQjmsAgent("WesternRegion", "WS.shipped_orders_topic", null);
/* create a remote subscriber with null selector*/
subscriber1 = ((AQjmsSession)jms_sess).createRemoteSubscriber(
shipped_orders, remoteAgent, null, message.getFactory);
|
Note: AQ does not support the use of multiple dblink to the same destination. As a workaround, use a single database link for each destination. |
Oracle Streams Advanced Queuing allows a remote subscriber, that is a subscriber at another database, to subscribe to a topic.
Transformations can be specified when creating remote subscribers using the createRemoteSubscriber() call. This enables propagation of messages between topics of different formats. When a message published at a topic meets the criterion of a remote subscriber, Oracle Streams Advanced Queuing automatically propagates the message to the queue/topic at the remote database specified for the remote subscriber. If a transformation is also specified, then Oracle Streams Advanced Queuing applies the transformation to the message before propagating it to the queue/topic at the remote database.
Example 14-19 Specifying Transformations for Remote Subscribers
A remote subscriber is created at the OE.OE_bookedorders_topic so that messages are automatically propagated to the WS.WS_bookedorders_topic. The transformation OE2WS is specified when creating the remote subscriber so that the messages reaching the WS_bookedorders_topic have the correct format.
Suppose that the WSOrder java class has been generated by Jpublisher to map to the Oracle object WS.WS_order
public void create_remote_sub(TopicSession jms_session)
{
AQjmsAgent subscriber;
Topic topic;
try
{
/* get a handle to the OE_bookedorders_topic */
topic = ((AQjmsSession)jms_session).getTopic("OE", "OE_bookedorders_topic");
subscriber = new AQjmsAgent("WShip", "WS.WS_bookedorders_topic");
((AQjmsSession )jms_session).createRemoteSubscriber(
topic, subscriber, null, WSOrder.getFactory(),"OE2WS");
}
catch (JMSException ex)
{
System.out.println("Exception :" ex);
}
}
public void unsubscribe(javax.jms.Topic topic,
java.lang.String subs_name)
throws JMSException
This method unsubscribes a durable subscription for a local subscriber. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Non-temporary topic to unsubscribe |
subs_name | Name used to identify this subscription |
Example 14-20 Unsubscribing a Durable Subscription for a Local Subscriber
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession jms_sess;
TopicSubscriber subscriber1;
Topic shipped_orders;
int myport = 5521;
AQjmsAgent[] recipList;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
/* unsusbcribe "WesternShipping" from shipped_orders */
jms_sess.unsubscribe(shipped_orders, "WesternShipping");
public void unsubscribe(javax.jms.Topic topic,
oracle.jms.AQjmsAgent remote_subscriber)
throws JMSException
This method unsubscribes a durable subscription for a remote subscriber. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Non-temporary topic to unsubscribe |
remote_subscriber | AQjmsAgent that refers to the remote subscriber. The address field of the AQjmsAgent cannot be null. |
Example 14-21 Unsubscribing a Durable Subscription for a Remote Subscriber
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
Topic shipped_orders;
int myport = 5521;
AQjmsAgent remoteAgent;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"OE", "Shipped_Orders_Topic");
remoteAgent = new AQjmsAgent("WS", "WS.Shipped_Orders_Topic", null);
/* unsubscribe the remote agent from shipped_orders */
((AQjmsSession)jms_sess).unsubscribe(shipped_orders, remoteAgent);
public oracle.jms.AQjmsTopicReceiver createTopicReceiver(
javax.jms.Topic topic,
java.lang.String receiver_name,
java.lang.String messageSelector)
throws JMSException
This method creates a TopicReceiver for a topic of standard JMS type messages. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to access |
receiver_name | Name of message receiver |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
Oracle Streams Advanced Queuing allows messages to be sent to specified recipients. These receivers may or may not be subscribers of the topic. If the receiver is not a subscriber to the topic, then it receives only those messages that are explicitly addressed to it. This method must be used order to create a TopicReceiver object for consumers that are not durable subscribers.
Example 14-22 Creating a TopicReceiver for Standard JMS Type Messages
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = ull;
TopicSession jms_sess;
Topic shipped_orders;
int myport = 5521;
TopicReceiver receiver;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"WS", "Shipped_Orders_Topic");
receiver = ((AQjmsSession)jms_sess).createTopicReceiver(
shipped_orders, "WesternRegion", null);
public oracle.jms.AQjmsTopicReceiver createTopicReceiver(
javax.jms.Topic topic,
java.lang.String receiver_name,
java.lang.String messageSelector,
java.lang.Object payload_factory)
throws JMSException
This method creates a TopicReceiver for a topic of Oracle object type messages with selector. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to access |
receiver_name | Name of message receiver |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
Oracle Streams Advanced Queuing allows messages to be sent to all subscribers of a topic or to specified recipients. These receivers may or may not be subscribers of the topic. If the receiver is not a subscriber to the topic, then it receives only those messages that are explicitly addressed to it. This method must be used order to create a TopicReceiver object for consumers that are not durable subscribers.
Example 14-23 Creating a TopicReceiver for Oracle Object Type Messages
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
Topic shipped_orders;
int myport = 5521;
TopicReceiver receiver;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"WS", "Shipped_Orders_Topic");
receiver = ((AQjmsSession)jms_sess).createTopicReceiver(
shipped_orders, "WesternRegion", null);
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic,
java.lang.String cons_name,
java.lang.String messageSelector)
throws JMSException
This method creates a TopicBrowser for topics with TextMessage, StreamMessage, ObjectMessage, BytesMessage, or MapMessage message bodies. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to access |
cons_name | Name of the durable subscriber or consumer |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
Example 14-24 Creating a TopicBrowser Without a Selector
/* Create a browser without a selector */ TopicSession jms_session; TopicBrowser browser; Topic topic; browser = ((AQjmsSession) jms_session).createBrowser(topic, "SUBS1");
Example 14-25 Creating a TopicBrowser With a Specified Selector
/* Create a browser for topics with a specified selector */
TopicSession jms_session;
TopicBrowser browser;
Topic topic;
/* create a Browser to look at messages with correlationID = RUSH */
browser = ((AQjmsSession) jms_session).createBrowser(
topic, "SUBS1", "JMSCorrelationID = 'RUSH'");
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic,
java.lang.String cons_name,
java.lang.String messageSelector,
boolean locked)
throws JMSException
This method creates a TopicBrowser for topics with text, stream, objects, bytes or map messages, locking messages while browsing. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to access |
cons_name | Name of the durable subscriber or consumer |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
locked | If set to true, then messages are locked as they are browsed (similar to a SELECT for UPDATE) |
Example 14-26 Creating a TopicBrowser Without a Selector, Locking Messages While Browsing
/* Create a browser without a selector */
TopicSession jms_session;
TopicBrowser browser;
Topic topic;
browser = ((AQjmsSession) jms_session).createBrowser(
topic, "SUBS1", true);
Example 14-27 Creating a TopicBrowser With a Specified Selector, Locking Messages
/* Create a browser for topics with a specified selector */
TopicSession jms_session;
TopicBrowser browser;
Topic topic;
/* create a Browser to look at messages with correlationID = RUSH in
lock mode */
browser = ((AQjmsSession) jms_session).createBrowser(
topic, "SUBS1", "JMSCorrelationID = 'RUSH'", true);
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic,
java.lang.String cons_name,
java.lang.String messageSelector,
java.lang.Object payload_factory)
throws JMSException
This method creates a TopicBrowser for topics of Oracle object type messages. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to access |
cons_name | Name of the durable subscriber or consumer |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
The CustomDatumFactory for a particular Java class that maps to the SQL object type payload can be obtained using the getFactory static method. Assume the topic test_topic has payload of type SCOTT.EMPLOYEE and the Java class that is generated by Jpublisher for this Oracle object type is called Employee. The Employee class implements the CustomDatum interface. The CustomDatumFactory for this class can be obtained by using the Employee.getFactory() method.
Example 14-28 Creating a TopicBrowser for AdtMessage Messages
/* Create a browser for a Topic with AdtMessage messages of type EMPLOYEE*/
TopicSession jms_session
TopicBrowser browser;
Topic test_topic;
browser = ((AQjmsSession) jms_session).createBrowser(
test_topic, "SUBS1", Employee.getFactory());
public oracle.jms.TopicBrowser createBrowser(javax.jms.Topic topic,
java.lang.String cons_name,
java.lang.String messageSelector,
java.lang.Object payload_factory,
boolean locked)
throws JMSException
This method creates a TopicBrowser for topics of Oracle object type messages, locking messages while browsing. It has the following parameters:
| Parameter | Description |
|---|---|
topic | Topic to access |
cons_name | Name of the durable subscriber or consumer |
messageSelector | Only messages with properties matching the messageSelector expression are delivered. A value of null or an empty string indicates that there is no messageSelector for the message consumer. |
payload_factory | CustomDatumFactory or ORADataFactory for the Java class that maps to the Oracle ADT |
locked | If set to true, then messages are locked as they are browsed (similar to a SELECT for UPDATE) |
|
Note: CustomDatum support will be deprecated in a future release. Use ORADataFactory payload factories instead. |
Example 14-29 Creating a TopicBrowser for AdtMessage Messages, Locking Messages
/* Create a browser for a Topic with AdtMessage messages of type EMPLOYEE* in
lock mode/
TopicSession jms_session
TopicBrowser browser;
Topic test_topic;
browser = ((AQjmsSession) jms_session).createBrowser(
test_topic, "SUBS1", Employee.getFactory(), true);
public void purgeSeen()
throws JMSException
This method browses messages using a TopicBrowser. Use methods in java.util.Enumeration to go through the list of messages. Use the method purgeSeen in TopicBrowser to purge messages that have been seen during the current browse.
Example 14-30 Creating a TopicBrowser with a Specified Selector
/* Create a browser for topics with a specified selector */
public void browse_rush_orders(TopicSession jms_session)
TopicBrowser browser;
Topic topic;
ObjectMessage obj_message
BolOrder new_order;
Enumeration messages;
/* get a handle to the new_orders topic */
topic = ((AQjmsSession) jms_session).getTopic("OE", "OE_bookedorders_topic");
/* create a Browser to look at RUSH orders */
browser = ((AQjmsSession) jms_session).createBrowser(
topic, "SUBS1", "JMSCorrelationID = 'RUSH'");
/* Browse through the messages */
for (messages = browser.elements() ; message.hasMoreElements() ;)
{obj_message = (ObjectMessage)message.nextElement();}
/* Purge messages seen during this browse */
browser.purgeSeen()
Advanced Queuing User's Guide
11g Release 2 (11.2)
E11013-04
July 2011
Oracle Streams Advanced Queuing User's Guide, 11g Release 2 (11.2)
E11013-04
Copyright © 1996, 2011, Oracle and/or its affiliates. All rights reserved.
Primary Authors: Denis Raphaely, Maitreyee Chaliha
Contributing Authors: Neerja Bhatt, Charles Hall
Contributor: Longxing Deng, Stella Kister, John Leinaweaver, Qiang Liu, Anil Madan, Abhishek Saxena, James Wilson
This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.
This chapter describes the basic operational Java Message Service (JMS) administrative interface to Oracle Streams Advanced Queuing (AQ).
This chapter contains these topics:
Users should never directly call methods in the DBMS_AQIN package, but they do need the EXECUTE privilege on DBMS_AQIN. Use the following syntax to accomplish this:
GRANT EXECUTE ON DBMS_AQIN to user;
You can register a ConnectionFactory four ways:
public static int registerConnectionFactory(java.sql.Connection connection,
java.lang.String conn_name,
java.lang.String hostname,
java.lang.String oracle_sid,
int portno,
java.lang.String driver,
java.lang.String type)
throws JMSException
This method registers a QueueConnectionFactory or TopicConnectionFactory through the database to a Lightweight Directory Access Protocol (LDAP) server with JDBC connection parameters. This method is static and has the following parameters:
| Parameter | Description |
|---|---|
connection | JDBC connection used in registration |
conn_name | Name of the connection to be registered |
hostname | Name of the host running Oracle Streams Advanced Queuing |
oracle_sid | Oracle system identifier |
portno | Port number |
driver | JDBC driver type |
type | Connection factory type (QUEUE or TOPIC) |
The database connection passed to registerConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE. After registration, you can look up the connection factory using Java Naming and Directory Interface (JNDI).
Example 12-1 Registering Through the Database Using JDBC Connection Parameters
String url; java.sql.connection db_conn; url = "jdbc:oracle:thin:@sun-123:1521:db1"; db_conn = DriverManager.getConnection(url, "scott", "tiger"); AQjmsFactory.registerConnectionFactory( db_conn, "queue_conn1", "sun-123", "db1", 1521, "thin", "queue");
public static int registerConnectionFactory(java.sql.Connection connection,
java.lang.String conn_name,
java.lang.String jdbc_url,
java.util.Properties info,
java.lang.String type)
throws JMSException
This method registers a QueueConnectionFactory or TopicConnectionFactory through the database with a JDBC URL to LDAP. It is static and has the following parameters:
| Parameter | Description |
|---|---|
connection | JDBC connection used in registration |
conn_name | Name of the connection to be registered |
jdbc_url | URL to connect to |
info | Properties information |
portno | Port number |
type | Connection factory type (QUEUE or TOPIC) |
The database connection passed to registerConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE. After registration, you can look up the connection factory using JNDI.
public static int registerConnectionFactory(java.util.Hashtable env,
java.lang.String conn_name,
java.lang.String hostname,
java.lang.String oracle_sid,
int portno,
java.lang.String driver,
java.lang.String type)
throws JMSException
This method registers a QueueConnectionFactory or TopicConnectionFactory through LDAP with JDBC connection parameters to LDAP. It is static and has the following parameters:
| Parameter | Description |
|---|---|
env | Environment of LDAP connection |
conn_name | Name of the connection to be registered |
hostname | Name of the host running Oracle Streams Advanced Queuing |
oracle_sid | Oracle system identifier |
portno | Port number |
driver | JDBC driver type |
type | Connection factory type (QUEUE or TOPIC) |
The hash table passed to registerConnectionFactory() must contain all the information to establish a valid connection to the LDAP server. Furthermore, the connection must have write access to the connection factory entries in the LDAP server (which requires the LDAP user to be either the database itself or be granted GLOBAL_AQ_USER_ROLE). After registration, look up the connection factory using JNDI.
Example 12-3 Registering Through LDAP Using JDBC Connection Parameters
Hashtable env = new Hashtable(5, 0.75f);
/* the following statements set in hashtable env:
* service provider package
* the URL of the ldap server
* the distinguished name of the database server
* the authentication method (simple)
* the LDAP username
* the LDAP user password
*/
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://sun-456:389");
env.put("searchbase", "cn=db1,cn=Oraclecontext,cn=acme,cn=com");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=db1aqadmin,cn=acme,cn=com");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
AQjmsFactory.registerConnectionFactory(env,
"queue_conn1",
"sun-123",
"db1",
1521,
"thin",
"queue");
public static int registerConnectionFactory(java.util.Hashtable env,
java.lang.String conn_name,
java.lang.String jdbc_url,
java.util.Properties info,
java.lang.String type)
throws JMSException
This method registers a QueueConnectionFactory or TopicConnectionFactory through LDAP with JDBC connection parameters to LDAP. It is static and has the following parameters:
| Parameter | Description |
|---|---|
env | Environment of LDAP connection |
conn_name | Name of the connection to be registered |
jdbc_url | URL to connect to |
| info | Properties information |
type | Connection factory type (QUEUE or TOPIC) |
The hash table passed to registerConnectionFactory() must contain all the information to establish a valid connection to the LDAP server. Furthermore, the connection must have write access to the connection factory entries in the LDAP server (which requires the LDAP user to be either the database itself or be granted GLOBAL_AQ_USER_ROLE). After registration, look up the connection factory using JNDI.
Example 12-4 Registering Through LDAP Using a JDBC URL
String url;
Hashtable env = new Hashtable(5, 0.75f);
/* the following statements set in hashtable env:
* service provider package
* the URL of the ldap server
* the distinguished name of the database server
* the authentication method (simple)
* the LDAP username
* the LDAP user password
*/
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://sun-456:389");
env.put("searchbase", "cn=db1,cn=Oraclecontext,cn=acme,cn=com");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=db1aqadmin,cn=acme,cn=com");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
url = "jdbc:oracle:thin:@sun-123:1521:db1";
AQjmsFactory.registerConnectionFactory(env, "topic_conn1", url, null, "topic");
You can unregister a queue/topic ConnectionFactory in LDAP two ways:
public static int unregisterConnectionFactory(java.sql.Connection connection,
java.lang.String conn_name)
throws JMSException
This method unregisters a QueueConnectionFactory or TopicConnectionFactory in LDAP. It is static and has the following parameters:
| Parameter | Description |
|---|---|
connection | JDBC connection used in registration |
conn_name | Name of the connection to be registered |
The database connection passed to unregisterConnectionFactory() must be granted AQ_ADMINISTRATOR_ROLE.
public static int unregisterConnectionFactory(java.util.Hashtable env,
java.lang.String conn_name)
throws JMSException
This method unregisters a QueueConnectionFactory or TopicConnectionFactory in LDAP. It is static and has the following parameters:
| Parameter | Description |
|---|---|
env | Environment of LDAP connection |
conn_name | Name of the connection to be registered |
The hash table passed to unregisterConnectionFactory() must contain all the information to establish a valid connection to the LDAP server. Furthermore, the connection must have write access to the connection factory entries in the LDAP server (which requires the LDAP user to be either the database itself or be granted GLOBAL_AQ_USER_ROLE).
Example 12-6 Unregistering Through LDAP
Hashtable env = new Hashtable(5, 0.75f);
/* the following statements set in hashtable env:
* service provider package
* the distinguished name of the database server
* the authentication method (simple)
* the LDAP username
* the LDAP user password
*/
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://sun-456:389");
env.put("searchbase", "cn=db1,cn=Oraclecontext,cn=acme,cn=com");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=db1aqadmin,cn=acme,cn=com");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
url = "jdbc:oracle:thin:@sun-123:1521:db1";
AQjmsFactory.unregisterConnectionFactory(env, "queue_conn1");
This section contains these topics:
Getting a QueueConnectionFactory with JDBC Connection Parameters
Getting a TopicConnectionFactory with JDBC Connection Parameters
Getting a QueueConnectionFactory or TopicConnectionFactory in LDAP
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
java.lang.String jdbc_url,
java.util.Properties info)
throws JMSException
This method gets a QueueConnectionFactory with JDBC URL. It is static and has the following parameters:
| Parameter | Description |
|---|---|
jdbc_url | URL to connect to |
| info | Properties information |
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
java.lang.String hostname,
java.lang.String oracle_sid,
int portno,
java.lang.String driver)
throws JMSException
This method gets a QueueConnectionFactory with JDBC connection parameters. It is static and has the following parameters:
| Parameter | Description |
|---|---|
hostname | Name of the host running Oracle Streams Advanced Queuing |
oracle_sid | Oracle system identifier |
portno | Port number |
driver | JDBC driver type |
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
java.lang.String jdbc_url,
java.util.Properties info)
throws JMSException
This method ge ts a TopicConnectionFactory with a JDBC URL. It is static and has the following parameters:
| Parameter | Description |
|---|---|
jdbc_url | URL to connect to |
| info | Properties information |
public static javax.jms.TopicConnectionFactory getTopicConnectionFactory(
java.lang.String hostname,
java.lang.String oracle_sid,
int portno,
java.lang.String driver)
throws JMSException
This method gets a TopicConnectionFactory with JDBC connection parameters. It is static and has the following parameters:
| Parameter | Description |
|---|---|
hostname | Name of the host running Oracle Streams Advanced Queuing |
oracle_sid | Oracle system identifier |
portno | Port number |
driver | JDBC driver type |
This method gets a QueueConnectionFactory or TopicConnectionFactory from LDAP.
Example 12-11 Getting a QueueConnectionFactory or TopicConnectionFactory in LDAP
Hashtable env = new Hashtable(5, 0.75f);
DirContext ctx;
queueConnectionFactory qc_fact;
/* the following statements set in hashtable env:
* service provider package
* the URL of the ldap server
* the distinguished name of the database server
* the authentication method (simple)
* the LDAP username
* the LDAP user password
*/
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://sun-456:389");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=db1aquser1,cn=acme,cn=com");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
ctx = new InitialDirContext(env);
ctx = (DirContext)ctx.lookup("cn=OracleDBConnections,cn=db1,cn=Oraclecontext,cn=acme,cn=com");
qc_fact = (queueConnectionFactory)ctx.lookup("cn=queue_conn1");
This method gets a queue or topic from LDAP.
Example 12-12 Getting a Queue or Topic in LDAP
Hashtable env = new Hashtable(5, 0.75f);
DirContext ctx;
topic topic_1;
/* the following statements set in hashtable env:
* service provider package
* the URL of the ldap server
* the distinguished name of the database server
* the authentication method (simple)
* the LDAP username
* the LDAP user password
*/
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://sun-456:389");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=db1aquser1,cn=acme,cn=com");
env.put(Context.SECURITY_CREDENTIALS, "welcome");
ctx = new InitialDirContext(env);
ctx = (DirContext)ctx.lookup("cn=OracleDBQueues,cn=db1,cn=Oraclecontext,cn=acme,cn=com");
topic_1 = (topic)ctx.lookup("cn=topic_1");
public oracle.AQ.AQQueueTable createQueueTable(
java.lang.String owner,
java.lang.String name,
oracle.AQ.AQQueueTableProperty property)
throws JMSException
This method creates a queue table. It has the following parameters:
| Parameter | Description |
|---|---|
owner | Queue table owner (schema) |
| name | Queue table name |
| property | Queue table properties |
If the queue table is used to hold queues, then the queue table must not be multiconsumer enabled (default). If the queue table is used to hold topics, then the queue table must be multiconsumer enabled.
CLOB, BLOB, and BFILE objects are valid attributes for an Oracle Streams Advanced Queuing object type load. However, only CLOB and BLOB can be propagated using Oracle Streams Advanced Queuing propagation in Oracle8i and after.
public oracle.AQ.AQQueueTable getQueueTable(java.lang.String owner,
java.lang.String name)
throws JMSException
This method gets a queue table. It has the following parameters:
| Parameter | Description |
|---|---|
owner | Queue table owner (schema) |
| name | Queue table name |
If the caller that opened the connection is not the owner of the queue table, then the caller must have Oracle Streams Advanced Queuing enqueue/dequeue privileges on queues/topics in the queue table. Otherwise the queue table is not returned.
This section contains these topics:
public javax.jms.Queue createQueue(
oracle.AQ.AQQueueTable q_table,
java.lang.String queue_name,
oracle.jms.AQjmsDestinationProperty dest_property)
throws JMSException
This method creates a queue in a specified queue table. It has the following parameters:
| Parameter | Description |
|---|---|
q_table | Queue table in which the queue is to be created. The queue table must be single-consumer. |
queue_name | Name of the queue to be created |
dest_property | Queue properties |
This method is specific to OJMS. You cannot use standard Java javax.jms.Session objects with it. Instead, you must cast the standard type to the OJMS concrete class oracle.jms.AQjmsSession.
public javax.jms.Topic createTopic(
oracle.AQ.AQQueueTable q_table,
java.lang.String topic_name,
oracle.jms.AQjmsDestinationProperty dest_property)
throws JMSException
This method creates a topic in the publish/subscribe model. It has the following parameters:
| Parameter | Description |
|---|---|
q_table | Queue table in which the queue is to be created. The queue table must be multiconsumer. |
queue_name | Name of the queue to be created |
dest_property | Queue properties |
This method is specific to OJMS. You cannot use standard Java javax.jms.Session objects with it. Instead, you must cast the standard type to the OJMS concrete class oracle.jms.AQjmsSession.
Example 12-16 Creating a Publish/Subscribe Topic
TopicSession t_sess; AQQueueTable q_table; AqjmsDestinationProperty dest_prop; Topic topic; topic = ((AQjmsSessa)t_sess).createTopic(q_table, "jms_t1", dest_prop);
In Example 12-17, if an order cannot be filled because of insufficient inventory, then the transaction processing the order is terminated. The bookedorders topic is set up with max_retries = 4 and retry_delay = 12 hours.Thus, if an order is not filled up in two days, then it is moved to an exception queue.
Example 12-17 Specifying Max Retries and Max Delays in Messages
public BolOrder process_booked_order(TopicSession jms_session)
{
Topic topic;
TopicSubscriber tsubs;
ObjectMessage obj_message;
BolCustomer customer;
BolOrder booked_order = null;
String country;
int i = 0;
try
{
/* get a handle to the OE_bookedorders_topic */
topic = ((AQjmsSession)jms_session).getTopic("WS",
"WS_bookedorders_topic");
/* Create local subscriber - to track messages for Western Region */
tsubs = jms_session.createDurableSubscriber(topic, "SUBS1",
"Region = 'Western' ",
false);
/* wait for a message to show up in the topic */
obj_message = (ObjectMessage)tsubs.receive(10);
booked_order = (BolOrder)obj_message.getObject();
customer = booked_order.getCustomer();
country = customer.getCountry();
if (country == "US")
{
jms_session.commit();
}
else
{
jms_session.rollback();
booked_order = null;
}
}catch (JMSException ex)
{ System.out.println("Exception " + ex) ;}
return booked_order;
}
This section contains these topics:
public void grantSystemPrivilege(java.lang.String privilege,
java.lang.String grantee,
boolean admin_option)
throws JMSException
This method grants Oracle Streams Advanced Queuing system privileges to a user or role.
| Parameter | Description |
|---|---|
privilege | ENQUEUE_ANY, DEQUEUE_ANY or MANAGE_ANY |
grantee | Grantee (user, role, or PUBLIC) |
admin_option | If this is set to true, then the grantee is allowed to use this procedure to grant the system privilege to other users or roles |
Initially only SYS and SYSTEM can use this procedure successfully. Users granted the ENQUEUE_ANY privilege are allowed to enqueue messages to any queues in the database. Users granted the DEQUEUE_ANY privilege are allowed to dequeue messages from any queues in the database. Users granted the MANAGE_ANY privilege are allowed to run DBMS_AQADM calls on any schemas in the database.
public void revokeSystemPrivilege(java.lang.String privilege,
java.lang.String grantee)
throws JMSException
This method revokes Oracle Streams Advanced Queuing system privileges from a user or role. It has the following parameters:
| Parameter | Description |
|---|---|
privilege | ENQUEUE_ANY, DEQUEUE_ANY or MANAGE_ANY |
grantee | Grantee (user, role, or PUBLIC) |
Users granted the ENQUEUE_ANY privilege are allowed to enqueue messages to any queues in the database. Users granted the DEQUEUE_ANY privilege are allowed to dequeue messages from any queues in the database. Users granted the MANAGE_ANY privilege are allowed to run DBMS_AQADM calls on any schemas in the database.
public void grantTopicPrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee,
boolean grant_option)
throws JMSException
This method grants a topic privilege in the publish/subscribe model. Initially only the queue table owner can use this procedure to grant privileges on the topic. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
privilege | ENQUEUE, DEQUEUE, or ALL (ALL means both.) |
grantee | Grantee (user, role, or PUBLIC) |
grant_option | If this is set to true, then the grantee is allowed to use this procedure to grant the system privilege to other users or roles |
public void revokeTopicPrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee)
throws JMSException
This method revokes a topic privilege in the publish/subscribe model. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
privilege | ENQUEUE, DEQUEUE, or ALL (ALL means both.) |
grantee | Revoked grantee (user, role, or PUBLIC) |
public void grantQueuePrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee,
boolean grant_option)
throws JMSException
This method grants a queue privilege in the point-to-point model. Initially only the queue table owner can use this procedure to grant privileges on the queue. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
privilege | ENQUEUE, DEQUEUE, or ALL (ALL means both.) |
grantee | Grantee (user, role, or PUBLIC) |
grant_option | If this is set to true, then the grantee is allowed to use this procedure to grant the system privilege to other users or roles |
public void revokeQueuePrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee)
throws JMSException
This method revokes queue privileges in the point-to-point model. Initially only the queue table owner can use this procedure to grant privileges on the queue. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
privilege | ENQUEUE, DEQUEUE, or ALL (ALL means both.) |
grantee | Revoked grantee (user, role, or PUBLIC) |
To revoke a privilege, the revoker must be the original grantor of the privilege. Privileges propagated through the GRANT option are revoked if the grantor privilege is also revoked.
This section contains these topics:
public void start(javax.jms.Session session,
boolean enqueue,
boolean dequeue)
throws JMSException
This method starts a destination. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
enqueue | If set to TRUE, then enqueue is enabled |
| dequeue | If set to TRUE, then dequeue is enabled |
public void stop(javax.jms.Session session,
boolean enqueue,
boolean dequeue,
boolean wait)
throws JMSException
This method stops a destination. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
enqueue | If set to TRUE, then enqueue is disabled |
| dequeue | If set to TRUE, then dequeue is disabled |
wait | If set to true, then pending transactions on the queue/topic are allowed to complete before the destination is stopped |
public void alter(javax.jms.Session session,
oracle.jms.AQjmsDestinationProperty dest_property)
throws JMSException
This method alters a destination. It has the following properties:
| Parameter | Description |
|---|---|
session | JMS session |
| dest_property | New properties of the queue or topic |
This section contains these topics:
public void schedulePropagation(javax.jms.Session session,
java.lang.String destination,
java.util.Date start_time,
java.lang.Double duration,
java.lang.String next_time,
java.lang.Double latency)
throws JMSException
This method schedules a propagation. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
destination | Database link of the remote database for which propagation is being scheduled. A null string means that propagation is scheduled for all subscribers in the database of the topic. |
start_time | Time propagation starts |
duration | Duration of propagation |
next_time | Next time propagation starts |
latency | Latency in seconds that can be tolerated. Latency is the difference between the time a message was enqueued and the time it was propagated. |
If a message has multiple recipients at the same destination in either the same or different queues, then it is propagated to all of them at the same time.
public void enablePropagationSchedule(javax.jms.Session session,
java.lang.String destination)
throws JMSException
This method enables a propagation schedule. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
destination | Database link of the destination database. A null string means that propagation is to the local database. |
public void alterPropagationSchedule(javax.jms.Session session,
java.lang.String destination,
java.lang.Double duration,
java.lang.String next_time,
java.lang.Double latency)
throws JMSException
This method alters a propagation schedule. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
destination | Database link of the remote database for which propagation is being scheduled. A null string means that propagation is scheduled for all subscribers in the database of the topic. |
duration | Duration of propagation |
next_time | Next time propagation starts |
latency | Latency in seconds that can be tolerated. Latency is the difference between the time a message was enqueued and the time it was propagated. |
public void disablePropagationSchedule(javax.jms.Session session,
java.lang.String destination)
throws JMSException
This method disables a propagation schedule. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
destination | Database link of the destination database. A null string means that propagation is to the local database. |
public void unschedulePropagation(javax.jms.Session session,
java.lang.String destination)
throws JMSException
This method unschedules a previously scheduled propagation. It has the following parameters:
| Parameter | Description |
|---|---|
session | JMS session |
destination | Database link of the destination database. A null string means that propagation is to the local database. |
This chapter describes the Oracle Streams Advanced Queuing (AQ) basic components.
This chapter contains the following topics:
Enumerated Constants in the Oracle Streams Advanced Queuing Administrative Interface
Enumerated Constants in the Oracle Streams Advanced Queuing Operational Interface
object_name := VARCHAR2 object_name := [schema_name.]name
This component names database objects. This naming convention applies to queues, queue tables, and object types.
Names for objects are specified by an optional schema name and a name. If the schema name is not specified, then the current schema is assumed. The name must follow the reserved character guidelines in Oracle Database SQL Language Reference. The schema name, agent name, and the object type name can each be up to 30 bytes long. However, queue names and queue table names can be a maximum of 24 bytes.
type_name := VARCHAR2
type_name := object_type | "RAW"
This component defines queue types. The maximum number of attributes in the object type is limited to 900.
To store payloads of type RAW, Oracle Streams Advanced Queuing creates a queue table with a LOB column as the payload repository. The size of the payload is limited to 32K bytes of data. Because LOB columns are used for storing RAW payload, the Oracle Streams Advanced Queuing administrator can choose the LOB tablespace and configure the LOB storage by constructing a LOB storage string in the storage_clause parameter during queue table creation time.
|
Note: Payloads containing LOBs require users to grant explicitSelect, Insert and Update privileges on the queue table for doing enqueues and dequeues. |
TYPE AQ$_AGENT IS OBJECT ( name VARCHAR2(30), address VARCHAR2(1024), protocol NUMBER);
This component identifies a producer or a consumer of a message.
All consumers that are added as subscribers to a multiconsumer queue must have unique values for the AQ$_AGENT parameters. Two subscribers cannot have the same values for the NAME, ADDRESS, and PROTOCOL attributes for the AQ$_AGENT type. At least one of the three attributes must be different for two subscribers.
You can add subscribers by repeatedly using the DBMS_AQADM.ADD_SUBSCRIBER procedure up to a maximum of 1024 subscribers for a multiconsumer queue.
This type has three attributes:
name
This attribute specifies the name of a producer or consumer of a message. It can be the name of an application or a name assigned by an application. A queue can itself be an agent, enqueuing or dequeuing from another queue. The name must follow the reserved character guidelines in Oracle Database SQL Language Reference.
address
This attribute is interpreted in the context of protocol. If protocol is 0 (default), then address is of the form [schema.]queue[@dblink].
protocol
This attribute specifies the protocol to interpret the address and propagate the message. The default value is 0.
TYPE AQ$_RECIPIENT_LIST_T IS TABLE OF aq$_agent
INDEX BY BINARY_INTEGER;
This component identifies the list of agents that receive a message.
TYPE AQ$_AGENT_LIST_T IS TABLE OF aq$_agent
INDEX BY BINARY INTEGER;
This component identifies the list of agents for DBMS_AQ.LISTEN to listen for.
TYPE AQ$_SUBSCRIBER_LIST_T IS TABLE OF aq$_agent
INDEX BY BINARY INTEGER;
This component identifies the list of subscribers that subscribe to this queue.
TYPE AQ$_REG_INFO_LIST AS VARRAY(1024) OF sys.aq$_reg_info;
This component identifies the list of registrations to a queue.
TYPE AQ$_POST_INFO_LIST AS VARRAY(1024) OF sys.aq$_post_info;
This component identifies the list of anonymous subscriptions to which messages are posted.
TYPE SYS.AQ$_REG_INFO IS OBJECT ( name VARCHAR2(128), namespace NUMBER, callback VARCHAR2(4000), context RAW(2000) DEFAULT NULL, qosflags NUMBER, timeout NUMBER ntfn_grouping_class NUMBER, ntfn_grouping_value NUMBER DEFAULT 600, ntfn_grouping_type NUMBER, ntfn_grouping_start_time TIMESTAMP WITH TIME ZONE, ntfn_grouping_repeat_count NUMBER);
This component identifies a producer or a consumer of a message. Its attributes are described in the following list. Attributes qosflags and timeout are part of Oracle Streams Advanced Queuing 10g Release 2 (10.2) notification enhancements.
Table 2-1 AQ$_REG_INFO Type Attributes
| Attribute | Description |
|---|---|
|
|
Specifies the name of the subscription. The subscription name is of the form |
|
|
Specifies the namespace of the subscription. To receive notification from Oracle Streams AQ queues, the namespace must be |
|
|
Specifies the action to be performed on message notification. For HTTP notifications, use |
|
|
Specifies the context that is to be passed to the callback function |
|
|
Can be set to one or more of the following values to specify the notification quality of service:
|
|
|
Currently, only the following flag can be set to specify criterion for grouping. The default value will be 0. If
|
|
|
Time-period of grouping notifications specified in seconds, meaning the time after which grouping notification would be sent periodically until |
|
|
|
|
|
Notification grouping start time. Notification grouping can start from a user-specified time that should a valid timestamp with time zone. If |
|
|
Grouping notifications will be sent as many times as specified by the notification grouping repeat count and after that revert to regular notifications. The ntfn_grouping_repeat_count, if not specified, will default to
|
TYPE SYS.AQ$_DESCRIPTOR IS OBJECT ( queue_name VARCHAR2(61), consumer_name VARCHAR2(30), msg_id RAW(16), msg_prop MSG_PROP_T, gen_desc AQ$_NTFN_DESCRIPTOR, msgid_array SYS.AQ$_NTFN_MSGID_ARRAY, ntfnsRecdInGrp NUMBER);
This component specifies the Oracle Streams Advanced Queuing descriptor received by Oracle Streams Advanced Queuing PL/SQL callbacks upon notification. It has the following attributes:
Table 2-2 AQ$_DESCRIPTOR Attributes
| Attribute | Description |
|---|---|
|
|
Name of the queue in which the message was enqueued which resulted in the notification |
|
|
Name of the consumer for the multiconsumer queue |
|
|
Identification number of the message |
|
|
Message properties specified by the |
|
|
Indicates the timeout specifications |
|
|
Group notification message ID list |
|
|
Notifications received in group |
The message properties type msg_prop_t has the following components:
TYPE AQ$_MSG_PROP_T IS OBJECT( priority number, delay number, expiration number, correlation varchar2(128), attempts number, recipent_list aq$_recipient_list_t, exception_queue varchar2(51), enqueue_time date, state number, sender_id aq$_agent, original_misgid raw(16), delivery_mode number);
The timeout specifications type AQ$_NTFN_DESCRIPTOR has a single component:
TYPE AQ$_NTFN_DESCRIPTOR IS OBJECT( NTFN_FLAGS number);
NTFN_FLAGS is set to 1 if the notifications are already removed after a stipulated timeout; otherwise the value is 0.
TYPE SYS.AQ$_POST_INFO IS OBJECT ( name VARCHAR2(128), namespace NUMBER, payload RAW(2000));
This component specifies anonymous subscriptions to which you want to post messages. It has three attributes:
name
This attribute specifies the name of the anonymous subscription to which you want to post.
namespace
This attribute specifies the namespace of the anonymous subscription. To receive notifications from other applications using DBMS_AQ.POST or OCISubscriptionPost(), the namespace must be DBMS_AQ.NAMESPACE_ANONYMOUS.
payload
This attribute specifies the payload to be posted to the anonymous subscription. The default is NULL.
TYPE SYS.AQ$_NTFN_MSGID_ARRAY AS VARRAY(1073741824)OF RAW(16);
This component is for storing grouping notification data for AQ namespace, value 230 which is the max varray size.
When enumerated constants such as INFINITE, TRANSACTIONAL, and NORMAL_QUEUE are selected as values, the symbol must be specified with the scope of the packages defining it. All types associated with the administrative interfaces must be prepended with DBMS_AQADM. For example:
DBMS_AQADM.NORMAL_QUEUE
Table 2-3 lists the enumerated constants in the Oracle Streams Advanced Queuing administrative interface.
Table 2-3 Enumerated Constants in the Oracle Streams Advanced Queuing Administrative Interface
| Parameter | Options |
|---|---|
|
| |
|
| |
|
| |
|
|
|
|
Note: Nonpersistent queues are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Oracle recommends that you use buffered messaging instead. |
When using enumerated constants such as BROWSE, LOCKED, and REMOVE, the PL/SQL constants must be specified with the scope of the packages defining them. All types associated with the operational interfaces must be prepended with DBMS_AQ. For example:
DBMS_AQ.BROWSE
Table 2-4 lists the enumerated constants in the Oracle Streams Advanced Queuing operational interface.
Table 2-4 Enumerated Constants in the Oracle Streams Advanced Queuing Operational Interface
| Parameter | Options |
|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
A number of Streams AQ or Streams tasks are executed in the background. These include converting messages with DELAY specified into the READY state, expiring messages, moving messages to exception queues, spilling and recovering of buffered messages, and similar operations.
These are executed by a set of AQ background process. These include a coordinator process, name QMNC (link), which dynamically spawns subordinate processes Qxx as needed. The number of subordinate processes is determined automatically and tuned constantly.
It is no longer necessary to set AQ_TM_PROCESSES when Oracle Streams AQ or Streams is used. If a value is specified, that value is taken into account when starting the Qxx processes. However, the number of Qxx processes can be different from what was specified by AQ_TM_PROCESSES.
QMNC only runs when you use queues and create new queues. It affects Streams Replication and Messaging users.
No separate API is needed to disable or enable the background processes. This is controlled by setting AQ_TM_PROCESSES to zero or nonzero. Oracle recommends, however, that you leave the AQ_TM_PROCESSES parameter unspecified and let the system autotune.
|
Note: If you want to disable the Queue Monitor Coordinator, then you must setAQ_TM_PROCESSES = 0 in your pfile or spfile. Oracle strongly recommends that you do NOT set AQ_TM_PROCESSES = 0. If you are using Oracle Streams, then setting this parameter to zero (which Oracle Database respects no matter what) can cause serious problems. |
Propagation and PL/SQL notifications are handled by job queue (Jnnn) processes. The parameter JOB_QUEUE_PROCESSES no longer needs to be specified. The database scheduler automatically starts the job queue processes that are needed for the propagation and notification jobs.
You can access Oracle Streams Advanced Queuing (AQ) over the Internet by using Simple Object Access Protocol (SOAP). Internet Data Access Presentation (IDAP) is the SOAP specification for Oracle Streams Advanced Queuing operations. IDAP defines XML message structure for the body of the SOAP request. An IDAP-structured message is transmitted over the Internet using HTTP.
Users can register for notifications using the IDAP interface.
This chapter contains these topics:
|
See Also:
|
This section contains these topics:
Oracle Streams Advanced Queuing Internet Operations Architecture
Configuring the Web Server to Authenticate Users Sending POST Requests
Oracle Streams Advanced Queuing Servlet Responses Using HTTP
Oracle Streams Advanced Queuing Propagation Using HTTP and HTTPS
Figure 6-1 shows the architecture for performing Oracle Streams Advanced Queuing operations over HTTP. The major components are:
Oracle Streams Advanced Queuing client program
Web server/servlet runner hosting the Oracle Streams Advanced Queuing servlet
Oracle Database server
A Web browser or any other HTTP client can serve as an Oracle Streams Advanced Queuing client program, sending XML messages conforming to IDAP to the Oracle Streams Advanced Queuing servlet, which interprets the incoming XML messages. The Oracle Streams Advanced Queuing servlet connects to the Oracle Database server and performs operations on user queues.
Figure 6-1 Architecture for Performing Oracle Streams Advanced Queuing Operations Using HTTP
Oracle Streams Advanced Queuing 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:
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>.
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.
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.
After the servlet is installed, the Web server must be configured to authenticate all users that send POST requests to the Oracle Streams Advanced Queuing servlet. The Oracle Streams Advanced Queuing 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 Advanced Queuing servlet, the username that is used to connect to the Web server is known as the Oracle Streams Advanced Queuing HTTP agent or Oracle Streams Advanced Queuing Internet user.
An Oracle Streams Advanced Queuing client begins a request to the Oracle Streams Advanced Queuing 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.
|
See Also: Table 1-3, "Oracle Streams Advanced Queuing XML Demonstrations" for the locations of AQ XML demonstrations illustratingPOST requests using HTTP |
After a client is authenticated and connects to the Oracle Streams Advanced Queuing servlet, an HTTP session is created on behalf of the user. The first request in the session also implicitly starts a new database transaction. This transaction remains open until it is explicitly committed or terminated. The responses from the servlet includes the session ID in the HTTP headers as cookies.
If the client wishes to continue work in the same transaction, then it must include this HTTP header containing the session ID cookie in subsequent requests. This is automatically accomplished by most Web browsers. However, if the client is using a Java or C client to post requests, then this must be accomplished programmatically.
|
See Also: Table 1-3, "Oracle Streams Advanced Queuing XML Demonstrations" for the locations of AQ XML demonstrations illustrating a Java program used to post requests as part of the same session |
An explicit commit or rollback must be applied to end the transaction. The commit or rollback requests can also be included as part of other Oracle Streams Advanced Queuing operations.
The server accepts the client HTTP(S) connection and authenticates the user (Oracle Streams Advanced Queuing agent) specified by the client. The server receives the POST request and invokes the Oracle Streams Advanced Queuing 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 Advanced Queuing agent. If any one of these users has privileges to access the queue/topic specified in the request, then the Oracle Streams Advanced Queuing 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.
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 Advanced Queuing servlet that enqueues them into the destination database, as shown in Figure 6-2.
Figure 6-2 HTTP Oracle Streams Advanced Queuing Propagation
You can set up any application to use Oracle Streams Advanced Queuing HTTP propagation without any change to the existing code. An application using Oracle Streams Advanced Queuing 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.
Follow these steps to deploy the AQ XML servlet using OC4J:
For JDK1.2.x or JDK1.3.x, include the following in your CLASSPATH:
ORACLE_HOME/jdbc/lib/classes12.zip ORACLE_HOME/jdbc/lib/nls_charset12.zip ORACLE_HOME/jlib/javax-ssl-1_1.jar ORACLE_HOME/jlib/jndi.jar ORACLE_HOME/jlib/jssl-1_1.jar ORACLE_HOME/jlib/jta.jar ORACLE_HOME/jlib/orai18n.jar ORACLE_HOME/jlib/orai18n-collation.jar ORACLE_HOME/jlib/orai18n-mapping.jar ORACLE_HOME/jlib/orai18n-utility.jar ORACLE_HOME/lib/http_client.jar ORACLE_HOME/lib/lclasses12.zip ORACLE_HOME/lib/servlet.jar ORACLE_HOME/lib/xmlparserv2.jar ORACLE_HOME/lib/xschema.jar ORACLE_HOME/lib/xsu12.jar ORACLE_HOME/rdbms/jlib/aqapi.jar ORACLE_HOME/rdbms/jlib/aqxml.jar ORACLE_HOME/rdbms/jlib/jmscommon.jar ORACLE_HOME/rdbms/jlib/xdb.jar ORACLE_HOME/rdbms/jlib/xsu12.jar
For JDK1.4.x, include the following in your CLASSPATH:
ORACLE_HOME/jdbc/lib/ojdbc14.jar ORACLE_HOME/jlib/javax-ssl-1_1.jar ORACLE_HOME/jlib/jndi.jar ORACLE_HOME/jlib/jssl-1_1.jar ORACLE_HOME/jlib/jta.jar ORACLE_HOME/jlib/orai18n.jar ORACLE_HOME/jlib/orai18n-collation.jar ORACLE_HOME/jlib/orai18n-mapping.jar ORACLE_HOME/jlib/orai18n-utility.jar ORACLE_HOME/lib/http_client.jar ORACLE_HOME/lib/lclasses12.zip ORACLE_HOME/lib/servlet.jar ORACLE_HOME/lib/xmlparserv2.jar ORACLE_HOME/lib/xschema.jar ORACLE_HOME/lib/xsu12.jar ORACLE_HOME/rdbms/jlib/aqapi.jar ORACLE_HOME/rdbms/jlib/aqxml.jar ORACLE_HOME/rdbms/jlib/jmscommon.jar ORACLE_HOME/rdbms/jlib/xdb.jar
|
Note: http_client.jar, jssl-1_1.jar, and javax-ssl-1_1.jar are required by HTTPClient used in AQHttp.java and AQHttpRq.java. |
Compile AQHttpRq.java:
cd ORACLE_HOME/rdbms/demo
javac AQHttpRq.java AQHttp.java
Set the following database initialization parameters to the indicated values:
job_queue_processes=2 compatible=10.2.0
Restart the database and listener.
Set up queues and authenticate users for restricted access.
|
See Also: aqxmlREADME.txt and aqxmldmo.sql in ORACLE_HOME/rdbms/demo for additional information. |
Deploy the servlet and start the OC4J instance:
cd ORACLE_HOME/bin
sh aqxmlctl deploy
sh aqxmlctl start
|
Note: Usesh aqxmlctl stop to stop the OC4J instance. The deploy servlet and start OC4J instance steps might have been done during your Oracle Database installation. You can verify this in the following steps. |
Check the status of the servlet and information on the protocol and port number used for deploying the servlet in the following files:
ORACLE_HOME/rdbms/demo/aqxml.ini ORACLE_HOME/oc4j/j2ee/OC4J_AQ/config/rmi.xml ORACLE_HOME/oc4j/j2ee/OC4J_AQ/config/http-web-site.xml
Point a web browser to the following URL:
https://hostname:portnumber/aqserv/servlet/AQDemoServlet
where hostname is the server name, and portnumber is the value discovered in the previous step. After you respond to a username/password prompt, the servlet displays:
Sample AQ Servlet AQxmlServlet is working!
Create an SSL Certificate and generate a keystore. The following files provide examples:
ORACLE_HOME/rdbms/demo/aqxmloc4j.cert ORACLE_HOME/rdbms/demo/keystore
|
See Also: Keytool documentation athttp://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html |
The following tags in ORACLE_HOME/oc4j/j2ee/OC4J_AQ/config/http-web-site.xml indicate that the Web site is secure and keystore is used for SSL authentication:
<web-site port="443" secure="true">
....
<ssl-config
keystore="ORACLE_HOME/oc4j/j2ee/home/keystore"
keystore-password="welcome" />
</web-site>
To make the site access only HTTP requests, remove secure="true" and <ssl-config> from http-web-site.xml.
Stop and restart the AQ XML servlet:
sh aqxmlctl stop sh aqxmlctl start
Internet Data Access Presentation (IDAP) uses the Content-Type of text/xml to specify the body of the SOAP request. XML provides the presentation for IDAP request and response messages as follows:
All request and response tags are scoped in the SOAP namespace.
Oracle Streams Advanced Queuing operations are scoped in the IDAP namespace.
The sender includes namespaces in IDAP elements and attributes in the SOAP body.
The receiver processes SOAP messages that have correct namespaces and returns an invalid request error for requests with incorrect namespaces.
The SOAP namespace has the value http://schemas.xmlsoap.org/soap/envelope/
The IDAP namespace has the value http://ns.oracle.com/AQ/schemas/access
SOAP structures a message request or response as follows:
This is the root or top element in an XML tree. Its tag is SOAP:Envelope. SOAP defines a global attribute SOAP:encodingStyle that indicates serialization rules used instead of those described by the SOAP specification. This attribute can appear on any element and is scoped to that element and all child elements not themselves containing such an attribute. Omitting this attribute means that type specification has been followed unless overridden by a parent element.
The SOAP envelope also contains namespace declarations and additional attributes, provided they are namespace-qualified. Additional namespace-qualified subelements can follow the body.
This is the first element under the root. Its tag is SOAP:Header. A SOAP header passes necessary information, such as the transaction identifier. The header is encoded as a child of the SOAP:Envelope XML element. Headers are identified by the name element and are namespace-qualified. A header entry is encoded as an embedded element.
This is the Oracle Streams Advanced Queuing XML document. Its tag is SOAP:Body, and it contains a first subelement whose name is the method name. This method request element contains elements for each input and output parameter. The element names are the parameter names. The body also contains SOAP:Fault, indicating information about an error. The Oracle Streams Advanced Queuing XML document has the namespace http://ns.oracle.com/AQ/schemas/access
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.
The POST method within the HTTP request header performs the SOAP method invocation. The request should include the header SOAPMethodName, whose value indicates the method to be invoked on the target. The value is of the form URI#method name. For example:
SOAPMethodName: http://ns.oracle.com/AQ/schemas/access#AQXmlSend
The URI used for the interface must match the implied or specified namespace qualification of the method name element in the SOAP:Body part of the payload. The method name must not include the "#" character.
SOAP method invocation consists of a method request and optionally a method response. The SOAP method request and method response are an HTTP request and response, respectively, whose contents are XML documents consisting of the root and mandatory body elements. These XML documents are referred to as SOAP payloads in the rest of this chapter.
A SOAP payload is defined as follows:
The SOAP root element is the top element in the XML tree.
The SOAP payload headers contain additional information that must travel with the request.
The method request is represented as an XML element with additional elements for parameters. It is the first child of the SOAP:Body element. This request can be one of the Oracle Streams Advanced Queuing XML client requests described in the next section.
The response is the return value or an error or exception that is passed back to the client.
At the receiving site, a request can have one of the following outcomes:
The HTTP infrastructure on the receiving site is able to receive and process the request. In this case, the HTTP infrastructure passes the headers and body to the SOAP infrastructure.
The HTTP infrastructure on the receiving site cannot receive and process the request. In this case, the result is an HTTP response containing an HTTP error in the status field and no XML body.
The SOAP infrastructure on the receiving site is able to decode the input parameters, dispatch to an appropriate server indicated by the server address, and invoke an application-level function corresponding semantically to the method indicated in the method request. In this case, the result of the method request consists of a response or error.
The SOAP infrastructure on the receiving site cannot decode the input parameters, dispatch to an appropriate server indicated by the server address, and invoke an application-level function corresponding semantically to the interface or method indicated in the method request. In this case, the result of the method is an error that prevented the dispatching infrastructure on the receiving side from successful completion.
In the last two cases, additional message headers can be present in the results of the request for extensibility.
The body of a SOAP message is an IDAP message. This XML document has the namespace http://ns.oracle.com/AQ/schemas/access. The body represents:
Server responses to client requests for enqueue, dequeue, and registration
Notifications from the server to the client
|
Note: Oracle Streams Advanced Queuing Internet access is supported only for 8.1or higher style queues. |
This section contains these topics:
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
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.
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.
Client requests for dequeue use AQXmlReceive, which contains the following elements:
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. |
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 Advanced Queuing 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.
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.
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>
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>
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.
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.
The response to a register request uses AQXmlRegisterResponse. It contains the status_response element described in "IDAP Server Response to a Dequeue Request".
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>
The response to a rollback request uses AQXmlRollbackResponse. It contains the status_response element described in "IDAP Server Response to a Dequeue Request".
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.
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 Advanced Queuing 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".
Here are the steps for setting up your database for e-mail notifications:
Set the SMTP mail host by invoking DBMS_AQELM.SET_MAILHOST as an Oracle Streams Advanced Queuing administrator.
Set the SMTP mail port by invoking DBMS_AQELM.SET_MAILPORT as an Oracle Streams Advanced Queuing administrator. If not explicit, set defaults to 25.
Set the SendFrom address by invoking DBMS_AQELM.SET_SENDFROM.
After setup, you can register for e-mail notifications using the Oracle Call Interface (OCI) or PL/SQL API.
application programming interface
The calling conventions by which an application program accesses operating system and other services.
approximate CSCN
An approximate system change number value, based on the current SCN of the database when a transaction that has enqueued messages into a commit-time queue is committed.
asynchronous
A process in a multitasking system is asynchronous if its execution can proceed independently in the background. Other processes can be started before the asynchronous process has finished. The opposite of synchronous.
BFILE
An external binary file that exists outside the database tablespaces residing in the operating system.
binary large object
A large object datatype whose content consists of binary data. This data is considered raw, because its structure is not recognized by the database.
broadcast
A publish/subscribe mode in which the message producer does not know the identity of any message consumer. This mode is similar to a radio or television station.
buffered queue
Buffered queues support queuing of messages with buffered attributes (buffered messages) and materialize them in memory. If the memory devoted to a buffered message is required for a newer message, or if a buffered message has exceeded a stipulated duration in memory, then that buffered message is swapped to the underlying queue table. The memory for buffered messages comes from a separate pool called the streams pool. Buffered messages cannot be recovered if the database is bounced. Messages that have no buffered attributes set are queued as persistent messages in the underlying persistent queue.
character large object
The large object datatype whose value is composed of character data corresponding to the database character set. A character large object can be indexed and searched by the Oracle Text search engine.
ConnectionFactory
A ConnectionFactory encapsulates a set of connection configuration parameters that has been defined by an administrator. A client uses it to create a connection with a Java Message Service provider.
data manipulation language
Data manipulation language (DML) statements manipulate database data. For example, querying, inserting, updating, and deleting rows of a table are all DML operations; locking a table or view and examining the execution plan of an SQL statement are also DML operations.
Database Configuration Assistant
An Oracle Database tool for creating and deleting databases and for managing database templates.
exception queue
Messages are transferred to an exception queue if they cannot be retrieved and processed for some reason.
index-organized table
Unlike an ordinary table whose data is stored as an unordered collection, data for an index-organized table is stored in a B-tree index structure sorted on a primary key. Besides storing the primary key column values of an index-organized table row, each index entry in the B-tree stores the nonkey column values as well.
Internet Data Access Presentation
The Simple Object Access Protocol (SOAP) specification for Oracle Streams Advanced Queuing operations. IDAP defines the XML message structure for the body of the SOAP request. An IDAP-structured message is transmitted over the Internet using HTTP(S).
Inter-process Communication
Exchange of data between one process and another, either within the same computer or over a network. It implies a protocol that guarantees a response to a request.
Java Database Connectivity
An industry-standard Java interface for connecting to a relational database from a Java program, defined by Sun Microsystems.
Java Message Service
A messaging standard defined by Sun Microsystems, Oracle, IBM, and other vendors. JMS is a set of interfaces and associated semantics that define how a JMS client accesses the facilities of an enterprise messaging product.
Java Naming and Directory Interface
A programming interface from Sun for connecting Java programs to naming and directory services.
Java Virtual Machine
The Java interpreter that converts the compiled Java bytecode into the machine language of the platform and runs it. JVMs can run on a client, in a browser, in a middle tier, on an intranet, on an application server such as Oracle Application Server 10g, or in a database server such as Oracle Database 10g.
JDBC driver
The vendor-specific layer of Java Database Connectivity that provides access to a particular database. Oracle Database provides three JDBC drivers--Thin, OCI, and KPRB.
JMS connection
An active connection of a client to its JMS provider, typically an open TCP/IP socket (or a set of open sockets) between a client and a provider's service daemon.
JMS message
JMS messages consist of a header, one or more optional properties, and a message payload.
JMS topic
Equivalent to a multiconsumer queue in the other Oracle Streams Advanced Queuing interfaces.
Lightweight Directory Access Protocol
A standard, extensible directory access protocol. It is a common language that LDAP clients and servers use to communicate. The framework of design conventions supporting industry-standard directory products, such as the Oracle Internet Directory.
local consumer
A local consumer dequeues the message from the same queue into which the producer enqueued the message.
logical change record
An object with a specific format that describes a database change, captured from the redo log by a capture process or user application. Capture processes enqueue messages containing logical change records (LCRs) only into ANYDATA queues. For improved performance, these LCRs are always stored in a buffered queue.
message
The smallest unit of information inserted into and retrieved from a queue. A message consists of control information (metadata) and payload (data).
multicast
A publish/subscribe mode in which the message producer knows the identity of each consumer. This mode is also known as point-to-multipoint.
national character large object
The large object datatype whose value is composed of character data corresponding to the database national character set.
nonpersistent
Nonpersistent queues store messages in memory. They are generally used to provide an asynchronous mechanism to send notifications to all users that are currently connected. Nonpersistent queues are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Oracle recommends that you use buffered messaging instead.
object type
An object type encapsulates a data structure along with the functions and procedures needed to manipulate the data. When you define an object type using the CREATE TYPE statement, you create an abstract template that corresponds to a real-world object.
Online Transaction Processing
Online transaction processing systems are optimized for fast and reliable transaction handling. Compared to data warehouse systems, most OLTP interactions involve a relatively small number of rows, but a larger group of tables.
Oracle Call Interface
An application programming interface that enables data and schema manipulation in Oracle Database.
Oracle Java Message Service
Oracle Java Message Service (OJMS) provides a Java API for Oracle Streams Advanced Queuing based on the Java Message Service (JMS) standard. OJMS supports the standard JMS interfaces and has extensions to support the Oracle Streams Advanced Queuing administrative operations and other Oracle Streams Advanced Queuing features that are not a part of the standard.
Oracle Objects for OLE
A custom control (OCX or ActiveX) combined with an object linking and embedding (OLE) in-process server that lets you plug native Oracle Database functionality into your Windows applications.
publish/subscribe
A type of messaging in which a producer enqueues a message to one or more multiconsumer queues, and then the message is dequeued by several subscribers. The published message can have a wide dissemination mode called broadcast or a more narrowly aimed mode called multicast.
QMNC
Queue monitor coordinator. It dynamically spawns slaves qXXX depending on the system load. The slaves do various background tasks.
queue table
A database table where queues are stored. Each queue table contains a default exception queue.
recipient
An agent authorized by the enqueuer or queue administrator to retrieve messages. The enqueuer can explicitly specify the consumers who can retrieve the message as recipients of the message. A queue administrator can specify a default list of recipients who can retrieve messages from a queue. A recipient specified in the default list is known as a subscriber. If a message is enqueued without specifying the recipients, then the message is sent to all the subscribers. Specific messages in a queue can be directed toward specific recipients, who may or may not be subscribers to the queue, thereby overriding the subscriber list.
If only the name of the recipient is specified, then the recipient must dequeue the message from the queue in which the message was enqueued. If the name and an address of the recipient are specified with a protocol value of 0, then the address should be the name of another queue in the same database or another installation of Oracle Database. If the recipient's name is NULL, then the message is propagated to the specified queue in the address and can be dequeued by any subscriber of the queue specified in the address. If the protocol field is nonzero, then the name and address are not interpreted by the system, and the message can be dequeued by a special consumer.
remote consumer
A remote consumer dequeues from a queue that is different from the queue where the message was enqueued.
rules
Boolean expressions that define subscriber interest in subscribing to messages. The expressions use syntax similar to the WHERE clause of a SQL query and can include conditions on: message properties (currently priority and correlation identifier), user data properties (object payloads only), and functions. If a rule associated with a subscriber evaluates to TRUE for a message, then the message is sent to that subscriber even if the message does not have a specified recipient.
rules engine
Oracle Database software that evaluates rules. Rules are database objects that enable a client to perform an action when an event occurs and a condition is satisfied. Rules are similar to conditions in WHERE clauses of SQL queries. Both user-created applications and Oracle Database features, such as Oracle Streams Advanced Queuing, can be clients of the rules engine.
schema
A collection of database objects, including logical structures such as tables, views, sequences, stored procedures, synonyms, indexes, clusters, and database links. A schema has the name of the user who controls it.
servlet
A Java program that runs as part of a network service and responds to requests from clients. It is typically an HTTP server.
Simple Object Access Protocol
A minimal set of conventions for invoking code using XML over HTTP defined by World Wide Web Consortium.
System Global Area
A group of shared memory structures that contain data and control information for one Oracle Database instance. The SGA and Oracle Database processes constitute an Oracle Database instance. Oracle Database automatically allocates memory for an SGA whenever you start an instance and the operating system reclaims the memory when you shut down the instance. Each instance has one and only one SGA.
synchronous
Two or more processes are synchronous if they depend upon the occurrences of specific events such as common timing signals. The opposite of asynchronous.
transformation
A mapping from one Oracle data type to another, represented by a SQL function that takes the source data type as input and returns an object of the target data type. A transformation can be specified during enqueue, to transform the message to the correct type before inserting it into the queue. It can be specified during dequeue to receive the message in the wanted format. If specified with a remote consumer, then the message is transformed before propagating it to the destination queue.
VARRAY
An ordered set of data elements. All elements of a given array are of the same datatype. Each element has an index, which is a number corresponding to the element's position in the array. The number of elements in an array is the size of the array. Oracle Database allows arrays to be of variable size.
wildcard
A special character or character sequence which matches any character in a string comparison.
This guide describes features of application development and integration using Oracle Streams Advanced Queuing (AQ). This information applies to versions of the Oracle Database server that run on all platforms, unless otherwise specified.
This Preface contains these topics:
This guide is intended for programmers who develop applications that use Oracle Streams Advanced Queuing.
To use this document, you need knowledge of an application development language and object-relational database management concepts.
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Access to Oracle Support
Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
For more information, see these Oracle resources:
Many of the examples in this book use the sample schemas, which are installed by default when you select the Basic Installation option with an Oracle Database installation. Refer to Oracle Database Sample Schemas for information on how these schemas were created and how you can use them yourself.
The following text conventions are used in this document:
| Convention | Meaning |
|---|---|
| boldface | Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary. |
| italic | Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values. |
monospace | Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |
After Oracle Messaging Gateway (MGW) is loaded and set up, it is ready to be configured and run. You can use DBMS_MGWADM.ALTER_AGENT to set the username, password, database specifier, and connection type the Messaging Gateway agent will use for creating database connections.
This chapter contains these topics:
Messages are propagated between Oracle Streams Advanced Queuing and non-Oracle messaging systems by the Messaging Gateway agent. The Messaging Gateway agent runs as an external process of the Oracle Database server.
Messaging Gateway supports multiple agents for a given database. A default agent is automatically created that has the name of DEFAULT_AGENT. Additional named agents can be created to provide propagation job isolation and grouping, and scaling in a Oracle RAC environment. The default agent is usually sufficient for single instance, non-Oracle RAC, environments.
This section contains these topics:
You can use DBMS_MGWADM.CREATE_AGENT to create additional Messaging Gateway agents. The Messaging Gateway default agent, DEFAULT_AGENT, is automatically created when Messaging Gateway is installed and will always exist.
Agents can be configured with an agent user, connection information, database service, and resource limits when the agent is created, or at a later time using DBMS_MGWADM.ALTER_AGENT. A Messaging Gateway agent must be configured with a database user that has been granted the role MGW_AGENT_ROLE before the agent can be started.
Example 19-1 creates the agent named myagent and specifies the database connection information for the agent user. Default values are used for all other parameters.
A Messaging Gateway agent can be removed by calling DBMS_MGWADM.REMOVE_AGENT. Before an agent can be removed, all Messaging Gateway links associated with the agent must be removed and the agent shut down. The default agent, DEFAULT_AGENT, cannot be removed. Example 19-2 removes the agent named myagent.
The Messaging Gateway agent runs as a process external to the database. To access Oracle Streams Advanced Queuing and the Messaging Gateway packages, the Messaging Gateway agent needs to establish connections to the database. You can use DBMS_MGWADM.ALTER_AGENT to set the username, password and the database connect string that the Messaging Gateway agent will use for creating database connections. The user must be granted the role MGW_AGENT_ROLE before the Messaging Gateway agent can be started.
Example 19-3 shows the Messaging Gateway default agent being configured for user mgwagent with password mgwagent_password using net service name mydatabase.
You can use DBMS_MGWADM.ALTER_AGENT to set resource limits for the Messaging Gateway agent. For example, you can set the heap size of the Messaging Gateway agent process and the number of propagation threads used by the agent process. The default values are 64 MB of memory heap and one propagation thread. For named agents, these values can also be specified when the agent is created by DBMS_MGWADM.CREATE_AGENT.
Example 19-4 sets the heap size to 96 MB and two propagation threads for the agent myagent.
Example 19-4 Setting the Resource Limits
SQL> exec DBMS_MGWADM.ALTER_AGENT(
agent_name => 'myagent',
max_memory => 96,
max_threads => 2);
The memory heap size and the number of propagation threads cannot be altered when the Messaging Gateway agent is running.
This section contains these topics:
After the Messaging Gateway agent is configured, you can start the agent with DBMS_MGWADM.STARTUP. Example 19-5 shows how to start the default agent and agent myagent.
Example 19-5 Starting the Messaging Gateway Agent
SQL> exec DBMS_MGWADM.STARTUP;
SQL> exec DBMS_MGWADM.STARTUP ('myagent');
You can use the MGW_GATEWAY view to check the status of the Messaging Gateway agent, as described in Chapter 21, "Monitoring Oracle Messaging Gateway".
You can use DBMS_MGWADM.SHUTDOWN to shut down the Messaging Gateway agent. Example 19-6 shows how to shut down the Messaging Gateway default agent and agent myagent.
Example 19-6 Shutting Down the Messaging Gateway Agent
SQL> exec DBMS_MGWADM.SHUTDOWN;
SQL> exec DBMS_MGWADM.SHUTDOWN ('myagent');
You can use the MGW_GATEWAY view to check if the Messaging Gateway agent has shut down successfully, as described in Chapter 21, "Monitoring Oracle Messaging Gateway".
Messaging Gateway uses a Scheduler job to start the Messaging Gateway agent. This job is created when procedure DBMS_MGWADM.STARTUP is called. When the job is run, it calls an external procedure that creates the Messaging Gateway agent in an external process. The job is removed after:
The agent shuts down because DBMS_MGWADM.SHUTDOWN was called
The agent terminates because a non-restartable error occurs
Messaging Gateway uses DBMS_SCHEDULER to create a repeatable Scheduler job with a repeat interval of one minute. The job is owned by SYS. A repeatable job enables the Messaging Gateway agent to restart automatically when a given job instance ends because of a database shutdown, database malfunction, or a restartable error. Only one instance of a Messaging Gateway agent job runs at a given time.
Each agent uses a Scheduler job class to specify the service affinity for the agent's Scheduler job. The job class will be configured with the database service specified by DBMS_MGWADM.CREATE_AGENT or DBMS_MGWADM.ALTER_AGENT. A database administrator is responsible for setting up the database service. If no database service is specified, the default database service that maps to every instance is used.
The name of the Scheduler job class used by the Messaging Gateway default agent is SYS.MGW_JOBCLS_DEFAULT_AGENT. The Scheduler job used by the default agent is SYS.MGW_JOB_DEFAULT_AGENT.
The name of the Scheduler job class used by a Messaging Gateway named agent is SYS.MGW_JOBCLS_<agent_name>. The Scheduler job used by a named agent is SYS.MGW_JOB_<agent_name>.
If the agent job encounters an error, then the error is classified as either a restartable error or non-restartable error. A restartable error indicates a problem that might go away if the agent job were to be restarted. A non-restartable error indicates a problem that is likely to persist and be encountered again if the agent job restarts. ORA-01089 (immediate shutdown in progress) and ORA-28576 (lost RPC connection to external procedure) are examples of restartable errors. ORA-06520 (error loading external library) is an example of a non-restartable error.
Messaging Gateway uses a database shutdown trigger. If the Messaging Gateway agent is running on the instance being shut down, then the trigger notifies the agent of the shutdown, and upon receipt of the notification, the agent will terminate the current run. The job scheduler will automatically schedule the job to run again at a future time.
If a Messaging Gateway agent job instance ends because of a database malfunction or a restartable error detected by the agent job, then the job will not be removed and the job scheduler will automatically schedule the job to run again at a future time.
The MGW_GATEWAY view shows the agent status, database service, and the database instance on which the Messaging Gateway agent is current running. The Oracle Scheduler views provide information about Scheduler jobs, job classes, and job run details.
|
See Also: |
While the Messaging Gateway job startup and shutdown principles are the same for Oracle Real Application Clusters (Oracle RAC) and non-Oracle RAC environments, there are some things to keep in mind for a Oracle RAC environment.
A single process of each configured Messaging Gateway agent can be running, even in a Oracle RAC environment. For example, if the default agent and two named agents have been configured with an agent user, then one instance of all three agents could be running at the same time. The database service associated with each agent determines the service affinity of the agent's Scheduler job, and thus, the database instance on which the agent process can run.
When a database instance is shut down in a Oracle RAC environment, the Messaging Gateway shutdown trigger will notify the agent to shut down only if the Messaging Gateway agent is running on the instance being shut down. The job scheduler will automatically schedule the job to be run again at a future time, either on another instance, or if the job can only run on the instance being shut down, when that instance is restarted.
Oracle recommends that all database connections made by the Messaging Gateway agent be made to the instance on which the Messaging Gateway agent process is running. This ensures correct failover behavior in a Oracle RAC environment.
If a Messaging Gateway agent has been associated with a database service, the agent's Scheduler job will not run unless that service is current enabled on a running instance. When you shut down a database Oracle stops all services to that database and you may need to manually restart the services when you start the database.
|
See Also:
|
Running as a client of non-Oracle messaging systems, the Messaging Gateway agent communicates with non-Oracle messaging systems through messaging system links. A messaging system link is a set of connections between the Messaging Gateway agent and a non-Oracle messaging system.
To configure a messaging system link of a non-Oracle messaging system, users must provide information for the agent to make connections to the non-Oracle messaging system. Users can specify the maximum number of messaging connections.
An agent name will be associated with each messaging system link. This is done when the link is created and cannot be changed. The agent associated with the link is then responsible for processing all propagation jobs that use a registered queue associated with that link. The Messaging Gateway default agent will be used if an agent name is not specified when the messaging system link is created.
When configuring a messaging system link for a non-Oracle messaging system that supports transactions and persistent messages, the native name of log queues for inbound and outbound propagation must be specified in order to guarantee exactly-once message delivery. The log queues should be used only by the Messaging Gateway agent. No other programs should enqueue or dequeue messages of the log queues. The inbound log queue and outbound log queue can refer to the same physical queue, but better performance can be achieved if they refer to different physical queues.
One and only one Messaging Gateway agent should access a propagation log queue. This insures that a given log queue contains log records for only those propagation jobs processed by that agent and that the agent is free to discard any other log records it might encounter.
When configuring a messaging system link, users can also specify an options argument. An options argument is a set of {name, value} pairs of type SYS.MGW_PROPERTY.
This section contains these topics:
A WebSphere MQ Base Java link is created by calling DBMS_MGWADM.CREATE_MSGSYSTEM_LINK with the following information provided:
Interface type: DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE
WebSphere MQ connection information:
Host name and port number of the WebSphere MQ server
Queue manager name
Channel name
User name and password
Maximum number of messaging connections allowed
Log queue names for inbound and outbound propagation
Optional information such as:
Send, receive, and security exits
Character sets
Example 19-7 configures a WebSphere MQ Base Java link mqlink. The link is configured to use the WebSphere MQ queue manager my.queue.manager on host myhost.mydomain and port 1414, using WebSphere MQ channel mychannel.
This example also sets the option to register a WebSphere MQ SendExit class. The class mySendExit must be in the CLASSPATH set in mgw.ora. The Messaging Gateway default agent (DEFAULT_AGENT) is responsible for the link and all propagation jobs using the link.
Example 19-7 Configuring a WebSphere MQ Base Java Link
DECLARE
v_options sys.mgw_properties;
v_prop sys.mgw_mqseries_properties;
BEGIN
v_prop := sys.mgw_mqseries_properties.construct();
v_prop.interface_type := dbms_mgwadm.MQSERIES_BASE_JAVA_INTERFACE;
v_prop.max_connections := 1;
v_prop.username := 'mqm';
v_prop.password := 'mqm';
v_prop.hostname := 'myhost.mydomain';
v_prop.port := 1414;
v_prop.channel := 'mychannel';
v_prop.queue_manager := 'my.queue.manager';
v_prop.outbound_log_queue := 'mylogq';
-- Specify a WebSphere MQ send exit class 'mySendExit' to be associated with
-- the queue.
-- Note that this is used as an example of how to use the options parameter,
-- but is not an option that is usually set.
v_options := sys.mgw_properties(sys.mgw_property('MQ_SendExit',
'mySendExit'));
dbms_mgwadm.create_msgsystem_link(
linkname => 'mqlink', agent_name=>'default_agent', properties => v_prop,
options => v_options );
END;
|
See Also:
|
A WebSphere MQ JMS link is created by calling DBMS_MGWADM.CREATE_MSGSYSTEM_LINK with the following information provided:
Interface type
Java Message Service (JMS) distinguishes between queue and topic connections. The Sun Microsystem JMS 1.1 standard supports domain unification that allows both JMS queues and topics to be accessed by a single JMS connection:
A WebSphere MQ JMS link created with interface type DBMS_MGWADM.JMS_CONNECTION can be used to access both JMS queues and topics. This is the recommended interface for a WebSphere MQ JMS link.
A WebSphere MQ JMS link created with interface type DBMS_MGWADM.JMS_QUEUE_CONNECTION can be used to access only JMS queues.
A WebSphere MQ JMS link created with interface type DBMS_MGWADM.JMS_TOPIC_CONNECTION can be used to access only JMS topics.
WebSphere MQ connection information:
Host name and port number of the WebSphere MQ server
Queue manager name
Channel name
User name and password
Maximum number of messaging connections allowed
A messaging connection is mapped to a JMS session.
Log destination (JMS queue or JMS topic) for inbound and outbound propagation
The log destination type must be valid for the link type. JMS unified links and JMS queue links must use JMS queues for log destinations, and JMS topic links must use topics:
For a WebSphere MQ JMS unified or queue link, the log queue name must be the name of a physical WebSphere MQ JMS queue created using WebSphere MQ administration tools.
For a WebSphere MQ JMS topic link, the log topic name must be the name of a WebSphere MQ JMS topic. The physical WebSphere MQ queue used by that topic must be created using WebSphere MQ administration tools. By default, the physical queue used is SYSTEM.JMS.D.SUBSCRIBER.QUEUE. A link option can be used to specify a different physical queue.
Optional information such as:
Send, receive, and security exits
Character sets
WebSphere MQ publish/subscribe configuration used for JMS topics
Example 19-8 configures a Messaging Gateway link to a WebSphere MQ queue manager using a JMS topic interface. The link is named mqjmslink and is configured to use the WebSphere MQ queue manager my.queue.manager on host myhost.mydomain and port 1414, using WebSphere MQ channel mychannel.
This example also uses the options parameter to specify a nondefault durable subscriber queue to be used with the log topic. The Messaging Gateway agent myagent is responsible for the link and all propagation jobs using the link.
Example 19-8 Configuring a WebSphere MQ JMS Link
DECLARE
v_options sys.mgw_properties;
v_prop sys.mgw_mqseries_properties;
BEGIN
v_prop := sys.mgw_mqseries_properties.construct();
v_prop.max_connections := 1;
v_prop.interface_type := DBMS_MGWADM.JMS_TOPIC_CONNECTION;
v_prop.username := 'mqm';
v_prop.password := 'mqm';
v_prop.hostname := 'myhost.mydomain';
v_prop.port := 1414;
v_prop.channel := 'mychannel';
v_prop.queue_manager := 'my.queue.manager';
v_prop.outbound_log_queue := 'mylogtopic'
-- Specify a WebSphere MQ durable subscriber queue to be used with the
-- log topic.
v_options := sys.mgw_properties(
sys.mgw_property('MQ_JMSDurSubQueue', 'myDSQueue'));
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK(
linkname => 'mqjmslink',
agent_name => 'myagent',
properties => v_prop,
options => v_options );
END;
|
See Also:
|
Messaging Gateway allows SSL support for IBM WebSphere MQ and WebSphere MQ JMS connections. This section describes how to configure Messaging Gateway to use SSL for a WebSphere MQ Base Java link and the same information applies to a WebSphere MQ JMS link. There are no differences in terms of the Messaging Gateway configuration.
The following are needed in order to use SSL for WebSphere MQ connections:
A WebSphere MQ channel configured to use SSL.
A truststore and optionally a keystore file that are in a location accessible to the Messaging Gateway agent process. In a Oracle RAC environment, these files must be accessible to all instances on which the Messaging Gateway agent process might run, using the same path specification.
Use DBMS_MGWADM.CREATE_MSGSYSTEM_LINK to create a WebSphere MQ link with the desired SSL related link options. At minimum, the MQ_SSLCIPHERSUITE property should be set to specify the SSL ciphersuite used by the channel.
Use DBMS_MGWADM.SET_OPTION to set certain JSSE Java properties for the Messaging Gateway agent assigned to the link.
JSEE related properties:
java.net.ssl.keyStore
This property is used to specify the location of the keystore. A keystore is a database of key material used for va rious purposes, including authentication and data integrity.
java.net.ssl.keyStorePassword
This property is used to specify the password of the keystore. This password is used to check the integrity of the data in the keystore before accessing it.
java.net.ssl.trustStore
This property is used to specify the location of the truststore. A truststore is a keystore that is used when making decisions about which clients and servers are trusted.
java.net.ssl.trustStorePassword
This property is used to specify the password of the truststore. This password is used to check the integrity of the data in the truststore before accessing it.
The java.net.ssl.keyStore and java.net.ssl.keyStorePassword properties are only needed if the WebSphere MQ channel is configured to use SSL client authentication.
Example 19-9 configures a WebSphere MQ Base Java link mqssllink to use SSL connections using the SSL_RSA_WITH_RC4_128_MD5 ciphersuite. It assumes the channel has been configured for SSL client authentication so the Messaging Gateway agent associated with the link, DEFAULT_AGENT, is configured with Java properties for both a keystore and a truststore.
This configuration should be done when the Messaging Gateway agent is shut down since the Java properties set by DBMS_MGWADM.SET_OPTION are set only when the agent first starts. If the agent is running when the configuration is done it will need to be shutdown and restarted before the SSL connections will be used.
Example 19-9 Configuring a WebSphere MQ Base Java Link for SSL
DECLARE
v_options sys.mgw_properties;
v_prop sys.mgw_mqseries_properties;
v_agent varchar2(30) := 'default_agent';
BEGIN
v_prop := sys.mgw_mqseries_properties.construct();
v_prop.interface_type := DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE;
v_prop.max_connections := 1;
v_prop.username := 'mqm';
v_prop.password := 'mqm';
v_prop.hostname := 'myhost.mydomain';
v_prop.port := 1414;
v_prop.channel := 'mysslchannel';
v_prop.queue_manager := 'my.queue.manager';
v_prop.outbound_log_queue := 'mylogq';
-- specify the SSL ciphersuite
v_options := sys.mgw_properties(
sys.mgw_property('MQ_SSLCIPHERSUITE','SSL_RSA_WITH_RC4_128_MD5') );
-- create the MQSeries link
DBMS_MGWADM.CREATE_MSGSYSTEM_LINK(linkname => 'mqssllink',
agent_name => v_agent,
properties => v_prop,
options => v_options);
-- set Java properties for the agent that specify the JSSE security
-- properties for the keystore and truststore; the paths will be
-- saved as cleartext and the passwords encrypted
DBMS_MGWADM.SET_OPTION(target_type => DBMS_MGWADM.AGENT_JAVA_PROP,
target_name => v_agent,
option_name => 'javax.net.ssl.keyStore',
option_value => '/tmp/mq_ssl/key.jks',
encrypted => false);
DBMS_MGWADM.SET_OPTION(target_type => DBMS_MGWADM.AGENT_JAVA_PROP,
target_name => v_agent,
option_name => 'javax.net.ssl.keyStorePassword',
option_value => 'welcome',
encrypted => true);
DBMS_MGWADM.SET_OPTION(target_type => DBMS_MGWADM.AGENT_JAVA_PROP,
target_name => v_agent,
option_name => 'javax.net.ssl.trustStore',
option_value => '/tmp/mq_ssl/trust.jks',
encrypted => false);
DBMS_MGWADM.SET_OPTION(target_type => DBMS_MGWADM.AGENT_JAVA_PROP,
target_name => v_agent,
option_name => 'javax.net.ssl.trustStorePassword',
option_value => 'welcome',
encrypted => true);
END;
A TIB/Rendezvous link is created by calling DBMS_MGWADM.CREATE_MSGSYSTEM_LINK with three parameters (service, network and daemon) for the agent to create a corresponding transport of TibrvRvdTransport type.
A TIB/Rendezvous message system link does not need propagation log queues. Logging information is stored in memory. Therefore, Messaging Gateway can only guarantee at-most-once message delivery.
Example 19-10 configures a TIB/Rendezvous link named rvlink that connects to the rvd daemon on the local computer. An agent name is not specified for the link so the Messaging Gateway default agent (DEFAULT_AGENT) is responsible for the link and all propagation jobs using the link.
Example 19-10 Configuring a TIB/Rendezvous Link
DECLARE v_options sys.mgw_properties; v_prop sys.mgw_tibrv_properties; BEGIN v_prop := sys.mgw_tibrv_properties.construct(); DBMS_MGWADM.CREATE_MSGSYSTEM_LINK(linkname => 'rvlink', properties => v_prop); END;
Using DBMS_MGWADM.ALTER_MSGSYSTEM_LINK, you can alter some link information after the link is created. You can alter link information with the Messaging Gateway agent running or shut down. Example 19-11 alters the link mqlink to change the max_connections property.
Example 19-11 Altering a WebSphere MQ Link
DECLARE
v_options sys.mgw_properties;
v_prop sys.mgw_mqseries_properties;
BEGIN
-- use alter_construct() for initialization
v_prop := sys.mgw_mqseries_properties.alter_construct();
v_prop.max_connections := 2;
DBMS_MGWADM.ALTER_MSGSYSTEM_LINK(
linkname => 'mqlink', properties => v_prop);
END;
|
See Also: "Configuration Properties" for restrictions on changes when the Messaging Gateway agent is running |
You can remove a Messaging Gateway link to a non-Oracle messaging system with DBMS_MGWADM.REMOVE_MSGSYSTEM_LINK, but only if all registered queues associated with this link have already been unregistered. The link can be removed with the Messaging Gateway agent running or shut down. Example 19-12 removes the link mqlink.
You can use the MGW_LINKS view to check links that have been created. It lists the name and link type, as shown in Example 19-13.
Example 19-13 Listing All Messaging Gateway Links
SQL> select link_name, link_type from MGW_LINKS; LINK_NAME LINK_TYPE ------------------------ MQLINK MQSERIES RVLINK TIBRV
You can use the MGW_MQSERIES_LINKS and MGW_TIBRV_LINKS views to check messaging system type-specific configuration information, as shown in Example 19-14.
Example 19-14 Checking Messaging System Link Configuration Information
SQL> select link_name, queue_manager, channel, hostname from mgw_mqseries_links; LINK_NAME QUEUE_MANAGER CHANNEL HOSTNAME ---------------------------------------------------------- MQLINK my.queue.manager mychannel myhost.mydomain SQL> select link_name, service, network, daemon from mgw_tibrv_links; LINK_NAME SERVICE NETWORK DAEMON ----------------------------------------------------- RVLINK
All non-Oracle messaging system queues involved in propagation as a source queue, destination queue, or exception queue must be registered through the Messaging Gateway administration interface. You do not need to register Oracle Streams Advanced Queuing queues involved in propagation.
This section contains these topics:
You can register a non-Oracle queue using DBMS_MGWADM.REGISTER_FOREIGN_QUEUE. Registering a non-Oracle queue provides information for the Messaging Gateway agent to access the queue. However, it does not create the physical queue in the non-Oracle messaging system. The physical queue must be created using the non-Oracle messaging system administration interfaces before the Messaging Gateway agent accesses the queue.
The following information is used to register a non-Oracle queue:
Name of the messaging system link used to access the queue
Native name of the queue (its name in the non-Oracle messaging system)
Domain of the queue
DBMS_MGWADM.DOMAIN_QUEUE for a point-to-point queue
DBMS_MGWADM.DOMAIN_TOPIC for a publish/subscribe queue
Options specific to the non-Oracle messaging system
These options are a set of {name, value} pairs, both of which are strings.
Example 19-15 shows how to register the WebSphere MQ Base Java queue my_mq_queue as a Messaging Gateway queue destq.
Example 19-15 Registering a WebSphere MQ Base Java Queue
BEGIN
DBMS_MGWADM.REGISTER_FOREIGN_QUEUE(
name => 'destq',
linkname => 'mqlink',
provider_queue => 'my_mq_queue',
domain => dbms_mgwadm.DOMAIN_QUEUE);
END;
The domain must be DBMS_MGWADM.DOMAIN_QUEUE or NULL, because only point-to-point queues are supported for WebSphere MQ.
When registering a WebSphere MQ JMS queue, the domain must be DBMS_MGWADM.DOMAIN_QUEUE, and the linkname parameter must refer to a WebSphere MQ JMS unified link or queue link.
When registering a WebSphere MQ JMS topic, the domain must be DBMS_MGWADM.DOMAIN_TOPIC, and the linkname parameter must refer to a WebSphere MQ JMS unified link or topic link. The provider_queue for a WebSphere MQ JMS topic used as a propagation source may include wildcards. See WebSphere MQ documentation for wildcard syntax.
When registering a TIB/Rendezvous subject with Messaging Gateway, the provider_queue parameter specifies a TIB/Rendezvous subject name. The domain of a registered TIB/Rendezvous queue must be DBMS_MGWADM.DOMAIN_TOPIC or NULL.
A registered TIB/Rendezvous queue with provider_queue set to a wildcard subject name can be used as a propagation source queue for inbound propagation. It is not recommended to use queues with wildcard subject names as propagation destination queues or exception queues. As documented in TIB/Rendezvous, sending messages to wildcard subjects can trigger unexpected behavior. However, neither Messaging Gateway nor TIB/Rendezvous prevents you from doing so.
A non-Oracle queue can be unregistered with DBMS_MGWADM.UNREGISTER_FOREIGN_QUEUE, but only if there are no propagation jobs referencing it.
Example 19-16 unregisters the queue destq of the link mqlink.
You can use the MGW_FOREIGN_QUEUES view to check which non-Oracle queues are registered and what link each uses, as shown in Example 19-17.
Propagating messages between an Oracle Streams AQ queue and a non-Oracle messaging system queue requires a propagation job. Each propagation job will have a unique propagation type, source, and destination triplet.
You can create a propagation job to propagate messages between JMS destinations. You can also create a propagation job to propagate messages between non-JMS queues. Messaging Gateway does not support message propagation between a JMS destination and a non-JMS queue.
This section contains these topics:
A propagation job specifies what messages are propagated and how the messages are propagated.
Messaging Gateway allows bidirectional message propagation. An outbound propagation moves messages from Oracle Streams Advanced Queuing to non-Oracle messaging systems. An inbound propagation moves messages from non-Oracle messaging systems to Oracle Streams Advanced Queuing.
If the propagation source is a queue (point-to-point), then the Messaging Gateway agent moves all messages from the source queue to the destination queue. If the propagation source is a topic (publish/subscribe), then the Messaging Gateway agent creates a subscriber of the propagation source queue in the messaging system. The agent only moves messages that are published to the source queue after the subscriber is created.
When propagating a message, the Messaging Gateway agent converts the message from the format in the source messaging system to the format in the destination messaging system. Users can customize the message conversion by providing a message transformation. If message conversion fails, then the message will be moved to an exception queue, if one has been provided, so that the agent can continue to propagate messages for the subscriber.
A Messaging Gateway exception queue is different from an Oracle Streams Advanced Queuing exception queue. Messaging Gateway moves a message to a Messaging Gateway exception queue when message conversion fails. Oracle Streams Advanced Queuing moves a message to an Oracle Streams Advanced Queuing exception queue after MAX_RETRIES dequeue attempts on the message.
Messages moved to an Oracle Streams Advanced Queuing exception queue may result in irrecoverable failures on the associated Messaging Gateway propagation job. To avoid the problem, the MAX_RETRIES parameter of any Oracle Streams Advanced Queuing queue that is used as the propagation source of a Messaging Gateway propagation job should be set to a value much larger than 16.
If the messaging system of the propagation source queue supports message selection, then a message selection rule can be specified for a propagation subscriber. Only messages that satisfy the message selector will be propagated.
Users can also specify propagation job options to control how messages are propagated, such as options for JMS message delivery mode and TIB/Rendezvous queue policies.
The MGW_JOBS view can be used to check the configuration and status of Messaging Gateway propagation jobs.
Messaging Gateway propagation jobs are created by DBMS_MGWADM.CREATE_JOB.
If the propagation source for non-JMS propagation is an Oracle Streams AQ queue, then the queue can be either a single consumer queue or multiple consumer queue. If it is a multiple consumer queue, Messaging Gateway creates a corresponding Oracle Streams AQ subscriber MGW_job_name for the propagation job job_name when DBMS_MGWADM.CREATE_JOB is called.
If the propagation source is a JMS topic, such as an Oracle Java Message Service (OJMS) topic or a WebSphere MQ JMS topic, then a JMS subscriber MGW_job_name is created on the topic in the source messaging system by the Messaging Gateway agent. If the agent is not running, then the subscriber will not be created until the agent is restarted.
If the propagation source is a queue, then only one propagation job can be created using that queue as the propagation source. If the propagation source is a topic, then multiple propagation jobs can be set up using that topic as the propagation source with each propagation job having its own corresponding subscriber on the topic in the messaging system.
Example 19-18 creates Messaging Gateway propagation job job_aq2mq.
Example 19-18 Creating a Messaging Gateway Propagation Job
BEGIN
DBMS_MGWADM.CREATE_JOB(
job_name => 'job_aq2mq',
propagation_type => DBMS_MGWADM.OUTBOUND_PROPAGATION,
source => 'mquser.srcq',
destination => 'deqq@mqlink');
END;
|
Note: If a WebSphere MQ JMS topic is involved in a propagation job and the interface type of the link isDBMS_MGWADM.JMS_TOPIC_CONNECTION, then a durable subscriber MGL_subscriber_id is created on the log topic. The durable subscriber is removed when the Messaging Gateway propagation job is successfully removed. |
A propagation job can be initially enabled or disabled when it is created by DBMS_MGWADM.CREATE_JOB. By default, a job is enabled when it is created. You can use DBMS_MGWADM.ENABLE_JOB to enable a propagation job and DBMS_MGWADM.DISABLE_JOB to disable a job. No propagation processing will occur when the job is disabled.
Example 19-19 enables the propagation for propagation job job_aq2mq.
Example 19-19 Enabling a Messaging Gateway Propagation Job
BEGIN DBMS_MGWADM.ENABLE_JOB(job_name => 'job_aq2mq'); END;
Example 19-20 disables the propagation for propagation job job_aq2mq.
When a problem occurs with a propagation job, the Messaging Gateway agent retries the failed operation up to 16 times in an exponential backoff scheme before the propagation job stops. You can use DBMS_MGWADM.RESET_JOB to reset the failure count to zero to allow the agent to retry the failed operation immediately.
Example 19-21 resets the failure count for propagation job job_aq2mq.
After a propagation job is created you can alter the selection rule, transformation, exception queue, job options, and poll interval of the job using DBMS_MGWADM.ALTER_JOB. The job can be altered with the Messaging Gateway running or shut down.
Example 19-22 adds an exception queue for a propagation job.
Example 19-22 Altering Propagation Job by Adding an Exception Queue
BEGIN
DBMS_MGWADM.ALTER_JOB(
job_name => 'job_aq2mq', exception_queue => 'mgwuser.my_ex_queue');
END;
Example 19-23 changes the polling interval for a propagation job. The polling interval determines how soon the agent can discover the available messages in the propagation source queue. The default polling interval is 5 seconds or the value set for oracle.mgw.polling_interval in the Messaging Gateway initialization file.
You can remove a Messaging Gateway propagation job by calling DBMS_MGWADM.REMOVE_JOB.
Before removing the propagation job from the Messaging Gateway configuration, Messaging Gateway does the following cleanup:
Removes from the messaging system the associated subscriber that may have been created by Messaging Gateway
Removes propagation log records from log queues for the job being removed
Messaging Gateway may fail to do the cleanup because:
The Messaging Gateway agent is not running
Non-Oracle messaging system is not running
The Messaging Gateway agent is unable to interact with the source or destination messaging system
If the Messaging Gateway cleanup fails for any reason, then the propagation job being removed is placed in a DELETE_PENDING state. The Messaging Gateway agent tries to clean up propagation jobs in a DELETE_PENDING state when:
DBMS_MGWADM.REMOVE_JOB is called and the Messaging Gateway agent is running.
The Messaging Gateway agent is starting and finds a propagation job in a DELETE_PENDING state.
DBMS_MGWADM.REMOVE_JOB has a force parameter that allows you to force the propagation job to be removed from the Messaging Gateway configuration without placing it in DELETE_PENDING state. This is useful in case of cleanup failures or if you want to remove a propagation job when the Messaging Gateway agent is not running.
Forcing a propagation job to be removed may result in obsolete log records being left in the log queues, and subscriptions in the messaging systems that may cause unnecessary message accumulation. Oracle recommends that the force option not be used for DBMS_MGWADM.REMOVE_JOB if possible.
Example 19-24 removes a propagation job in a non-forced manner.
Subprograms are provided as part of the DBMS_MGWADM package that simplify the creation and management of propagation jobs. Those subprograms allow a user to configure a propagation job rather than a disjoint subscriber and schedule as was done in prior releases. Oracle recommends that you use the propagation job procedures but still supports the subscriber and schedule procedures for backward compatibility.
Table 19-1 lists the Messaging Gateway propagation job procedures and shows which subscriber and/or schedule procedures it replaces. All procedures are from the DBMS_MGWADM package.
Table 19-1 Messaging Gateway Propagation Job Subprograms
| Job Procedure | Replaces Subscriber, Schedule Procedure |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
This section contains the following topics:
The user can create two types of propagation jobs, a new style job or an old style job. A new style job is created by DBMS_MGWADM.CREATE_JOB. An old style job is created by calling DBMS_MGWADM.ADD_SUBSCRIBER and DBMS_MGWADM.SCHEDULE_PROPAGATION using the same {propagation_type, source, destination} triplet. A subscriber that does not have a matching schedule, or a schedule that does not have a matching subscriber, is not considered to be a propagation job.
For new style job, the job name will serve as both the subscriber ID and the schedule ID. For an old style job, the subscriber ID is used as the job name.
Both the propagation job subprograms and the subscriber/schedule subprograms can be used for old style propagation jobs. Oracle recommends that you use the job subprograms to create and manage propagation jobs. The job subprograms cannot be used for an unmatched subscriber or schedule since those do not constitute a propagation job.
Only the new job subprograms can be used for new style propagation jobs. An error will occur if a user tries to call a subscriber or scheduler procedure on a new style job.
Other than DBMS_MGWADM.REMOVE_JOB, calling the job subprograms for an old style job is straightforward and the results are effectively the same as calling the corresponding subscriber/schedule subprograms. There may be certain restrictions in the future but there are none at this time.
The DBMS_MGWADM.REMOVE_JOB procedure can be used to remove both new style and old style jobs. A forced and non-forced remove is supported. If the Messaging Gateway agent is not running when a non-forced remove is done, the job will be flagged as delete pending and neither the underlying subscriber nor schedule will be removed at that time. The job (subscriber /schedule pair) will be removed once the agent is restarted and performs its cleanup work or a forced DBMS_MGWADM.REMOVE_JOB is performed. In order to insure that the subscriber/schedule pair is removed at the same time, an error will occur if you first call DBMS_MGWADM.REMOVE_JOB and subsequently attempt to call DBMS_MGWADM.REMOVE_SUBSCRIBER or DBMS_MGWADM.UNSCHEDULE_PROPAGATION for an old style job.
Once DBMS_MGWADM.REMOVE_JOB as been called for a job and it has been flagged as delete pending, all job procedures, other than DBMS_MGWADM.REMOVE_JOB, will fail for both new style and old style jobs. In addition, all subscriber and schedule subprograms will fail if the propagation job happens to be an old style job.DBMS_MGWADM.REMOVE_SUBSCRIBER and DBMS_MGWADM.UNSCHEDULE_PROPAGATION can be used for an old style job as long as DBMS_MGWADM.REMOVE_JOB has not been called for that job. If DBMS_MGWADM.UNSCHEDULE_PROPAGATION is called for an old style job, the schedule is immediately removed and it ceases to be a propagation job and DBMS_MGWADM.REMOVE_SUSCRIBER must be used to remove the subscriber. If DBMS_MGWADM.REMOVE_SUBSCRIBER is called for an old style job, the user can subsequently call DBMS_MGWADM.REMOVE_JOB as long as the subscriber exists.
The MGW_JOBS view shows information for the current propagation jobs, both new style jobs and old style jobs, and includes all the pertinent information shown by the MGW_SUBSCRIBERS and MGW_SCHEDULES views. The MGW_SUBSCRIBERS and MGW_SCHEDULES views are still useful for finding an unmatched subscriber or schedule since they don't constitute a propagation job and will not show up in the MGW_JOBS view.
Messaging Gateway allows an Oracle Streams AQ multiple consumer queue or a single consumer queue to be a propagation source for an outbound new style job created by DBMS_MGWADM.CREATE_JOB. A multiple consumer queue must be used for the propagation source for an outbound old style job. An error will occur if an administrator attempts to call DBMS_MGWADM.ADD_SUBSCRIBER and the source is a single consumer queue.
An Oracle Streams AQ dequeue condition is not supported for native (non-JMS) outbound propagation when the propagation source is a single consumer queue.
This section summarizes basic and optional properties related to Messaging Gateway links, foreign queues, and propagation jobs.
This section contains these topics:
Table 19-2 summarizes the basic configuration properties for a WebSphere MQ messaging link. The table indicates which properties of SYS.MGW_MQSERIES_PROPERTIES are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.
Table 19-2 WebSphere MQ Link Properties
| Attribute | NULL Allowed? | Alter Value? | Dynamic? |
|---|---|---|---|
|
|
no |
no |
no |
|
|
yes (1) |
no |
no |
|
|
yes (1) |
no |
no |
|
|
yes (1), (6) |
yes |
no |
|
|
yes (2) |
no |
no |
|
|
yes (3) |
yes |
yes |
|
|
yes |
yes |
yes |
|
|
yes |
yes |
yes |
|
|
yes (4) |
yes(4) |
yes |
|
|
yes (5) |
yes(5) |
yes |
Notes on Table 19-2
If hostname is NULL, then the port and channel must be NULL. If the hostname is not NULL, then the port must be not NULL. If the hostname is NULL, then a WebSphere MQ bindings connection is used; otherwise a client connection is used.
If interface_type is NULL, then a default value of DBMS_MGWADM.MQSERIES_BASE_JAVA_INTERFACE is used.
If max_connections is NULL, then a default value of 1 is used.
Attribute inbound_log_queue can be NULL if the link is not used for inbound propagation. The log queue can be altered only when no inbound propagation job references the link.
Attribute outbound_log_queue can be NULL if the link is not used for outbound propagation. The log queue can be altered only when no outbound propagation job references the link.
The channel attribute must be NULL if a client channel definition table (CCDT) is used. The MQ_ccdtURL link option can be used to specify a CCDT.
Table 19-3 summarizes the optional configuration properties supported when a WebSphere MQ Base Java interface is used to access the WebSphere MQ messaging system. Table 19-4 summarizes the optional configuration properties supported when a WebSphere MQ JMS interface is used. Each table lists the property name, where that property applies, whether the property can be altered, and if alterable, whether the value can be dynamically changed. Only the properties listed in the tables are supported, and any extra properties are ignored.
Table 19-3 Optional Configuration Properties for WebSphere MQ Base Java
| Property Name | Used For | Alter Value? | Dynamic? |
|---|---|---|---|
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
link |
yes |
no |
|
|
foreign queue |
no |
no |
|
|
job |
yes |
yes |
|
|
job |
yes |
yes |
Table 19-4 Optional Configuration Properties for WebSphere MQ JMS
Table 19-5 summarizes the basic configuration properties for a TIB/Rendezvous messaging link. It indicates which properties of SYS.MGW_TIBRV_PROPERTIES are optional (NULL allowed), which can be altered, and if alterable, which values can be dynamically changed.
Table 19-5 TIB/Rendezvous Link Properties
| Attribute | NULL allowed? | Alter value? | Dynamic? |
|---|---|---|---|
|
|
yes(1) |
no |
no |
|
|
yes(1) |
no |
no |
|
|
yes(1) |
no |
no |
|
|
yes(2) |
no |
no |
|
|
yes(2) |
no |
no |
Notes on Table 19-5:
System default values will be used if service, daemon, or network are NULL.
The cm_name and cm_ledger attributes are reserved for future use when TIB/Rendezvous certified messages are supported. At present, a NULL must be specified for these parameters when a TIB/Rendezvous link is configured.
Table 19-6 summarizes the optional configuration properties supported when a TIB/Rendezvous messaging system is used. The table lists the property name, where that property applies, whether the property can be altered, and if alterable, whether the value can be dynamically changed. Only the properties listed in the table are supported, and any extra properties will be ignored.
This section describes optional link properties you can specify using the options parameter of DBMS_MGWADM.CREATE_MSGSYSTEM_LINK and DBMS_MGWADM.ALTER_MSGSYSTEM_LINK. Each listing also indicates which messaging system might use that property.
This property is used by WebSphere MQ JMS. It specifies the name of the broker control queue and corresponds to WebSphere MQ JMS administration tool property BROKERCONQ. The WebSphere MQ default is SYSTEM.BROKER.CONTROL.QUEUE.
This property is used by WebSphere MQ JMS. It specifies the name of the broker publish queue and corresponds to WebSphere MQ JMS administration tool property BROKERPUBQ. The WebSphere MQ default is SYSTEM.BROKER.DEFAULT.STREAM.
This property is used by WebSphere MQ JMS. It specifies the name of the broker queue manager and corresponds to WebSphere MQ administration tool property BROKERQMGR. If it is not set, then no default is used.
This property is used by WebSphere MQ JMS. It specifies the broker version number and corresponds to WebSphere MQ JMS administration tool property BROKERVER. The WebSphere MQ default is 0.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the URL string of a client channel definition table (CCDT) to be used. If not set, a CCDT is not used. If a CCDT is used, then the SYS.MGW_MQSERIES_PROPERTIES.channel link property must be NULL.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the character set identifier to be used to translate information in the WebSphere MQ message header. This should be the integer value of the character set (for example, 819) rather than a descriptive string. If it is not set, then the WebSphere MQ default character set 819 is used.
This property is used by WebSphere MQ JMS. It applies to WebSphere MQ JMS topic links only. The SYS.MGW_MQSERIES_PROPERITES attributes, inbound_log_queue and outbound_log_queue, specify the names of WebSphere MQ JMS topics used for propagation logging. This property specifies the name of the WebSphere MQ queue from which durable subscription messages are retrieved by the log topic subscribers. The WebSphere MQ default queue is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.
This property is used by WebSphere MQ JMS. It specifies the interval, in number of messages, between publish requests that require acknowledgment from the broker and corresponds to WebSphere MQ JMS administration tool property PUBACKINT. The WebSphere MQ default is 25.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the fully qualified Java classname of a class implementing the MQReceiveExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.
This initialization string is used by WebSphere MQ JMS. It is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_ReceiveExit and corresponds to WebSphere MQ JMS administration tool property RECEXITINIT. There is no default.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the fully qualified Java classname of a class implementing the MQSecurityExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.
This initialization string is used by WebSphere MQ JMS. It is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SecurityExit and corresponds to WebSphere MQ JMS administration tool property SECEXITINIT. There is no default.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the fully qualified Java classname of a class implementing the MQSendExit interface. This class must be in the CLASSPATH of the Messaging Gateway agent. There is no default.
This initialization string is used by WebSphere MQ JMS. It is passed by WebSphere MQ JMS to the constructor of the class specified by MQ_SendExit. It corresponds to WebSphere MQ JMS administration tool property SENDEXITINIT. There is no default.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the CipherSuite to be used; for example, SSL_RSA_WITH_RC4_128_MD5. This corresponds to the WebSphere MQ SSLCIPHERSUITE administration property.
This property is used by WebSphere MQ JMS. It specifies a space-delimited list of LDAP servers that can be used for certificate revocation list (CRL) checking. If not set, no CRL checking is done. This corresponds to the WebSphere MQ SSLCRL administration property. This option is not supported for WebSphere MQ Base Java, and instead, a client channel definition table (CCDT) must be used if CRL checking is needed.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It indicates whether the CipherSuite being used is supported by the IBM Java JSSE FIPS provider (IBMSJSSEFIPS). The value should be TRUE or FALSE. The default value is FALSE. This corresponds to the WebSphere MQ SSLFIPSREQUIRED administration property.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies a distinguished name (DN) pattern that the queue manager certificate must match in order for a connection to be established. If not set, no DN check is performed. This corresponds to the WebSphere MQ SSLPEERNAME administration property.
This property is used by WebSphere MQ Base Java and WebSphere MQ JMS. It specifies the total number of bytes sent and received before the secret key is renegotiated. If not set, the key is not renegotiated. This corresponds to the WebSphere MQ SSLRESETCOUNT administration property.
This section describes optional foreign queue properties that you can specify using the options parameter of DBMS_MGWADM.REGISTER_FOREIGN_QUEUE. Each listing also indicates which messaging system might use that property.
This property is used by WebSphere MQ JMS. It is used only for outbound propagation to a JMS queue or topic. It specifies the character set to be used to encode text strings sent to the destination. It should be the integer value of the character set (for example, 1208) rather than a descriptive string. The default value used by Messaging Gateway is 1208 (UTF8).
This property is used by WebSphere MQ JMS. It is a string representing the name of the WebSphere MQ queue from which durable subscription messages are retrieved by subscribers on this topic. It applies only to WebSphere MQ JMS topics. The WebSphere MQ default queue is SYSTEM.JMS.D.SUBSCRIBER.QUEUE.
This property is used by WebSphere MQ JMS. It is used only for outbound propagation to a JMS queue or topic. Supported values are TRUE and FALSE. TRUE indicates that WebSphere MQ should store the message as a JMS message. FALSE indicates that WebSphere MQ should store the message in non-JMS format so that non-JMS applications can access it. Default is TRUE.
This property is used by WebSphere MQ Base Java. It specifies the value used for the openOptions argument of the WebSphere MQ Base Java MQQueueManager.accessQueue method. No value is required. But if one is given, then the Messaging Gateway agent adds MQOO_OUTPUT to the specified value for an enqueue (put) operation. MQOO_INPUT_SHARED is added for a dequeue (get) operation. The default is MQOO_OUTPUT for an enqueue/put operation; MQOO_INPUT_SHARED for a dequeue/get operation.
This section describes optional propagation job properties that you can specify using the options parameter of DBMS_MGWADM.CREATE_JOB and DBMS_MGWADM.ALTER_JOB.
This property is used by TIB/Rendezvous. It specifies how Oracle Streams AQ message properties will be used during message propagation. Supported values are TRUE and FALSE. The default value is FALSE.
For an outbound propagation job, if the value is TRUE (case insensitive), then the Messaging Gateway agent will add a field for most Oracle Streams AQ message properties to the message propagated to the TIB/Rendezvous subject.
For an inbound propagation job, if the value is TRUE (case insensitive), then the Messaging Gateway agent will search the source message for a field with a reserved name, and if it exists, use its value to set the corresponding Oracle Streams AQ message property. A default value will be used if the field does not exist or does not have an expected datatype.
This property is used by WebSphere MQ JMS and Oracle JMS. You can use this property when the propagation destination is a JMS messaging system. It sets the delivery mode of messages enqueued to the propagation destination queue by a JMS MessageProducer. The default is PRESERVE_MSG. Supported values and their associated delivery modes are:
PERSISTENT (DeliveryMode.PERSISTENT)
NON_PERSISTENT (DeliveryMode.NON_PERSISTENT)
PRESERVE_MSG (delivery mode of the source JMS message is used)
This property is used by WebSphere MQ JMS and Oracle JMS. You can use it when the propagation source is a JMS messaging system. It sets the noLocal parameter of a JMS TopicSubscriber. TRUE indicates that messages that have been published to this topic through the same Messaging Gateway link will not be propagated. The default value FALSE indicates that such messages will be propagated from the topic.
This property can be used by any supported messaging system. It specifies the maximum number of messages, if available, to be propagated in one transaction. The default is 30.
This property is used by WebSphere MQ Base Java, WebSphere MQ JMS, TIB/Rendezvous, and Oracle JMS. It specifies whether Messaging Gateway should preserve the original message identifier when the message is propagated to the destination messaging system. The exact details depend on the capabilities of the messaging systems involved. Supported values are TRUE and FALSE. The default value is FALSE.
This property is used by TIB/Rendezvous. It specifies the discard amount of a queue. It is meaningful only for an inbound propagation job. The default is 0.
This property is used by TIB/Rendezvous. It specifies the limit policy for resolving overflow of a queue limit. It is meaningful only for an inbound propagation job. The default is DISCARD_NONE. Supported values and their associated limit policies are: DISCARD_NONE, DISCARD_FIRST, DISCARD_LAST and DISCARD_NEW.
DISCARD_NONE (TibrvQueue.DISCARD_NONE)
DISCARD_FIRST (TibrvQueue.DISCARD_FIRST)
DISCARD_LAST (TibrvQueue.DISCARD_LAST)
DISCARD_NEW (TibrvQueue.DISCARD_NEW)
This property is used by TIB/Rendezvous. It specifies the maximum event limit of a queue. It is meaningful only for an inbound propagation job. The default is 0.
This chapter discusses performance and scalability issues relating to Oracle Streams Advanced Queuing (AQ).
This chapter contains the following topics:
When persistent messages are enqueued, they are stored in database tables. The performance characteristics of queue operations on persistent messages are similar to underlying database operations. The code path of an enqueue operation is comparable to SELECT and INSERT into a multicolumn queue table with three index-organized tables. The code path of a dequeue operation is comparable to a SELECT operation on the multi-column table and a DELETE operation on the dequeue index-organized table. In many scenarios, for example when Oracle Real Application Clusters (Oracle RAC) is not used and there is adequate streams pool memory, the dequeue operation is optimized and is comparable to a SELECT operation on a multi-column table.
|
Note: Performance is not affected by the number of queues in a table. |
Oracle Real Application Clusters (Oracle RAC) can be used to ensure highly available access to queue data. The entry and exit points of a queue, commonly called its tail and head respectively, can be extreme hot spots. Because Oracle RAC may not scale well in the presence of hot spots, limit usual access to a queue from one instance only. If an instance failure occurs, then messages managed by the failed instance can be processed immediately by one of the surviving instances.
You can associate Oracle RAC instance affinities with 8.1-compatible queue tables. If you are using q1 and q2 in different instances, then you can use ALTER_QUEUE_TABLE or CREATE_QUEUE_TABLE on the queue table and set primary_instance to the appropriate instance_id.
Queue operation scalability is similar to the underlying database operation scalability. If a dequeue operation with wait option is applied, then it does not return until it is successful or the wait period has expired. In a shared server environment, the shared server process is dedicated to the dequeue operation for the duration of the call, including the wait time. The presence of many such processes can cause severe performance and scalability problems and can result in deadlocking the shared server processes. For this reason, Oracle recommends that dequeue requests with wait option be applied using dedicated server processes. This restriction is not enforced.
|
See Also: "DEQUEUE_OPTIONS_T Type" in Oracle Database PL/SQL Packages and Types Reference for more information on the wait option |
Oracle Streams Advanced Queuing table layout is similar to a layout with ordinary database tables and indexes.
Streams pool size should be at least 20 MB for optimal multi-consumer dequeue performance in a non-RACdatabase. Persistent queuing dequeue operations use the streams pool to optimize performance, especially under concurrency situations. This is, however, not a requirement and the code automatically switches to a less optimal code path.
Storage parameters can be specified when creating a queue table using the storage_clause parameter. Storage parameters are inherited by other IOTs and tables created with the queue table. The tablespace of the queue table should have sufficient space to accommodate data from all the objects associated with the queue table. With retention specified, the history table as well as the queue table can grow to be quite big.
Oracle recommends you use automatic segment-space management (ASSM). Otherwise initrans, freelists and freelist groups must be tuned for AQ performance under high concurrency.
Increasing PCTFREE will reduce the number of messages in a queue table/IOT block. This will reduce block level contention when there is concurrency.
Storage parameters specified at queue table creation are shared by the queue table, IOTs and indexes. These may be individually altered by an online redefinition using DBMS_REDEFINTION.
Because Oracle Streams Advanced Queuing is very I/O intensive, you will usually need to tune I/O to remove any bottlenecks.
Some environments must process messages in a constant flow, requiring that enqueue and dequeue processes run concurrently. If the message delivery system has only one queue table and one queue, then all processes must work on the same segment area at the same time. This precludes reasonable performance levels when delivering a high number of messages.
The best number for concurrent processes depends on available system resources. For example, on a four-CPU system, it is reasonable to start with two concurrent enqueue and two concurrent dequeue processes. If the system cannot deliver the wanted number of messages, then use several subscribers for load balancing rather than increasing the number of processes.
Tune the enqueue and dequeue rates on the queue so that in the common case the queue size remains small and bounded. A queue that grows and shrinks considerably will have indexes and IOTs that are out of balance, which will affect performance.
With multi-consumer queues, using several subscribers for load balancing rather than increasing the number of processes will reduce contention. Multiple queue tables may be used garnering horizontal scalability.
When enqueue and dequeue processes are running serially, contention on the same data segment is lower than in the case of concurrent processes. The total time taken to deliver messages by the system, however, is longer than when they run concurrently. Increasing the number of processes helps both enqueuing and dequeuing. The message throughput rate may be higher for enqueuers than for dequeuers when the number of processes is increased, especially with single consumer queues. Dequeue processes on multi-consumer queues scale much better.
Creating an index on a queue table is useful if you:
Dequeue using correlation ID
An index created on the column corr_id of the underlying queue table AQ$_QueueTableName expedites dequeues.
Dequeue using a condition
This is like adding the condition to the where-clause for the SELECT on the underlying queue table. An index on QueueTableName expedites performance on this SELECT statement.
Ensure that statistics are being gathered so that the optimal query plans for retrieving messages are being chosen. By default, queue tables are locked out from automatic gathering of statistics. The recommended use is to gather statistics with a representative queue message load and lock them.
The queue table indexes and IOTs are automatically coalesced by AQ background processes. However, they must continue to be monitored and coalesced if needed. In 10.2, with automatic space segment management (ASSM), an online shrink operation may be used for the same purpose. A well balanced index reduces queue monitor CPU consumption, and ensures optimal enqueue-dequeue performance.
Ensure that there are enough queue monitor processes running to perform the background tasks. The queue monitor must also be running for other crucial background activity. Multiple qmn processes share the load; make sure that there are enough of them. These are auto-tuned, but can be forced to a minimum number, if needed.
It is recommended that dequeue with a wait time is only used with dedicated server processes. In a shared server environment, the shared server process is dedicated to the dequeue operation for the duration of the call, including the wait time. The presence of many such processes can cause severe performance and scalability problems and can result in deadlocking the shared server processes.
Long running dequeue transactions worsen dequeue contention on the queue, and must be avoided.
Batching multiple dequeue operations on multi-consumer queues into a single transaction gives best throughput.
Use NEXT as navigation mode, if not using message priorities. This offers the same semantics but improved performance.
Use the REMOVE_NODATA dequeue mode if dequeuing in BROWSE mode followed by a REMOVE.
Propagation can be considered a special kind of dequeue operation with an additional INSERT at the remote (or local) queue table. Propagation from a single schedule is not parallelized across multiple job queue processes. Rather, they are load balanced. For better scalability, configure the number of propagation schedules according to the available system resources (CPUs).
Propagation rates from transactional and nontransactional (default) queue tables vary to some extent because Oracle Streams Advanced Queuing determines the batching size for nontransactional queues, whereas for transactional queues, batch size is mainly determined by the user application.
Optimized propagation happens in batches. If the remote queue is in a different database, then Oracle Streams Advanced Queuing uses a sequencing algorithm to avoid the need for a two-phase commit. When a message must be sent to multiple queues in the same destination, it is sent multiple times. If the message must be sent to multiple consumers in the same queue at the destination, then it is sent only once.
Buffered messaging operations in a Oracle Real Application Clusters environment will be fastest on the OWNER_INSTANCE of the queue.
Oracle provides views to monitor system performance and troubleshooting:
(G)V$PERSISTENT_QUEUES: All Active Persistent Queues in the Instance
(G)V$PERSISTENT_SUBSCRIBERS: All Active Subscribers of the Persistent Queues in the Instance
(G)V$PERSISTENT_PUBLISHERS: All Active Publishers of the Persistent Queues in the Instance
(G)V$BUFFERED_SUBSCRIBERS: Subscribers for All Buffered Queues in the Instance
(G)V$BUFFERED_PUBLISHERS: All Buffered Publishers in the Instance
(G)V$PERSISTENT_QMN_CACHE: Performance Statistics on Background Tasks for Persistent Queues
These views are integrated with the Automatic Workload Repository (AWR). Users can generate a report based on two AWR snapshots to compute enqueue rate, dequeue rate, and other statistics per queue/subscriber.
This chapter describes the Java Message Service (JMS) operational interface (shared interfaces) to Oracle Streams Advanced Queuing (AQ).
This chapter contains these topics:
Oracle Streams Advanced Queuing JMS Operational Interface: Shared Interfaces
Setting Default TimeToLive for All Messages Sent by a MessageProducer
Setting Default Priority for All Messages Sent by a MessageProducer
This section discusses Oracle Streams Advanced Queuing shared interfaces for JMS operations.
This section contains these topics:
public void start()
throws JMSException
AQjmsConnection.start() starts a JMS connection for receiving messages.
public oracle.jms.AQjmsConnection getJmsConnection()
throws JMSException
AQjmsSession.getJmsConnection() gets a JMS connection from a session.
public void commit()
throws JMSException
AQjmsSession.commit() commits all JMS and SQL operations performed in a session.
public void rollback()
throws JMSException
AQjmsSession.rollback() terminates all JMS and SQL operations performed in a session.
public java.sql.Connection getDBConnection()
throws JMSException
AQjmsSession.getDBConnection() gets the underlying JDBC connection from a JMS session. The JDBC connection can be used to perform SQL operations as part of the same transaction in which the JMS operations are accomplished.
public oracle.jdbc.pool.OracleOCIConnectionPool getOCIConnectionPool()
AQjmsConnection.getOCIConnectionPool() gets the underlying OracleOCIConnectionPool from a JMS connection. The settings of the OracleOCIConnectionPool instance can be tuned by the user depending on the connection usage, for example, the number of sessions the user wants to create using the given connection. The user should not, however, close the OracleOCIConnectionPool instance being used by the JMS connection.
public javax.jms.BytesMessage createBytesMessage()
throws JMSException
AQjmsSession.createBytesMessage() creates a bytes message. It can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_BYTES_MESSAGE or AQ$_JMS_MESSAGE payload types.
public javax.jms.MapMessage createMapMessage()
throws JMSException
AQjmsSession.createMapMessage() creates a map message. It can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_MAP_MESSAGE or AQ$_JMS_MESSAGE payload types.
public javax.jms.StreamMessage createStreamMessage()
throws JMSException
AQjmsSession.createStreamMessage() creates a stream message. It can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_STREAM_MESSAGE or AQ$_JMS_MESSAGE payload types.
public javax.jms.ObjectMessage createObjectMessage(java.io.Serializable object)
throws JMSException
AQjmsSession.createObjectMessage() creates an object message. It can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_OBJECT_MESSAGE or AQ$_JMS_MESSAGE payload types.
public javax.jms.TextMessage createTextMessage()
throws JMSException
AQjmsSession.createTextMessage() creates a text message. It can be used only if the queue table that contains the destination queue/topic was created with the SYS.AQ$_JMS_TEXT_MESSAGE or AQ$_JMS_MESSAGE payload types.
public javax.jms.Message createMessage()
throws JMSException
AQjmsSession.createMessage() creates a JMS message. You can use the AQ$_JMS_MESSAGE construct message to construct messages of different types. The message type must be one of the following:
DBMS_AQ.JMS_TEXT_MESSAGE
DBMS_AQ.JMS_OBJECT_MESSAGE
DBMS_AQ.JMS_MAP_MESSAGE
DBMS_AQ.JMS_BYTES_MESSAGE
DBMS_AQ.JMS_STREAM_MESSAGE
You can also use this ADT to create a header-only JMS message.
public oracle.jms.AdtMessage createAdtMessage()
throws JMSException
AQjmsSession.createAdtMessage() creates an AdtMessage. It can be used only if the queue table that contains the queue/topic was created with an Oracle ADT payload type. An AdtMessage must be populated with an object that implements the CustomDatum interface. This object must be the Java mapping of the SQL ADT defined as the payload for the queue/topic. Java classes corresponding to SQL ADT types can be generated using the Jpublisher tool.
Property names starting with JMS are provider-specific. User-defined properties cannot start with JMS.
The following provider properties can be set by clients using text, stream, object, bytes or map messages:
JMSXAppID (string)
JMSXGroupID (string)
JMSXGroupSeq (int)
JMS_OracleExcpQ (string)
This message property specifies the exception queue.
JMS_OracleDelay (int)
This message property specifies the message delay in seconds.
The following properties can be set on AdtMessage
JMS_OracleExcpQ (String)
This message property specifies the exception queue as "schema.queue_name"
JMS_OracleDelay (int)
This message property specifies the message delay in seconds.
This section contains these topics:
public void setBooleanProperty(java.lang.String name,
boolean value)
throws JMSException
AQjmsMessage.setBooleanProperty() specifies a message property as Boolean. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the Boolean property |
value | Boolean property value to set in the message |
public void setStringProperty(java.lang.String name,
java.lang.String value)
throws JMSException
AQjmsMessage.setStringProperty() specifies a message property as string. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the string property |
value | String property value to set in the message |
public void setIntProperty(java.lang.String name,
int value)
throws JMSException
AQjmsMessage.setIntProperty() specifies a message property as integer. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the integer property |
value | Integer property value to set in the message |
public void setDoubleProperty(java.lang.String name,
double value)
throws JMSException
AQjmsMessage.setDoubleProperty() specifies a message property as double. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the double property |
value | Double property value to set in the message |
public void setFloatProperty(java.lang.String name,
float value)
throws JMSException
AQjmsMessage.setFloatProperty() specifies a message property as float. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the float property |
value | Float property value to set in the message |
public void setByteProperty(java.lang.String name,
byte value)
throws JMSException
AQjmsMessage.setByteProperty() specifies a message property as byte. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the byte property |
value | Byte property value to set in the message |
public void setLongProperty(java.lang.String name,
long value)
throws JMSException
AQjmsMessage.setLongProperty() specifies a message property as long. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the long property |
value | Long property value to set in the message |
public void setShortProperty(java.lang.String name,
short value)
throws JMSException
AQjmsMessage.setShortProperty() specifies a message property as short. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the short property |
value | Short property value to set in the message |
public void setObjectProperty(java.lang.String name,
java.lang.Object value)
throws JMSException
AQjmsMessage.setObjectProperty() specifies a message property as object. Only objectified primitive values are supported: Boolean, byte, short, integer, long, float, double and string. It has the following parameters:
| Parameter | Description |
|---|---|
name | Name of the Java object property |
value | Java object property value to set in the message |
public void setTimeToLive(long timeToLive)
throws JMSException
This method sets the default TimeToLive for all messages sent by a MessageProducer. It is calculated after message delay has taken effect. This method has the following parameter:
| Parameter | Description |
|---|---|
timeToLive | Message time to live in milliseconds (zero is unlimited) |
public void setPriority(int priority)
throws JMSException
This method sets the default Priority for all messages sent by a MessageProducer. It has the following parameter:
| Parameter | Description |
|---|---|
priority | Message priority for this message producer. The default is 4. |
Priority values can be any integer. A smaller number indicates higher priority. If a priority value is explicitly specified during a send() operation, then it overrides the default value set by this method.
public void createAQAgent(java.lang.String agent_name,
boolean enable_http,
throws JMSException
This method creates an AQjmsAgent. It has the following parameters:
| Parameter | Description |
|---|---|
agent_name | Name of the AQ agent |
enable_http | If set to true, then this agent is allowed to access AQ through HTTP |
You can receive a message synchronously by specifying Timeout or without waiting. You can also receive a message using a transformation:
public javax.jms.Message receive(long timeout)
throws JMSException
This method receives a message using a message consumer by specifying timeout.
| Parameter | Description |
|---|---|
timeout | Timeout value in milliseconds |
Example 15-6 Using a Message Consumer by Specifying Timeout
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
Topic shipped_orders;
int myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"WS", "Shipped_Orders_Topic");
/* create a subscriber, specifying the correct CustomDatumFactory and
selector */
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders, 'WesternShipping',
" priority > 1 and tab.user_data.region like 'WESTERN %'",
false, AQjmsAgent.getFactory());
/* receive, blocking for 30 seconds if there were no messages */
Message = subscriber.receive(30000);
Example 15-7 JMS: Blocking Until a Message Arrives
public BolOrder get_new_order1(QueueSession jms_session)
{
Queue queue;
QueueReceiver qrec;
ObjectMessage obj_message;
BolCustomer customer;
BolOrder new_order = null;
String state;
try
{
/* get a handle to the new_orders queue */
queue = ((AQjmsSession) jms_session).getQueue("OE", "OE_neworders_que");
qrec = jms_session.createReceiver(queue);
/* wait for a message to show up in the queue */
obj_message = (ObjectMessage)qrec.receive();
new_order = (BolOrder)obj_message.getObject();
customer = new_order.getCustomer();
state = customer.getState();
System.out.println("Order: for customer " + customer.getName());
}
catch (JMSException ex)
{
System.out.println("Exception: " + ex);
}
return new_order;
}
public javax.jms.Message receiveNoWait()
throws JMSException
This method receives a message using a message consumer without waiting.
Example 15-8 JMS: Nonblocking Messages
public BolOrder poll_new_order3(QueueSession jms_session)
{
Queue queue;
QueueReceiver qrec;
ObjectMessage obj_message;
BolCustomer customer;
BolOrder new_order = null;
String state;
try
{
/* get a handle to the new_orders queue */
queue = ((AQjmsSession) jms_session).getQueue("OE", "OE_neworders_que");
qrec = jms_session.createReceiver(queue);
/* check for a message to show in the queue */
obj_message = (ObjectMessage)qrec.receiveNoWait();
new_order = (BolOrder)obj_message.getObject();
customer = new_order.getCustomer();
state = customer.getState();
System.out.println("Order: for customer " + customer.getName());
}
catch (JMSException ex)
{
System.out.println("Exception: " + ex);
}
return new_order;
}
A transformation can be applied when receiving a message from a queue or topic. The transformation is applied to the message before returning it to JMS application.
The transformation can be specified using the setTransformation() interface of the AQjmsQueueReceiver, AQjmsTopicSubscriber or AQjmsTopicReceiver.
Example 15-9 JMS: Receiving Messages from a Destination Using a Transformation
Assume that the Western Shipping application retrieves messages from the OE_bookedorders_topic. It specifies the transformation OE2WS to retrieve the message as the Oracle object type WS_order. Assume that the WSOrder Java class has been generated by Jpublisher to map to the Oracle object WS.WS_order:
public AQjmsAdtMessage retrieve_bookedorders(TopicSession jms_session)
AQjmsTopicReceiver receiver;
Topic topic;
Message msg = null;
try
{
/* get a handle to the OE_bookedorders_topic */
topic = ((AQjmsSession)jms_session).getTopic("OE", "OE_bookedorders_topic");
/* Create a receiver for WShip */
receiver = ((AQjmsSession)jms_session).createTopicReceiver(
topic, "WShip, null, WSOrder.getFactory());
/* set the transformation in the publisher */
receiver.setTransformation("OE2WS");
msg = receiver.receive(10);
}
catch (JMSException ex)
{
System.out.println("Exception :", ex);
}
return (AQjmsAdtMessage)msg;
}
public void setNavigationMode(int mode)
throws JMSException
This method specifies the navigation mode for receiving messages. It has the following parameter:
| Parameter | Description |
|---|---|
mode | New value of the navigation mode |
Example 15-10 Specifying Navigation Mode for Receiving Messages
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
Topic shipped_orders;
int myport = 5521;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic("WS", "Shipped_Orders_Topic");
/* create a subscriber, specifying the correct CustomDatumFactory and selector */
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders, 'WesternShipping',
"priority > 1 and tab.user_data.region like 'WESTERN %'", false,
AQjmsAgent.getFactory());
subscriber1.setNavigationMode(AQjmsConstants.NAVIGATION_FIRST_MESSAGE);
/* get message for the subscriber, returning immediately if there was nomessage */
Message = subscriber.receive();
You can receive a message asynchronously two ways:
public void setMessageListener(javax.jms.MessageListener myListener)
throws JMSException
This method specifies a message listener at the message consumer. It has the following parameter:
| Parameter | Description |
|---|---|
myListener | Sets the consumer message listener |
Example 15-11 Specifying Message Listener at Message Consumer
TopicConnectionFactory tc_fact = null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
TopicSession jms_sess;
Topic shipped_orders;
int myport = 5521;
MessageListener mLis = null;
/* create connection and session */
tc_fact = AQjmsFactory.getTopicConnectionFactory(
"MYHOSTNAME", "MYSID", myport, "oci8");
t_conn = tc_fact.createTopicConnection("jmstopic", "jmstopic");
jms_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
shipped_orders = ((AQjmsSession )jms_sess).getTopic(
"WS", "Shipped_Orders_Topic");
/* create a subscriber, specifying the correct CustomDatumFactory and selector */
subscriber1 = jms_sess.createDurableSubscriber(
shipped_orders, 'WesternShipping',
"priority > 1 and tab.user_data.region like 'WESTERN %'",
false, AQjmsAgent.getFactory());
mLis = new myListener(jms_sess, "foo");
/* get message for the subscriber, returning immediately if there was nomessage */
subscriber.setMessageListener(mLis);
The definition of the myListener class
import oracle.AQ.*;
import oracle.jms.*;
import javax.jms.*;
import java.lang.*;
import java.util.*;
public class myListener implements MessageListener
{
TopicSession mySess;
String myName;
/* constructor */
myListener(TopicSession t_sess, String t_name)
{
mySess = t_sess;
myName = t_name;
}
public onMessage(Message m)
{
System.out.println("Retrieved message with correlation: " ||
m.getJMSCorrelationID());
try{
/* commit the dequeue */
mySession.commit();
} catch (java.sql.SQLException e)
{System.out.println("SQL Exception on commit"); }
}
}
This section contains these topics:
public java.lang.String getJMSCorrelationID()
throws JMSException
AQjmsMessage.getJMSCorrelationID() gets the correlation identifier of a message.
This section contains these topics:
public boolean getBooleanProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getBooleanProperty() gets a message property as Boolean. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the Boolean property |
public java.lang.String getStringProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getStringProperty() gets a message property as string. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the string property |
public int getIntProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getIntProperty() gets a message property as integer. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the integer property |
public double getDoubleProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getDoubleProperty() gets a message property as double. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the double property |
public float getFloatProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getFloatProperty() gets a message property as float. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the float property |
public byte getByteProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getByteProperty() gets a message property as byte. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the byte property |
public long getLongProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getLongProperty() gets a message property as long. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the long property |
public short getShortProperty(java.lang.String name)
throws JMSException
AQjmsMessage.getShortProperty() gets a message property as short. It has the following parameter:
| Parameter | Description |
|---|---|
name | Name of the short property |
This section contains these topics:
public void close()
throws JMSException
AQjmsProducer.close() closes a MessageProducer.
public void close()
throws JMSException
AQjmsConsumer.close() closes a message consumer.
public void stop()
throws JMSException
AQjmsConnection.stop() stops a JMS connection.
public void close()
throws JMSException
AQjmsSession.close() closes a JMS session.
public void close()
throws JMSException
AQjmsConnection.close() closes a JMS connection and releases all resources allocated on behalf of the connection. Because the JMS provider typically allocates significant resources outside the JVM on behalf of a connection, clients should close them when they are not needed. Relying on garbage collection to eventually reclaim these resources may not be timely enough.
This section contains these topics:
public java.lang.String getErrorCode()
AQjmsException.getErrorCode() gets the error code for a JMS exception.
public int getErrorNumber()
AQjmsException.getErrorNumber() gets the error number for a JMS exception.
|
Note: This method will be deprecated in a future release. UsegetErrorCode() instead. |
public java.lang.String getLinkString()
AQjmsException.getLinkString() gets the exception linked to a JMS exception. In general, this contains the SQL exception raised by the database.
public void printStackTrace(java.io.PrintStream s)
AQjmsException.printStackTrace() prints the stack trace for a JMS exception.
public void setExceptionListener(javax.jms.ExceptionListener listener)
throws JMSException
AQjmsConnection.setExceptionListener() specifies an exception listener for a connection. It has the following parameter:
| Parameter | Description |
|---|---|
listener | Exception listener |
If an exception listener has been registered, then it is informed of any serious problem detected for a connection. This is accomplished by calling the listener onException() method, passing it a JMS exception describing the problem. This allows a JMS client to be notified of a problem asynchronously. Some connections only consume messages, so they have no other way to learn the connection has failed.
Example 15-13 Specifying Exception Listener for Connection
//register an exception listener
Connection jms_connection;
jms_connection.setExceptionListener(
new ExceptionListener() {
public void onException (JMSException jmsException) {
System.out.println("JMS-EXCEPTION: " + jmsException.toString());
}
};
);
ޙB>T@T/ _ F`CX&p! 21ަX]v 3Ư 01=0&ld 'y []j7
8{ ySA>T/ ` ^p Wp,([ z| 8#9 }li!gGA j))@7l [irUUL^`
V1
@GA>|ғ@
.p Pa
/o [7(oH|ǀ5Si嶰E<^
Pgl]
wrNv7 k{ ՀgM+(* Y=6zDfrg pZ Z SoG {/ pWrwrp@| x-
wwvWx+@| I~%u#
y?mffEG& p9 Є9PAoqx 0 @ T0 l "hv$v6 | ~0Z0 @ p l xS @
3iP hO.TZ !p8H P
l yhzᅣw
W x m [q{a'/"ȍэh"DH 8ȎhQ8؏p ?` J
x9o`V `;0
` x5 ` E y &9[YƐ9 8'f C# ]9Yɐ; 9`@ip !0n`1 )瘗븗uw9ɗy闅َ Q
]49@
2=m?Up 9 23=gIe34Q ! ٠ ] TіsI1⨎qiɘٞ뉟 )A6E 8?R5!b6 &63|WOt6E
ʠ
*bI@n aJV,j>UkO @?E #WҢF7)`}ʤMJ16 B'a F0 GeO QPHPGT`fPaf`hz G@N
*Jjʨꨏ
*JjK p 01 W`hX O L:PW7KQS @{کɚ ip ^5\0VX ۚW :FQ d950X5 lU}抮K V*6{
3USX Z
۬ `pS} W z:PzjHP5u"&; 1^) ̊"gaBU[^P1
[9XڰjW S55eh UZ*WHHP9:kڶ:v ŪlQ\VڊVZWkP#kOŊS ڭZU f9 PQ kl
l pW`.۹
CZS2Ź95pYKT\p{.` 皭5ljf{9\PT'5P
;aFQͪXp :[Y㪬-f[ 0?X^ FU kq> :[GܹܹWãzP^} SЮk;c+,<غliZ\hڊH bpLpܵlk̽ |[ ulx X*ۭbe|zZ5зiLʣ#ӿj;ýlūze>lhZl˲{ zZhSP <S[S\ D7;1K>>+aB\=q(܌Jt PѲl؊9
фʿk <\bD<BöS$
-ÿ۽ ;ڭL|9pQښWkuMC Z] ˫@ѻZ]>C˟aƳ
P
O-sM'Q
t Z[ÜʦJkigV<
&;t
ّ] XZt `۫X ֵ-q*j=+٭`[՜՚ݬ\
˾|6i
|W1Lb7|ݬ<7-
m9Q][ԼӃ6 1ҠS*✪]\ ]`= 0%
.Nnq ;PK&R&SMj Hj PK -A OEBPS/img/adque042.gif GIF87aP ? * *? * * * U U? U U U ? ? ? ? * * ?* * * ** **?*******U *U?*U*U*U* *?**** *?**** *?**** *?***U U ?U U U U* U*?U*U*U*UU UU?UUUUUUU U?UUUU U?UUUU U?UUUU U?UUU ? * *?***U U?UUU ? ? ? ? ? * *?***U U?UUU ? ? ? ? ? * *?***U U?UUU ?ժ ժ?ժժժ ? ? ? * *?***U U?UUU ? ? ? ? ? ***UUU, P H*\ȰÇ#JHŋ3jȱǏ C Iɓ(S\ɲ˗0cʜI͛8sɳϟ@
JѣH*]?8П?O@O@ϟ(?(?o@
O@
O@8?8?8П?O@O@ϟ? 4xaB 6tbD)O@ϟ(?(?o@
O@
O@8?8?8П?O@O@ϟ(?(?o@O@
DPB
>QD-^ĘQFqȑ#G 9rȑ#G 9rȑ#G 9rȑ#G 9rȑ#A8rȑ#G 9rȑ#G!̗/_>~ !Ǒ#G 9rȑ#G 0@}Coc| 9rȑ#G 9rϟ?'p_|˗߾| /_>O |/?Ǒ#G 9rȑ#G _> _> ߾}/|_}qȑB8rȑ#G'_>'0~o`>'0>~ 7p| H*\ȰÇ"D!B"D
O`} '0>~O`} /w0 D!Bq?!B"D!Ba _>/|'0?>"D!B\ D!B"D!Bt/_|/ӗ_>˗ϟ@}_|˗o| H*\ȰÇ#JHŋ3jȱǏ C IHL4iҤI&MϟI&M4iҤI ?~ 8`A&TaC ,h
2l!Ĉ'Rџ?ӗ/>}П <0
2Ǐ ?}˷?$XA .dC%NXq?
˗o_?-Zh?~g?-ZhѢE-V̧ϟE-ZO>hѢE-Zh|-Zhb>}gѢE-Zh"E,Zh"E}YE-ZhѢEhѢEg?-ZhѢE-RϢE-RԗoE-ZhѢE-ϢE-RԗoE-ZhѢEHП>-ZHQ_}-ZhѢE-F"A,Zh"E}YhѢE,""ȟ?$X`A '1 ?8&[)!
:+ۋ?@p7ГH=6hG:@ȃ uKZؤp$Tb05
D)l0 ɒ,p#~R <ȫ2yAVTq ~DI i6 Ӣ otn@9 s@ Lθ{bw
`N C АrV%tyv"HxC@zH7s器*j4 :饛~A,0YÝưW@ڹ;| ?}_?}_>~?} _> H*$`> 4XP'p "LP| .\80 .\P |,h>O@
DPaA$X A}O@
DPB8`A߿߿߿| ?~߿|/߿_/߿/?$XA 0 4 ?} H*T/
篠|ϟ> OO@'p`~? P7p
8P`} H |߿|`>~ HA;xAw| 8@} ߿_>70|
/>~O`} '0| 70'p A~ 80 'p
?O@} _>$@̷߿'p| 8p|7p / ,h +/_~
O?ϟ)o ?
@
8p@}'P@ 7P ?~ӧO8p@ (߿ 8`A;x|w|0@O >_ ߾|O`>>O
0@ (0o}(p_
@7p@ ?8_| 8p`8po? 4xaB̷/߾_>~O`>'p_|˗_>70_|O?˗A}gP OA}8?G A|
70_|O`~/_>~| /߿|뗏}/_>˗o|G0? ˗/ ?#|˧ϟ|O_>~/_|?}/_>}>~ /_>~G A
'P AG?}'p 7p̗/>7p`} /_>˗߿| / ?/_|/_}˗'p "L(0?ۗo`>~߿}O`>~ϟ| 'P ߾|S@~%O!A}wP?}#PF 'P`> (P_>~
o|_> ߾|߿|o߿|_>~ ϟ| 'P ߾|7p8P>~ 8p ('p
@~! B O~3ȏ A7߿O@
A/_}o>۷_>/_~'0|o߿|G_>$XA Gp_o`O`>؏ | '0|
GP ?
>~8p ~8p 8"_ +X0
o`?~ 70߿|
70|O`>/| 70|`A
ǯ`+X |+X`+XW?'p N 8> 'p / GP`?G߾|/|
/| ' ?~O`| H
|/߿߿|/߿ (0>~O`o?} ϟ @ 8`? O@ 8 @} /_O@
`/|/>_o`} '0| 70 | <(P w+П8`' p8|? #H 0@_/߿|/ /| 70߿|
/ ,h /_? ?}O| _>~O`>>#B+П8`?$p 'p/?$X | ` 70?} 7P_70|
_>?~`> ? 4xaB 6tbD%Gb|˗ ʼn 8P>$XA .dC%N E=ܗ/_?'p} H*\ȰÇ#J(Q?#/_?'p} H*\ȰÇ#J(> 4xaB'p "Lp>? 4xaB 6tbD% |ПO H |ϟ?$XA 0'p "Lp!Æ B(q"E 8p `>'p 8 ,h
O@ 8`A&TaC!F8@ ?
08? ? 4xaB'p} H*\ȰÇ#JHQ |O H | <0B 8P>$XA .dC%N(`>O@'p@$`>O@
DP} (p ,h
2l!Ĉ'R0'p A 8p 0'p "L>? 4xaB 6tbD)
O 8~ 8? O 8`A&Thp |
<0
:|1ĉ'p} HP`? 'p~ H*4`>O@
DPB
>QD8p>$( |O@ 8p`?$XA 0'p "Lp!Æ B(q"E 8p `>'p 8 ,h
O@ 8`A&TaC!F8@ ?
08? ? 4xaB'p} H*\ȰÇ#JHQ |O H | <0B 8P>$XA .dC%N(`>O@'p@$`>O@
DP} (p ,h
2l!Ĉ'R0'p A 8p 0'p "L>? 4xaB 6tbD)
O 8~ 8? O 8`A&Thp |
<0
:|1ĉ'p} HP`? 'p~ H*4`>O@
DPB
>QD8p>$( |O@ 8p`?$XA 0'p "Lp!Æ B(q"E 8p `>'p 8 ,h
O@ 8`A&TaC!F8@ ?
08? ? 4xaB'p} H*\ȰÇ#JHQ |O H | <0B 8P>
̗/_>} 8 O@
DPB
>Q"B ?
08? ? 4xaB'p} o`| 'p "Lp!Æ B(!|O H | <0B 8P>
7_'p_>}O_|_|? 4xaB 6tbć 8p `>'p 8 ,h
O@ (0@~߾}_> } ,h
2l!Ĉ8p>$( |O@ 8p`?$XA 0'P |?~/߿߿ ?}'p "Lp!Æ B`>O@'p@$`>O@
DP} (p `>/߿/߾/ ,h
2l!Ĉ8p>$( |O@ 8p`?$XA 0'P`'}'0߿}>~? 4xaB 6tbĈ 8p `>'p 8 ,h
O@ (0˗O}_|O߿}? 4xaB 6tbĈ 8p `>'p 8 ,h
O@ 8`A 8`A&TaC!F8`>O@'p@$`>O@
DP} (p ,8P_| 8`A&TaC!F8`>O@'p@$`>O@
DP} (p ,h
2l!Ĉ'R0'p A 8p 0'p "L>? 4xaB 6tbD)
O 8~ 8? O 8`A&Thp |
<0
:|1ĉ'p} HP`? 'p~ H*4`>O@
DPB
>QD8p>$( |O@ 8p`?$XA 0'p "Lp!Æ B(q"E 8p `>'p 8 ,h
O@ 8`A&TaC!F8@ ?
08? ? 4xaB'p} H*\ȰÇ#JHQ |O H | <0B 8P>$XA .dC%N(`>O@'p@$`>O@
DP} (p ,h
2l!Ĉ'R0'p A 8p 0'p "L>? 4xaB 6tbDOD 8p `>'p 8 ˗/_>~ H0'p "Lp!Æ B0@}$J,0'p A 8p 0'p|O@
Dp>? 4xaB 6tbD_|˧/| / ?/_>~8p>$( |O@ 8p`?o?}O| '0@~O`>G 8P>$XA .dC#>_>o| }+0'p A 8p 0'p|'0 }'0|߿|O`>~ 0'p "Lp!Æ B0 |ӗo`>o ?} /@~
'p} HP`? 'p~ / |ӗo`>o ?} /@~$`>O@
DPB
>a 8P߿|
߿|
O@ ?
08? ?`>/߿@$(p |
<0
:|1"|O ?O`O ?>~+0'p A 8p 0'p|O ?O`O ?>~#H>? 4xaB 6tbDO| ԗ/_>'p_|˧/}30'p A 8p 0'p|'p_|˗/}/_>}ӗO|$H>? 4xaB 6tbD
M\0'p A 8p 0'p ;x'p} H*\ȰÇ#JToB ?
08? ? 4(0 `>O@
DPB
>QD8p>$( |O@ 8p`?$XA 0'p "Lp!Æ B(q"E 8p `>'p 8 ,h
O@ 8`A&TaC!F8"@'p} 8p 'p |П@ H*`>O@
DPB
>QD 8` 8 |O@$XР?$XA O@ 8`A&TaC!F81"|,HP 0( |,Hp ,h
O@ 8`A&TaC!F81b?$Xp
08p |,(P ,h
O@ 8`A&TaC!F8Q>$X0_?`>'p?} H`>$XA 0'p "Lp!Æ B(qD$Xp 08P |,? 4xaB'p} H*\ȰÇ#J8 | ? O ( | ? 4xaB'p} H*\ȰÇ#JH |O 8P |̧? 4xaB'p} H*\ȰÇ#JH>$? 08 | <0B 8P>$XA .dC%N(`>O@'p@$`>O@
DP} (p ,h
2l!Ĉ'R`>O@'p@$ | <0 8P>$XA .dC%N8 |'p A 8p `>8`A&Tp |
<0
:|1ĉ ˗/_>~'p@$8`>'p "L>? 4xaB 6tbD)̗/ 8p /_| 8`A&Tp |
<0
:|1ĉ ˗b? ˧? 4xaB
'p} H*\ȰÇ#JH ?'p@$Xp ,h
O@ 8`A&TaC!F8bŁ 8p ,h
2$`>O@
DPB
>QDO H*\Ȑ>? 4xaB 6D ?~'p "Lp!Æ ϟ?$X`? ?~ H*408`A Ǐ_? H*珟|ӷ ?8`A&Ta (p>}ǯ ,`>'p ˗/} ? 4xaB 6,˗O>~ 8`A& /_})TPB
*T~O~ 8?ӗO ~ 8`A&TaC /_>~ >ԧÇ >|A~-08 | 8`A&TaC
ӗ D
"D!Bo~ 8? <0
:|p_>!&"D!BQ|O / ,h
2lB~AП>
0?~
b|Q|O / A $H A$Hp`>$?$H |$H A
/ ,h %L0~%4_ `>%L|O / A $H #H|$H_>$H>$H A / ,h %L0?}
̧/>'0߿| |ӗO߿|O`>}70_ ˧/a? $H A _'0|O |/_ | ̧/_? A $H | 8`A/a |/_/?~o?>_ۗ0aK`>'p| $H A|/_/?~o?>_>$H A /_>$XAK0aB~'0|
/߿|
'_| ̗`+0@ 8`A ˧~ 8?#H A $ȏ?~__O`>/|#H A $(_| H ӗ0a _߿_맏_|O߿| o| HӇ_? $H A O/߿|/߿|_?}/߿/߿|O|O@
,/_>"Dϟ>" O} _'0_> '0߾}O`Ӈ!BӇ_? $H A o>~Ǐ߿|/߿|/@o>'0 䧏 A $H | 8`A/aO߿|/_>~ϟ|˗o}߾| '0_|ۗ0aK`>'p| $H AO߿|/_>~ϟ|˗o}߾| '0 AG A $(_| H ӗ0a̗0a &LP_>} 'p@? 4x|%L0a "/_ /a +/a &L|O / ,h
K0a &D/_ &,O_ &L0a &LHP_>} 'p@? 4xaB 6tP!| BLO D!B@}%08_>$XA .dC1?}!*/_?'0|˗| ̧/_?} / ?1|O / ,h _|ӗ?/|O_~O`}&L |&L?} &LX߾O>~/ '0|/?~/ &4/ 8p < }O>~_>O`>_ _>~ &Lh_| &LXП &,oO`>}'0| /@~K0aK`>'p| H
/ | O߾~ '0|7&L |&L?} &LX0_|'0߿~O`> | <|O / ,h B#_>o߿| '0| 8_>$XA˗0aK0a o>'0߾~ _>>~/a ˧/a? 'p "4o| _>'0߿|O`>'&L |&L?} &LXП| ܗ/ ?/_~ӗO`>/_>}%L0A}%08_>$XA˗߿}O`߾| '0|˧O` &} 'p@? 4xaB 6tP!| BLO D!B@}%08_>$XA .dC1?}!B"Dӗ |O 8`A&TaC˗"Ą5ܷ0|惘@kدB}%08_>
G| G A G A$HP?~$HP`~
/ ,h % o_B
̗0| KP`ԗP|O / AG| G A G A$Hp`$8P A ~O |̧/>ϟ|/ ?GП| '0߿|O_|˗߿|/|˗||O / A/>~ '0?~#(0|˗?'_|˧/ A/|˷?}/_~/߿|/_>~ ?˗? 4xaA70 }#߿}/߿|o|/ |'0|o_>o?'0߿|o|ϟӗ |O$/|O`>~G_~_ }۷|/߿| ߾}߾O`۷>O?} / ,h % o`>_70@ӷ|70 A}'0߿|o`_
_ӗO_~ 8?#H|
'0|G_}O_o`>O߾~
/|
̗o ?}G?~'p ",O_O`>'p>~_}/ o|70߿~o|7`>߿| HP_>} 08_> '0| O@_>} | ߿| ؏_} '0|˷/@o |߿'p@~'p ",O__|O ?Ǐ_>O`>}o?'0|?~}70߿|㧏@~/?}%08_> '0|O ??~o_?'}Gp_?/|㷯| /|Ǐ>~>˗? 4xaAO`>'0}+/_>~˷O߾~o_|˗/ ~'p_>}˗߿~ϟ|70?}/_>} /?}%08_> _'0߿}#(P_|˷O߾~'p_|˗/ ~o_>}˗߿~O_|| ܗ/>G?~'p ",O_%L0a &L྄ӗ |O$ ?$XA .dذ>s谡?}
9tСC P_>} 'p@ A'p "Lp!Æ S/_> СC :tP |%08_} H*\ȰÇ˗"D"D!B |ۗ |O? 4xaB 6tP?~˗"ą˗O ?~A"D
o>'p@ /_|? 4xaB 6tHП~O| 8`A"`>
O@
DPB
'p 'p 8p 0'p "Lp!Æ 8`A~ HO |,h
2l谡>~ 8 ~ 8?
o |,h
2l谡>~'p "L? (> 4xaB 6<@'p 'p@$Xp? p <0
O~'p "Lp!Æ B(qb~ 8? 4xaB 6tbD)Vxc 8p ,h
2l!Ĉ'Rh"ƌ'p@$XA .dC%NXEO H*\ȰÇ#JHŋ308`A&TaC!F8bE1f`>'p "Lp!Æ B(q"Ŋ/b |O@
DPB
>QD ?W~*V4`>'p "L_?~
S?
B
*TPB
O~
O OB
"08`A&珟>)_>
?}
*TPB
*L菟>'0>~˗|˧/}SH0_|ӧPB'p@$XA _>} ̷߿|O`}ӗO߾~)$/_SPB
*TPB۷_>~'P /߿~ۧ`>
*T8 |O@
D`~| _>~߾ԷOa>
*TPB
*Do`G0߿|'0?~
'P O@
Da? <0a|70_>_>WП>}SPB
*TPBO`|70߿|˧`>
*T8 |O@
D`/ |
/}!ԗ`>
*TPB
*D?~o>70߿|g`>80 ,h 'p@$XA ۷O>~
/~O_?*TPB
*Ta| '0߿}o` O|
*Tp`? <0a|o`'0|_}SPB
*TPB*4OB
*T( |O@
D`>
SPB
*TPB
S |*TPB 8`A HK | 8`A&TaC!F8bŅ 8`A 8`A&TaC!F8bE1BO@O@
DPB
>QD-^ |,(? 4xaB 6tbD)Vx} H?$XA .dC%NXE'p 8`A&TaC!F8bE1ZO@'p "Lp!Æ B(q"Ŋ/b`> O@
DPB
>QD-^Ęq | <0
:|1ĉ+Z1?} o ,h
2l!Ĉ'Rh"ƌ8P ,h
2l!Ĉ'Rh"ƌ'P ,h
2l!Ĉ'Rh"ƌ˗F5jԨQF5RԗoF5jԨQF5Z <0
:|1ĉ+Z1ƍ ;z2ȑ$K<2ʕ,[| 3̙4kڼ3Ν<{ 4Сo @},h
2lP ?~'p "Lp!Æ B(q"E˗O>~O@
DPB
o>}? 4xaB 6tbD%ۗO ?)RHQ~"E)RH"EH"EǏ"E)RH"ŁQH"E
H"E)RHQ ?~)RH|QH"E)R ?{?~ /b|0_>)RH"E)Ǐ"~=' |E7P_?
G"E)RH?~(B/ |O_} _|˗?}'_|ӗ_|0_>)RH"( ? 4xa
߾}۷_>/߿}O` _>~G0 B˗ ,h
2l!Ĉ'.ǏC~70|O`| /|G0߿|G0 ņH"E)RH ?~ 'PO맏_|/߿|_'P`'p ̗ ,h
2l!Ĉ'.Ǐ~'0 ӷO`|O` _>
ņH"E)RH ?~ 7>/_|ϟ|˗o}O| '0_|Ga|(RH"E)RǏ EG"EG"E)RH?~(R `>)R/?)RH"EG"E)*̗ E)RH"EH"E"E)RH"E ď ,h '_|ӗ?/|O_~O`}&L`| 8`A&TaC!F8q!?~)
|߿|?O`>~ } EG"E)RH?~(RoO`O`>_G|QH"E)R ?+`؏_} '0|O 8`A̗ ,h
2l!Ĉ'.Ǐ"E o>'0}_| '0?}/ EG"E)RH?~(RO_|˗|/_~ӗO`>/_>}Q(0_>)RH"E)Ǐ"E)RT/?)RH"EG"E)*̗ E)RH"EH"E"E)RH"5ܷ0| 惘O?~5oa|(RH"E)RǏ ~[? 4H0 This chapter discusses means of monitoring the Oracle Messaging Gateway (MGW) agent, abnormal situations you may experience, several sources of information about Messaging Gateway errors and exceptions, and suggested remedies. This chapter contains these topics: Messaging Gateway agent status, history, and errors are recorded in Messaging Gateway log files. A different log file is created each time the Messaging Gateway agent is started. You should monitor the log file because any errors, configuration information read at startup time, or dynamic configuration information is written to the log. The format of the log file name for the default agent is: The format of the log file name for a named agent is: By default the Messaging Gateway log file is in This section contains these topics: The following sample log file shows the Messaging Gateway agent starting. The sample log file shows that a messaging link, a registered foreign queue, a propagation job, and a schedule associated with the job have been added. The log file shows that the propagation job has been activated. The last line indicates that the Messaging Gateway is up and running and ready to propagate messages. Example 21-1 Sample Messaging Gateway Log File Exception messages logged to the Messaging Gateway log file may include one or more linked exceptions, identified by The following example shows entries from a Messaging Gateway log file when an invalid value ( Example 21-2 Sample Exception Message This section contains these topics: The The Indicates that the agent is neither running nor scheduled to be run. Indicates that the agent job is waiting to be run by the job scheduler. Indicates that the agent is in the process of starting. Indicates that the agent has started and is reading configuration data. Indicates that the agent is ready to propagate any available messages or process dynamic configuration changes. Indicates that the agent is in the process of shutting down. Indicates that, while attempting to start an agent process, Messaging Gateway has detected another agent already running. This situation should never occur under normal usage. Querying the The columns See Also: A status of This section describes the causes and solutions for some error messages that may appear in the ORA-01089: Immediate shutdown in progress - no operations are permitted The Messaging Gateway agent has shut down because the ORA-06520: PL/SQL: Error loading external library The Messaging Gateway agent process was unable to start because the shared library was not loaded. This may be because the Java shared library was not in the library path. Verify that the library path in ORA-28575: Unable to open RPC connection to external procedure agent The Messaging Gateway agent was unable to start. It will attempt to start again automatically. Possible causes include: The listener is not running. If you have modified Values in In particular, ORA-28576: Lost RPC connection to external procedure agent The Messaging Gateway agent process ended prematurely. This may be because the process was stopped by an outside entity or because an internal error caused a malfunction. The agent will attempt to start again automatically. Check the Messaging Gateway log file to determine if further information is available. If the problem persists, then contact Oracle Support Services for assistance. ORA-32830: Result code -2 returned by Messaging Gateway agent An error occurred when the Messaging Gateway agent tried to read its initialization file, usually ORA-32830: Result code -3 returned by Messaging Gateway agent An error occurred creating the Messaging Gateway log file. Verify that the log directory can be written to. The default location is ORA-32830: Result code -8 returned by Messaging Gateway agent An error occurred starting the Java Virtual Machine (JVM). Verify that: You are using the correct Java version Your operating system version and patch level are sufficient for the JDK version You are using a reasonable value for the JVM heap size The heap size is specified by the On Windows platforms, verify the ORA-32830: Result code -12 returned by Messaging Gateway agent An error occurred writing to the Messaging Gateway log file. Check the free disk space or any other issues that might result in file I/O problems. ORA-32830: Result code -17 returned by Messaging Gateway agent The JVM was successfully created but an error occurred trying to call the MGW Java agent program. Verify that the CLASSPATH set in ORA-32830: Result code -19 returned by Messaging Gateway agent The Messaging Gateway agent was configured to use a particular initialization file but that file does not exist. The ORA-32830: Result code -100 returned by Messaging Gateway agent The Messaging Gateway agent JVM encountered a runtime exception or error on startup before it could write to the log file. ORA-32830: Result code -101 returned by Messaging Gateway agent An irrecoverable error caused the Messaging Gateway agent to shut down. Check the Messaging Gateway log file for further information. Verify that the values specified in ORA-32830: Result code -102 returned by Messaging Gateway agent The Messaging Gateway agent shut down because the version of file ORA-32830: Result code -103 returned by Messaging Gateway agent The Messaging Gateway agent shut down because the database instance on which it was running was shutting down. The agent should restart automatically, either on another instance if set up to do so, or when the instance that shut down is restarted. ORA-32830: Result code -104 returned by Messaging Gateway agent See previous error. ORA-32830: Result code -105 returned by Messaging Gateway agent The Messaging Gateway agent detected that it was running when it should not be. This should not happen. If it does, Terminate any Messaging Gateway agent process that may still be running. The process is usually named Run Start the Messaging Gateway agent using ORA-32830: Result code -106 returned by Messaging Gateway agent See previous error. This section discusses possible causes for Database Service Not Started Messaging Gateway uses an Oracle Scheduler job to start the Messaging Gateway agent. Oracle Scheduler allows you to specify a database service under which a job should be run (service affinity). Messaging Gateway allows an administrator to configure the Messaging Gateway agent with a database service that will be used to configure the Scheduler job class associated with that agent. When you shutdown a database Oracle stops all services to that database. You may need to manually restart the services when you start the database. If a Scheduler job is associated with a service then the job will not run until the service is started. If See Also: Too Few Job Queue Processes Messaging Gateway uses Oracle Scheduler to start the Messaging Gateway external process. When If the value of the database initialization parameter If Messaging Gateway status remains Scheduler Job Broken or Disabled The Messaging Gateway agent status will remain Check other Scheduler views, such as See Also: Oracle Real Application Clusters (Oracle RAC) Environment If Messaging Gateway is being used in a Oracle RAC environment and the agent has been configured with a database service but no database instances are running that have the service enabled, then the Messaging Gateway Messaging Gateway propagation can be monitored using the Besides showing configuration information, the The The The If a Messaging Gateway propagation job has been configured with an exception queue, then the Messaging Gateway agent will move messages to that exception queue the first time the Messaging Gateway agent encounters a propagation failure caused by a message conversion failure. A message conversion failure is indicated by If an error occurs during message propagation for a propagation job, a count is incremented in the If an error occurs, then examine the Messaging Gateway log file for further information. This section lists some of the most commonly occurring errors that are shown in the Two primary types of errors are logged to the Messaging Gateway agent log file: This error type is logged when a message conversion failure occurs. The Messaging Gateway agent probably cannot propagate the message causing the failure, and the propagation job will eventually be stopped. This error type is logged when some failure other than message conversion occurs. Depending on the cause, the problem may fix itself or require user action. [221] Failed to access <messaging_system> queue: <queue> An error occurred while trying to access either an Oracle Streams Advanced Queuing queue or a non-Oracle queue. Check the linked exception error code and message in the log file. [241] Failed to connect to database. SQL error: <error>, connect string: <connect_string> This is probably caused by incorrect MGW agent connection information specified for If the These two errors together indicate that the Messaging Gateway agent is attempting to connect to the database using a local IPC connection, but the A local connection is used when the database parameter is set to If setting If the JDBC Thin connection is used, then the database parameter must be not [415] Missing messages from source queue of job <job_name> Possible causes include: The agent partially processed persistent messages that were dequeued by someone other than the Messaging Gateway agent. The propagation source queue was purged or re-created. A message was moved to the Oracle Streams Advanced Queuing exception queue. If this error occurs, then call procedure The call takes effect only if the propagation job has encountered the missing message problem and the agent is running. The agent treats the missing messages as nonpersistent messages and continues processing the propagation job. [416] Missing log records in receiving log queue for job <job_name> Possible causes include: Log records were dequeued from the log queues by someone other than the Messaging Gateway agent. The log queues were purged or re-created. If this error occurs, then call procedure The call takes effect only if the propagation job has encountered the missing log records problem and the agent is running. Note: [417] Missing log records in sending log queue for job <job_name> See previous error. [421] WARNING: Unable to get connections to recover job <job_name> This message is a warning message indicating that the Messaging Gateway agent failed to get a connection to recover the propagation job, because other propagation jobs are using them all. The agent will keep trying to get a connection until it succeeds. If this message is repeated many times for a WebSphere MQ link, then increase the maximum number of connections used by the Messaging Gateway link associated with the propagation job. [434] Failed to access queue <queue>; provider queue <queue> This message indicates that a messaging system native queue cannot be accessed. The queue may have been registered by Possible causes include: The foreign queue was registered incorrectly, or the Messaging Gateway link was configured incorrectly. Verify configuration information. If possible, use the same configuration information to run a sample application of the non-Oracle messaging system. The non-Oracle messaging system is not accessible. Check that the non-Oracle messaging system is running and can be accessed using the information supplied in the Messaging Gateway link. The Oracle Streams Advanced Queuing queue does not exist. Perhaps the queue was removed after the Messaging Gateway propagation job was created. Check that the Oracle Streams Advanced Queuing queue still exists. [436] LOW MEMORY WARNING: total memory = < >, free_mem = < > The Messaging Gateway agent JVM is running low on memory. Java garbage collection will be invoked, but this may represent a JVM heap size that is too small. Use the [703] Failed to retrieve information for transformation <transformation_id> The Messaging Gateway agent could not obtain all the information it needs about the transformation. The transformation parameter of Possible causes include: The transformation does not exist. Verify that the transformation has been created. You can see this from the following query performed as user SYS: The wrong transformation is registered with Messaging Gateway. Verify that the transformation registered is the one intended. The Messaging Gateway agent user does not have It is not sufficient to grant Example 21-3 shows such a case for the Example 21-3 No EXECUTE Privilege on Object Type [720] AQ payload type <type> not supported; queue: <queue> The payload type of the Oracle Streams Advanced Queuing queue used by a Messaging Gateway propagation job is not directly supported by Messaging Gateway. For non-JMS propagation, Messaging Gateway directly supports the payload types Possible actions include: Configure the Messaging Gateway propagation job to use a transformation that converts the queue payload type to a supported type. Remove the Messaging Gateway propagation job and create a new job that uses an Oracle Streams Advanced Queuing queue with a supported payload type. For Java Message Service (JMS) propagation, the Messaging Gateway propagation job must be removed and a new job created whose Oracle Streams Advanced Queuing payload type is supported by Oracle Java Message Service (OJMS). Transformations are not supported for JMS propagation. [721] Transformation type <type> not supported; queue: <queue_name>, transform: <transformation> A Messaging Gateway propagation job was configured with a transformation that uses an object type that is not one of the Messaging Gateway canonical types. For an outbound job, the transformation [722] Message transformation failed; queue: <queue_name>, transform: <transformation> An error occurred while attempting execution of the transformation. ORA-25229 is typically thrown by Oracle Streams Advanced Queuing when the transformation function raises a PL/SQL exception or some other Oracle error occurs when attempting to use the transformation. Possible causes include: The Messaging Gateway agent user does not have It is not sufficient to grant Example 21-4 No EXECUTE Privilege on Transformation Function The transformation function does not exist, even though the registered transformation does. If the transformation function does not exist, it must be re-created. The Messaging Gateway agent user does not have It is not sufficient to grant The transformation function raised the error. Verify that the transformation function can handle all messages it receives. [724] Message conversion not supported; to AQ payload type: <type>, from type: <type> A Messaging Gateway propagation job is configured for inbound propagation where the canonical message type generated by the non-Oracle messaging system link is not compatible with the Oracle Streams Advanced Queuing queue payload type. For example, propagation from a TIB/Rendezvous messaging system to an Oracle Streams Advanced Queuing queue with a Possible actions include: Configure the Messaging Gateway propagation job with a transformation that maps the canonical message type generated by the non-Oracle messaging link to the Oracle Streams Advanced Queuing payload type. Remove the Messaging Gateway propagation job and create a new job whose Oracle Streams Advanced Queuing queue payload type matches the canonical message type generated by the non-Oracle link. [725] Text message not supported for RAW payload A Messaging Gateway propagation job is configured for inbound propagation to an Oracle Streams Advanced Queuing destination having a If support for text data is required, remove the Messaging Gateway propagation job and create a new job to an Oracle Streams Advanced Queuing destination whose payload type supports text data. [726] Message size <size> too large for RAW payload; maximum size is <size> A Messaging Gateway propagation job is configured for inbound propagation to an Oracle Streams Advanced Queuing destination having a If large data support is required, remove the Messaging Gateway propagation job and create a new job to an Oracle Streams Advanced Queuing destination whose payload type supports large data, usually in the form of an object type with a BLOB attribute. [728] Message contains too many large (BLOB) fields The source message contains too many fields that must be stored in [729] Message contains too many large (CLOB) fields The source message contains too many fields that contain a large text value that must be stored in a [805] MQSeries Message error while enqueuing to queue: <queue> WebSphere MQ returned an error when an attempt was made to put a message in a WebSphere MQ queue. Check the linked exception error code and message in the log file. Consult WebSphere MQ documentation. This chapter describes Oracle Messaging Gateway (MGW) prerequisites and how to load, set up, and unload Messaging Gateway. It also describes how to set up and modify the This chapter contains these topics: Messaging Gateway uses one Oracle Scheduler job for each Messaging Gateway agent. If the value of the Verify that a non-zero value is set, and that it is large enough to accommodate a Scheduler job for each Messaging Gateway agent to be started. Perform the following procedures before running Messaging Gateway: Configuring Oracle Messaging Gateway in a Oracle RAC Environment Note: Using SQL*Plus, run This procedure is for Linux 32-bit operating systems only. Static service information for the listener is not necessary on the Windows operating system. You must modify Verify that the default Inter-process Communication (IPC) protocol address for the external procedures is set. Add static service information for the listener in step 1. This involves setting a Table 18-1 SID_DESC Parameters The SID that is specified in the net service name in Set up the It should also contain any additional libraries required by third-party messaging systems. See "Setting Up Non-Oracle Messaging Systems". Your Oracle home directory. Using The name of the external procedure agent, which is Note: Example 18-1 adds This procedure is for Linux 32-bit operating systems only. For the external procedure, configure a net service name Example 18-2 Configuring MGW_AGENT Note: The Messaging Gateway default initialization file The following procedure sets environment variables and other parameters required for all applications of Messaging Gateway: Windows Operating System Only: Set the This variable is prepended to the path inherited by the Messaging Gateway agent process. Set JRE runtime classes: Oracle JDBC classes: Oracle internationalization classes: SQLJ runtime: Java Message Service (JMS) interface Oracle JMS implementation classes Java transaction API Any additional classes needed for Messaging Gateway to access non-Oracle messaging systems Note: Users of the Windows operating system must set To perform Messaging Gateway administration work, a database user must be created with To establish the Messaging Gateway agent connection back to the database, a database user with After the Messaging Gateway agent user is created, the administration user uses For this release, always specify a not Example 18-5 Configuring Messaging Gateway Connection Information This section contains these topics: Configuring Connection Information for the MGW Agent Connections Setting the Oracle RAC Instance for the Messaging Gateway Agent You must make all database connections made by the Messaging Gateway agent to the instance on which the Messaging Gateway agent process is running. This ensures correct failover behavior in a Oracle RAC environment. You can configure connections this way by having the instances use slightly different For example, in a two-instance Oracle RAC environment with instances The You would then configure Messaging Gateway agent user connection information by running the following command: Messaging Gateway provides service affinity for the Messaging Gateway agent external process by leveraging the database service support of the Oracle Scheduler. By default, a Messaging Gateway agent will use the default database service that is mapped to all instances. If you want a Messaging Gateway agent to start on a select group of database instances, you must create a database service for those instances and then assign the database service to the Messaging Gateway agent using the The database service specified by the This section contains these topics: Running as a TIB/Rendezvous Java client application, the Messaging Gateway agent requires TIB/Rendezvous software to be installed on the computer where the Messaging Gateway agent runs. In this section On the Linux operating system, On the Windows operating system, you are not required to modify You can set the following Java properties to change the default setting: The WebSphere MQ client and WebSphere MQ classes for Java and JMS must be installed on the computer where the Messaging Gateway agent runs. In this section No extra modification of When using WebSphere MQ Base Java (non-JMS) interface, set When using WebSphere MQ JMS interface, set The following procedure verifies the setup and includes a simple startup and shutdown of the Messaging Gateway agent: Start the database listeners. Start the listener for the external procedure and other listeners for the regular database connection. Test the database connect string for the Messaging Gateway agent user. Run If it is successful, then the Messaging Gateway agent is able to connect to the database. Linux Operating System Only: Test the net service entry used to call the external procedure. Run This should fail with "ORA-28547: connection to server failed, probable Oracle Net admin error". Any other error indicates that the Connect as Using the Connect as Using the Use this procedure to unload Messaging Gateway: Shut down Messaging Gateway. Remove any user-created queues whose payload is a Messaging Gateway canonical type (for example, Using SQL*Plus, run This drops the database objects used by Messaging Gateway, including roles, tables, views, packages, object types, and synonyms. Remove entries for Messaging Gateway created in Messaging Gateway reads initialization information from a text file when the Messaging Gateway agent starts. The initialization file contains lines for setting initialization parameters, environment variables, and Java properties. Each entity must be specified on one line. Leading whitespace is trimmed in all cases. A Messaging Gateway administrator can specify the initialization file to be used for a Messaging Gateway agent via The default initialization file for the default agent is The default initialization file for a named agent is The initialization parameters are typically specified by lines having a " Usage: Specifies the directory where the Messaging Gateway log/trace file is created. Format: Default: Example: Usage: Specifies the level of logging detail recorded by the Messaging Gateway agent. The logging level can be dynamically changed by changed by calling Format: Values: Example: Because the Messaging Gateway process environment is not under the direct control of the user, certain environment variables should be set using the initialization file. The environment variables currently used by the Messaging Gateway agent are Environment variables such as Usage: Used by the Java Virtual Machine to find Java classes needed by the Messaging Gateway agent for propagation between Oracle Streams Advanced Queuing and non-Oracle messaging systems. Format: Example: Usage: Appended to the front of the path inherited by the Messaging Gateway process. For the Windows operating system, this variable must be set to indicate where the library Format: Example: Usage: Can be used when a service name is not specified when configuring Messaging Gateway. Format: Example: You must specify Java system properties for the Messaging Gateway JVM when working with TIB/Rendezvous subjects. You can use the Usage: This Java property represents the maximum number of messages propagated in one transaction. It serves as a default value if the Messaging Gateway job option, Syntax: Example: Usage: This parameter specifies the time (in milliseconds) that must elapse between polls for available messages of a propagation source queue. The default polling interval used by Messaging Gateway is 5000 milliseconds (5 seconds). Syntax: Example: Usage: This parameter specifies the character encoding to be used by the TIB/Rendezvous messaging system links. Only one character set for all configured TIB/Rendezvous links is allowed due to TIB/Rendezvous restrictions. The default is ISO 8859-1 or the character set specified by the Java system property Syntax: Example: oracle.mgw.tibrv.intraProcAdvSubjects Usage Used for all TIB/Rendezvous messaging system links, this parameter specifies the names of system advisory subjects that present on the intraprocess transport. Syntax Example: oracle.mgw.tibrv.advMsgCallback Usage: Used for all TIB/Rendezvous messaging system links, this parameter specifies the name of the Java class that implements the Syntax: Example: Usage: This parameter specifies the directory of the tnsnames.ora file. It must be set if the Messaging Gateway agent is configured to use the JDBC Thin driver and the database specifier of the agent connection information is a TNSNames alias. This does not need to be set if the JDBC OCI driver is used or the database specifier is something other than a TNSNames alias. Syntax: Example: Applications at the top and bottom of the illustration are linked by arrows with three unlabeled queues in the middle. At top left Application A, Producer is linked with the leftmost queue by a downward-pointing arrow labeled Enqueue (Message 1). At bottom left, Application B, Consumer and Producer is linked to the leftmost queue with a downward-pointing arrow labeled Dequeue (Message 1) and to the middle queue with an upward-pointing arrow labeled Enqueue (Message 2). At top right, Application C, Producer and Consumer is linked to the middle queue by an upward-pointing arrow labeled Dequeue (Message 2) and to the rightmost queue with a downward-pointing arrow labeled Enqueue (Message 3). At bottom right, Application D, Consumer is linked to the rightmost queue with a downward-pointing arrow labeled Dequeue (Message 3). Three messages are linked by arrows to illustrate the conversion process. The Advanced Queuing Message consists of an AQ Property and an AQ Payload. The Messaging Gateway Message consists of an AQ Property and a Canonical Type. The Non-Oracle Message consists of the Message only. Arrows labeled Outbound Propagation point from the Advanced Queuing Message to the Messaging Gateway Message and from there to the Non-Oracle Message. Arrows labeled Inbound Propagation form the same links, but pointing in the other direction. An AQ Client is linked to an AQ Servlet in a Web Server with a double-headed arrow labeled XML Message over HTTP. A second arrow points from the Web Server to an Oracle Server containing an AQ Queue. Applications at the top and bottom of the illustration are linked by arrows with a queue labeled Multiple Consumer Queue in the middle. At the top, Application A is linked to the queue with a downward-pointing arrow labeled Enqueue. At the bottom, Application B and Application C are each linked to the queue with downward-pointing arrows labeled Dequeue. An Oracle database server appears as a hub, with messages traveling along spokes linking the hub with applications and users at the edges of the illustration. Inside the database hub are labels for Rules and Transformations and Advanced Queues. A second Oracle database is linked to the hub with a spoke labeled Internet Propagation. A third Oracle database is linked to the hub with a spoke labeled Internet Propagation (Oracle Net). This third Oracle database is also linked by a double-headed arrow to an array of databases labeled Global Agents, Global Subscriptions, Global Events. The array is linked to the hub, so the array and two Oracle databases form a triangle. Internet Users are linked to the hub by a spoke labeled XML-Based Internet Transport (HTTP(s)) and Internet Access. OCI, PL/SQL, Java Clients are linked to the hub with an unlabeled spoke, as is a representation of a third-party message system labeled MQ Series. This flow diagram shows the environment and calling sequence for the Streams Messaging example. The environment is explained in the text. A CRM Application at the left of the illustration is linked to a Web Application at the right by right-pointing arrows through an Integration Hub in the middle. Inside the Integration Hub, also linked together by right-pointing arrows, are Out Queue on the left, then Routing and Transformation, Propagation, and finally In Queue. Two messages are linked by arrows to illustrate the conversion process. The Messaging Gateway Message consists of an AQ Property and a Canonical Body. The TIB/Rendezvous Message consists of Fields and Supplementary Information. Arrows labeled Outbound Propagation point from the Messaging Gateway Message to the TIB/Rendezvous Message, linking AQ Property to Fields, Canonical Body to Fields, and Canonical Body to Supplementary Information. Arrows labeled Inbound Propagation form the same links, but pointing in the other direction. A structure with four levels. The top level, labeled cn=acme, cn=com, is the administrative context. The second level, labeled cn=OracleContext, is the root of the Oracle RDBMS schema. The third level, labeled cn=db1, is the database. The fourth level splits into three nodes. They are Connection Factories, labeled cn=OracleDBConnections, Queues/Topics, labeled cn=OracleDBQueue, and Other DB Objects, labeled cn=... Two messages are linked by arrows to illustrate the conversion process. The Advanced Queuing Message consists of an AQ Property and an AQ Payload. The Messaging Gateway Message consists of an AQ Property and a Canonical Type. An arrow labeled Outbound Propagation points from the AQ Property of the Advanced Queuing Message to the AQ Property of the Messaging Gateway Message. Another Outbound Propagation arrow points from the AQ Payload of the Advanced Queuing Message to the Canonical Type of the Messaging Gateway Message. Arrows labeled Inbound Propagation form the same links, but pointing in the other direction. Optional user-supplied Transformation Functions, to convert between message types, are represented as detours on the two arrows linking message payloads. Three applications, one at the top and two at the bottom, each with a pair of queues labeled Inbox and Outbox, are linked through Oracle Streams AQ Message Propagation Infrastructure in the middle. Each application is labeled Producer and Consumer. Arrows labeled Enqueue point from each application to its Outbox, and arrows labeled Dequeue point to each application from its Inbox. Application A, at the top of the illustration, resides in Database 1. Application B and Application C, at the bottom of the illustration, reside in Database 2. The Outbox of Application A is linked to the Inbox of Application B by an arrow that passes through the Message Propagation Infrastructure. Similar arrows link the Outbox of Application B to the Inbox of Application C and the Outbox of Application C to the Inbox of Application A. Applications at the top and bottom of the illustration are linked by arrows with an unlabeled queue in the middle. At the top, Application A is linked to the queue with a downward-pointing arrow labeled Enqueue. At the bottom are three more applications, each labeled consumer (subscriber). Application B and Application C each carry the additional label Implicit Recipient and are linked to the queue with solid downward-pointing arrows labeled Dequeue. Application D carries the additional label Explicit Recipient and is linked to the queue with a dashed downward-pointing arrow. Unlabeled applications, two at the left and two at the right of the illustration, are linked to a database labeled Oracle Advanced Queues in the middle. The two links at the left are double-headed arrows labeled Publish. The two links at the right are double-headed arrows labeled Subscribe and Publish/Subscribe respectively. An arrow points from a Job Queue Process on a Source Database to an AQ Queue in the same database. A second arrow from the Job Queue Process points to an AQ Servlet on a Web Server. A third arrow points from the AQ Servlet to an AQ Queue on a Destination Database. Applications at the top and bottom of the illustration are linked by arrows with two queues in the middle of the illustration. The application at the top is labeled Application A, Consumer and Producer and Client. It is linked to a queue labeled Request Queue by a downward-pointing arrow labeled Enqueue and to a queue labeled Response Queue by an upward-pointing arrow labeled Dequeue. The application at the bottom of the illustration is labeled Application B, Producer and Consumer and Server. It is linked to Request Queue by a downward-pointing arrow labeled Dequeue and to Response Queue by an upward-pointing arrow labeled Enqueue. Two messages are linked by arrows to illustrate the conversion process. The Messaging Gateway Message consists of an AQ Property, a Canonical Header, and a Canonical Body. The MQSeries Message consists of a Header and a Body. Arrows labeled Outbound Propagation point from the Messaging Gateway Message to the MQSeries Message, linking AQ Property to Header, Canonical Header to Header, and Canonical Body to Body. Arrows labeled Inbound Propagation form the same links, but pointing in the other direction. Applications, one at the top and three at the bottom of the illustration, are linked to an unlabeled queue in the middle. The queue contains three messages labeled priority 3, priority 1, and priority 2 respectively. At the top of the illustration, Application A, Producer is linked to the queue with a downward-pointing arrow labeled Enqueue. All three applications at the bottom carry the label Consumer (Rule-Based Subscriber). At bottom left, Application B carries the additional label "priority = 1" and is linked to the queue with a downward-pointing arrow labeled Dequeue. Application D carries the additional label "priority = 3" and is also linked to the queue with a downward-pointing arrow. Application C carries the additional label "priority > 1" and is linked to the queue with two arrows. One points downward and is labeled Dequeue. The other arrow points back to the queue and is labeled Register. Messaging Gateway architecture is represented by four elements connected with arrows. At the upper left is Messaging Gateway Administration PL/SQL Interface, with an arrow pointing to an Oracle Database at lower left. The database contains AQ Queues. The database is connected by a double-headed arrow to Messaging Gateway Agent, which contains the Propagation Engine and three drivers. Each driver is connected by a double-headed arrow labeled Messaging System Link to one of three databases at lower right. MQ Base Java Driver is connected to MQSeries, MQ JMS Driver is connected to another MQSeries, and TIB/Rendezvous Driver is connected to TIB/Rendezvous. Three messages linked by arrows illustrate message conversion. The Oracle JMS Message, Messaging Gateway Message, and Third-Party JMS Message each consist of a Header, Properties, and a Body. Arrows labeled Outbound Propagation point from the Oracle JMS Message to the Messaging Gateway Message, and from there to the Third-Party JMS Message. Arrows labeled Inbound Propagation form the same links, but pointing in the other direction. Unlabeled applications at the left and right of the illustration are linked to a database labeled Oracle Advanced Queues in the middle. The links are double-headed arrows labeled Enqueue/Dequeue. The examples in this chapter illustrate a messaging environment that can be constructed using Oracle Streams. The examples assume you are in a SQL*Plus testing environment with access to a database named This chapter contains these topics: Dequeuing Messages Explicitly and Querying for Applied Messages Enqueuing and Dequeuing Messages Using JMS See Also: This example illustrates using a single Enqueuing messages containing order payload as Enqueuing messages containing customer payload as Enqueuing messages containing row LCRs as Creating a rule set for applying the events Creating an evaluation context used by the rule set Creating an Oracle Streams apply process to dequeue and process the events based on rules Creating a message handler and associating it with the apply process Explicitly dequeuing and processing events based on rules without using the apply process Figure 23-1 provides an overview of this environment. Figure 23-1 Example Oracle Streams Messaging Environment Because the examples in this chapter use the Note: Most of the configuration and administration actions illustrated in these examples are performed by the Oracle Streams administrator In Example 23-1, you connect to database Example 23-1 Setting Up ANYDATA Users Note: The If you plan to use the Oracle Streams tool in Oracle Enterprise Manager, then grant the Oracle Streams administrator In Example 23-2, you connect to database Example 23-2 Creating an ANYDATA Queue In Example 23-3, you connect to database Queue Example 23-3 Enabling Enqueue on the ANYDATA Queue The examples in this section create two PL/SQL procedures that enqueue messages into the In Example 23-4, you connect to database Example 23-4 Creating an Orders Type In Example 23-5, you connect to database Note: Example 23-5 Creating a Customers Type In Example 23-6, you connect to database Note: Example 23-6 Creating a Procedure to Enqueue Non-LCR Messages In Example 23-7, you connect to database See Also: Example 23-7 Creating a Procedure to Construct and Enqueue Row LCR Events The examples in this section configure an apply process to apply the user-enqueued messages in the In Example 23-8, you connect to database This function determines the value of the Example 23-8 Creating a Function to Determine the Value of the Action Attribute In Example 23-9, you connect to database Example 23-9 Creating a Message Handler In Example 23-10, you connect to database Example 23-10 Creating an Evaluation Context for the Rule Set In Example 23-11, you connect to database Example 23-11 Creating a Rule Set for the Apply Process In Example 23-12, you connect to database Example 23-12 Creating a Rule that Evaluates to TRUE if Action Is Apply In Example 23-13, you connect to database For convenience, this rule uses the Oracle-supplied evaluation context Example 23-13 Creating a Rule that Evaluates to TRUE for Row LCR Events In Example 23-14, you connect to database Example 23-14 Adding Rules to the Rule Set In Example 23-15, you connect to database Example 23-15 Creating an Apply Process Because Example 23-16 Granting EXECUTE Privilege on the Rule Set To oe User In Example 23-17, you connect to database Example 23-17 Starting the Apply Process The examples in this section illustrate how to configure explicit dequeue of messages based on message contents. In Example 23-18, you connect to database Example 23-18 Creating an Agent for Explicit Dequeue The In Example 23-19, you connect to database Example 23-19 Associating User oe with Agent explicit_dq In Example 23-20, you connect to database Example 23-20 Adding a Subscriber to the oe_queue Queue In Example 23-21, you connect to database The procedure commits after the dequeue of the messages. The commit informs the queue that the dequeued messages have been consumed successfully by this subscriber. The procedure can process multiple transactions and uses two exception handlers. Exception handler Example 23-21 Creating a Procedure to Dequeue Messages Explicitly The examples in this section illustrate how to enqueue non-LCR messages and row LCR messages into a queue. Note: In Example 23-22, you connect to database Example 23-22 Enqueuing Non-LCR Messages to Be Dequeued by an Apply Process In Example 23-23, you connect to database Example 23-23 Enqueuing Non-LCR Messages to Be Dequeued Explicitly In Example 23-24, you connect to database Note: Example 23-24 Enqueuing Row LCRs to Be Dequeued by an Apply Process The examples in this section illustrate how to dequeue messages explicitly and query messages that were applied by the apply process. The examples use messages that were enqueued in the previous section. In Example 23-25, you connect to database Example 23-25 Dequeuing Messages Explicitly The example returns the payload of the messages enqueued in Example 23-23: Example 23-26, you connect to database Example 23-26 Querying for Applied Messages The example returns three rows: The examples in this section illustrate how to enqueue non-LCR messages and row LCRs into a queue and then dequeue them using Java Message Service (JMS). Note that the Oracle Database does not support JDK 1.2, JDK 1.3, JDK 1.4, and all classes12*.* files. You need to use the For JDK 1.5.x, the For JDK 1.6.x, the The following files are used for either JDK version: Also, make sure These examples show sample schema user Sample schema user Enqueue of JMS types and XML types does not work with Oracle Streams Example 23-28 Enabling JMS Types on an ANYDATA Queue Note: In Example 23-29, you connect to database Example 23-29 Creating Oracle Object Types address and person In Example 23-30, you use JPublisher to generate two Java classes named Example 23-30 Creating Java Classes That Map to Oracle Object Types Example 23-31 is the Java code that you use to publish JMS text messages, LCRs, and non-LCR ADT messages into an Oracle Streams topic. It does the following: Creates a Note: Creates a Starts the connection Creates method Creates method Publishes three messages, providing feedback as it proceeds Method Gets the topic Creates a publisher Specifies agent Creates a Sets the payload in the message Specifies Publishes the Creates a JMS Text message Publishes the JMS Text message Method Gets the topic Creates a publisher Gets the JDBC connection Specifies agent Creates an ADT message Creates the LCR representation in XML Creates the Sets the payload in the message Specifies Publishes the LCR The code is compiled in Example 23-33. For now, just save it as Example 23-31 Java Code for Enqueuing Messages Example 23-32 is the Java code you use to receive messages from a Oracle Streams topic. It does the following: Creates a Note: Creates a Starts the connection Creates method Receives three messages, providing feedback as it proceeds Method Gets the topic Creates a Registers mappings for Registers a mapping for Receives the enqueued messages The code is compiled in Example 23-33. For now, just save it as Example 23-32 Java Code for Dequeuing Messages In Example 23-33, you compile the scripts. Example 23-33 Compiling StreamsEnq.java and StreamsDeq.java In Example 23-34, you run the enqueue program, specifying values for The example returns: In Example 23-35, you run the dequeue program, specifying values for This appendix describes nonpersistent queues, which are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Oracle recommends that you use buffered messaging instead. Oracle Streams Advanced Queuing can deliver nonpersistent messages asynchronously to subscribers. These messages can be event-driven and do not persist beyond the failure of the system (or instance). The messages are stored in a system-created queue table. Oracle Streams Advanced Queuing supports persistent and nonpersistent messages with a common API. Nonpersistent queues, which can be either single-consumer or multiconsumer, provide a mechanism for notification to all currently connected users. Subscribers can be added to multiconsumer nonpersistent queues, and nonpersistent queues can be destinations for propagation. You use the enqueue interface to enqueue messages into a nonpersistent queue in the usual way. You can enqueue RAW and Oracle object type messages into a nonpersistent queue. OCI notifications are used to deliver such messages to users that are currently registered for notification. This appendix contains these topics: This procedure creates a nonpersistent queue. Only local recipients are supported for nonpersistent queues. The queue can be either single-consumer or multiconsumer. All queue names must be unique within a schema. The queues are created in an 8.1-compatible system-created queue table ( Note: Once a queue is created with You can enqueue RAW and Oracle object type messages into a nonpersistent queue. You cannot dequeue from a nonpersistent queue. The only way to retrieve a message from a nonpersistent queue is by using the Oracle Call Interface (OCI) notification mechanism. You cannot invoke the A nonpersistent queue can be dropped only by its owner. For 8.1-style or higher queues, the For nonpersistent queues, the message is delivered as part of the notification. Table A-1 shows the actions performed for nonpersistent queues for different notification mechanisms when RAW presentation is specified. Table A-2 shows the actions performed when XML presentation is specified. Table A-1 Actions Performed for Nonpersistent Queues When RAW Presentation Specified RAW OCI callback receives the RAW data in the payload. Not supported PL/SQL callback receives the RAW data in the payload. Oracle object type Not supported Not supported Not supported Table A-2 Actions Performed for Nonpersistent Queues When XML Presentation Specified RAW OCI callback receives the XML data in the payload. XML data is formatted as a SOAP message and e-mailed to the registered e-mail address. PL/SQL callback receives the XML data in the payload. Oracle object type OCI callback receives the XML data in the payload. XML data is formatted as a SOAP message and e-mailed to the registered e-mail address. PL/SQL callback receives the XML data in the payload. You can create nonpersistent queues of The This chapter discusses Oracle Streams Advanced Queuing (AQ) and the requirements for complex information handling in an integrated environment. This chapter contains the following topics: When Web-based business applications communicate with each other, producer applications enqueue messages and consumer applications dequeue messages. At the most basic level of queuing, one producer enqueues one or more messages into one queue. Each message is dequeued and processed once by one of the consumers. A message stays in the queue until a consumer dequeues it or the message expires. A producer may stipulate a delay before the message is available to be consumed, and a time after which the message expires. Likewise, a consumer may wait when trying to dequeue a message if no message is available. An agent program or application may act as both a producer and a consumer. Producers can enqueue messages in any sequence. Messages are not necessarily dequeued in the order in which they are enqueued. Messages can be enqueued without being dequeued. At a slightly higher level of complexity, many producers enqueue messages into a queue, all of which are processed by one consumer. Or many producers enqueue messages, each message being processed by a different consumer depending on type and correlation identifier. Enqueued messages are said to be propagated when they are reproduced on another queue, which can be in the same database or in a remote database. Applications often use data in different formats. A transformation defines a mapping from one data type to another. The transformation is represented by a SQL function that takes the source data type as input and returns an object of the target data type. You can arrange transformations to occur when a message is enqueued, when it is dequeued, or when it is propagated to a remote subscriber. Oracle Streams Advanced Queuing provides database-integrated message queuing functionality. It is built on top of Oracle Streams and leverages the functions of Oracle Database so that messages can be stored persistently, propagated between queues on different computers and databases, and transmitted using Oracle Net Services and HTTP(S). Because Oracle Streams Advanced Queuing is implemented in database tables, all operational benefits of high availability, scalability, and reliability are also applicable to queue data. Standard database features such as recovery, restart, and security are supported by Oracle Streams Advanced Queuing. You can use database development and management tools such as Oracle Enterprise Manager to monitor queues. Like other database tables, queue tables can be imported and exported. Messages can be queried using standard SQL. This means that you can use SQL to access the message properties, the message history, and the payload. With SQL access you can also do auditing and tracking. All available SQL technology, such as indexes, can be used to optimize access to messages. Note: Oracle Streams Advanced Queuing supports system-level access control for all queuing operations, allowing an application designer or DBA to designate users as queue administrators. A queue administrator can invoke Oracle Streams Advanced Queuing administrative and operational interfaces on any queue in the database. This simplifies administrative work because all administrative scripts for the queues in a database can be managed under one schema. Oracle Streams Advanced Queuing supports queue-level access control for enqueue and dequeue operations. This feature allows the application designer to protect queues created in one schema from applications running in other schemas. The application designer can grant only minimal access privileges to applications that run outside the queue schema. Requests for service must be decoupled from supply of services to increase efficiency and enable complex scheduling. Oracle Streams Advanced Queuing exhibits high performance as measured by: Number of messages enqueued and dequeued each second Time to evaluate a complex query on a message warehouse Time to recover and restart the messaging process after a failure Queuing systems must be scalable. Oracle Streams Advanced Queuing exhibits high performance when the number of programs using the application increases, when the number of messages increases, and when the size of the message warehouse increases. Messages that constitute requests for service must be stored persistently and processed exactly once for deferred execution to work correctly in the presence of network, computer, and application failures. Oracle Streams Advanced Queuing is able to meet requirements in the following situations: Applications do not have the resources to handle multiple unprocessed messages arriving simultaneously from external clients or from programs internal to the application. Communication links between databases are not available all the time or are reserved for other purposes. If the system falls short in its capacity to deal with these messages immediately, then the application must be able to store the messages until they can be processed. External clients or internal programs are not ready to receive messages that have been processed. Queuing systems must deal with priorities, and those priorities can change: Messages arriving later can be of higher priority than messages arriving earlier. Messages may wait for later messages before actions are taken. The same message may be accessed by different processes. Messages in a specific queue can become more important, and so must be processed with less delay or interference from messages in other queues. Messages sent to some destinations can have a higher priority than others. Persistence for Accessing and Analyzing Metadata Queuing systems must preserve message metadata, which can be as important as the payload data. For example, the time that a message is received or dispatched can be crucial for business and legal reasons. With the persistence features of Oracle Streams Advanced Queuing, you can analyze periods of greatest demand or evaluate the lag between receiving and completing an order. Oracle Streams Advanced Queuing supports enqueue, dequeue, and propagation operations where the queue type is an abstract datatype, ADT. It also supports enqueue and dequeue operations if the types are inherited types of a base ADT. Propagation between two queues where the types are inherited from a base ADT is not supported. Oracle Streams Advanced Queuing also supports If you plan to enqueue, propagate, or dequeue user-defined type messages, then each type used in these messages must exist at every database where the message can be enqueued in a queue. Some environments use directed networks to route messages through intermediate databases before they reach their destination. In such environments, the type must exist at each intermediate database, even if the messages of this type are never enqueued or dequeued at a particular intermediate database. In addition, the following requirements must be met for such types: Type name must be the same at each database. Type must be in the same schema at each database. Shape of the type must match exactly at each database. Type cannot use inheritance or type evolution at any database. Type cannot contain varrays, nested tables, LOBs, rowids, or urowids. The object identifier need not match at each database. Structured and XMLType Payloads You can use object types to structure and manage message payloads. Relational database systems in general have a richer typing system than messaging systems. Because Oracle Database is an object-relational database system, it supports traditional relational and user-defined types. Many powerful features are enabled as a result of having strongly typed content, such as content whose format is defined by an external type system. These include: Content-based routing Oracle Streams Advanced Queuing can examine the content and automatically route the message to another queue based on the content. Content-based subscription A publish and subscribe system is built on top of a messaging system so that you can create subscriptions based on content. Querying The ability to run queries on the content of the message enables message warehousing. You can create queues that use the new opaque type, Store any type of message in a queue Store Store Query XMLType columns using the operator Specify the operators in subscriber rules or dequeue conditions Integration with Oracle Internet Directory You can register system events, user events, and notifications on queues with Oracle Internet Directory. System events are database startup, database shutdown, and system error events. User events include user log on and user log off, DDL statements (create, drop, alter), and DML statement triggers. Notifications on queues include OCI notifications, PL/SQL notifications, and e-mail notifications. You can also create aliases for Oracle Streams Advanced Queuing agents in Oracle Internet Directory. These aliases can be specified while performing Oracle Streams Advanced Queuing enqueue, dequeue, and notification operations. This is useful when you do not want to expose an internal agent name. Support for Oracle Real Application Clusters(Oracle RAC) Oracle Real Application Clusters can be used to improve Oracle Streams Advanced Queuing performance by allowing different queues to be managed by different instances. You do this by specifying different instance affinities (preferences) for the queue tables that store the queues. This allows queue operations (enqueue and dequeue) on different queues to occur in parallel. If compatibility is set to Oracle8i release 8.1.5 or higher, then an application can specify the instance affinity for a queue table. When Oracle Streams Advanced Queuing is used with Oracle RAC and multiple instances, this information is used to partition the queue tables between instances for queue-monitor scheduling as well as for propagation. The queue table is monitored by the queue monitors of the instance specified by the user. If the owner of the queue table is terminated, then the secondary instance or some available instance takes over the ownership for the queue table. If an instance affinity is not specified, then the queue tables are arbitrarily partitioned among the available instances. This can result in pinging between the application accessing the queue table and the queue monitor monitoring it. Specifying the instance affinity prevents this, but does not prevent the application from accessing the queue table and its queues from other instances. Oracle Streams Advanced Queuing provides the message management and communication needed for application integration. In an integrated environment, messages travel between the Oracle Database server, applications, and users, as shown in Figure 1-1. Messages are exchanged between a client and the Oracle Database server or between two Oracle Database servers using Oracle Net Services. Oracle Net Services also propagates messages from one Oracle Database queue to another. Or, as shown in Figure 1-1, you can perform Oracle Streams Advanced Queuing operations over the Internet using HTTP(S). In this case, the client, a user or Internet application, produces structured XML messages. During propagation over the Internet, Oracle Database servers communicate using structured XML also. Application integration also involves the integration of heterogeneous messaging systems. Oracle Streams Advanced Queuing seamlessly integrates with existing non-Oracle Database messaging systems like IBM WebSphere MQ through Messaging Gateway, thus allowing existing WebSphere MQ-based applications to be integrated into an Oracle Streams Advanced Queuing environment. This section contains these topics: Figure 1-1 Integrated Application Environment Using Oracle Streams Advanced Queuing Client/Server applications usually run in a synchronous manner. Figure 1-2 demonstrates the asynchronous alternative using Oracle Streams Advanced Queuing. In this example Application B (a server) provides service to Application A (a client) using a request/response queue. Application A enqueues a request into the request queue. In a different transaction, Application B dequeues and processes the request. Application B enqueues the result in the response queue, and in yet another transaction, Application A dequeues it. The client need not wait to establish a connection with the server, and the server dequeues the message at its own pace. When the server is finished processing the message, there is no need for the client to be waiting to receive the result. A process of double-deferral frees both client and server. Figure 1-2 Client/Server Communication Using Oracle Streams Advanced Queuing A message can only be enqueued into one queue at a time. If a producer had to insert the same message into several queues in order to reach different consumers, then this would require management of a very large number of queues. To allow multiple consumers to dequeue the same message, Oracle Streams Advanced Queuing provides for queue subscribers and message recipients. To allow for subscriber and recipient lists, the queue must reside in a queue table that is created with the multiple consumer option. Each message remains in the queue until it is consumed by all its intended consumers. Multiple consumers, which can be either applications or other queues, can be associated with a queue as subscribers. This causes all messages enqueued in the queue to be made available to be consumed by each of the queue subscribers. The subscribers to the queue can be changed dynamically without any change to the messages or message producers. You cannot add subscriptions to single-consumer queues or exception queues. A consumer that is added as a subscriber to a queue is only able to dequeue messages that are enqueued after the subscriber is added. No two subscribers can have the same values for name, address, and protocol. At least one of these attributes must be different for two subscribers. It cannot be known which subscriber will dequeue which message first, second, and so on, because there is no priority among subscribers. More formally, the order of dequeuing by subscribers is indeterminate. Subscribers can also be rule-based. Similar in syntax to the In Figure 1-3, Application B and Application C each need messages produced by Application A, so a multiconsumer queue is specially configured with Application B and Application C as queue subscribers. Each receives every message placed in the queue. Figure 1-3 Communication Using a Multiconsumer Queue A message producer can submit a list of recipients at the time a message is enqueued. This allows for a unique set of recipients for each message in the queue. The recipient list associated with the message overrides the subscriber list associated with the queue, if there is one. The recipients need not be in the subscriber list. However, recipients can be selected from among the subscribers. A recipient can be specified only by its name, in which case the recipient must dequeue the message from the queue in which the message was enqueued. It can be specified by its name and an address with a protocol value of 0. The address should be the name of another queue in the same database or another installation of Oracle Database (identified by the database link), in which case the message is propagated to the specified queue and can be dequeued by a consumer with the specified name. If the recipient's name is NULL, then the message is propagated to the specified queue in the address and can be dequeued by the subscribers of the queue specified in the address. If the protocol field is nonzero, then the name and address are not interpreted by the system and the message can be dequeued by a special consumer. Subscribing to a queue is like subscribing to a magazine: each subscriber is able to dequeue all the messages placed into a specific queue, just as each magazine subscriber has access to all its articles. Being a recipient, on the other hand, is like getting a letter: each recipient is a designated target of a particular message. Figure 1-4 shows how Oracle Streams Advanced Queuing can accommodate both kinds of consumers. Application A enqueues messages. Application B and Application C are subscribers. But messages can also be explicitly directed toward recipients like Application D, which may or may not be subscribers to the queue. The list of such recipients for a given message is specified in the enqueue call for that message. It overrides the list of subscribers for that queue. Figure 1-4 Explicit and Implicit Recipients of Messages Note: Figure 1-5 illustrates the use of Oracle Streams Advanced Queuing for implementing a workflow, also known as a chained application transaction: Application A begins a workflow by enqueuing Message 1. Application B dequeues it, performs whatever activity is required, and enqueues Message 2. Application C dequeues Message 2 and generates Message 3. Application D, the final step in the workflow, dequeues it. Figure 1-5 Implementing a Workflow using Oracle Streams Advanced Queuing Note: The queues are used to buffer the flow of information between different processing stages of the business process. By specifying delay interval and expiration time for a message, a window of execution can be provided for each of the applications. From a workflow perspective, knowledge of the volume and timing of message flows is a business asset quite apart from the value of the payload data. Oracle Streams Advanced Queuing helps you gain this knowledge by supporting the optional retention of messages for analysis of historical patterns and prediction of future trends. A point-to-point message is aimed at a specific target. Senders and receivers decide on a common queue in which to exchange messages. Each message is consumed by only one receiver. Figure 1-6 shows that each application has its own message queue, known as a single-consumer queue. A publish/subscribe message can be consumed by multiple receivers, as shown in Figure 1-7. Publish/subscribe messaging has a wide dissemination mode called broadcast and a more narrowly aimed mode called multicast. Broadcasting is like a radio station not knowing exactly who the audience is for a given program. The dequeuers are subscribers to multiconsumer queues. In contrast, multicast is like a magazine publisher who knows who the subscribers are. Multicast is also referred to as point-to-multipoint, because a single publisher sends messages to multiple receivers, called recipients, who may or may not be subscribers to the queues that serve as exchange mechanisms. Publish/subscribe describes a situation in which a publisher application enqueues messages to a queue anonymously (no recipients specified). The messages are then delivered to subscriber applications based on rules specified by each application. The rules can be defined on message properties, message data content, or both. You can implement a publish/subscribe model of communication using Oracle Streams Advanced Queuing as follows: Set up one or more queues to hold messages. These queues should represent an area or subject of interest. For example, a queue can be used to represent billed orders. Set up a set of rule-based subscribers. Each subscriber can specify a rule which represents a specification for the messages that the subscriber wishes to receive. A null rule indicates that the subscriber wishes to receive all messages. Publisher applications publish messages to the queue by invoking an enqueue call. Subscriber applications can receive messages with a dequeue call. This retrieves messages that match the subscription criteria. Subscriber applications can also use a listen call to monitor multiple queues for subscriptions on different queues. This is a more scalable solution in cases where a subscriber application has subscribed to many queues and wishes to receive messages that arrive in any of the queues. Subscriber applications can also use the Oracle Call Interface (OCI) notification mechanism. This allows a push mode of message delivery. The subscriber application registers the queues (and subscriptions specified as subscribing agent) from which to receive messages. This registers a callback to be invoked when messages matching the subscriptions arrive. Figure 1-8 illustrates the use of Oracle Streams Advanced Queuing for implementing a publish/subscribe relationship between publisher Application A and subscriber Applications B, C, and D: Application B subscribes with rule "priority = 1". Application C subscribes with rule "priority > 1". Application D subscribes with rule "priority = 3". Figure 1-8 Implementing Publish/Subscribe using Oracle Streams Advanced Queuing If Application A enqueues three messages with priorities 1, 2, and 3 respectively, then the messages will be delivered as follows: Application B receives a single message (priority 1). Application C receives two messages (priority 2, 3). Application D receives a single message (priority 3). Buffered messaging, a new feature in Oracle Streams Advanced Queuing 10g Release 2 (10.2), combines the rich functionality that this product has always offered with a much faster queuing implementation. Buffered messaging is ideal for applications that do not require the reliability and transaction support of Oracle Streams Advanced Queuing persistent messaging. Buffered messaging is faster than persistent messaging, because its messages reside in shared memory. They are usually written to disk only when the total memory consumption of buffered messages approaches the available shared memory limit. Note: Message retention is not supported for buffered messaging. When using buffered messaging, Oracle recommends that you do one of the following: Set parameter This parameter controls the size of shared memory available to Oracle Streams Advanced Queuing. If unspecified, up to 10% of the shared pool size may be allocated for the Oracle Streams Advanced Queuing pool from the database cache. Turn on SGA autotuning Oracle will automatically allocate the appropriate amount of memory from the SGA for Oracle Streams Advanced Queuing, based on Oracle Streams Advanced Queuing usage as well as usage of other components that use the SGA. Examples of such other components are buffer cache and library cache. If See Also: This section contains the following topics: Buffered and persistent messages use the same single-consumer or multiconsumer queues and the same administrative and operational interfaces. They are distinguished from each other by a delivery mode parameter, set by the application when enqueuing the message to an Oracle Streams Advanced Queuing queue. Recipient lists are supported for buffered messaging enqueue. Buffered messaging is supported in all queue tables created with compatibility 8.1 or higher. Transaction grouping queues and array enqueues are not supported for buffered messages in this release. You can still use the array enqueue procedure to enqueue buffered messages, but the array size must be set to one. Buffered messages can be queried using the The queue type for buffered messaging can be All ordering schemes available for persistent messages are also available for buffered messages, but only within each message class. Ordering among persistent and buffered messages enqueued in the same session is not currently supported. Both enqueue and dequeue buffered messaging operations must be with Rule-based subscriptions are supported with buffered messaging. The procedure for adding subscribers is enhanced to allow an application to express interest in persistent messages only, buffered messages only, or both. Array dequeue is not supported for buffered messaging, but you can still use the array dequeue procedure by setting array size to one message. Dequeuing applications can choose to dequeue persistent messages only, buffered messages only, or both types. Visibility must be set to Dequeue modes Navigation modes Correlation identifier Dequeue condition Message identifier Propagation of buffered messages is supported. A single propagation schedule serves both persistent and buffered messages. The Oracle Streams AQ deletes buffered messages once they are propagated to the remote sites. If the receiving site fails before these messages are consumed, then these messages will be lost. The source site will not be able to re-send them. Duplicate delivery of messages is also possible. Oracle Streams Advanced Queuing implements a flow control system that prevents applications from flooding the shared memory with messages. If the number of outstanding messages per sender exceeds a system-defined threshold, the enqueue call will block and timeout with an error message. A message sender is identified by sender_id.name in the enqueue options. A sender blocked due to flow control on a queue does not affect other message senders. The resolution is to dequeue messages, thereby resolving flow control, after which new messages can be enqueued. Flow control threshold varies with memory pressure and could come down to the system-defined limit if streams pool usage becomes significant. Message senders will block on event Even with flow control, slow consumers of a multiconsumer queue can cause the number of messages stored in memory to grow without limit. Provided there is at least one subscriber who is keeping pace, older messages are spilled to disk and removed from the pool to free up memory. This ensures that the cost of disk access is paid by the slower consumers, and faster subscribers can proceed unhindered. Buffered Messaging with Oracle Real Application Clusters (Oracle RAC) An application can enqueue and dequeue buffered messages from any Oracle RAC instance as long as it uses password-based authentication to connect to the database. The structures required for buffered messaging are implemented on one Oracle RAC instance. The instance where the buffered messaging structures are implemented is the See Also: "ALL_QUEUE_TABLES: Queue Tables Queue Accessible to the Current User" for more information on "REMOTE_LISTENER" in Oracle Database Reference for more information on setting the A service name is associated with each queue in Oracle RAC and displayed in the Oracle recommends that you use buffered messaging with queue-to-queue propagation. This results in transparent failover when propagating messages to a destination Oracle RAC system. You do not need to re-point your database links if the primary Oracle Streams Advanced Queuing RAC instance fails. Buffered Messaging Restrictions The following Oracle Streams Advanced Queuing features are not currently supported for buffered messaging: Message retention Message delay Transaction grouping Array enqueue Array dequeue Message export and import Posting for subscriber notification Messaging Gateway Retry count and retry delay are not supported for buffered messages. Message expiration is supported. When a buffered message has been in the queue beyond its expiration period, it is moved into the exception queue as a persistent message. Asynchronous notification allows clients to receive notifications of messages of interest. The client can use these notifications to monitor multiple subscriptions. The client need not be connected to the database to receive notifications regarding its subscriptions. Asynchronous notification is supported for buffered messages. The delivery mode of the message is available in the message descriptor of the notification descriptor. Note: The client specifies a callback function which is run for each message. Asynchronous notification cannot be used to invoke an executable, but it is possible for the callback function to invoke a stored procedure. Clients can receive notifications procedurally using PL/SQL, Java Message Service (JMS), or OCI callback functions, or clients can receive notifications through e-mail or HTTP post. Clients can also specify the presentation for notifications as either For JMS queues, the dequeue is accomplished as part of the notification; explicit dequeue is not required. For RAW queues, clients can specify payload delivery; but they still must dequeue the message in Payload Delivery for RAW Queues For RAW queues, Oracle Streams Advanced Queuing clients can now specify that the message payload be delivered along with its notification. In earlier releases of Oracle Streams Advanced Queuing, message notifications were stored in shared memory and were lost if the instance failed. Clients can now specify persistent message notification. If a Oracle RAC instance fails, its notifications are delivered by another Oracle RAC node. If a standalone instance fails, its notifications are delivered when the instance restarts. Note: Oracle Streams Advanced Queuing clients can now use the OCI subscription handle attribute Note: See Also: IPv6 Compliance and Designated IP Support Oracle Streams AQ supports IPv6 and Oracle Streams AQ clients can use the OCI subscription handle attribute In earlier releases of Oracle Streams Advanced Queuing, registrations for notification persisted until explicitly removed by the client or purged in case of extended client failure. In Oracle Streams Advanced Queuing 10g Release 2 (10.2) clients can register for a specified time, after which the registration is automatically purged. When the registration is purged, Oracle Streams Advanced Queuing sends a notification to the client, so the client can invoke its callback and take any necessary action. Clients can also register to receive only the first notification, after which the registration is automatically purged. An example where purge on notification is useful is a client waiting for enqueues to start. In this case, only the first notification is useful; subsequent notifications provide no additional information. Previously, this client would be required to unregister once enqueuing started; now the registration can be configured to go away automatically. Clients can register for notification of buffered messages. The registration requests apply to both buffered and persistent messages. The message properties delivered with the PL/SQL or OCI notification specify whether the message is buffered or persistent. See Also: "Registering for Notification" for more information on PL/SQL notification Appendix C, "OCI Examples", which appears only in the HTML version of this guide, for an example of OCI notification Reliable notification is not supported. The dictionary views Event-based notifications are processed by a set of coordinator ( Notification applications may register to receive a single notification for all events that occur within a specified time interval. Notification Clients may specify a start time for the notifications. Additionally, they must specify a time as the grouping class and the time interval as the grouping value. A repeat count may be used to limit the number of notifications delivered.Clients can receive two types of grouping events, Summary or Last. A summary notification is a list of Message Identifiers of all the messages for the subscription. If last was specified as a grouping type, notification would have information about the last message in the notification interval. A count of the number of messages in the interval is also sent.The registration interfaces in PLSQL and OCI allow for specification of the The notification descriptor received by the AQ notification client provides information about the group of message identifiers and the number of notifications in the group. The following features apply to enqueuing messages: When enqueuing messages into a queue, you can operate on an array of messages simultaneously, instead of one message at a time. This can improve the performance of enqueue operations. When enqueuing an array of messages into a queue, each message shares the same enqueue options, but each message can have different message properties. You can perform array enqueue operations using PL/SQL or OCI. Array enqueuing is not supported for buffered messages in this release. You can assign an identifier to each message, thus providing a means to retrieve specific messages at a later time. Priority and Ordering of Messages in Enqueuing You can specify the priority of an enqueued message and its exact position in the queue. This means that users can specify the order in which messages are consumed in three ways: A priority can be assigned to each message. A sort order specifies which properties are used to order all messages in a queue. This is set when the queue table is created and cannot be changed. You can choose to sort messages by priority, enqueue time, or commit time. The commit-time option, a new feature in Oracle Streams Advanced Queuing 10 g Release 2 (10.2), orders messages by an approximate CSCN calculated for each transaction. Commit-time ordering is useful when transactions are interdependent or when browsing the messages in a queue must yield consistent results. See Also: "Commit-Time Queues" in Oracle Streams Concepts and Administration "Creating a Queue Table" for more information on sort order A sequence deviation positions a message in relation to other messages. Note: If several consumers act on the same queue, then each consumer gets the first message that is available for immediate consumption. A message that is in the process of being consumed by another consumer is skipped. Priority ordering of messages is achieved by specifying priority, enqueue time as the sort order. If priority ordering is chosen, then each message is assigned a priority at enqueue time by the enqueuing agent. At dequeue time, the messages are dequeued in the order of the priorities assigned. If two messages have the same priority, then the order in which they are dequeued is determined by the enqueue time. A first-in, first-out (FIFO) priority queue can also be created by specifying enqueue time, priority as the sort order of the messages. Messages belonging to one queue can be grouped to form a set that can only be consumed by one user at a time. This requires that the queue be created in a queue table that is enabled for message grouping. All messages belonging to a group must be created in the same transaction, and all messages created in one transaction belong to the same group. This feature allows users to segment complex messages into simple messages. For example, messages directed to a queue containing invoices can be constructed as a group of messages starting with a header message, followed by messages representing details, followed by a trailer message. Message grouping is also useful if the message payload contains complex large objects such as images and video that can be segmented into smaller objects. Group message properties priority, delay, and expiration are determined solely by the message properties specified for the first message in a group, irrespective of which properties are specified for subsequent messages in the group. The message grouping property is preserved across propagation. However, the destination queue where messages are propagated must also be enabled for transactional grouping. There are also some restrictions you must keep in mind if the message grouping property is to be preserved while dequeuing messages from a queue enabled for transactional grouping. Applications can mark the messages they send with a custom identification. Oracle Streams Advanced Queuing also automatically identifies the queue from which a message was dequeued. This allows applications to track the pathway of a propagated message or a string message within the same database. Time Specification and Scheduling Messages can be enqueued with an expiration that specifies the interval of time the message is available for dequeuing. The default for expiration is never. When a message expires, it is moved to an exception queue. Expiration processing requires that the queue monitor be running. The following features apply to dequeuing messages: When there are multiple processes dequeuing from a single-consumer queue or dequeuing for a single consumer on the multiconsumer queue, different processes skip the messages that are being worked on by a concurrent process. This allows multiple processes to work concurrently on different messages for the same consumer. A message can be dequeued using one of the following dequeue methods: Specifying a correlation identifier A correlation identifier is a user-defined message property. Multiple messages with the same correlation identifier can be present in a queue, which means that the ordering (enqueue order) between messages might not be preserved on dequeue calls. Specifying a message identifier A message identifier is a system-assigned value (of Specifying a dequeue condition A dequeue condition is expressed in terms of message properties or message content and is similar in syntax to the Default dequeue A default dequeue retrieves the first available message. Note: A dequeue request can browse a message, remove it, or remove it with no data. If a message is browsed, then it remains available for further processing. If a message is removed or removed with no data, then it is no longer available for dequeue requests. Depending on the queue properties, a removed message can be retained in the queue table. A message is retained in the queue table after it has been consumed only if a retention time is specified for its queue. The browse mode has three risks. First, there is no guarantee that the message can be dequeued again after it is browsed, because a dequeue call from a concurrent user might have removed the message. To prevent a viewed message from being dequeued by a concurrent user, you should view the message in the locked mode. Second, your dequeue position in browse mode is automatically changed to the beginning of the queue if a nonzero wait time is specified and the navigating position reaches the end of the queue. If you repeat a dequeue call in the browse mode with the Third, if the sort order of the queue is When a message is dequeued using When dequeuing messages from a queue, you can operate on an array of messages simultaneously, instead of one message at a time. This can improve the performance of dequeue operations. If you are dequeuing from a transactional queue, you can dequeue all the messages for a transaction with a single call, which makes application programming easier. When dequeuing an array of messages from a queue, each message shares the same dequeue options, but each message can have different message properties. You can perform array enqueue and array dequeue operations using PL/SQL or OCI. Array dequeuing is not supported for buffered messages in this release. Multiple processes or operating system threads can use the same consumer name to dequeue concurrently from a queue. In that case Oracle Streams Advanced Queuing provides the first unlocked message that is at the head of the queue and is intended for the consumer. Unless the message identifier of a specific message is specified during dequeue, consumers can dequeue messages that are in the A message is considered Expired messages from multiconsumer queues cannot be dequeued by the intended recipients of the message. However, they can be dequeued in the Note: Queues created in a queue table with Beginning with Oracle Streams Advanced Queuing release 8.1.6, only the queue monitor removes messages from multiconsumer queues. This allows dequeuers to complete the dequeue operation by not locking the message in the queue table. Because the queue monitor removes messages that have been processed by all consumers from multiconsumer queues approximately once every minute, users can see a delay between when the messages have been completely processed and when they are physically removed from the queue. Navigation of Messages in Dequeuing You have several options for selecting a message from a queue. You can select the first message with the The If the queue is enabled for transactional grouping, then the navigation options work in a slightly different way. If Transaction grouping has no effect if you dequeue by specifying a correlation identifier or message identifier, or if you dequeue some of the messages of a transaction and then commit. If you reach the end of the queue while using the Oracle Streams Advanced Queuing allows applications to block on one or more queues waiting for the arrival of either a newly enqueued message or a message that becomes ready. You can use the Note: When the blocking When there are messages for multiple agents in the agent list, Note: Applications can optionally specify a timeout of zero or more seconds to indicate the time that Oracle Streams Advanced Queuing must wait for the arrival of a message. The default is to wait forever until a message arrives in the queue. This removes the burden of continually polling for messages from the application, and it saves CPU and network resources because the application remains blocked until a new message is enqueued or becomes An application that is blocked on a dequeue is either awakened directly by the enqueuer if the new message has no If the transaction dequeuing a message from a queue fails, then it is regarded as an unsuccessful attempt to consume the message. Oracle Streams Advanced Queuing records the number of failed attempts to consume the message in the message history. Applications can query the Note: A bad condition can cause the transaction receiving a message to end. Oracle Streams Advanced Queuing allows users to hide the bad message for a specified retry delay interval, during which it is in the WAITING state. After the retry delay, the failed message is again available for dequeue. The Oracle Streams Advanced Queuing time manager enforces the retry delay property. The default value for retry delay is 0. If multiple sessions are dequeuing messages from a queue simultaneously, then Note: Queues created in a queue table with Optional Transaction Protection Enqueue and dequeue requests are usually part of a transaction that contains the requests, thereby providing the wanted transactional action. You can, however, specify that a specific request is a transaction by itself, making the result of that request immediately visible to other transactions. This means that messages can be made visible to the external world when the enqueue or dequeue statement is applied or after the transaction is committed. Note: An exception queue is a repository for expired or unserviceable messages. Applications cannot directly enqueue into exception queues. Also, a multiconsumer exception queue cannot have subscribers associated with it. However, an application that intends to handle these expired or unserviceable messages can dequeue them exactly once from the exception queue using remove mode. The consumer name specified while dequeuing should be null. Messages can also be dequeued from the exception queue by specifying the message identifier. Note: Messages intended for single-consumer queues, or for 8.0-style multiconsumer queues, can only be dequeued by their message identifiers once the messages have been moved to an exception queue. Queues created in a queue table with After a message has been moved to an exception queue, there is no way to identify which queue the message resided in before moving to the exception queue. If this information is important, then the application must save this information in the message itself. The exception queue is a message property that can be specified during enqueue time. If an exception queue is not specified, then a default exception queue is used. The default exception queue is automatically created when the queue table is created. A message is moved to an exception queue under the following conditions: It was not dequeued within the specified expiration interval. For a message intended for multiple recipients, the message is moved to the exception queue if one or more of the intended recipients was not able to dequeue the message within the specified expiration interval. The default expiration interval is never, meaning the messages does not expire. The message was dequeued successfully, but the application that dequeued it rolled back the transaction because of an error that arose while processing the message. If the message has been dequeued but rolled back more than the number of times specified by the retry limit, then the message is moved to the exception queue. For a message intended for multiple recipients, a separate retry count is kept for each recipient. The message is moved to the exception queue only when retry counts for all recipients of the message have exceeded the specified retry limit. The default retry limit is five for single-consumer queues and 8.1-style multiconsumer queues. No retry limit is supported for 8.0-style multiconsumer queues, which are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Note: The statement processed by the client contains a dequeue that succeeded but the statement itself was undone later due to an exception. If the dequeue procedure succeeds but the PL/SQL procedure raises an exception, then Oracle Streams Advanced Queuing increments the retry count of the message returned by the dequeue procedure. The client program successfully dequeued a message but terminated before committing the transaction. Messages can be propagated from one queue to another, allowing applications to communicate with each other without being connected to the same database or to the same queue. The destination queue can be located in the same database or in a remote database. Propagation enables you to fan out messages to a large number of recipients without requiring them all to dequeue messages from a single queue. You can also use propagation to combine messages from different queues into a single queue. This is known as compositing or funneling messages. Note: A message is marked as processed in the source queue immediately after the message has been propagated, even if the consumer has not dequeued the message at the remote queue. Similarly, when a propagated message expires at the remote queue, the message is moved to the exception queue of the remote queue, and not to the exception queue of the local queue. Oracle Streams Advanced Queuing does not currently propagate the exceptions to the source queue. To enable propagation, one or more subscribers are defined for the queue from which messages are to be propagated and a schedule is defined for each destination where messages are to be propagated from the queue. Oracle Streams Advanced Queuing automatically checks if the type of the remote queue is structurally equivalent to the type of the local queue within the context of the character sets in which they are created. Messages enqueued in the source queue are then propagated and automatically available for dequeuing at the destination queue or queues. When messages arrive at the destination queues, sessions based on the source queue schema name are used for enqueuing the newly arrived messages into the destination queues. This means that you must grant schemas of the source queues enqueue privileges to the destination queues. Propagation runs as an Oracle Scheduler job. A background process, the Oracle Streams Advanced Queuing offers two kinds of propagation: Queue-to-dblink propagation Queue-to-queue propagation Queue-to-dblink propagation delivers messages or events from the source queue to all subscribing queues at the destination database identified by the dblink. A single propagation schedule is used to propagate messages to all subscribing queues. Hence any changes made to this schedule will affect message delivery to all the subscribing queues. Queue-to-queue propagation delivers messages or events from the source queue to a specific destination queue identified on the dblink. This allows the user to have fine-grained control on the propagation schedule for message delivery. This new propagation mode also supports transparent failov er when propagating to a destination Oracle RAC system. With queue-to-queue propagation, you are no longer required to re-point a database link if the owner instance of the queue fails on Oracle RAC. Oracle Streams Advanced Queuing provides detailed statistics about the messages propagated and the schedule itself. This information can be used to tune propagation schedules for best performance. Consumers of a message in multiconsumer queues can be local or remote. Local consumers dequeue messages from the same queues into which the producer enqueued the messages. Local consumers have a name but no address or protocol in their agent descriptions. Remote consumers dequeue from queues that are different from the queues where the messages were enqueued. Remote consumers fall into three categories: The address refers to a queue in the same database. In this case the consumer dequeues the message from a different queue in the same database. These addresses are of the form The address refers to a queue in a different database. In this case the database must be reachable using database links and the protocol must be either The address refers to a destination that can be reached by a third party protocol. You must refer to the documentation of the third party software to determine how to specify the address and the protocol database link and schedule propagation. Propagation to Remote Subscribers Oracle Streams Advanced Queuing validates the database link specified in a propagation schedule when the schedule runs, but not when the schedule is created. It is possible, therefore, to create a queue-to-dblink or queue-to-queue propagation before creating its associated database link. Also, the propagation schedule is not disabled if you remove the database link. Oracle Streams AQ offers two kinds of propagation: A) Queue-to-dblink propagation - specified by providing a (source) queue and (destination) databaselink. Messages from the source queue for any queues at the destination specified by the dblink will be handled by this propagation. In this scenario, we cannot have multiple propagations from a source queue, with dblinks connecting to the same database. Thus(q1, dblink1) and (q1, dblink2) cannot co-exist if both dblinks connect to the same database. On the other hand (q1, dblink1) and (q2, dblink1) OR (q1, dblink1) and (q2, dblink2) can co-exist as source queues are different. B) Queue-to-queue propagation - specified by providing a (source) queue, (destination) dblink and (destination) queue. Messages from the source queue for the indicated queue at the destination dblink will be handled by this propagation. Here, either (q1, dblink1, dq1), (q1, dblink1, dq2) OR (q1, dblink1, dq1), (q1, dblink2, dq2) succeeds. This strategy works because the destination queues are different even though source queue is the same and dblink connects to the same database. In this scenario, we cannot have multiple propagations between a source queue, destination queue, even if using different dblinks: (q1, dblink1, q2) and (q1, dblink2, q2) cannot co-exist, if dblink1 and dblink2 are pointing to the same database. Priority and Ordering of Messages in Propagation The delay, expiration, and priority parameters apply identically to both local and remote consumers in both queue-to-dblink and queue-to-queue propagation. Oracle Streams Advanced Queuing accounts for any delay in propagation by adjusting the delay and expiration parameters accordingly. For example, if expiration is set to one hour, and the message is propagated after 15 minutes, then the expiration at the remote queue is set to 45 minutes. Figure 1-9 illustrates applications on different databases communicating using Oracle Streams Advanced Queuing. Each application has an inbox for handling incoming messages and an outbox for handling outgoing messages. Whenever an application enqueues a message, it goes into its outbox regardless of the message destination. Similarly, an application dequeues messages from its inbox no matter where the message originates. Figure 1-9 Message Propagation in Oracle Streams Advanced Queuing A queue-to-dblink propagation schedule is defined for a pair of source and destination database links. A queue-to-queue propagation schedule is defined for a pair of source and destination queues. If a queue has messages to be propagated to several queues, then a schedule must be defined for each of the destination queues. With queue-to-dblink propagation, all schedules for a particular remote database have the same frequency. With queue-to-queue propagation, the frequency of each schedule can be adjusted independently of the others A schedule indicates the time frame during which messages can be propagated from the source queue. This time frame can depend on a number of factors such as network traffic, load at the source database, and load at the destination database. If the duration is unspecified, then the time frame is an infinite single window. If a window must be repeated periodically, then a finite duration is specified along with a When a schedule is created, a job is automatically submitted to the job queue facility to handle propagation. The propagation schedules defined for a queue can be changed or dropped at any time during the life of the queue. You can also temporarily disable a schedule instead of dropping it. All administrative calls can be made irrespective of whether the schedule is active or not. If a schedule is active, then it takes a few seconds for the calls to be processed. Propagation of Messages with LOBs Large Objects can be propagated using Oracle Streams Advanced Queuing using two methods: Propagation from In Propagation from object queues with LOB attributes The user can populate the Note: Detailed runtime information about propagation is gathered and stored in the For each schedule, detailed propagation statistics are maintained: Total number of messages propagated in a schedule Total number of bytes propagated in a schedule Maximum number of messages propagated in a window Maximum number of bytes propagated in a window Average number of messages propagated in a window Average size of propagated messages Average time to propagated a message Propagation has built-in support for handling failures and reporting errors. For example, if the specified database link is invalid, if the remote database is unavailable, or if the remote queue is not enabled for enqueuing, then the appropriate error message is reported. Propagation uses a linear backoff scheme for retrying propagation from a schedule that encountered a failure. If a schedule continuously encounters failures, then the first retry happens after 30 seconds, the second after 60 seconds, the third after 120 seconds and so forth. If the retry time is beyond the expiration time of the current window, then the next retry is attempted at the start time of the next window. A maximum of 16 retry attempts is made, after which the schedule is automatically disabled. Note: When a schedule is disabled automatically due to failures, the relevant information is written into the alert log. A check for scheduling failures indicates: How many successive failures were encountered The error message indicating the cause for the failure The time at which the last failure was encountered By examining this information, a queue administrator can fix the failure and enable the schedule. If propagation is successful during a retry, then the number of failures is reset to 0. In some situations that indicate application errors in queue-to-dblink propagations, Oracle Streams Advanced Queuing marks messages as When a new job queue process starts, it clears the mismatched type errors so the types can be reverified. If you have capped the number of job queue processes and propagation remains busy, then you might not want to wait for the job queue process to terminate and restart. Queue types can be reverified at any time using Note: Propagation with Oracle Real Application Clusters Propagation has support built-in for Oracle Real Application Clusters. It is transparent to the user and the queue administrator. The job that handles propagation is submitted to the same instance as the owner of the queue table where the queue resides. If there is a failure at an instance and the queue table that stores the source queue is migrated to a different instance, then the propagation job is also migrated to the new instance. This minimizes pinging between instances and thus offers better performance. The destination can be identified by a database link or by destination queue name. Specifying the destination database results in queue-to-dblink propagation. If you propagate messages to several queues in another database, then all queue-to-dblink propagations to that database have the same frequency. Specifying the destination queue name results in queue-to-queue propagation, a new feature in Oracle Streams Advanced Queuing 10g Release 2 (10.2). If you propagate messages to several queues in another database, then queue-to-queue propagation enables you to adjust the frequency of each schedule independently of the others. You can even enable or disable individual propagations. This new queue-to-queue propagation mode also supports transparent failover when propagating to a destination Oracle RAC system. With queue-to-queue propagation, you are no longer required to re-point a database link if the owner instance of the queue fails on Oracle RAC. Propagation has been designed to handle any number of concurrent schedules. The number of job queue processes is limited to a maximum of 1000, and some of these can be used to handle jobs unrelated to propagation. Hence, propagation has built-in support for multitasking and load balancing. The propagation algorithms are designed such that multiple schedules can be handled by a single job queue process. The propagation load on a job queue process can be skewed based on the arrival rate of messages in the different source queues. If one process is overburdened with several active schedules while another is less loaded with many passive schedules, then propagation automatically redistributes the schedules so they are loaded uniformly. If the protocol number for a recipient is in the range 128 - 255, then the address of the recipient is not interpreted by Oracle Streams Advanced Queuing and the message is not propagated by the Oracle Streams Advanced Queuing system. Instead, a third-party propagator can dequeue the message by specifying a reserved consumer name in the dequeue operation. The reserved consumer names are of the form Another way for Oracle Streams Advanced Queuing to propagate messages to and from third-party messaging systems is through Messaging Gateway. Messaging Gateway dequeues messages from an Oracle Streams Advanced Queuing queue and guarantees delivery to supported third-party messaging systems. Messaging Gateway can also dequeue messages from these systems and enqueue them to an Oracle Streams Advanced Queuing queue. In Oracle Database 10g you can set up Oracle Streams Advanced Queuing propagation over HTTP and HTTPS (HTTP over SSL). HTTP propagation uses the Internet access infrastructure and requires that the Oracle Streams Advanced Queuing servlet that connects to the destination database be deployed. The database link must be created with the connect string indicating the Web server address and port and indicating HTTP as the protocol. The source database must be created for running Java and XML. Otherwise, the setup for HTTP propagation is more or less the same as Oracle Net Services propagation. Applications often use data in different formats. A transformation defines a mapping from one Oracle data type to another. The transformation is represented by a SQL function that takes the source data type as input and returns an object of the target data type. Only one-to-one message transformations are supported. To transform a message during enqueue, specify a mapping in the enqueue options. To transform a message during dequeue, specify a mapping either in the dequeue options or when you add a subscriber. A dequeue mapping overrides a subscriber mapping. To transform a message during propagation, specify a mapping when you add a subscriber. You can create transformations by creating a single PL/SQL function or by creating an expression for each target type attribute. The PL/SQL function returns an object of the target type or the constructor of the target type. This representation is preferable for simple transformations or those not easily broken down into independent transformations for each attribute. Creating a separate expression specified for each attribute of the target type simplifies transformation mapping creation and management for individual attributes of the destination type. It is useful when the destination type has many attributes. As Figure 1-10 shows, queuing, routing, and transformation are essential building blocks to an integrated application architecture. The figure shows how data from the Out queue of a CRM application is routed and transformed in the integration hub and then propagated to the In queue of the Web application. The transformation engine maps the message from the format of the Out queue to the format of the In queue. Figure 1-10 Transformations in Application Integration You can transform XML data using the This section contains these topics: Before 10g Release 1 (10.1), the Oracle Streams Advanced Queuing time manager process was called queue monitor ( Message delay Message expiration Retry delay Garbage collection for the queue table Memory management tasks for buffered messages Because the number of processes is determined automatically and tuned constantly, you are saved the trouble of setting it with Although it is no longer necessary to set Note: Integration with Oracle Internet Directory Oracle Internet Directory is a native LDAPv3 directory service built on Oracle Database that centralizes a wide variety of information, including e-mail addresses, telephone numbers, passwords, security certificates, and configuration data for many types of networked devices. You can look up enterprise-wide queuing information—queues, subscriptions, and events—from one location, the Oracle Internet Directory. Refer to the Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory for more information. Integration with Oracle Enterprise Manager You can use Oracle Enterprise Manager to: Create and manage queues, queue tables, propagation schedules, and transformations Monitor your Oracle Streams Advanced Queuing environment using its topology at the database and queue levels, and by viewing queue errors and queue and session statistics The systems administrator specifies the retention duration to retain messages after consumption. Oracle Streams Advanced Queuing stores information about the history of each message, preserving the queue and message properties of delay, expiration, and retention for messages destined for local or remote receivers. The information contains the enqueue and dequeue times and the identification of the transaction that executed each request. This allows users to keep a history of relevant messages. The history can be used for tracking, data warehouse, and data mining operations, as well as specific auditing functions. Message retention is not supported for buffered messaging. The Oracle Streams Advanced Queuing retention feature can be used to automatically clean up messages after the user-specified duration after consumption. If messages are accidentally inserted into a queue for the wrong subscriber, you can dequeue them with the subscriber name or by message identifier. This consumes the messages, which are cleaned up after their retention time expires. To clean up messages for a particular subscriber, you can remove the subscriber and add the subscriber again. Removing the subscriber removes all the messages for that subscriber. Retained messages can be related to each other to form sequences. These sequences represent event journals, which are often constructed by applications. Oracle Streams Advanced Queuing is designed to let applications create event journals automatically. Oracle Streams Advanced Queuing maintains the entire history of information about a message along with the message itself. This information serves as proof of sending and receiving of messages and can be used for non-repudiation of the sender and non-repudiation of the receiver. The following information is kept at enqueue for non-repudiation of the enqueuer: Oracle Streams Advanced Queuing agent doing the enqueue Database user doing the enqueue Enqueue time Transaction ID of the transaction doing enqueue The following information is kept at dequeue for non-repudiation of the dequeuer: Oracle Streams Advanced Queuing agent doing dequeue Database user doing dequeue Dequeue time Transaction ID of the transaction doing dequeue After propagation, the Stronger non-repudiation can be achieved by enqueuing the digital signature of the sender at the time of enqueue with the message and by storing the digital signature of the dequeuer at the time of dequeue. You can access Oracle Streams Advanced Queuing over the Internet by using Simple Object Access Protocol (SOAP). Internet Data Access Presentation (IDAP) is the SOAP specification for Oracle Streams Advanced Queuing operations. IDAP defines the XML message structure for the body of the SOAP request. An IDAP message encapsulates the Oracle Streams Advanced Queuing request and response in XML. IDAP is used to perform Oracle Streams Advanced Queuing operations such as enqueue, dequeue, send notifications, register for notifications, and propagation over the Internet standard transports—HTTP(s) and e-mail. In addition, IDAP encapsulates transactions, security, transformation, and the character set ID for requests. You can create an alias to an Oracle Streams Advanced Queuing agent in Oracle Internet Directory and then use the alias in IDAP documents sent over the Internet to perform Oracle Streams Advanced Queuing operations. Using aliases prevents exposing the internal name of the Oracle Streams Advanced Queuing agent. Figure 1-11 shows the architecture for performing Oracle Streams Advanced Queuing operations over HTTP. The major components are: Oracle Streams Advanced Queuing client program Web server/servlet runner hosting the Oracle Streams Advanced Queuing servlet Oracle Database server The Oracle Streams Advanced Queuing client program sends XML messages (conforming to IDAP) to the Oracle Streams Advanced Queuing servlet, which understands the XML message and performs Oracle Streams Advanced Queuing operations. Any HTTP client, a Web browser for example, can be used. The Web server/servlet runner hosting the Oracle Streams Advanced Queuing servlet, Apache/Jserv or Tomcat for example, interprets the incoming XML messages. The Oracle SiWtreams Advanced Queuing servlet connects to the Oracle Database server and performs operations on user queues. Note: Figure 1-11 Architecture for Performing Oracle Streams Advanced Queuing Operations Using HTTP You can access Oracle Streams Advanced Queuing functionality through the following interfaces: PL/SQL using Visual Basic using Oracle Objects for OLE Java Message Service (JMS) using the Internet access using HTTP(S) Note: See Also: Online Help for Oracle Objects for OLE Oracle Streams Advanced Queuing demos can be installed from the Oracle Database Companion CD. Once they are installed, you can find them in the Table 1-1 lists and briefly describes the PL/SQL and OCI demos. Table 1-2 lists and briefly describes the JMS demos. Table 1-3 lists and briefly describes the XML demos. Table 1-1 Oracle Streams Advanced Queuing Demonstrations Create users, message types, and tables Create queue tables, queues, subscribers, and propagation schedule Enqueue messages into input queue Install dequeue procedures Perform blocking dequeues Perform listen for multiple agents Clean up users, queue tables, queues, and subscribers in Enqueue and dequeue to XMLType queue using XPATH expressions Demonstrates server-to-server email notifications with default XML presentation Set up queues and subscribers for array enqueue and dequeue (for OCI array demos also) Array enqueue 10 messages Array dequeue 10 messages Clean up queues and subscribers for array enqueue and dequeue (for OCI array demos also) Enqueue messages Perform blocking dequeues Perform listen for multiple agents Array enqueue 10 messages Array dequeue 10 messages Table 1-2 Oracle Streams Advanced Queuing JMS Demonstrations Describes the Oracle Streams Advanced Queuing Java API and JMS demos Set up Oracle Streams Advanced Queuing JMS demos Enqueue text messages and dequeue based on message properties Message listener demo (enqueue messages) Message listener demo (set up listener and dequeue messages) Oracle type payload: dequeue on payload content Queue browser example Schedule propagation between queues in the database Send and receive an ADT message containing XML data JMS 1.1 domain unification demo JMS bulk array enqueue and dequeue ANYDATA messaging with JMS message types and ADT messages Clean up AQ JMS demos Set up Oracle Streams Advanced Queuing Java API demos Enqueue and dequeue RAW messages Enqueue and dequeue object type messages using ORAData interface Clean up AQ Java API demos Enqueues and dequeues a message within the database Set up kprb driver demo Defines Java program Runs Clean up AQ kprb driver demo Table 1-3 Oracle Streams Advanced Queuing XML Demonstrations Describes the Internet access demos Create users, queue tables, and queues AQXmlSend: Enqueue three messages to an ADT single- consumer queue with piggyback commit AQXmlReceive: Dequeue messages from ADT single-consumer queue with piggyback commit AQXmlPublish: Enqueue two messages to an ADT multiconsumer queue AQXmlReceive: Dequeue messages from an ADT (with LOB) multiconsumer queue AQXmlCommit: Commit previous operation AQXmlSend: Enqueue a message to a JMS TEXT single-consumer queue with piggyback commit AQXmlReceive: Dequeue messages from a JMS TEXT single-consumer queue with piggyback commit AQXmlPublish: Enqueue a JMS MAP message with recipient into multiconsumer queue AQXmlReceive: Dequeue JMS MAP messages from a multiconsumer queue AQXmlRollback: Roll back previous operation HTTP propagation Servlet to post Oracle Streams Advanced Queuing XML files (for Jserv) Servlet for Oracle Streams Advanced Queuing HTTP propagation Clean up AQ XML demo This chapter discusses topics related to managing Oracle Streams Advanced Queuing (AQ). This chapter contains these topics: The queues in which buffered messages are stored must be created with compatibility set to 8.1 or higher. The Queue-level access control Support for Oracle Real Application Clusters environments Rule-based subscribers for publish/subscribe Asynchronous notification Sender identification Separate storage of history management information Secure queues Mixed case (upper and lower case together) queue names, queue table names, and subscriber names are supported if database compatibility is 10.0, but the names must be enclosed in double quote marks. So This section contains these topics: Configuration information can be managed through procedures in the See Also: Users of the Java Message Service (JMS) API need This section contains these topics: The Perform any queue administrative operation, including create queues and queue tables on any schema in the database Perform enqueue and dequeue operations on any queues in the database Access statistics views used for monitoring the queue workload Create transformations using Run all procedures in Run all procedures in You should avoid granting Your database administrator has the option of granting the system privileges You as the application developer give rights to a queue by granting and revoking privileges at the object level by exercising As a database user, you do not need any explicit object-level or system-level privileges to enqueue or dequeue to queues in your own schema other than the Oracle Streams Advanced Queuing administrators of Oracle Database can create queues. When you create queues, the default value of the To enqueue or dequeue, users need You can grant or revoke privileges at the object level on queues. You can also grant or revoke various system-level privileges. Table 4-1 lists all common Oracle Streams Advanced Queuing operations and the privileges needed to perform these operations. Table 4-1 Operations and Required Privileges Must be granted Must be granted Must be granted Must be granted Must be granted For an Oracle Call Interface (OCI) application to access a queue, the session user must be granted either the object privilege of the queue he intends to access or the Oracle Streams Advanced Queuing propagates messages through database links. The propagation driver dequeues from the source queue as owner of the source queue; hence, no explicit access rights need be granted on the source queue. At the destination, the login user in the database link should either be granted When a queue table is exported, the queue table data and anonymous blocks of PL/SQL code are written to the export dump file. When a queue table is imported, the import utility executes these PL/SQL anonymous blocks to write the metadata to the data dictionary. Oracle AQ does not export registrations with a user export. All applications that make use of client registrations should take this into account as the client may not be present in the imported database. Note: If there exists a queue table with the same name in the same schema in the database as in the export dump, then ensure that the database queue table is empty before importing a queue table with queues. Failing to do so has a possibility of ruining the metadata for the imported queue. This section contains these topics: The export of queues entails the export of the underlying queue tables and related dictionary tables. Export of queues can also be accomplished at queue-table granularity. Exporting Queue Tables with Multiple Recipients A queue table that supports multiple recipients is associated with the following tables: Dequeue index-organized table (IOT) Time-management index-organized table Subscriber table A history IOT These tables are exported automatically during full database mode, user mode and table mode exports. See "Export Modes". Because the metadata tables contain ROWIDs of some rows in the queue table, the import process generates a note about the ROWIDs being made obsolete when importing the metadata tables. This message can be ignored, because the queuing system automatically corrects the obsolete ROWIDs as a part of the import operation. However, if another problem is encountered while doing the import (such as running out of rollback segment space), then you should correct the problem and repeat the import. Exporting operates in full database mode, user mode, and table mode. Incremental exports on queue tables are not supported. In full database mode, queue tables, all related tables, system-level grants, and primary and secondary object grants are exported automatically. In user mode, queue tables, all related tables, and primary object grants are exported automatically. However, doing a user-level export from one schema to another using the In table mode, queue tables, all related tables, and primary object grants are exported automatically. For example, when exporting a multiconsumer queue table, the following tables are automatically exported: Similar to exporting queues, importing queues entails importing the underlying queue tables and related dictionary data. After the queue table data is imported, the import utility executes the PL/SQL anonymous blocks in the dump file to write the metadata to the data dictionary. Importing Queue Tables with Multiple Recipients A queue table that supports multiple recipients is associated with the following tables: A dequeue IOT A time-management IOT A subscriber table A history IOT These tables must be imported as well as the queue table itself. You must not import queue data into a queue table that already contains data. The The Data Pump replace and skip modes are supported for queue tables. In the replace mode an existing queue table is dropped and replaced by the new queue table from the export dump file. In the skip mode, a queue table that already exists is not imported. The truncate and append modes are not supported for queue tables. The behavior in this case is the same as the replace mode. Oracle Enterprise Manager supports most of the administrative functions of Oracle Streams Advanced Queuing. Oracle Streams Advanced Queuing functions are found under the Distributed node in the navigation tree of the Enterprise Manager console. Functions available through Oracle Enterprise Manager include: Using queues as part of the schema manager to view properties Creating, starting, stopping, and dropping queues Scheduling and unscheduling propagation Adding and removing subscribers Viewing propagation schedules for all queues in the database Viewing errors for all queues in the database Viewing the message queue Granting and revoking privileges Creating, modifying, or removing transformations You must specify " The large object (LOB) memory management concepts from the Pro* documentation are not relevant for Oracle Streams Advanced Queuing raw messages because Oracle Streams Advanced Queuing provides a simple RAW buffer abstraction (although they are stored as LOBs). When using the Oracle Streams Advanced Queuing navigation option, you must reset the dequeue position by using the See Also: "Working with Transaction Monitors with Oracle XA" in Oracle Database Advanced Application Developer's Guide for more information on XA "Large Objects (LOBs)" in Pro*C/C++ Programmer's Guide This section discusses restrictions on queue management. This section contains these topics: Note: You cannot have more than 1,000 local subscribers for each queue. Also, only 32 remote subscribers are allowed for each remote destination database. Oracle Streams Advanced Queuing does not support data manipulation language (DML) operations on queue tables or associated index-organized tables (IOTs), if any. The only supported means of modifying queue tables is through the supplied APIs. Queue tables and IOTs can become inconsistent and therefore effectively ruined, if DML operations are performed on them. Oracle Streams Advanced Queuing does not support propagation from object queues that have REF attributes in the payload. You cannot construct a message payload using a VARRAY that is not itself contained within an object. You also cannot currently use a NESTED Table even as an embedded object within a message payload. However, you can create an object type that contains one or more VARRAYs, and create a queue table that is founded on this object type, as shown in Example 4-1. No Oracle Streams Advanced Queuing PL/SQL calls resolve synonyms on queues and queue tables. Although you can create synonyms, you should not apply them to the Oracle Streams Advanced Queuing interface. If you have created synonyms on object types, you cannot use them in Oracle Streams Advanced Queuing currently does not support tablespace point-in-time recovery. Creating a queue table in a tablespace disables that particular tablespace for point-in-time recovery. Oracle Streams Advanced Queuing does support regular point-in-time recovery. You can use Oracle Streams Advanced Queuing with Virtual Private Database by specifying a security policy with Oracle Streams Advanced Queuing queue tables. While dequeuing, use the dequeue condition ( Note: This section contains these topics: Caution: Propagation jobs are owned by Propagation from object queues with AQ propagation does not support non-final types. Propagation of See Also: AQ propagation jobs are run by the Oracle Scheduler. Propagation may be scheduled in the following ways: A dedicated schedule in which the propagation runs forever or for a specified duration. This mode provides the lowest propagation latencies. A periodic schedule in which the propagation runs periodically for a specified interval. This may be used when propagation can be run in a batched mode. An event based system in which propagation is started when there are messages to be propagated. This mode makes more efficient use of available resources, while still providing a fast response time. The administrator may choose a schedule that best meets the application performance requirements. Oracle Scheduler will start the required number of job queue processes for the propagation schedules. Since the scheduler optimizes for throughput, if the system is heavily loaded, it may not run some propagation jobs. The resource manager may be used to have better control over the scheduling decisions. In particular, associating propagation jobs with different resource groups can allow for fairness in scheduling which may be important in heavy load situations. A scheduling algorithm handles propagation. The algorithm optimizes available job queue processes and minimizes the time it takes for a message to show up at a destination after it has been enqueued into the source queue, thereby providing near-OLTP action. The algorithm can handle an unlimited number of schedules and various types of failures. While propagation tries to make the optimal use of the available job queue processes, the number of job queue processes to be started also depends on the existence of jobs unrelated to propagation, such as replication jobs. Hence, it is important to use the following guidelines to get the best results from the scheduling algorithm. The scheduling algorithm uses the job queue processes as follows (for this discussion, an active schedule is one that has a valid current window): If the number of active schedules is fewer than half the number of job queue processes, then the number of job queue processes acquired corresponds to the number of active schedules. If the number of active schedules is more than half the number of job queue processes, after acquiring half the number of job queue processes, then multiple active schedules are assigned to an acquired job queue process. If the system is overloaded (all schedules are busy propagating), depending on availability, then additional job queue processes are acquired up to one fewer than the total number of job queue processes. If none of the active schedules handled by a process has messages to be propagated, then that job queue process is released. The algorithm performs automatic load balancing by transferring schedules from a heavily loaded process to a lightly load process such that no process is excessively loaded. The scheduling algorithm has robust support for handling failures. Common failures that prevent message propagation include the following: Database link failed Remote database is not available Remote queue does not exist Remote queue was not started Security violation while trying to enqueue messages into remote queue Under all these circumstances the appropriate error messages are reported in the When an error occurs in a schedule, propagation of messages in that schedule is attempted again after a retry period of 30*(number of failures) seconds, with an upper bound of ten minutes. After sixteen consecutive retries, the schedule is disabled. If the problem causing the error is fixed and the schedule is enabled, then the error fields that indicate the last error date, time, and message continue to show the error information. These fields are reset only when messages are successfully propagated in that schedule.
PK%5 PK -A OEBPS/mg_start.htm
21 Monitoring Oracle Messaging Gateway
Oracle Messaging Gateway Log Files
oramgw-hostname-timestamp-processid.log
oramgw-AGENTNAME-hostname-timestamp-processid.log
ORACLE_HOME/mgw/log. This location can overridden by the parameter log_directory in the Messaging Gateway initialization file used by the agent, usually mgw.ora.
Sample Oracle Messaging Gateway Log File
>>2007-01-16 15:04:49 MGW C-Bootstrap 0 LOG process-id=11080
Bootstrap program starting
>>2007-01-16 15:04:50 MGW C-Bootstrap 0 LOG process-id=11080
JVM created -- heapsize = 64
>>2007-01-16 15:04:53 MGW Engine 0 200 main
MGW Agent version: 11.1.0.0
>>2007-01-16 15:04:53 MGW AdminMgr 0 LOG main
Connecting to database using connect string = jdbc:oracle:oci:@INST1
>>2007-01-16 15:05:00 MGW Engine 0 200 main
MGW Component version: 11.1.0.3.0
>>2007-01-16 15:05:01 MGW Engine 0 200 main
MGW agent name: DEFAULT_AGENT, MGW job instance id: 273006EC6ED255F1E040578C6D021A8C, MGW database instance: 1
>>2007-01-16 15:05:09 MGW Engine 0 1 main
Agent is initializing.
>>2007-01-16 15:05:09 MGW Engine 0 23 main
The number of worker threads is set to 1.
>>2007-01-16 15:05:09 MGW Engine 0 22 main
The default polling interval is set to 5000ms.
>>2007-01-16 15:05:09 MGW MQD 0 LOG main
Creating MQSeries messaging link:
link : MQLINK
link type : Base Java interface
queue manager : my.queue.manager
channel : channel1
host : my.machine
port : 1414
user :
ccdt url :
ssl cipherSuite :
connections : 1
inbound logQ : logq1
outbound logQ : logq2
>>2007-01-16 15:05:09 MGW Engine 0 4 main
Link MQLINK has been added.
>>2007-01-16 15:05:09 MGW Engine 0 7 main
Queue DESTQ@MQLINK has been registered; provider queue: MGWUSER.MYQUEUE.
>>2007-01-16 15:05:09 MGW Engine 0 9 main
Propagation Schedule JOB_AQ2MQ (MGWUSER.MGW_BASIC_SRC --> DESTQ@MQLINK) has been
added.
>>2007-01-16 15:05:09 MGW AQN 0 LOG main
Creating AQ messaging link:
link : oracleMgwAq
link type : native
database : INST1
user : MGWAGENT
connection type : JDBC OCI
connections : 1
inbound logQ : SYS.MGW_RECV_LOG
outbound logQ : SYS.MGW_SEND_LOG
>>2007-01-16 15:05:10 MGW Engine 0 19 main
MGW propagation job JOB_AQ2MQ has been activated.
>>2007-01-16 15:05:10 MGW Engine 0 14 main
MGW propagation job JOB_AQ2MQ (MGWUSER.MGW_BASIC_SRC --> DESTQ@MQLINK) has been added.
>>2007-01-16 15:05:11 MGW Engine 0 2 main
Agent is up and running.
Interpreting Exception Messages in an Oracle Messaging Gateway Log File
[Linked-exception] in the log file. These are often the most useful means of determining the cause of a problem. For instance, a linked exception could be a java.sql.SQLException, possibly including an Oracle error message, a PL/SQL stack trace, or both.bad_service_name) was specified for the database parameter of DBMS_MGWADM.CREATE_AGENT or DBMS_MGWADM.ALTER_AGENT. This resulted in the Messaging Gateway agent being unable to establish database connections.
>>2003-07-22 15:27:26 MGW AdminMgr 0 LOG main
Connecting to database using connect string = jdbc:oracle:oci8:@BAD_SERVICE_NAME
>>2003-07-22 15:27:29 MGW Engine 0 EXCEPTION main
oracle.mgw.admin.MgwAdminException: [241] Failed to connect to database. SQL
error: 12154, connect string: jdbc:oracle:oci8:@BAD_SERVICE_NAME
[ …Java stack trace here…]
[Linked-exception]
java.sql.SQLException: ORA-12154: TNS:could not resolve the connect identifier
specified
[ …Java stack trace here…]
>>2003-07-22 15:27:29 MGW Engine 0 25 main
Agent is shutting down.
Monitoring the Oracle Messaging Gateway Agent Status
MGW_GATEWAY View
MGW_GATEWAY view monitors the progress of the Messaging Gateway agent. Among the fields that can be used to monitor the agent are:AGENT_NAMEAGENT_INSTANCEAGENT_PINGAGENT_STATUSLAST_ERROR_MSGSERVICEAGENT_STATUS field shows the status of the agent. This column has the following possible values:AGENT_PING field pings the Messaging Gateway agent. Its value is either REACHABLE or UNREACHABLE. An agent with status of RUNNING should almost always be REACHABLE.LAST_ERROR_MSG, LAST_ERROR_DATE, and LAST_ERROR_TIME give valuable information if an error in starting or running the Messaging Gateway agent occurs. AGENT_INSTANCE indicates the Oracle Database instance on which the Messaging Gateway instance was started.
MGW_GATEWAY view
Oracle Messaging Gateway Irrecoverable Error Messages
NOT_STARTED in the AGENT_STATUS field of the MGW_GATEWAY view indicates that the Messaging Gateway agent is not running. If the AGENT_STATUS is NOT_STARTED and the LAST_ERROR_MSG field is not NULL, then the Messaging Gateway agent has encountered an irrecoverable error while starting or running. Check if a Messaging Gateway log file has been generated and whether it indicates any errors. If a log file is not present, then the Messaging Gateway agent process was probably not started.LAST_ERROR_MSG field of the MGW_GATEWAY view. Unless indicated otherwise, the Messaging Gateway agent will not attempt to restart itself when one of these errors occurs.SHUTDOWN IMMEDIATE command was used to shut down a running Oracle Database instance on which the agent was running. The agent will restart itself on the next available database instance on which it is set up to run.listener.ora has been set correctly.listener.ora, then you must stop and restart the listener before the changes will take effect.tnsnames.ora, listener.ora, or both are not correct.tnsnames.ora must have a net service name entry of MGW_AGENT. This entry is not needed for Messaging Gateway on Windows. The SID value specified for CONNECT_DATA of the MGW_AGENT net service name in tnsnames.ora must match the SID_NAME value of the SID_DESC entry in listener.ora. If the MGW_AGENT net service name is set up for an Inter-process Communication (IPC) connection, then the KEY values for ADDRESS in tnsnames.ora and listener.ora must match. If the names.default_domain parameter for sqlnet.ora has been used to set a default domain, then that domain must be appended to the MGW_AGENT net service name in tnsnames.ora.mgw.ora. Verify that the file is readable.ORACLE_HOME/mgw/log.max_memory parameter of DBMS_MGWADM.ALTER_AGENTMGW_PRE_PATH set in mgw.ora contains the path to the correct JVM library (jvm.dll).mgw.ora is correct.INITFILE field of the MGW_GATEWAY view shows the full pathname of the file specified by the administrator. Either create that initialization file, or use DBMS_MGWADM.ALTER_AGENT to set INITFILE to another file or NULL to use the default initialization file.mgw.ora are correct. Incorrect values can cause the Messaging Gateway agent to terminate due to unusual error conditions.ORACLE_HOME/mgw/jlib/mgw.jar does not match the version of the Messaging Gateway PL/SQL packages. Verify that all Messaging Gateway components are from the same release.AGENT_STATUS will be BROKEN and the agent will shut down automatically. If you encounter this error:extprocmgwextproc.DBMS_MGWADM.CLEANUP_GATEWAY(DBMS_MGWADM.CLEAN_STARTUP_STATE).DBMS_MGWADM.STARTUP.
Other Oracle Messaging Gateway Error Conditions
AGENT_STATUS remaining START_SCHEDULED in MGW_GATEWAY view for an extended period.AGENT_STATUS for a Messaging Gateway agent remains START_SCHEDULED for an extended period that might indicate that the database service is disabled or no database instances associated with the service are running. Use the MGW_GATEWAY view, Oracle Scheduler views, and service views to determine how the agent was configured and the current state of the Scheduler job and database service.
AGENT_STATUS is START_SCHEDULED, the Messaging Gateway agent Scheduler job is waiting to be run by the Scheduler. The Messaging Gateway job will not run until there is an available job process. Messaging Gateway holds its Scheduler job process for the lifetime of the Messaging Gateway agent session. If multiple Messaging Gateway agents have been started, each agent uses its own Scheduler job and require its own job process.JOB_QUEUE_PROCESSES is zero, then no Oracle Scheduler jobs will run. If the value is non-zero, it effectively becomes the maximum number of Scheduler jobs and job queue jobs than can concurrently run.START_SCHEDULED for an extended period of time, then it may indicate that the database has been started with a value for JOB_QUEUE_PROCESSES that is zero or is too low and that all job slaves are busy. Verify that the value is non-zero and that the database instance has been started with enough job queue processes so that one is available for each Messaging Gateway agent.START_SCHEDULED if the Oracle Scheduler job associated with a Messaging Gateway agent has become disabled or broken for some reason. To determine if this is the case, use the DBA_SCHEDULER_JOBS view to look at STATE field for the agent's Scheduler job. Normally the Scheduler job state will be SCHEDULED when the Messaging Gateway agent's Scheduler job is waiting to be run, or RUNNING when the Messaging Gateway agent is running. The agent's Scheduler job should not exist if the Messaging Gateway agent status is NOT_STARTED.DBA_SCHEDULER_JOB_RUN_DETAILS, for additional information about the Messaging Gateway Scheduler jobs. Also check the MGW_GATEWAY view and the Messaging Gateway log file for any error messages that may indicate a problem.
AGENT_STATUS will remain START_SCHEDULED until the service is started on a running database instance.
Monitoring Oracle Messaging Gateway Propagation
MGW_JOBS view and the Messaging Gateway log file. The view provides information on propagated messages and errors that may have occurred during propagation attempts. The log file can be used to determine the cause of the errors.MGW_JOBS view also has dynamic information that can be used to monitor message propagation. Applicable fields include STATUS, ENABLED, PROPAGATED_MSGS, EXCEPTIONQ_MSGS, FAILURES, LAST_ERROR_MSG, LAST_ERROR_DATE, and LAST_ERROR_TIME.STATUS field indicates current status of the job. READY means that the job is ready for propagation (but only if the ENABLED field is TRUE). RETRY means that a propagation failure occurred but that propagation will be retried. FAILED means that the agent has stopped propagation for the job due to an unrecoverable error or the maximum number of consecutive propagation failures has been reached. DELETE_PENDING means job removal is pending due to DBMS_MGWADM.REMOVE_JOB being called but certain cleanup tasks pertaining to the job are still outstanding. SUBSCRIBER_DELETE_PENDING means that DBMS_MGWADM.REMOVE_SUBSCRIBER has been called on an old style propagation job but certain cleanup tasks pertaining to the job are still outstanding.ENABLED field indicates whether the propagation job is currently enabled. TRUE indicates the job is enabled while FALSE indicates the job is disabled. No propagation will occur unless the job is enabled.PROPAGATED_MSGS field of the MGW_JOBS view indicates how many messages have been successfully propagated. This field is reset to zero when the Messaging Gateway agent is started.oracle.mgw.common.MessageException in the Messaging Gateway log file. The EXCEPTIONQ_MSGS field indicates how many messages have been moved to the exception queue. This field is reset to zero when the Messaging Gateway agent is started.FAILURES field. This field indicates the number of failures encountered since the last successful propagation of messages. Each time a failure occurs, an error message and the time it occurred will be shown by LAST_ERROR_MSG, LAST_ERROR_DATE, and LAST_ERROR_TIME. When the number of failures reaches sixteen, Messaging Gateway halts propagation attempts for this propagation job. To resume propagation attempts you must call DBMS_MGWADM.RESET_JOB for the propagation job.
Oracle Messaging Gateway Agent Error Messages
LAST_ERROR_MSG column of the MGW_JOBS view and logged to the Messaging Gateway agent log file. Also shown are some errors that require special action. When you notice that a failure has occurred, look at the linked exceptions in the log file to determine the root cause of the problem.oracle.mgw.common.MessageExceptionoracle.mgw.common.GatewayExceptionDBMS_MGWADM.CREATE_AGENT or DBMS_MGWADM.ALTER_AGENT. Either the Messaging Gateway agent user or password is incorrect or the database specifier (database parameter) is iJ"ncorrect. Verify that the connection information is correct for the connection type used by the agent, JDBC OCI or JDBC Thin.database parameter is NULL, then check the Messaging Gateway log file for the following Oracle linked errors:
ORA-01034: ORACLE not available
ORA-27101: shared memory realm does not exist
ORACLE_SID value is not correct.NULL. If a local connection is desired, the correct ORACLE_SID value must be set in the Messaging Gateway agent process. This can be done by adding the following line to the MGW initialization file, usually mgw.ora:
set ORACLE_SID = sid_value
ORACLE_SID need not be set in the MGW initialization file if the database parameter is not NULL.ORACLE_SID in the MGW initialization file does not work, then the database parameter must be set to a value that is not NULL.NULL. If the JDBC Thin connection is used and the database parameter is a TNSNames alias, make sure that the oracle.net.tns_names Java property is set in the MGW initialization file. The property can be set by adding the following line to the MGW initialization file:
setJavaProp oracle.net.tns_admin=<directory containing tnsnames.ora>
CLEANUP_GATEWAY in the DBMS_MGWADM package:
DBMS_MGWADM.CLEANUP_GATEWAY (
action => DBMS_MGWADM.RESET_SUB_MISSING_MESSAGE,
sarg => <job_name>);
CLEANUP_GATEWAY in the DBMS_MGWADM package:
DBMS_MGWADM.CLEANUP_GATEWAY (
action => DBMS_MGWADM.RESET_SUB_MISSING_LOG_REC,
sarg => <job_name>);
DBMS_MGWADM.CLEANUP_GATEWAY may result in duplicated messages if the missing messages have already been propagated to the destination queue. Users should check the source and destination queues for any messages that exist in both places. If such messages exist, then they should be removed from either the source or destination queue before calling this procedure.
DBMS_MGWADM.REGISTER_FOREIGN_QUEUE, or it may be an Oracle Streams Advanced Queuing queue. The linked exceptions should give more information.max_memory parameter of DBMS_MGWADM.ALTER_AGENT to increase the JVM heap size. If the Messaging Gateway agent is running, then it must be restarted for this change to take effect.DBMS_MGWADM.CREATE_JOB must specify the name of the registered transformation and not the name of the transformation function.
SELECT TRANSFORMATION_ID, OWNER FROM DBA_TRANSFORMATIONS;
EXECUTE privilege on the object type used for the from_type or the to_type of the transformation indicated in the exception.EXECUTE to MGW_AGENT_ROLE and then grant MGW_AGENT_ROLE to the agent user. You must grant EXECUTE privilege on the object type directly to the agent user or to PUBLIC.from_type. It also shows the use of linked exceptions for determining the precise cause of the error.
Errors occurred during processing of job JOB_AQ2MQ_2
oracle.mgw.common.GatewayException: [703] Failed to retrieve information for
transformation mgwuser.SAMPLEADT_TO_MGW_BASIC_MSG
[…Java stack trace here…]
[Linked-exception]
java.sql.SQLException: "from_type" is null
[…Java stack trace here…]
RAW, SYS.MGW_BASIC_MSG_T and SYS.MGW_TIBRV_MSG_T.from_type must be the Oracle Streams Advanced Queuing payload type, and the to_type must be a Messaging Gateway canonical type. For an inbound job, the transformation from_type must be a Messaging Gateway canonical type and the to_type must be the Oracle Streams Advanced Queuing payload type.EXECUTE privilege on the transformation function. This is illustrated in Example 21-4.EXECUTE to MGW_AGENT_ROLE and then grant MGW_AGENT_ROLE to the Messaging Gateway agent user. You must grant EXECUTE privilege on the transformation function directly to the Messaging Gateway agent user or to PUBLIC.
Errors occurred during processing of job JOB_MQ2AQ_2
oracle.mgw.common.GatewayException: [722] Message transformation failed queue:
MGWUSER.DESTQ_SIMPLEADT, transform: MGWUSER.MGW_BASIC_MSG_TO_SIMPLEADT
[…Java stack trace here…]
[Linked-exception]
oracle.mgw.common.MessageException: [722] Message transformation failed;
queue: MGWUSER.DESTQ_SIMPLEADT, transform:
MGWUSER.MGW_BASIC_MSG_TO_SIMPLEADT
[…Java stack trace here…]
[Linked-exception]
java.sql.SQLException: ORA-25229: error on transformation of message msgid:
9749DB80C85B0BD4E03408002086745E
ORA-00604: error occurred at recursive SQL level 1
ORA-00904: invalid column name
[…Java stack trace here…]
EXECUTE privilege on the payload object type for the queue indicated in the exception.EXECUTE to MGW_AGENT_ROLE and then grant MGW_AGENT_ROLE to the Messaging Gateway agent user. You must grant EXECUTE privilege on the object type directly to the Messaging Gateway agent user or to PUBLIC.SYS.MGW_BASIC_MSG_T payload type, or propagation from WebSphere MQ to an Oracle Streams Advanced Queuing queue with a SYS.MGW_TIBRV_MSG_T payload type.RAW payload type. A text message was received from the source (non-Oracle) queue resulting in a message conversion failure.RAW payload type. A message conversion failure occurred when a message containing a large RAW value was received from the source (non-Oracle) queue.BLOB types. SYS.MGW_TIBRV_MSG_T is limited to three BLOB fields. Reduce the number of large fields in the message, perhaps by breaking them into smaller fields or combining them into fewer large fields.CLOB. SYS.MGW_TIBRV_MSG_T is limited to three CLOB fields. Reduce the number of large fields in the message, perhaps by breaking them into smaller fields or combining them into fewer large fields.
PKfR PK -A OEBPS/img_text/adque040.htm(
18 Getting Started with Oracle Messaging Gateway
mgw.ora initialization file.
Oracle Messaging Gateway Prerequisites
JOB_QUEUE_PROCESSES database initialization parameter is zero, then no Oracle Scheduler jobs will run. If the value is non-zero, it effectively becomes the maximum number of Scheduler jobs and job queue jobs than can run concurrently.
Loading and Setting Up Oracle Messaging Gateway
Loading Database Objects into the Database
ORACLE_HOME/mgw/admin/catmgw.sql as user SYS as SYSDBA. This script loads the database objects necessary for Messaging Gateway, including roles, tables, views, object types, and PL/SQL packages. It creates public synonyms for Messaging Gateway PL/SQL packages. It creates two roles, MGW_ADMINISTRATOR_ROLE and MGW_AGENT_ROLE, with certain privileges granted. All objects are owned by SYS.
Modifying listener.ora for the External Procedure
listener.ora so that the Messaging Gateway PL/SQL packages can call the external procedure.
LISTENER = (ADDRESS_LIST=
(ADDRESS=(PROTOCOL=IPC)(KEY=EXTPROC))
SID_DESC for the listener. Within the SID_DESC, the parameters described in Table 18-1 are important to Messaging Gateway and must be specified according to your own situation.
Parameter Description
SID_NAME
tnsnames.ora. In the following example, the SID_NAME is mgwextproc.
ENVS
LD_LIBRARY_PATH environment needed for the external procedure to run. The LD_LIBRARY_PATH must contain the following paths:
JRE_HOME/lib/PLATFORM_TYPE
JRE_HOME/lib/PLATFORM_TYPE/server
ORACLE_HOME/lib
ORACLE_HOME
$ORACLE_HOME does not work.
PROGRAM
extproc
JRE_HOME represents the root directory of a JRE installation, just as ORACLE_HOME represents the root directory of an Oracle installation. Oracle recommends that you use the JRE installed with Oracle Database.SID_NAME mgwextproc to a listener.ora file for Linux x86.
Modifying tnsnames.ora for the External Procedure
MGW_AGENT in tnsnames.ora whose connect descriptor matches the information configured in listener.ora, as shown in Example 18-2. The net service name must be MGW_AGENT (this value is fixed). The KEY value must match the KEY value specified for the IPC protocol in listener.ora. The SID value must match the value specified for SID_NAME of the SID_DESC entry in listener.ora.
MGW_AGENT =
(DESCRIPTION=
(ADDRESS_LIST= (ADDRESS= (PROTOCOL=IPC)(KEY=EXTPROC)))
(CONNECT_DATA= (SID=mgwextproc)))
names.default_domain parameter for sqlnet.ora has been used to set a default domain, then that domain must be appended to the MGW_AGENT net service name in tnsnames.ora. For example, if sqlnet.ora contains the entry names.default_domain=acme.com, then the net service name in tnsnames.ora must be MGW_AGENT.acme.com.
Setting Up a mgw.ora Initialization File
ORACLE_HOME/mgw/admin/mgw.ora is a text file. The Messaging Gateway external procedure uses it to get initialization parameters to start the Messaging Gateway agent. Copy ORACLE_HOME/mgw/admin/sample_mgw.ora to mgw.ora and modify it according to your situation.MGW_PRE_PATH variable. Its value is the path to the jvm.dll library:
set MGW_PRE_PATH = JRE_HOME\bin\client
CLASSPATH to include at least the following:
JRE_HOME/lib/rt.jar
ORACLE_HOME/jdbc/lib/ojdbc5.jar
ORACLE_HOME/jlib/orai18n.jar
ORACLE_HOME/sqlj/lib/runtime12.jar
ORACLE_HOME/rdbms/jlib/jmscommon.jar
ORACLE_HOME/rdbms/jlib/aqapi.jar
ORACLE_HOME/jlib/jta.jar
ORACLE_HOME with the appropriate, spelled-out value. Using $ORACLE_HOME, for example, does not work.
CLASSPATH using the Windows operating system path syntax.
Creating an Oracle Messaging Gateway Administration User
MGW_ADMINISTRATOR_ROLE privileges, as shown in Example 18-3.
Creating an Oracle Messaging Gateway Agent User
MGW_AGENT_ROLE privileges must be created, as shown in Example 18-4.
Configuring Oracle Messaging Gateway Connection Information
DBMS_MGWADM.ALTER_AGENT to configure Messaging Gateway with the username, password, and database connect string used by the Messaging Gateway agent to connect back to the database, as shown in Example 18-5. Use the Messaging Gateway username and password that you created in "Creating an Oracle Messaging Gateway Agent User". The database connect string parameter can be set to either a net service name in tnsnames.ora (with IPC protocol for better performance) or NULL. If NULL, then the oracle_sid parameter must be set in mgw.ora.NULL value for the database connect string parameter when calling DBMS_MGWADM.ALTER_AGENT.
set echo off
set verify off
connect admin_user
ACCEPT password CHAR PROMPT 'Enter the password for AGENT_USER: ' HIDE
EXEC DBMS_MGWADM.ALTER_AGENT(
agent_name => 'default_agent',
username => 'agent_user',
password => '&password',
database => 'agent_database');
Configuring Oracle Messaging Gateway in a Oracle RAC Environment
Configuring Connection Information for the MGW Agent Connections
tnsnames.ora files. Each file contains an entry with the same net service name, but the connect data refers to only the instance associated with that tnsnames.ora file. The common net service name would then be used for the database parameter when DBMS_MGWADM.ALTER_AGENT is used to configure the Messaging Gateway agent database connection information.OraDB1 and OraDB2, where the net service name AGENT_DB is to be used, the tnsnames.ora for instance OraDB1 would look like this:
AGENT_DB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = myhost1.mycorp.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = OraDB10.mycorp.com)
(INSTANCE_NAME = OraDB1)
)
)
tnsnames.ora for OraDB2 would look like this:
AGENT_DB =
(DESCRIPTION =
(ADDRESS = (PROTOCOL = TCP)(HOST = myhost2.mycorp.com)(PORT = 1521))
(CONNECT_DATA =
(SERVER = DEDICATED)
(SERVICE_NAME = OraDB10.mycorp.com)
(INSTANCE_NAME = OraDB2)
)
)
EXEC DBMS_MGWADM.ALTER_AGENT(
agent_name => 'default_agent',
username => 'agent_user',
password => 'agent_password',
database => 'agent_db');
Setting the Oracle RAC Instance for the Messaging Gateway Agent
SERVICE parameter of the DBMS_MGWADM.CREATE_AGENT or DBMS_MGWADM.ALTER_AGENT procedures. The DBMS_MGWADM.STARTUP procedure submits an Oracle Scheduler job that starts the Messaging Gateway agent external process when the Scheduler job is executed. The Scheduler job will use the database service configured for the Messaging Gateway agent.SERVICE parameter is only used for the service affinity of the Oracle Scheduler job and thus the service affinity for the Messaging Gateway external process. It is not used for the database connections made by the Messaging Gateway agent user. Those JDBC client connections are based on the values specified for the DATABASE and CONNTYPE parameters.
Setting Up Non-Oracle Messaging Systems
Setting Up for TIB/Rendezvous
TIBRV_HOME refers to the installed TIB/Rendezvous software location.LD_LIBRARY_PATH in the entry for Messaging Gateway must include TIBRV_HOME/lib for the agent to access TIB/Rendezvous shared library files.listener.ora. But the system environment variable PATH must include TIBRV_HOME\bin.MGW_PRE_PATH must include the directory that contains the TIB/Rendezvous license ticket file (tibrv.tkt), which usually is located in TIBRV_HOME/bin.CLASSPATH must include the TIB/Rendezvous jar file TIBRV_HOME/lib/tibrvj.jar. If you use your own customized TIB/Rendezvous advisory message callback, then the location of the callback class must also be included.oracle.mgw.tibrv.encodingoracle.mgw.tibrv.intraProcAdvSubjectsoracle.mgw.tibrv.advMsgCallback
Setting Up for WebSphere MQ Base Java or JMS
MQ_HOME refers to the location of the installed client. On the Linux operating system, this location is always /opt/mqm. On the Windows operating system, the installed location can vary.listener.ora is necessary for Messaging Gateway to access WebSphere MQ.CLASSPATH to include at least the following (in addition to those in "Setting Up a mgw.ora Initialization File"):MQ_HOME/java/lib/com.ibm.mq.jarMQ_HOME/java/lib/connector.jarCLASSPATH to include at least the following (in addition to those in "Setting Up a mgw.ora Initialization File"):MQ_HOME/java/lib/com.ibm.mqjms.jarMQ_HOME/java/lib/com.ibm.mq.jarMQ_HOME/java/lib/connector.jar
Verifying the Oracle Messaging Gateway Setup
sqlplus agent_user/agent_password@agent_database.sqlplus agent_user/agent_password@MGW_AGENT.tnsnames.ora, listener.ora, or both are not correct.admin_user and call DBMS_MGWADM.STARTUP to start the Messaging Gateway agent.MGW_GATEWAY view, wait for AGENT_STATUS to change to RUNNING and AGENT_PING to change to REACHABLE.admin_user and call DBMS_MGWADM.SHUTDOWN to shut down the Messaging Gateway agent.MGW_GATEWAY view, wait for AGENT_STATUS to change to NOT_STARTED.
Unloading Oracle Messaging Gateway
SYS.MGW_BASIC_MSG_T).ORACLE_HOME/mgw/admin/catnomgw.sql as user SYS as SYSDBA.listener.ora and tnsnames.ora.
Understanding the mgw.ora Initialization File
DBMS_MGWADM.CREATE_AGENT and DBMS_MGWADM.ALTER_AGENT. If an initialization file is not specified then a default initialization file will be used.ORACLE_HOME/mgw/admin/mgw.ora.ORACLE_HOME/mgw/admin/mgw_AGENTNAME.ora where AGENTNAME is the name in uppercase of the Messaging Gateway agent. For example, if the agent name is my_agent then the name of the agent's default initialization file is ORACLE_HOME/mgw/admin/mgw_MY_AGENT.ora. If the default initialization file for a named agent is not found then ORACLE_HOME/mgw/admin/mgw.ora will be used.
mgw.ora Initialization Parameters
name=value<NL>" format where name represents the parameter name, value represents its value and <NL> represents a new line.
log_directory = value
ORACLE_HOME/mgw/log
log_directory = /private/mgwlog
DBMS_MGWADM.SET_LOG_LEVEL while the Messaging Gateway agent is running. Oracle recommends that log level 0 (the default value) be used at all times.
log_level = value
0 for basic logging; equivalent to DBMS_MGWADM.BASIC_LOGGING1 for light tracing; equivalent to DBMS_MGWADM.TRACE_LITE_LOGGING2 for high tracing; equivalent to DBMS_MGWADM.TRACE_HIGH_LOGGING3 for debug tracing; equivalent to DBMS_MGWADM.TRACE_DEBUG_LOGGING
log_level = 0
mgw.ora Environment Variables
CLASSPATH, MGW_PRE_PATH, and ORACLE_SID.CLASSPATH and MGW_PRE_PATH are set so the Messaging Gateway agent can find the required shared objects, Java classes, and so on. Environment variables are specified by lines having a "set env_var=value<NL>" or "setenv env_var=value<NL>" format where env_var represents the name of the environment variable to set, value represents the value of the environment variable, and <NL> represents a new line.
set CLASSPATH=value
set CLASSPATH=ORACLE_HOME/jdbc/lib/ojdbc5.jar:JRE_HOME/lib/rt.jar:
ORACLE_HOME/sqlj/lib/runtime12.jar:ORACLE_HOME/jlib/orai18n.jar:ORACLE_HOME/rdbms/
jlib/jmscommon.jar:ORACLE_HOME/rdbms/jlib/aqapi.jar:ORACLE_HOME/jlib/jta.jar:
/opt/mqm/java/lib/com.ibm.mq.jar:/opt/mqm/java/lib/com.ibm.mqjms.jar:/opt/mqm/java
/lib/connector.jar
jvm.dll is found.
set MGW_PRE_PATH=value
set MGW_PRE_PATH=JRE_HOME\bin\client
set ORACLE_SID=value
set ORACLE_SID=my_sid
mgw.ora Java Properties
setJavaProp parameter of the Messaging Gateway initialization file for this. Java properties are specified by lines having a "setJavaProp prop_name=value<NL>" format, where prop_name represents the name of the Java property to set, value represents the value of the Java property, and <NL> represents a new line character.MsgBatchSize, is not specified. If altered from the default, then consideration should be given to the expected message size and the Messaging Gateway agent memory (see max_memory parameter of DBMS_MGWADM.ALTER_AGENT). The minimum value of this Java property is 1, the maximum is 100, and the default is 30.
setJavaProp oracle.mgw.batch_size=value
setJavaProp oracle.mgw.batch_size=10
setJavaProp oracle.mgw.polling_interval=value
setJavaProp oracle.mgw.polling_interval=1000
file.encoding.
setJavaProp oracle.mgw.tibrv.encoding=value
setJavaProp oracle.mgw.tibrv.encoding=ISO8859_1
setJavaProp oracle.mgw.tibrv.intraProcAdvSubjects=
advisorySubjectName[:advisorySubjectName]
setJavaProp oracle.mgw.tibrv.intraProcAdvSubjects=_RV.>
TibrvMsgCallback interface to handle system advisory messages. If it is not specified, then the default system advisory message handler provided by Messaging Gateway is used, which writes system advisory messages into Messaging Gateway log files. If it is specified, then the directory where the class file is stored must be included in the CLASSPATH in mgw.ora.
setJavaProp oracle.mgw.tibrv.advMsgCallback=className
setJavaProp oracle.mgw.tibrv.advMsgCallback=MyAdvCallback
setJavaProp oracle.net.tns_admin=value
setJavaProp oracle.net.tns_admin=/myoraclehome/network/admin
PK]5d& U& PK -A OEBPS/ap_nonpers.htm1
23 Oracle Streams Messaging Examples
db01.
ANYDATA queues
Overview of Messaging Example
ANYDATA queue to create an Oracle Streams messaging environment in which message payloads of different types are stored in the same queue. Specifically, this example illustrates the following messaging features of Oracle Streams:ANYDATA payloadsANYDATA payloadsANYDATA payloads
Description of "Figure 23-1 Example Oracle Streams Messaging Environment"
Setting Up Users and Creating an ANYDATA Queue
oe sample schema, the oe user must have privileges to run the subprograms in the DBMS_AQ package. This is accomplished in Example 23-1.
oe user is specified as the queue user when the ANYDATA queue is created in Example 23-2. The SET_UP_QUEUE procedure grants the oe user enqueue and dequeue privileges on the queue, but the oe user also needs EXECUTE privilege on the DBMS_AQ package to enqueue and dequeue messages.strmadmin. Example 23-1 also creates this user and grants the necessary privileges. These privileges enable the user to run subprograms in packages related to Oracle Streams, create rule sets, create rules, and monitor the Oracle Streams environment by querying data dictionary views.db01 as a user with administrative privileges.
GRANT EXECUTE ON DBMS_AQ TO oe;
CREATE USER strmadmin IDENTIFIED BY strmadmin DEFAULT TABLESPACE example;
GRANT DBA, SELECT_CATALOG_ROLE TO strmadmin;
GRANT EXECUTE ON DBMS_APPLY_ADM TO strmadmin;
GRANT EXECUTE ON DBMS_AQ TO strmadmin;
GRANT EXECUTE ON DBMS_AQADM TO strmadmin;
GRANT EXECUTE ON DBMS_STREAMS_ADM TO strmadmin;
BEGIN
DBMS_RULE_ADM.GRANT_SYSTEM_PRIVILEGE(
privilege => DBMS_RULE_ADM.CREATE_RULE_SET_OBJ,
grantee => 'strmadmin',
grant_option => FALSE);
DBMS_RULE_ADM.GRANT_SYSTEM_PRIVILEGE(
privilege => DBMS_RULE_ADM.CREATE_RULE_OBJ,
grantee => 'strmadmin',
grant_option => FALSE);
DBMS_RULE_ADM.GRANT_SYSTEM_PRIVILEGE(
privilege => DBMS_RULE_ADM.CREATE_EVALUATION_CONTEXT_OBJ,
grantee => 'strmadmin',
grant_option => FALSE);
END;
/
SELECT_CATALOG_ROLE is not required for the Oracle Streams administrator. It is granted in this example so that the Oracle Streams administrator can monitor the environment easily.SELECT ANY DICTIONARY privilege, in addition to the privileges shown in this step.db01 as administrator user strmadmin to create ANYDATA queue oe_queue. The SET_UP_QUEUE procedure creates a queue table for the queue and then creates and starts the queue.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDE
CONNECT strmadmin/&password@db01;
set echo on
BEGIN
DBMS_STREAMS_ADM.SET_UP_QUEUE(
queue_table => 'oe_queue_table',
queue_name => 'oe_queue');
END;
/
db01 as administrator user strmadmin to grant the oe user privileges on queue oe_queue, create agent explicit_enq that will be used to perform explicit enqueue operations on the queue, and associate the oe user with the agent.oe_queue is a secure queue because it was created using SET_UP_QUEUE. For a user to perform enqueue and dequeue operations on a secure queue, the user must be configured as a secure queue user of the queue. Associating the oe user with agent explicit_enq enables the oe user to perform enqueue operations on this queue.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDE
CONNECT strmadmin/&password@db01;
set echo on
BEGIN
SYS.DBMS_AQADM.GRANT_QUEUE_PRIVILEGE(
privilege => 'ALL',
queue_name => 'strmadmin.oe_queue',
grantee => 'oe');
SYS.DBMS_AQADM.CREATE_AQ_AGENT(
agent_name => 'explicit_enq');
DBMS_AQADM.ENABLE_DB_ACCESS(
agent_name => 'explicit_enq',
db_username => 'oe');
END;
/
Creating Enqueue Procedures
ANYDATA queue oe_queue. One procedure enqueues non-LCR messages, and the other procedure enqueues row LCR messages.db01 as sample schema user oe to create a type to represent orders based on the columns in the oe.orders table. This type is used for messages that are enqueued into the ANYDATA queue oe_queue. The type attributes include the columns in the oe.orders table, along with one extra attribute named action. The value of the action attribute for instances of this type is used to determine the correct action to perform on the instance (either apply process dequeue or explicit dequeue).
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDE
CONNECT oe/&password@db01;
set echo on
CREATE TYPE order_event_typ AS OBJECT(
order_id NUMBER(12),
order_date TIMESTAMP(6) WITH LOCAL TIME ZONE,
order_mode VARCHAR2(8),
customer_id NUMBER(6),
order_status NUMBER(2),
order_total NUMBER(8,2),
sales_rep_id NUMBER(6),
promotion_id NUMBER(6),
action VARCHAR(7));
/
db01 as sample schema user oe to create a type to represent customers based on the columns in the oe.customers table. This type is used for messages that are enqueued into the ANYDATA queue oe_queue. The type attributes include the columns in the oe.customers table, along with one extra attribute named action. The value of the action attribute for instances of this type is used to determine the correct action to perform on the instance (either apply process dequeue or explicit dequeue).
cust_geo_location column from the oe.customers table. This column is useful only with Oracle Spatial.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
CREATE TYPE customer_event_typ AS OBJECT(
customer_id NUMBER(6),
cust_first_name VARCHAR2(20),
cust_last_name VARCHAR2(20),
cust_address CUST_ADDRESS_TYP,
phone_numbers PHONE_LIST_TYP,
nls_language VARCHAR2(3),
nls_territory VARCHAR2(30),
credit_limit NUMBER(9,2),
cust_email VARCHAR2(30),
account_mgr_id NUMBER(6),
date_of_birth DATE,
marital_status VARCHAR2(20),
gender VARCHAR2(1),
income_level VARCHAR2(20),
action VARCHAR(7));
/
db01 as sample schema user oe to create a PL/SQL procedure called enq_proc to enqueue non-LCR messages into ANYDATA queue oe_queue.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
CREATE PROCEDURE oe.enq_proc (event IN ANYDATA) IS
enqopt DBMS_AQ.ENQUEUE_OPTIONS_T;
mprop DBMS_AQ.MESSAGE_PROPERTIES_T;
enq_eventid RAW(16);
BEGIN
mprop.SENDER_ID := SYS.AQ$_AGENT('explicit_enq', NULL, NULL);
DBMS_AQ.ENQUEUE(
queue_name => 'strmadmin.oe_queue',
enqueue_options => enqopt,
message_properties => mprop,
payload => event,
msgid => enq_eventid);
END;
/
db01 as sample schema user oe to create a PL/SQL procedure called enq_row_lcr that constructs a row LCR and then enqueues the row LCR into ANYDATA queue oe_queue.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
CREATE PROCEDURE oe.enq_row_lcr(
source_dbname VARCHAR2,
cmd_type VARCHAR2,
obj_owner VARCHAR2,
obj_name VARCHAR2,
old_vals SYS.LCR$_ROW_LIST,
new_vals SYS.LCR$_ROW_LIST)
AS
eopt DBMS_AQ.ENQUEUE_OPTIONS_T;
mprop DBMS_AQ.MESSAGE_PROPERTIES_T;
enq_msgid RAW(16);
row_lcr SYS.LCR$_ROW_RECORD;
BEGIN
mprop.SENDER_ID := SYS.AQ$_AGENT('explicit_enq', NULL, NULL);
row_lcr := SYS.LCR$_ROW_RECORD.CONSTRUCT(
source_database_name => source_dbname,
command_type => cmd_type,
object_owner => obj_owner,
object_name => obj_name,
old_values => old_vals,
new_values => new_vals);
DBMS_AQ.ENQUEUE(
queue_name => 'strmadmin.oe_queue',
enqueue_options => eopt,
message_properties => mprop,
payload => ANYDATA.ConvertObject(row_lcr),
msgid => enq_msgid);
END enq_row_lcr;
/
Configuring an Apply Process
ANYDATA queue oe_queue.db01 as sample schema user oe to create a function called get_oe_action and to grant EXECUTE privilege on the function to administrator user strmadmin.action attribute in the messages in queue oe_queue. It is used in rules later in this chapter to determine the value of the action attribute for an event. Then, the clients of the rules engine perform the appropriate action for the event (either dequeue by apply process or explicit dequeue). In this example, the clients of the rules engine are the apply process and the oe.explicit_dq PL/SQL procedure.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
CREATE FUNCTION oe.get_oe_action (event IN ANYDATA)
RETURN VARCHAR2
IS
ord oe.order_event_typ;
cust oe.customer_event_typ;
num NUMBER;
type_name VARCHAR2(61);
BEGIN
type_name := event.GETTYPENAME;
IF type_name = 'OE.ORDER_EVENT_TYP' THEN
num := event.GETOBJECT(ord);
RETURN ord.action;
ELSIF type_name = 'OE.CUSTOMER_EVENT_TYP' THEN
num := event.GETOBJECT(cust);
RETURN cust.action;
ELSE
RETURN NULL;
END IF;
END;
/
GRANT EXECUTE ON get_oe_action TO strmadmin;
db01 as sample schema user oe to create a PL/SQL procedure called mes_handler that is used as a message handler by the apply process. You also grant EXECUTE privilege on this procedure to administrator user strmadmin. This procedure takes the payload in a user-enqueued message of type oe.order_event_typ or oe.customer_event_typ and inserts it as a row in the oe.orders table or oe.customers table, respectively.
set echo offset verify offACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
CREATE PROCEDURE oe.mes_handler (event IN ANYDATA) IS
ord oe.order_event_typ;
cust oe.customer_event_typ;
num NUMBER;
type_name VARCHAR2(61);
BEGIN
type_name := event.GETTYPENAME;
IF type_name = 'OE.ORDER_EVENT_TYP' THEN
num := event.GETOBJECT(ord);
INSERT INTO oe.orders VALUES (ord.order_id, ord.order_date,
ord.order_mode, ord.customer_id, ord.order_status, ord.order_total,
ord.sales_rep_id, ord.promotion_id);
ELSIF type_name = 'OE.CUSTOMER_EVENT_TYP' THEN
num := event.GETOBJECT(cust);
INSERT INTO oe.customers VALUES (cust.customer_id, cust.cust_first_name,
cust.cust_last_name, cust.cust_address, cust.phone_numbers,
cust.nls_language, cust.nls_territory, cust.credit_limit, cust.cust_email,
cust.account_mgr_id, cust.date_of_birth, cust.marital_status,
cust.gender, cust.income_level);
END IF;
END;
/
GRANT EXECUTE ON mes_handler TO strmadmin;
db01 as administrator user strmadmin to create an evaluation context for the rule set.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDE
CONNECT strmadmin/&password@db01;
set echo on
DECLARE
table_alias SYS.RE$TABLE_ALIAS_LIST;
BEGIN
table_alias := SYS.RE$TABLE_ALIAS_LIST(
SYS.RE$TABLE_ALIAS('tab', 'strmadmin.oe_queue_table'));
DBMS_RULE_ADM.CREATE_EVALUATION_CONTEXT(
evaluation_context_name => 'oe_eval_context',
table_aliases => table_alias);
END;
/
db01 as administrator user strmadmin to create a rule set for the apply process.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDE
CONNECT strmadmin/&password@db01;
set echo on
BEGIN
DBMS_RULE_ADM.CREATE_RULE_SET(
rule_set_name => 'apply_oe_rs',
evaluation_context => 'strmadmin.oe_eval_context');
END;
/
db01 as administrator user strmadmin to create a rule that evaluates to TRUE if the action value of a message is apply. Notice that tab.user_data is passed to the oe.get_oe_action function. The tab.user_data column holds the event payload in a queue table. The table alias for the queue table was specified as tab in Example 23-10.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDE
CONNECT strmadmin/&password@db01;
set echo on
BEGIN
DBMS_RULE_ADM.CREATE_RULE(
rule_name => 'strmadmin.apply_action',
condition => 'oe.get_oe_action(tab.user_data) = ''APPLY'' ');
END;
/
db01 as administrator user strmadmin to create a rule that evaluates to TRUE if the event in the queue is a row LCR that changes either the oe.orders table or the oe.customers table. This rule enables the apply process to apply user-enqueued changes to the tables directly.SYS.STREAMS$_EVALUATION_CONTEXT because the rule is used to evaluate LCRs. When this rule is added to the rule set, the Oracle-supplied evaluation context is used for the rule during evaluation instead of evaluation context oe_eval_context created in Example 23-10.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDE
CONNECT strmadmin/&password@db01;
set echo on
BEGIN
DBMS_RULE_ADM.CREATE_RULE(
rule_name => 'apply_lcrs',
condition => ':dml.GET_OBJECT_OWNER() = ''OE'' AND ' ||
' (:dml.GET_OBJECT_NAME() = ''ORDERS'' OR ' ||
':dml.GET_OBJECT_NAME() = ''CUSTOMERS'') ',
evaluation_context => 'SYS.STREAMS$_EVALUATION_CONTEXT');
END;
/
db01 as administrator user strmadmin to add the apply_action rule created in Example 23-12 and the apply_lcrs rule created in Example 23-13 to the apply_oe_rs rule set created in Example 23-11.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
BEGIN
DBMS_RULE_ADM.ADD_RULE(
rule_name => 'apply_action',
rule_set_name => 'apply_oe_rs');
DBMS_RULE_ADM.ADD_RULE(
rule_name => 'apply_lcrs',
rule_set_name => 'apply_oe_rs');
END;
/
db01 as administrator user strmadmin to create an apply process that is associated with queue oe_queue, that uses the apply_oe_rs rule set, and that uses the mes_handler procedure as a message handler.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
BEGIN
DBMS_APPLY_ADM.CREATE_APPLY(
queue_name => 'strmadmin.oe_queue',
apply_name => 'apply_oe',
rule_set_name => 'strmadmin.apply_oe_rs',
message_handler => 'oe.mes_handler',
apply_user => 'oe',
apply_captured => false);
END;
/
oe was specified as the apply user when the apply process was created in Example 23-15, you must grant this user EXECUTE privilege on the strmadmin.apply_oe_rs rule set used by the apply process. You connect to database db01 as administrator user strmadmin to accomplish this in Example 23-16.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
BEGIN
DBMS_RULE_ADM.GRANT_OBJECT_PRIVILEGE(
privilege => DBMS_RULE_ADM.EXECUTE_ON_RULE_SET,
object_name => 'strmadmin.apply_oe_rs',
grantee => 'oe',
grant_option => FALSE);
END;
/
db01 as administrator user strmadmin to start the apply process with the disable_on_error parameter set to n so that the apply process is not disabled if it encounters an error.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
BEGIN
DBMS_APPLY_ADM.SET_PARAMETER(
apply_name => 'apply_oe',
parameter => 'disable_on_error',
value => 'n');
DBMS_APPLY_ADM.START_APPLY(
apply_name => 'apply_oe');
END;
/
Configuring Explicit Dequeue
db01 as administrator user strmadmin to create agent explicit_dq. This agent is used to perform explicit dequeue operations on the oe_queue queue.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
BEGIN
SYS.DBMS_AQADM.CREATE_AQ_AGENT(
agent_name => 'explicit_dq');
END;
/
oe_queue queue is a secure queue because it was created using SET_UP_QUEUE in Example 23-2. For a user to perform enqueue and dequeue operations on a secure queue, the user must be configured as a secure queue user of the queue.db01 as administrator user strmadmin to associate the oe user with agent explicit_dq. The oe user is able to perform dequeue operations on the oe_queue queue when the agent is used to create a subscriber to the queue in Example 23-20.
set echo offset verify offACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
BEGIN
DBMS_AQADM.ENABLE_DB_ACCESS(
agent_name => 'explicit_dq',
db_username => 'oe');
END;
/
db01 as administrator user strmadmin to add a subscriber to the oe_queue queue. This subscriber will perform explicit dequeues of messages. A subscriber rule is used to dequeue any messages where the action value is not apply. If the action value is apply for a message, then the message is ignored by the subscriber. Such messages are dequeued and processed by the apply process.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for STRMADMIN: ' HIDECONNECT strmadmin/&password@db01;set echo on
DECLARE
subscriber SYS.AQ$_AGENT;
BEGIN
subscriber := SYS.AQ$_AGENT('explicit_dq', NULL, NULL);
SYS.DBMS_AQADM.ADD_SUBSCRIBER(
queue_name => 'strmadmin.oe_queue',
subscriber => subscriber,
rule => 'oe.get_oe_action(tab.user_data) != ''APPLY''');
END;
/
db01 as sample schema user oe to create a PL/SQL procedure called explicit_dq to dequeue messages explicitly using the subscriber created in Example 23-20.next_trans moves to the next transaction, and exception handler no_messages exits the loop when there are no more messages.
SET ECHO OFFSET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
CREATE PROCEDURE oe.explicit_dq (consumer IN VARCHAR2) AS
deqopt DBMS_AQ.DEQUEUE_OPTIONS_T;
mprop DBMS_AQ.MESSAGE_PROPERTIES_T;
msgid RAW(16);
payload ANYDATA;
new_messages BOOLEAN := TRUE;
ord oe.order_event_typ;
cust oe.customer_event_typ;
tc pls_integer;
next_trans EXCEPTION;
no_messages EXCEPTION;
pragma exception_init (next_trans, -25235);
pragma exception_init (no_messages, -25228);
BEGIN
deqopt.consumer_name := consumer;
deqopt.wait := 1;
WHILE (new_messages) LOOP
BEGIN
DBMS_AQ.DEQUEUE(
queue_name => 'strmadmin.oe_queue',
dequeue_options => deqopt,
message_properties => mprop,
payload => payload,
msgid => msgid);
COMMIT;
deqopt.navigation := DBMS_AQ.NEXT;
DBMS_OUTPUT.PUT_LINE('Message Dequeued');
DBMS_OUTPUT.PUT_LINE('Type Name := ' || payload.GetTypeName);
IF (payload.GetTypeName = 'OE.ORDER_EVENT_TYP') THEN
tc := payload.GetObject(ord);
DBMS_OUTPUT.PUT_LINE('order_id - ' || ord.order_id);
DBMS_OUTPUT.PUT_LINE('order_date - ' || ord.order_date);
DBMS_OUTPUT.PUT_LINE('order_mode - ' || ord.order_mode);
DBMS_OUTPUT.PUT_LINE('customer_id - ' || ord.customer_id);
DBMS_OUTPUT.PUT_LINE('order_status - ' || ord.order_status);
DBMS_OUTPUT.PUT_LINE('order_total - ' || ord.order_total);
DBMS_OUTPUT.PUT_LINE('sales_rep_id - ' || ord.sales_rep_id);
DBMS_OUTPUT.PUT_LINE('promotion_id - ' || ord.promotion_id);
END IF;
IF (payload.GetTypeName = 'OE.CUSTOMER_EVENT_TYP') THEN
tc := payload.GetObject(cust);
DBMS_OUTPUT.PUT_LINE('customer_id - ' || cust.customer_id);
DBMS_OUTPUT.PUT_LINE('cust_first_name - ' || cust.cust_first_name);
DBMS_OUTPUT.PUT_LINE('cust_last_name - ' || cust.cust_last_name);
DBMS_OUTPUT.PUT_LINE('street_address - ' ||
cust.cust_address.street_address);
DBMS_OUTPUT.PUT_LINE('postal_code - ' ||
cust.cust_address.postal_code);
DBMS_OUTPUT.PUT_LINE('city - ' || cust.cust_address.city);
DBMS_OUTPUT.PUT_LINE('state_province - ' ||
cust.cust_address.state_province);
DBMS_OUTPUT.PUT_LINE('country_id - ' ||
cust.cust_address.country_id);
DBMS_OUTPUT.PUT_LINE('phone_number1 - ' || cust.phone_numbers(1));
DBMS_OUTPUT.PUT_LINE('phone_number2 - ' || cust.phone_numbers(2));
DBMS_OUTPUT.PUT_LINE('phone_number3 - ' || cust.phone_numbers(3));
DBMS_OUTPUT.PUT_LINE('nls_language - ' || cust.nls_language);
DBMS_OUTPUT.PUT_LINE('nls_territory - ' || cust.nls_territory);
DBMS_OUTPUT.PUT_LINE('credit_limit - ' || cust.credit_limit);
DBMS_OUTPUT.PUT_LINE('cust_email - ' || cust.cust_email);
DBMS_OUTPUT.PUT_LINE('account_mgr_id - ' || cust.account_mgr_id);
DBMS_OUTPUT.PUT_LINE('date_of_birth - ' || cust.date_of_birth);
DBMS_OUTPUT.PUT_LINE('marital_status - ' || cust.marital_status);
DBMS_OUTPUT.PUT_LINE('gender - ' || cust.gender);
DBMS_OUTPUT.PUT_LINE('income_level - ' || cust.income_level);
END IF;
EXCEPTION
WHEN next_trans THEN
deqopt.navigation := DBMS_AQ.NEXT_TRANSACTION;
WHEN no_messages THEN
new_messages := FALSE;
DBMS_OUTPUT.PUT_LINE('No more messagess');
END;
END LOOP;
END;
/
Enqueuing Messages
db01 as sample schema user oe to enqueue two messages with apply for the action value. Based on the apply process rules, the apply process dequeues and processes these messages with the oe.mes_handler message handler procedure created in Example 23-9. The COMMIT after the enqueues makes these two enqueues part of the same transaction. An enqueued message is not visible until the session that enqueued it commits the enqueue.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
BEGIN
oe.enq_proc(ANYDATA.convertobject(oe.order_event_typ(
2500,'05-MAY-01','online',117,3,44699,161,NULL,'APPLY')));
END;
/
BEGIN
oe.enq_proc(ANYDATA.convertobject(oe.customer_event_typ(
990,'Hester','Prynne',oe.cust_address_typ('555 Beacon Street',
'02109','Boston','MA','US'),oe.phone_list_typ('+1 617 123 4104',
'+1 617 083 4381','+1 617 742 5813'),'i','AMERICA',5000,
'a@scarlet_letter.com',145,NULL,'SINGLE','F','UNDER 50,000','APPLY')));
END;
/
COMMIT;
db01 as sample schema user oe to enqueue two messages with dequeue for the action value. The oe.explicit_dq procedure created in Example 23-21 dequeues these messages because the action is not apply. Based on the apply process rules, the apply process ignores these messages. The COMMIT after the enqueues makes these two enqueues part of the same transaction.
SET ECHO OFFSET VERIFY OFFACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDECONNECT oe/&password@db01;set echo on
BEGIN
oe.enq_proc(ANYDATA.convertobject(oe.order_event_typ(
2501,'22-JAN-00','direct',117,3,22788,161,NULL,'DEQUEUE')));
END;
/
BEGIN
oe.enq_proc(ANYDATA.convertobject(oe.customer_event_typ(
991,'Nick','Carraway',oe.cust_address_typ('10th Street',
'11101','Long Island','NY','US'),oe.phone_list_typ('+1 718 786 2287',
'+1 718 511 9114', '+1 718 888 4832'),'i','AMERICA',3000,
'nick@great_gatsby.com',149,NULL,'MARRIED','M','OVER 150,000','DEQUEUE')));
END;
/
COMMIT;
db01 as sample schema user oe to create a row LCR that inserts a row into the oe.orders table and another LCR that updates that row. The apply process applies these messages directly.
COMMIT statement is run after each enqueue, making each enqueue a separate transaction. However, you can perform multiple LCR enqueues before a commit if there is more than one LCR in a transaction.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDE
CONNECT oe/&password@db01;
set echo on
DECLARE
newunit1 SYS.LCR$_ROW_UNIT;
newunit2 SYS.LCR$_ROW_UNIT;
newunit3 SYS.LCR$_ROW_UNIT;
newunit4 SYS.LCR$_ROW_UNIT;
newunit5 SYS.LCR$_ROW_UNIT;
newunit6 SYS.LCR$_ROW_UNIT;
newunit7 SYS.LCR$_ROW_UNIT;
newunit8 SYS.LCR$_ROW_UNIT;
newvals SYS.LCR$_ROW_LIST;
BEGIN
newunit1 := SYS.LCR$_ROW_UNIT(
'ORDER_ID',ANYDATA.ConvertNumber(2502),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newunit2 := SYS.LCR$_ROW_UNIT(
'ORDER_DATE',ANYDATA.ConvertTimestampLTZ('04-NOV-00'),DBMS_LCR.NOT_A_LOB,
NULL,NULL);
newunit3 := SYS.LCR$_ROW_UNIT(
'ORDER_MODE',ANYDATA.ConvertVarchar2('online'),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newunit4 := SYS.LCR$_ROW_UNIT(
'CUSTOMER_ID',ANYDATA.ConvertNumber(145),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newunit5 := SYS.LCR$_ROW_UNIT(
'ORDER_STATUS',ANYDATA.ConvertNumber(3),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newunit6 := SYS.LCR$_ROW_UNIT(
'ORDER_TOTAL',ANYDATA.ConvertNumber(35199),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newunit7 := SYS.LCR$_ROW_UNIT(
'SALES_REP_ID',ANYDATA.ConvertNumber(160),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newunit8 := SYS.LCR$_ROW_UNIT(
'PROMOTION_ID',ANYDATA.ConvertNumber(1),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newvals := SYS.LCR$_ROW_LIST(
newunit1,newunit2,newunit3,newunit4,newunit5,newunit6,newunit7,newunit8);
oe.enq_row_lcr('DB01','INSERT','OE','ORDERS',NULL,newvals);
END;
/
COMMIT;
DECLARE
oldunit1 SYS.LCR$_ROW_UNIT;
oldunit2 SYS.LCR$_ROW_UNIT;
oldvals SYS.LCR$_ROW_LIST;
newunit1 SYS.LCR$_ROW_UNIT;
newvals SYS.LCR$_ROW_LIST;
BEGIN
oldunit1 := SYS.LCR$_ROW_UNIT(
'ORDER_ID',ANYDATA.ConvertNumber(2502),DBMS_LCR.NOT_A_LOB,NULL,NULL);
oldunit2 := SYS.LCR$_ROW_UNIT(
'ORDER_TOTAL',ANYDATA.ConvertNumber(35199),DBMS_LCR.NOT_A_LOB,NULL,NULL);
oldvals := SYS.LCR$_ROW_LIST(oldunit1,oldunit2);
newunit1 := SYS.LCR$_ROW_UNIT(
'ORDER_TOTAL',ANYDATA.ConvertNumber(5235),DBMS_LCR.NOT_A_LOB,NULL,NULL);
newvals := SYS.LCR$_ROW_LIST(newunit1);
oe.enq_row_lcr('DB01','UPDATE','OE','ORDERS',oldvals,newvals);
END;
/
COMMIT;
Dequeuing Messages Explicitly and Querying for Applied Messages
db01 as sample schema user oe to run procedure explicit_dq, created in Example 23-21. You specify subscriber explicit_dq, added in Example 23-20, as the consumer of the messages you want to dequeue. In these examples, messages that are not dequeued explicitly by this procedure are dequeued by the apply process.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDE
CONNECT oe/&password@db01;
set echo on
CREATE PROCEDURE oe.enq_proc (payload ANYDATA) IS
SET SERVEROUTPUT ON SIZE 100000;
EXEC oe.explicit_dq('explicit_dq');
Message Dequeued
Type Name := OE.ORDER_EVENT_TYP
order_id - 2501
order_date - 22-JAN-00 12.00.00.000000 AM
order_mode - direct
customer_id - 117
order_status - 3
order_total - 22788
sales_rep_id - 161
promotion_id -
Message Dequeued
Type Name := OE.CUSTOMER_EVENT_TYP
customer_id - 991
cust_first_name - Nick
cust_last_name - Carraway
street_address - 10th Street
postal_code - 11101
city - Long Island
state_province - NY
country_id - US
phone_number1 - +1 718 786 2287
phone_number2 - +1 718 511 9114
phone_number3 - +1 718 888 4832
nls_language - i
nls_territory - AMERICA
credit_limit - 3000
cust_email - nick@great_gatsby.com
account_mgr_id - 149
date_of_birth -
marital_status - MARRIED
gender - M
income_level - OVER 150,000
No more messages
db01 as sample schema user oe to query the oe.orders and oe.customers tables to see the rows corresponding to the messages applied by apply process apply_oe, created in Example 23-15.
SET ECHO OFF
SET VERIFY OFF
ACCEPT password CHAR PROMPT 'Enter the password for OE: ' HIDE
CONNECT oe/&password@db01;
set echo on
CREATE PROCEDURE oe.enq_proc (payload ANYDATA) IS
SELECT order_id, order_date, customer_id, order_total
FROM oe.orders WHERE order_id = 2500;
SELECT cust_first_name, cust_last_name, cust_email
FROM oe.customers WHERE customer_id = 990;
SELECT order_id, order_date, customer_id, order_total
FROM oe.orders WHERE order_id = 2502;
ORDER_ID ORDER_DATE CUSTOMER_ID ORDER_TOTAL
---------- ------------------------------ ----------- -----------
2500 05-MAY-01 12.00.00.000000 AM 117 44699
1 row selected.
CUST_FIRST_NAME CUST_LAST_NAME CUST_EMAIL
-------------------- -------------------- ------------------------------
Hester Prynne a@scarlet_letter.com
1 row selected.
ORDER_ID ORDER_DATE CUSTOMER_ID ORDER_TOTAL
---------- ------------------------------ ----------- -----------
2502 04-NOV-00 12.00.00.000000 AM 145 5235
1 row selected.
Enqueuing and Dequeuing Messages Using JMS
ojdbc5.jar and ojbc6.jar files with JDK 5.n and JDK 6.n, respectively. The following jar and zip files should be in the CLASSPATH based on the release of JDK you are using.CLASSPATH must contain:
ORACLE_HOME/jdbc/lib/ojdbc5.jar
CLASSPATH must contain:
ORACLE_HOME/jdbc/lib/ojdbc6.jar
ORACLE_HOME/lib/jta.jar
ORACLE_HOME/xdk/lib/xmlparserv2.jar
ORACLE_HOME/rdbms/jlib/xdb.jar
ORACLE_HOME/jlib/aqapi.jar
ORACLE_HOME/rdbms/jlib/jmscommon.jar
LD_LIBRARY_PATH (Linux and Solaris) or PATH (Windows) includes ORACLE_HOME/lib.oe enqueuing JMS messages into a queue and agent explicit_dq dequeuing them. Agent explicit_dq was created in Example 23-18, associated with sample schema user oe in Example 23-19, and made a subscriber to queue oe_queue in Example 23-20.oe was granted EXECUTE on DBMS_AQ in Example 23-1. In order for this user to use the Oracle JMS interface, it must have EXECUTE privilege on DBMS_AQIN as well. In Example 23-27, you connect to database db01 as a user with administrative privileges to grant the necessary privilege to oe.ANYDATA queues unless you call DBMS_AQADM.ENABLE_JMS_TYPES(queue_table_name) after DBMS_STREAMS_ADM.SET_UP_QUEUE(). In Example 23-28, you connect to database db01 as administrator user strmadmin, created in Example 23-1, to run ENABLE_JMS_TYPES on ANYDATA queue table oe_queue_table, created in Example 23-2.
CONNECT strmadmin;
Enter password: password
BEGIN
DBMS_AQADM.ENABLE_JMS_TYPES('oe_queue_table');
END;
/
db01 as sample schema user oe to create types address and person.
CONNECT oe;
Enter password: password
CREATE TYPE address AS OBJECT (street VARCHAR (30), num NUMBER)
/
CREATE TYPE person AS OBJECT (name VARCHAR (30), home ADDRESS)
/
JPerson and JAddress for the person and address types, respectively. The input to JPublisher is a file called input.typ with the following lines:
SQL PERSON AS JPerson
SQL ADDRESS AS JAddress
jpub -input=input.typ -user=OE/OE
TopicConnectionFactory using the JDBC OCI driver
TopicSessionpublishUserMessages() to publish an ADT message and a JMS text message to an Oracle Streams topicpublishLcrMessages() to publish an XML LCR message to an Oracle Streams topicpublishUserMessages() does the following:explicit_enq to access queue oe_queuePERSON ADT messageexplicit_dq as the recipientPERSON ADT messagepublishLcrMessages() does the following:explicit_enq to access queue oe_queueXMLType containing the LCRexplicit_dq as the recipientStreamsEnq.java.
import oracle.AQ.*;
import oracle.jms.*;
import javax.jms.*;
import java.lang.*;
import oracle.xdb.*;
public class StreamsEnq
{
public static void main (String args [])
throws java.sql.SQLException, ClassNotFoundException, JMSException
{
TopicConnectionFactory tc_fact= null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
try
{
if (args.length < 3 )
System.out.println("Usage:java filename [SID] [HOST] [PORT]");
else
{
tc_fact = AQjmsFactory.getTopicConnectionFactory(
args[1], args[0], Integer.parseInt(args[2]), "oci8");
t_conn = tc_fact.createTopicConnection( "OE","OE");
t_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
t_conn.start() ;
publishUserMessages(t_sess);
publishLcrMessages(t_sess);
t_sess.close() ;
t_conn.close() ;
System.out.println("End of StreamsEnq Demo") ;
}
}
catch (Exception ex)
{
System.out.println("Exception-1: " + ex);
ex.printStackTrace();
}
}
public static void publishUserMessages(TopicSession t_sess) throws Exception
{
Topic topic = null;
TopicPublisher t_pub = null;
JPerson pers = null;
JAddress addr = null;
TextMessage t_msg = null;
AdtMessage adt_msg = null;
AQjmsAgent agent = null;
AQjmsAgent[] recipList = null;
try
{
topic = ((AQjmsSession)t_sess).getTopic("strmadmin", "oe_queue");
t_pub = t_sess.createPublisher(topic);
agent = new AQjmsAgent("explicit_enq", null);
adt_msg = ((AQjmsSession)t_sess).createAdtMessage();
pers = new JPerson();
addr = new JAddress();
addr.setNum(new java.math.BigDecimal(500));
addr.setStreet("Oracle Pkwy");
pers.setName("Mark");
pers.setHome(addr);
adt_msg.setAdtPayload(pers);
((AQjmsMessage)adt_msg).setSenderID(agent);
System.out.println("Publish message 1 -type PERSON\n");
recipList = new AQjmsAgent[1];
recipList[0] = new AQjmsAgent("explicit_dq", null);
((AQjmsTopicPublisher)t_pub).publish(topic, adt_msg, recipList);
t_sess.commit();
t_msg = t_sess.createTextMessage();
t_msg.setText("Test message");
t_msg.setStringProperty("color", "BLUE");
t_msg.setIntProperty("year", 1999);
((AQjmsMessage)t_msg).setSenderID(agent);
System.out.println("Publish message 2 -type JMS TextMessage\n");
((AQjmsTopicPublisher)t_pub).publish(topic, t_msg, recipList);
t_sess.commit();
}
catch (JMSException jms_ex)
{
System.out.println("JMS Exception: " + jms_ex);
if(jms_ex.getLinkedException() != null)
System.out.println("Linked Exception: " + jms_ex.getLinkedException());
}
}
public static void publishLcrMessages(TopicSession t_sess) throws Exception
{
Topic topic = null;
TopicPublisher t_pub = null;
XMLType xml_lcr = null;
AdtMessage adt_msg = null;
AQjmsAgent agent = null;
StringBuffer lcr_data = null;
AQjmsAgent[] recipList = null;
java.sql.Connection db_conn = null;
try
{
topic = ((AQjmsSession)t_sess).getTopic("strmadmin", "oe_queue");
t_pub = t_sess.createPublisher(topic);
db_conn = ((AQjmsSession)t_sess).getDBConnection();
agent = new AQjmsAgent("explicit_enq", null);
adt_msg = ((AQjmsSession)t_sess).createAdtMessage();
lcr_data = new StringBuffer();
lcr_data.append("<ROW_LCR ");
lcr_data.append("xmlns='http://xmlns.oracle.com/streams/schemas/lcr' \n");
lcr_data.append("xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' \n");
lcr_data.append("xsi:schemaLocation='http://xmlns.oracle.com/streams/schemas/lcr ");
lcr_data.append("http://xmlns.oracle.com/streams/schemas/lcr/streamslcr.xsd'");
lcr_data.append("> \n");
lcr_data.append("<source_database_name>source_dbname</source_database_name> \n");
lcr_data.append("<command_type>INSERT</command_type> \n");
lcr_data.append("<object_owner>Ram</object_owner> \n");
lcr_data.append("<object_name>Emp</object_name> \n");
lcr_data.append("<tag>0ABC</tag> \n");
lcr_data.append("<transaction_id>0.0.0</transaction_id> \n");
lcr_data.append("<scn>0</scn> \n");
lcr_data.append("<old_values> \n");
lcr_data.append("<old_value> \n");
lcr_data.append("<column_name>C01</column_name> \n");
lcr_data.append("<data><varchar2>Clob old</varchar2></data> \n");
lcr_data.append("</old_value> \n");
lcr_data.append("<old_value> \n");
lcr_data.append("<column_name>C02</column_name> \n");
lcr_data.append("<data><varchar2>A123FF</varchar2></data> \n");
lcr_data.append("</old_value> \n");
lcr_data.append("<old_value> \n");
lcr_data.append("<column_name>C03</column_name> \n");
lcr_data.append("<data> \n");
lcr_data.append("<date><value>1997-11-24</value><format>SYYYY-MM-DD</format></date> \n");
lcr_data.append("</data> \n");
lcr_data.append("</old_value> \n");
lcr_data.append("<old_value> \n");
lcr_data.append("<column_name>C04</column_name> \n");
lcr_data.append("<data> \n");
lcr_data.append("<timestamp><value>1999-05-31T13:20:00.000</value>");
lcr_data.append("<format>SYYYY-MM-DD\"T\"HH24:MI:SS.FF</format></timestamp> \n");
lcr_data.append("</data> \n");
lcr_data.append("</old_value> \n");
lcr_data.append("<old_value> \n");
lcr_data.append("<column_name>C05</column_name> \n");
lcr_data.append("<data><raw>ABCDE</raw></data> \n");
lcr_data.append("</old_value> \n");
lcr_data.append("</old_values> \n");
lcr_data.append("<new_values> \n");
lcr_data.append("<new_value> \n");
lcr_data.append("<column_name>C01</column_name> \n");
lcr_data.append("<data><varchar2>A123FF</varchar2></data> \n");
lcr_data.append("</new_value> \n");
lcr_data.append("<new_value> \n");
lcr_data.append("<column_name>C02</column_name> \n");
lcr_data.append("<data><number>35.23</number></data> \n");
lcr_data.append("</new_value> \n");
lcr_data.append("<new_value> \n");
lcr_data.append("<column_name>C03</column_name> \n");
lcr_data.append("<data><number>-100000</number></data> \n");
lcr_data.append("</new_value> \n");
lcr_data.appeU&nd("<new_value> \n");
lcr_data.append("<column_name>C04</column_name> \n");
lcr_data.append("<data><varchar2>Hello</varchar2></data> \n");
lcr_data.append("</new_value> \n");
lcr_data.append("<new_value> \n");
lcr_data.append("<column_name>C05</column_name> \n");
lcr_data.append("<data><char>world</char></data> \n");
lcr_data.append("</new_value> \n");
lcr_data.append("</new_values> \n");
lcr_data.append("</ROW_LCR>");
xml_lcr = oracle.xdb.XMLType.createXML(db_conn, lcr_data.toString());
adt_msg.setAdtPayload(xml_lcr);
((AQjmsMessage)adt_msg).setSenderID(agent);
System.out.println("Publish message 3 - XMLType containing LCR ROW\n");
recipList = new AQjmsAgent[1];
recipList[0] = new AQjmsAgent("explicit_dq", null);
((AQjmsTopicPublisher)t_pub).publish(topic, adt_msg, recipList);
t_sess.commit();
}
catch (JMSException jms_ex)
{
System.out.println("JMS Exception: " + jms_ex);
if(jms_ex.getLinkedException() != null)
System.out.println("Linked Exception: " + jms_ex.getLinkedException());
}
}
}
TopicConnectionFactory using the JDBC OCI driver
TopicSessionreceiveMessages() to receive messages from an Oracle Streams topicreceiveMessages() does the following:TopicReceiver to receive messages for consumer explicit_dqADDRESS and PERSON in the JMS typemapXMLType in the typemap (required for LCRs)StreamsDeq.java.
import oracle.AQ.*;
import oracle.jms.*;
import javax.jms.*;
import java.lang.*;
import oracle.xdb.*;
import java.sql.SQLException;
public class StreamsDeq
{
public static void main (String args [])
throws java.sql.SQLException, ClassNotFoundException, JMSException
{
TopicConnectionFactory tc_fact= null;
TopicConnection t_conn = null;
TopicSession t_sess = null;
try
{
if (args.length < 3 )
System.out.println("Usage:java filename [SID] [HOST] [PORT]");
else
{
tc_fact = AQjmsFactory.getTopicConnectionFactory(
args[1], args[0], Integer.parseInt(args[2]), "oci8");
t_conn = tc_fact.createTopicConnection( "OE","OE");
t_sess = t_conn.createTopicSession(true, Session.CLIENT_ACKNOWLEDGE);
t_conn.start() ;
receiveMessages(t_sess);
t_sess.close() ;
t_conn.close() ;
System.out.println("\nEnd of StreamsDeq Demo") ;
}
}
catch (Exception ex)
{
System.out.println("Exception-1: " + ex);
ex.printStackTrace();
}
}
public static void receiveMessages(TopicSession t_sess) throws Exception
{
Topic topic = null;
JPerson pers = null;
JAddress addr = null;
XMLType xtype = null;
TextMessage t_msg = null;
AdtMessage adt_msg = null;
Message jms_msg = null;
TopicReceiver t_recv = null;
int i = 0;
java.util.Map map= null;
try
{
topic = ((AQjmsSession)t_sess).getTopic("strmadmin", "oe_queue");
t_recv = ((AQjmsSession)t_sess).createTopicReceiver(topic, "explicit_dq", null);
map = ((AQjmsSession)t_sess).getTypeMap();
map.put("OE.PERSON", Class.forName("JPerson"));
map.put("OE.ADDRESS", Class.forName("JAddress"));
map.put("SYS.XMLTYPE", Class.forName("oracle.xdb.XMLTypeFactory"));
System.out.println("Receive messages ...\n");
do
{
try
{
jms_msg = (t_recv.receive(10));
i++;
((AQjmsTopicReceiver)t_recv).setNavigationMode(AQjmsConstants.NAVIGATION_NEXT_MESSAGE);
}
catch (JMSException jms_ex2)
{
if((jms_ex2.getLinkedException() != null) &&
(jms_ex2.getLinkedException() instanceof SQLException))
{
SQLException sql_ex2 =(SQLException)(jms_ex2.getLinkedException());
if(sql_ex2.getErrorCode() == 25235)
{
((AQjmsTopicReceiver)t_recv).setNavigationMode(
AQjmsConstants.NAVIGATION_NEXT_TRANSACTION);
continue;
}
else
throw jms_ex2;
}
else
throw jms_ex2;
}
if(jms_msg == null)
{
System.out.println("\nNo more messages");
}
else
{
if(jms_msg instanceof AdtMessage)
{
adt_msg = (AdtMessage)jms_msg;
System.out.println("Retrieved message " + i + ": " +
adt_msg.getAdtPayload());
if(adt_msg.getAdtPayload() instanceof JPerson)
{
pers =(JPerson)( adt_msg.getAdtPayload());
System.out.println("PERSON: Name: " + pers.getName());
}
else if(adt_msg.getAdtPayload() instanceof JAddress)
{
addr =(JAddress)( adt_msg.getAdtPayload());
System.out.println("ADDRESS: Street" + addr.getStreet());
}
else if(adt_msg.getAdtPayload() instanceof oracle.xdb.XMLType)
{
xtype = (XMLType)adt_msg.getAdtPayload();
System.out.println("XMLType: Data: \n" + xtype.getStringVal());
}
System.out.println("Msg id: " + adt_msg.getJMSMessageID());
System.out.println();
}
else if(jms_msg instanceof TextMessage)
{
t_msg = (TextMessage)jms_msg;
System.out.println("Retrieved message " + i + ": " +
t_msg.getText());
System.out.println("Msg id: " + t_msg.getJMSMessageID());
System.out.println();
}
else
System.out.println("Invalid message type");
}
} while (jms_msg != null);
t_sess.commit();
}
catch (JMSException jms_ex)
{
System.out.println("JMS Exception: " + jms_ex);
if(jms_ex.getLinkedException() != null)
System.out.println("Linked Exception: " + jms_ex.getLinkedException());
t_sess.rollback();
}
catch (java.sql.SQLException sql_ex)
{
System.out.println("SQL Exception: " + sql_ex);
sql_ex.printStackTrace();
t_sess.rollback();
}
}
}
javac StreamsEnq.java StreamsDeq.java JPerson.java JAddress.java
ORACLE_SID, HOST, and PORT that are appropriate for your testing environment.
Publish message 1 -type PERSON
Publish message 2 -type JMS TextMessage
Publish message 3 - XMLType containing LCR ROW
End of StreamsEnq Demo
ORACLE_SID, HOST, and PORT that are appropriate for your testing environment.
PK1 1 PK -A
OEBPS/toc.ncxS
A Nonpersistent Queues
Creating Nonpersistent Queues
DBMS_AQADM.CREATE_NP_QUEUE (
queue_name IN VARCHAR2,
multiple_consumers IN BOOLEAN DEFAULT FALSE,
comment IN VARCHAR2 DEFAULT NULL);
AQ$_MEM_SC or AQ$_MEM_MC) in the same schema as that specified by the queue name. If the queue name does not specify a schema name, then the queue is created in the login user's schema.
Managing Nonpersistent Queues
CREATE_NP_QUEUE, it can be enabled by calling START_QUEUE. By default, the queue is created with both enqueue and dequeue disabled.listen call on a nonpersistent queue.
Compatibility of Nonpersistent Queues
compatible parameter of init.ora and the compatible parameter of the queue table should be set to 8.1 or higher to use nonpersistent queues.
Nonpersistent Queue Notification
Queue Payload Type OCI Callback E-mail PL/SQL Callback
Queue Payload Type OCI Callback E-mail PL/SQL Callback
Restrictions on Nonpersistent Queues
RAW and Oracle object type.You are limited to sending messages only to subscribers and explicitly specified recipients who are local. Propagation is not supported from nonpersistent queues. When retrieving messages, you cannot use the dequeue call, but must instead employ the asynchronous notification mechanism, registering for the notification by mean of OCISubscriptionRegister.visibility attribute of enqueue_options must be set to IMMEDIATE for nonpersistent messages.
PK2W iW PK -A OEBPS/content.opfk6
1 Introduction to Oracle AQ
What Is Queuing?
Oracle Streams Advanced Queuing Leverages Oracle Database
ANYDATA queues, which enable applications to enqueue different message types in a single queue.XMLType. These queues can be used to transmit and store messages that are XML documents. Using XMLType, you can do the following:documents internally as CLOB objectsmore than one type of payload in a queueExistsNode()
Oracle Streams Advanced Queuing in Integrated Application Environments
Description of "Figure 1-1 Integrated Application Environment Using Oracle Streams Advanced Queuing"
Oracle Streams Advanced Queuing Client/Server Communication
Description of "Figure 1-2 Client/Server Communication Using Oracle Streams Advanced Queuing"
Multiconsumer Dequeuing of the Same Message
WHERE clause of a SQL query, rules are expressed in terms of attributes that represent message properties or message content. These subscriber rules are evaluated against incoming messages, and those rules that match are used to determine message recipients.
Description of "Figure 1-3 Communication Using a Multiconsumer Queue"
Description of "Figure 1-4 Explicit and Implicit Recipients of Messages"
Oracle Streams Advanced Queuing Implementation of Workflows
Description of "Figure 1-5 Implementing a Workflow using Oracle Streams Advanced Queuing"
Oracle Streams Advanced Queuing Implementation of Publish/Subscribe
Description of "Figure 1-8 Implementing Publish/Subscribe using Oracle Streams Advanced Queuing"
Buffered Messaging
streams_pool_sizestreams_pool_size is specified, it is used as the lower bound.
AQ$Queue_Table_Name view. They appear with states IN-MEMORY or SPILLED.ADT, XML, ANYDATA, or RAW. For ADT types with LOB attributes, only buffered messages with null LOB attributes can be enqueued.IMMEDIATE visibility mode. Thus they cannot be part of another transaction. You cannot specify delay when enqueuing buffered messages.
IMMEDIATE for dequeuing buffered messages. All of the following dequeue options are supported:BROWSE, LOCK, REMOVE, and REMOVE_NO_DATAFIRST_MESSAGE and NEXT_MESSAGE
DBA_QUEUE_SCHEDULES view displays statistics and error information.Streams AQ: enqueue blocked due to flow control and time out with error ORA-25307 if flow control is not resolved. Applications are expected to handle this error, and re-enqueue the failed message.OWNER_INSTANCE of the queue table containing the queue. Enqueue and dequeue requests received at other instances are forwarded to the OWNER_INSTANCE over the interconnect. The REMOTE_LISTENER parameter in listener.ora must also be set to enable forwarding of buffered messaging requests to correct instance.
OWNER_INSTANCEREMOTE_LISTENER parameterDBA_QUEUES and USER_QUEUES views. This service name always points to the instance with the most efficient access for buffered messaging, minimizing pinging between instances. OCI clients can use the service name for buffered messaging operations.
Asynchronous Notifications
RAW or XML.REMOVE_NO_DATA mode. For all other persistent queues, the notification contains only the message properties; clients explicitly dequeue to receive the message.
OCI_ATTR_SUBSCR_PORTNO to designate the port at which notifications are delivered. This is especially useful for clients on a computer behind a firewall. The port for the listener thread can be designated before the first registration, using an attribute in the environment handle. The thread is started the first time an OCISubscriptionRegister is called. If the client attempts to start another thread on a different port using a different environment handle, then Oracle Streams Advanced Queuing returns an error.
OCI_ATTR_SUBSCR_IPADDR to designate the IP address at which notifications are delivered. This is especially useful for clients on a computer that has multiple network interface cards or IP addresses. The IP address for the listener thread can be designated before the first registration using an attribute in the environment handle. The thread is started the first time an OCISubscriptionRegister is called. If the client attempts to start another thread on a different IP address using a different environment handle, Oracle Streams AQ returns an error. If no IP address is specified, Oracle Streams AQ will deliver notifications on all IP addresses of the computer the client is on.
Views on Registration
DBA_SUBSCR_REGISTRATIONS and USER_SUBSCR_REGISTRATIONS display the various registrations in the system. The diagnostic view GV$SUBSCR_REGISTRATION_STATS may be used to monitor notification statistics and performance.
Event-Based Notification
EMNC) and subordinate processes (EXXX). The event notification load is distributed amongst these processes. These processes work on the system notifications in parallel, offering a capability to process a larger volume of notifications, a faster response time and lower shared memory use for staging notifications.
Notification Grouping by Time
START_TIME, REPEAT_COUNT, GROUPING CLASS, GROUPING VALUE, GROUPING TYPE in the AQ$_REGISTRATION_INFO and the OCI subscription Handle.
Enqueue Features
Dequeue Features
RAW datatype). Only one message with a given message identifier can be present in the queue.WHERE clause of a SQL query. Messages in the queue are evaluated against the condition, and messages that satisfy the given condition are returned. When a dequeue condition is used, the order of the messages dequeued is indeterminate, and the sort order of the queue is not honored.
NEXT_MESSAGE navigation option and a nonzero wait time, then you can end up dequeuing the same message over and over again. Oracle recommends that you use a nonzero wait time for the first dequeue call on a queue in a session, and then use a zero wait time with the NEXT_MESSAGE navigation option for subsequent dequeue calls. If a dequeue call gets an "end of queue" error message, then the dequeue position can be explicitly set by the dequeue call to the beginning of the queue using the FIRST_MESSAGE navigation option, following which the messages in the queue can be browsed again.ENQ_TIME, PRIORITY, or a combination of these two, then results may not be repeatable from one browse to the next. If you must have consistent browse results, then you should use a commit-time queue.
REMOVE_NODATA mode, the payload of the message is not retrieved. This mode can be useful when the user has already examined the message payload, possibly by means of a previous BROWSE dequeue.READY state.PROCESSED only when all intended consumers have successfully dequeued the message. A message is considered EXPIRED if one or more consumers did not dequeue the message before the EXPIRATION time. When a message has expired, it is moved to an exception queue.REMOVE mode exactly once by specifying a NULL consumer name in the dequeue options.
compatible parameter set to 8.0, then expired messages can be dequeued only by specifying a message identifier.
compatible set to 8.0 (referred to in this guide as 8.0-style queues) are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Oracle recommends that any new queues you create be 8.1-style or newer and that you migrate existing 8.0-style queues at your earliest convenience.FIRST_MESSAGE navigation option. Alternatively, once you have selected a message and established its position in the queue, you can then retrieve the next message with the NEXT_MESSAGE navigation option.FIRST_MESSAGE navigation option performs a SELECT on the queue. The NEXT_MESSAGE navigation option fetches from the results of the SELECT run in the FIRST_MESSAGE navigation. Thus performance is optimized because subsequent dequeues need not run the entire SELECT again.FIRST_MESSAGE is requested, then the dequeue position is still reset to the beginning of the queue. But if NEXT_MESSAGE is requested, then the position is set to the next message in the same transaction. Transactional grouping also offers a NEXT_TRANSACTION option. It sets the dequeue position to the first message of the next transaction.NEXT_MESSAGE or NEXT_TRANSACTION option, and you have specified a nonzero wait time, then the navigating position is automatically changed to the beginning of the queue. If a zero wait time is specified, then you can get an exception when the end of the queue is reached.DEQUEUE operation to wait for the arrival of a message in a single queue or the LISTEN operation to wait for the arrival of a message in more than one queue.
EXPIRED messages.DEQUEUE call returns, it returns the message properties and the message payload. When the blocking LISTEN call returns, it discloses only the name of the queue where a message has arrived. A subsequent DEQUEUE operation is needed to dequeue the message.LISTEN returns with the first agent for whom there is a message. To prevent one agent from starving other agents for messages, the application can change the order of the agents in the agent list.
READY after its DELAY time.DELAY or is awakened by the queue monitor process when the DELAY or EXPIRATION time has passed. If an application is waiting for the arrival of a message in a remote queue, then the Oracle Streams Advanced Queuing propagator wakes up the blocked dequeuer after a message has been propagated.RETRY_COUNT column of the queue table view to find out the number of unsuccessful attempts on a message. In addition, Oracle Streams Advanced Queuing allows the application to specify, at the queue level, the maximum number of retries for messages in the queue. The default value for maximum retries is 5. If the number of failed attempts to remove a message exceeds this number, then the message is moved to the exception queue and is no longer available to applications.
ALTER SYSTEM KILL SESSION) or SHUTDOWN ABORT on the instance, then RETRY_COUNT is not incremented.RETRY_COUNT information might not always be updated correctly. If session one dequeues a message and rolls back the transaction, then Oracle Streams AQ notes that the RETRY_COUNT information for this message must be updated. However RETRY_COUNT cannot be incremented until session one completes the rollback. If session two attempts to dequeue the same message after session one has completed the rollback but before it has incremented RETRY_COUNT, then the dequeue by session two succeeds. When session one attempts to increment RETRY_COUNT, it finds that the message is locked by session two and RETRY_COUNT is not incremented. A trace file is then generated in the USER_DUMP_DESTINATION for the instance with the following message:
Error on rollback: ORA-25263: no message in queue schema.qname with message ID ...
compatible set to 8.0 (referred to in this guide as 8.0-style queues) are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Oracle recommends that any new queues you create be 8.1-style or newer and that you migrate existing 8.0-style queues at your earliest convenience.
compatible set to 8.0 (referred to in this guide as 8.0-style queues) are deprecated in Oracle Streams Advanced Queuing 10g Release 2 (10.2). Oracle recommends that any new queues you create be 8.1-style or newer and that you migrate existing 8.0-style queues at your earliest convenience.
ALTER SYSTEM KILL SESSION) or SHUTDOWN ABORT on the instance, then RETRY_COUNT is not incremented.
Propagation Features
JOB_QUEUE_PROCESS will run the job. Propagation scheduling may be a dedicated process, running continuously and without end, or it may be event driven, in which case it runs only if there is a message to be propagated.[schema].queue_name. If the schema is not specified, then the schema of the current user is used.NULL or 0. These addresses are of the form [schema].queue_name@dblink. If the schema is not specified, then the schema of the current user is used. If the database link does not have a domain name specified, then the default domain as specified by the DB_DOMAIN init.ora parameter is used.
Description of "Figure 1-9 Message Propagation in Oracle Streams Advanced Queuing"
NEXT_TIME function that defines the periodic interval between successive windows.RAW queuesRAW queues the message payload is stored as a BLOB. This allows users to store up to 32KB of data when using the PL/SQL interface and as much data as can be contiguously allocated by the client when using OCI. This method is supported by all releases after 8.0.4 inclusive.LOB and read from the LOB using Oracle Database LOB handling routines. The LOB attributes can be BLOBs or CLOBs (not NCLOBs). If the attribute is a CLOB, then Oracle Streams Advanced Queuing automatically performs any necessary character set conversion between the source queue and the destination queue. This method is supported by all releases from 8.1.3 inclusive.
Select, Insert and Update privileges on the queue table for doing enqueues and dequeues.DBA_QUEUE_SCHEDULES view for each propagation schedule. This information can be used by queue designers and administrators to fix problems or tune performance. Similarly, errors reported by the view can be used to diagnose and fix problems. The view also describes additional information such as the session ID of the session handling the propagation and the process name of the job queue process handling the propagation.
next_time parameter of DBMS_AQADM.SCHEDULE_PROPAGATION results in a short interval between windows, then the number of unsuccessful retry attempts can quickly reach 16, disabling the schedule.UNDELIVERABLE and logs a message in alert.log. Examples of such errors are when the remote queue does not exist or when there is a type mismatch between the source queue and the remote queue. The trace files in the background_dump_dest directory can provide additional information about the error.DBMS_AQADM.VERIFY_QUEUE_TYPES.
DBA_SCHEDULES view to determine the last error that occurred during propagation to a particular destination. The message is not marked as UNDELIVERABLE.
AQ$_Pprotocol_number. For example, the consumer name AQ$_P128 can be used to dequeue messages for recipients with protocol number 128. The list of recipients for a message with the specific protocol number is returned in the recipient_list message property on dequeue.
Message Format Transformation
Description of "Figure 1-10 Transformations in Application Integration"
extract() method supported on XMLType to return an object of XMLType after applying the supplied XPath expression. You can also create a PL/SQL function that transforms the XMLType object by applying an XSLT transformation to it, using the package XSLPROCESSOR.
Other Oracle Streams Advanced Queuing Features
QMNn), a background process controlled by setting the dynamic init.ora parameter AQ_TM_PROCESSES. Beginning with 10g Release 1 (10.1), time management and many other background processes are automatically controlled by a coordinator-slave architecture called Queue Monitor Coordinator (QMNC). QMNC dynamically spawns slaves named qXXX depending on the system load. The slaves provide mechanisms for:AQ_TM_PROCESSES.init.ora parameter AQ_TM_PROCESSES, it is still supported. If you do set it (up to a maximum of 40), then QMNC still autotunes the number of processes. But you are guaranteed at least the set number of processes for persistent queues. Processes for a buffered queue and other Oracle Streams tasks, however, are not affected by this parameter.
AQ_TM_PROCESSES = 0 in your pfile or spfile. Oracle strongly recommends that you do NOT set AQ_TM_PROCESSES = 0. If you are using Oracle Streams, setting this parameter to zero (which Oracle Database respects no matter what) can cause serious problems.ORIGINAL_MSGID field in the destination queue of the propagation corresponds to the message ID of the source message. This field can be used to correlate the propagated messages. This is useful for non-repudiation of the dequeuer of propagated messages.
Description of "Figure 1-11 Architecture for Performing Oracle Streams Advanced Queuing Operations Using HTTP"
Interfaces to Oracle Streams Advanced Queuing
DBMS_AQ, DBMS_AQADM, and DBMS_AQELMoracle.jms Java package
oracle.AQ Java package was deprecated in Oracle Streams Advanced Queuing 10g Release 1 (10.1). Oracle recommends that you migrate existing Java AQ applications to Oracle JMS and use Oracle JMS to design your future Java AQ applications.
Oracle Streams Advanced Queuing Demonstrations
$ORACLE_HOME/rdbms/demo directory. Refer to aqxmlREADME.txt and aqjmsREADME.txt in the demo directory for more information.
Demo and Locations Topic
aqdemo00.sql
aqdemo01.sql
aqdemo03.sql
aqdemo06.sql
aqdemo00.sql to aqdemo05.sql
aqdemo07.sql
aqdemo09.sql
aqdemo12.sql
ociaqdemo00.c
ociaqdemo01.c
ociaqdemo02.c
ociaqarrayenq.c
ociaqarraydeq.c
Demo and Locations Topic
aqjmsREADME.txt
aqjmsdmo.sql
aqjmsdemo01.java
aqjmsdemo02.java
aqjmsdemo03.java
aqjmsdemo04.java
aqjmsdemo05.java
aqjmsdemo06.java
aqjmsdemo07.java
aqjmsdemo08.java
aqjmsdemo09.java
aqjmsdemo10.java
aqjmsdrp.sql
aqoradmo.sql
aqorademo01.java
aqorademo02.java
aqoradrp.sql
aqjmskprb01.java
aqjmskprb01a.sql
aqjmskprb01b.sql
aqjmskprb01.java as stored procedure
aqjmskprb01c.sql
aqjmskprb01.java as stored procedure
aqjmskprb01d.sql
Demo and Locations Topic
aqxmlREADME.txt
aqxmldmo.sql
aqxml01.xml
aqxml02.xml
aqxml03.xml
aqxml04.xml
aqxml05.xml
aqxml06.xml
aqxml07.xml
aqxml08.xml
aqxml09.xml
aqxml10.xml
aqxmlhtp.sql
AQDemoServlet.java
AQPropServlet.java
aqxmldrp.sql
PK][ Q PK -A OEBPS/dcommon/prodbig.gif GIF87a !!!)))111BBBZZZsss{{ZRRcZZ!!1!91)JB9B9)kkcJJB991ssc絽Zcc!! {祽BZc!9B!c{ !)c{9{Z{{cZB1)s Jk {{Z{kBsZJ91)Z{!{ BcsRsBc{ 9Z Zk甽k Bk R!BZ 9c )JJc{!))BZks{BcR{JsBk9k)Zck ! !B Z1k!ZcRBZc ZJkBk1Z9c!R!c9kZRZR B Z9{ 9 9 !R 1{ 99R{ 1!1)c 1 J)1B ! B J Rkk{ƽ絵ތkk絵RRs{{{{JJsssBBkkk!!9ss{{ZZssccJJZZRRccRRZZ))cBBJJ99JJ!!c11991199Z11!c!!))Z!! ! 1 B R c k { )!cJBkZRZ , HP)XRÇEZ֬4jJ0 @ "8p YҴESY3CƊ @* U:lY0_0#
5tX1E: C_xޘeK T4 Managing Oracle Streams Advanced Queuing
Oracle Streams Advanced Queuing Compatibility Parameters
compatible parameter of init.ora and the compatible parameter of the queue table should be set to 8.1 or higher to use the following features:
abc.efg means the schema is ABC and the name is EFG, but "abc"."efg" means the schema is abc and the name is efg.
Queue Security and Access Control
Oracle Streams Advanced Queuing SecurityDBMS_AQADM package. Initially, only SYS and SYSTEM have execution privilege for the procedures in DBMS_AQADM and DBMS_AQ. Users who have been granted EXECUTE rights to these two packages are able to create, manage, and use queues in their own schemas. The MANAGE_ANY AQ system privilege is used to create and manage queues in other schemas.
EXECUTE privileges on DBMS_AQJMS and DBMS_AQIN.
Administrator Role
AQ_ADMINISTRATOR_ROLE has all the required privileges to administer queues. The privileges granted to the role let the grantee:DBMS_TRANSFORMDBMS_AQELMDBMS_AQJMS
User Role
AQ_USER_ROLE, because this role does not provide sufficient privileges for enqueuing or dequeuing.ENQUEUE_ANY and DEQUEUE_ANY, exercising DBMS_AQADM.GRANT_SYSTEM_PRIVILEGE and DBMS_AQADM.REVOKE_SYSTEM_PRIVILEGE directly to a database user, if you want the user to have this level of control.DBMS_AQADM.GRANT_QUEUE_PRIVILEGE and DBMS_AQADM.REVOKE_QUEUE_PRIVILEGE.EXECUTE right on DBMS_AQ.
Queue Security
compatible parameter in DBMS_AQADM.CREATE_QUEUE_TABLE is that of the compatible parameter.EXECUTE rights on DBMS_AQ and either enqueue or dequeue privileges on target queues, or ENQUEUE_ANY/DEQUEUE_ANY system privileges.
Queue Privileges and Access Control
Operation(s) Privileges Required
CREATE/DROP/MONITOR own queues
EXECUTE rights on DBMS_AQADM. No other privileges needed.
CREATE/DROP/MONITOR any queues
EXECUTE rights on DBMS_AQADM and be granted AQ_ADMINISTRATOR_ROLE by another user who has been granted this role (SYS and SYSTEM are the first granters of AQ_ADMINISTRATOR_ROLE)
ENQUEUE/ DEQUEUE to own queues
EXECUTE rights on DBMS_AQ. No other privileges needed.
ENQUEUE/ DEQUEUE to another's queues
EXECUTE rights on DBMS_AQ and be granted privileges by the owner using DBMS_AQADM.GRANT_QUEUE_PRIVILEGE.
ENQUEUE/ DEQUEUE to any queues
EXECUTE rights on DBMS_AQ and be granted ENQUEUE ANY QUEUE or DEQUEUE ANY QUEUE system privileges by an Oracle Streams Advanced Queuing administrator using DBMS_AQADM.GRANT_SYSTEM_PRIVILEGE.
OCI Applications and Queue Access
ENQUEUE ANY QUEUE or DEQUEUE ANY QUEUE system privileges. The EXECUTE right of DBMS_AQ is not checked against the session user's rights.
Security Required for Propagation
ENQUEUE ANY QUEUE privilege or be granted the right to enqueue to the destination queue. However, if the login user in the database link also owns the queue tables at the destination, then no explicit Oracle Streams Advanced Queuing privileges must be granted.
Queue Table Export-Import
Exporting Queue Table Data
FROMUSER TOUSER clause is not supported.AQ$_queue_table_I (the dequeue IOT)AQ$_queue_table_T (the time-management IOT)AQ$_queue_table_S (the subscriber table)AQ$_queue_table_H (the history IOT)
Importing Queue Table Data
IGNORE parameter of the import utility must always be set to NO when importing queue tables. If the IGNORE parameter is set to YES, and the queue table that already exists is compatible with the table definition in the dump file, then the rows are loaded from the dump file into the existing table. At the same time, the old queue table definition is lost and re-created. Queue table definition prior to the import is lost and duplicate rows appear in the queue table.
Data Pump Export and Import
Oracle Enterprise Manager Support
Using Oracle Streams Advanced Queuing with XA
Objects=T" in the xa_open string if you want to use the Oracle Streams Advanced Queuing OCI interface. This forces XA to initialize the client-side cache in Objects mode. You are not required to do this if you plan to use Oracle Streams Advanced Queuing through PL/SQL wrappers from OCI or Pro*C.FIRST_MESSAGE option if you want to continue dequeuing between services (such as xa_start and xa_end boundaries). This is because XA cancels the cursor fetch state after an xa_end. If you do not reset, then you get an error message stating that the navigation is used out of sequence (ORA-25237).
Restrictions on Queue Management
abc.efg means the schema is ABC and the name is EFG, but "abc"."efg" means the schema is abc and the name is efg.
Subscribers
DML Not Supported on Queue Tables or Associated IOTs
Propagation from Object Queues with REF Payload Attributes
Collection Types in Message Payloads
Synonyms on Queue Tables and Queues
Synonyms on Object Types
DBMS_AQADM.CREATE_QUEUE_TABLE. Error ORA-24015 results.
Tablespace Point-in-Time Recovery
Virtual Private Database
deq_cond) or the correlation identifier for the policy to be applied. You can use "1=1" as the dequeue condition. If you do not use a dequeue condition or correlation ID, then the dequeue results in an error.
Managing Propagation
aq$_prop_notify_X should never be stopped or dropped and the table aq$_prop_table_X should never be dropped.
EXECUTE Privileges Required for Propagation
SYS, but the propagation occurs in the security context of the queue table owner. Previously propagation jobs were owned by the user scheduling propagation, and propagation occurred in the security context of the user setting up the propagation schedule. The queue table owner must be granted EXECUTE privileges on the DBMS_AQADM package. Otherwise, the Oracle Database snapshot processes do not propagate and generate trace files with the error identifier SYS.DBMS_AQADM not defined. Private database links owned by the queue table owner can be used for propagation. The username specified in the connection string must have EXECUTE access on the DBMS_AQ and DBMS_AQADM packages on the remote database.
Propagation from Object Queues
BFILE objects is supported. To be able to propagate object queues with BFILE objects, the source queue owner must have read privileges on the directory object corresponding to the directory in which the BFILE is stored. The database link user must have write privileges on the directory object corresponding to the directory of the BFILE at the destination database.BFILE objects from object queues without specifying a database link is not supported.
Optimizing Propagation
In setting the number of JOB_QUEUE_PROCESSES, DBAs should be aware that this number is determined by the number of queues from which the messages must be propagated and the number of destinations (rather than queues) to which messages must be propagated.
Handling Failures in Propagation
DBA_QUEUE_SCHEDULES view.g C)rr9+c:b Жf*s^ fKS7^}
*{zq_@8# p F~
[VPe(nw0MW=3#kȵ z晨cy PpG#W:% drMh] 3HH<\]ԁ |_ W
HHҡb}P >k {ZErxMX@8C&qs kLۙOnO^sCk7ql2XCw5VG.S~ H 8=(s 1~ cV5z
%v|U2QF=NoW]ո?<`~}=ӬfԵ,=; "~Iy7K#g{ñJ?5$y`
zz @-~ m7 mG宝Gٱ>G&K#]y1$$t>wqjstX.b̐{Wej)Dxfc:8)=$y|L`xV8ߙ~E)HkwW$J0uʟk>6S gp~;4W+חc"=|ř9bc5 > *r g {~cj1rnI#G|8v4wĿhFb><^ pJLm[Dl1;Vx5IZ: 1* p)إ1Z bAK(1ׅ|S& 5{^
KG ^ 5r>;X K^?
s fk^8O/"J)3K]N)iLYsm7/T H#eݲg ë"m.1Rkx'+yc P
