Skip Headers

Oracle® Streams Advanced Queuing User's Guide and Reference
Release 10.1

Part Number B10785-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

12 Oracle Streams AQ JMS Interface: Basic Operations

This chapter describes the basic operational Java Message Service (JMS) administrative interface to Oracle Streams Advanced Queuing (AQ).

This chapter contains these topics:

EXECUTE Privilege on DBMS_AQIN

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; 

Registering a Queue/Topic Connection Factory

You can register a queue/topic connection factory four ways:

Registering Through the Database Using JDBC Connection Parameters


Purpose

Registers a queue/topic connection factory through the database with JDBC connection parameters to a Lightweight Directory Access Protocol (LDAP) server.


Syntax
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

Parameters
connection

JDBC connection used in registration.

conn_name

Name of the connection to be registered.

hostname

Name of the host running Oracle Streams AQ.

oracle_sid

Oracle system identifier.

portno

Port number.

driver

Type of JDBC driver.

type

QUEUE or TOPIC.


Usage Notes

registerConnectionFactory is a static method. To successfully register the connection factory, the database connection passed to registerConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE. After registration, look up the connection factory using Java Naming and Directory Interface (JNDI).


Example
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");

Registering Through the Database Using a JDBC URL


Purpose

Registers a queue/topic connection factory through the database with a JDBC URL to LDAP.


Syntax
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

Parameters
connection

JDBC connection used in registration.

conn_name

Name of the connection to be registered.

jdbc_url

URL to connect to.

info

Properties information.

type

QUEUE or TOPIC.


Usage Notes

registerConnectionFactory is a static method. To successfully register the connection factory, the database connection passed to registerConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE. After registration, look up the connection factory using JNDI.


Example
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, 
                                       "topic_conn1", 
                                       url,
                                       null, 
                                       "topic");

Registering Through LDAP Using JDBC Connection Parameters


Purpose

Registers a queue/topic connection factory through LDAP with JDBC connection parameters to LDAP.


Syntax
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

Parameters
env

Environment of LDAP connection.

conn_name

Name of the connection to be registered.

hostname

Name of the host running Oracle Streams AQ.

oracle_sid

Oracle system identifier.

portno

Port number.

driver

Type of JDBC driver.

type

QUEUE or TOPIC.


Usage Notes

registerConnectionFactory is a static method. To successfully register the connection factory, 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
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");

Registering Through LDAP Using a JDBC URL


Purpose

Registers a queue/topic connection factory through LDAP with JDBC connection parameters to LDAP.


Syntax
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

Parameters
env

Environment of LDAP connection.

conn_name

Name of the connection to be registered.

jdbc_url

URL to connect to.

info

Properties information.

type

QUEUE or TOPIC.


Usage Notes

registerConnectionFactory is a static method. To successfully register the connection factory, 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
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");

Unregistering a Queue/Topic Connection Factory

You can unregister a queue/topic connection factory in LDAP two ways:

Unregistering Through the Database


Purpose

Unregisters a queue/topic connection factory in LDAP.


Syntax
public static int unregisterConnectionFactory(java.sql.Connection connection,
                                              java.lang.String conn_name)
                                       throws JMSException

Parameters
connection

JDBC connection used in registration.

conn_name

Name of the connection to be unregistered.


Usage Notes

unregisterConnectionFactory is a static method. To successfully unregister the connection factory, the database connection passed to unregisterConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE.


Example
String               url;
java.sql.connection  db_conn;

url = "jdbc:oracle:thin:@sun-123:1521:db1";
db_conn = DriverManager.getConnection(url, "scott", "tiger");
AQjmsFactory.unregisterConnectionFactory(db_conn, "topic_conn1");

Unregistering Through LDAP


Purpose

Unregisters a queue/topic connection factory in LDAP.


Syntax
public static int unregisterConnectionFactory(java.util.Hashtable env,
                                              java.lang.String conn_name)
                                       throws JMSException

Parameters
env

Environment of LDAP connection.

conn_name

Name of the connection to be unregistered.


Usage Notes

unregisterConnectionFactory is a static method. To successfully unregister the connection factory, 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
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");

Getting a Queue/Topic Connection Factory

This section contains these topics:

Getting a Queue Connection Factory with JDBC URL


Purpose

Gets a queue connection factory with JDBC URL.


Syntax
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
              java.lang.String jdbc_url,
              java.util.Properties info)
       throws JMSException

Parameters
jdbc_url

URL to connect to.

info

Properties information.


Usage Notes

getQueueConnectionFactory is a static method.


Example
String      url          = "jdbc:oracle:oci10:internal/oracle"
 Properties  info         = new Properties();
 QueueConnectionFactory   qc_fact;

 info.put("internal_logon", "sysdba");
 qc_fact = AQjmsFactory.getQueueConnectionFactory(url, info);

Getting a Queue Connection Factory with JDBC Connection Parameters


Purpose

Gets a queue connection factory with JDBC connection parameters.


Syntax
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
              java.lang.String hostname,
              java.lang.String oracle_sid,
              int portno,
              java.lang.String driver)
       throws JMSException

Parameters
hostname

Name of the host running Oracle Streams AQ.

oracle_sid

Oracle system identifier.

portno

Port number.

driver

Type of JDBC driver.


Usage Notes

getQueueConnectionFactory is a static method.


Example
String      host         = "dlsun";
 String      ora_sid      = "rdbms10i"
 String      driver       = "thin";
 int         port         = 5521;
 QueueConnectionFactory   qc_fact;

 qc_fact = AQjmsFactory.getQueueConnectionFactory(host, ora_sid, port, driver);

Getting a Topic Connection Factory with JDBC URL


Purpose

Gets a topic connection factory with a JDBC URL.


Syntax
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
              java.lang.String jdbc_url,
              java.util.Properties info)
       throws JMSException

Parameters
jdbc_url

URL to connect to.

info

Properties information.


Usage Notes

getTopicConnectionFactory is a static method.


Example
String      url          = "jdbc:oracle:oci10:internal/oracle"
 Properties  info         = new Properties();
 TopicConnectionFactory   tc_fact;

 info.put("internal_logon", "sysdba");
 tc_fact = AQjmsFactory.getTopicConnectionFactory(url, info);

Getting a Topic Connection Factory with JDBC Connection Parameters


Purpose

Gets a topic connection factory with JDBC connection parameters.


Syntax
public static javax.jms.TopicConnectionFactory getTopicConnectionFactory(
              java.lang.String hostname,
              java.lang.String oracle_sid,
              int portno,
              java.lang.String driver)
       throws JMSException

Parameters
hostname

Name of the host running Oracle Streams AQ.

oracle_sid

Oracle system identifier.

portno

Port number.

driver

Type of JDBC driver.


Usage Note

getTopicConnectionFactory is a Static Method.


Example
String      host         = "dlsun";
String      ora_sid      = "rdbms10i"
String      driver       = "thin";
int         port         = 5521;
TopicConnectionFactory   tc_fact;

tc_fact = AQjmsFactory.getTopicConnectionFactory(host, ora_sid, port, driver);

Getting a Queue/Topic Connection Factory in LDAP


Purpose

Gets a queue/topic connection factory from LDAP.


Example
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");

Getting a Queue/Topic in LDAP


Purpose

Gets a queue/topic from LDAP.


Example
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");

Creating a Queue Table


Purpose

Creates a queue table.


Syntax
public oracle.AQ.AQQueueTable createQueueTable(
                 java.lang.String owner,
                 java.lang.String name,
                 oracle.AQ.AQQueueTableProperty property)
          throws JMSException

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


Usage Notes

CLOB, BLOB, and BFILE objects are valid attributes for an Oracle Streams AQ object type load. However, only CLOB and BLOB can be propagated using Oracle Streams AQ propagation in Oracle8i and after.


Example
QueueSession              q_sess    = null;
AQQueueTable              q_table   = null;
AQQueueTableProperty      qt_prop   = null;

qt_prop = new AQQueueTableProperty("SYS.AQ$_JMS_BYTES_MESSAGE");
  q_table = ((AQjmsSession)q_sess).createQueueTable("boluser",
                                                    "bol_ship_queue_table", 
                                                     qt_prop);

Getting a Queue Table


Purpose

Gets a queue table.


Syntax
public oracle.AQ.AQQueueTable getQueueTable(java.lang.String owner,
                                            java.lang.String name)
                                     throws JMSException

Parameters
owner

Queue table owner (schema)

name

Queue table name


Usage Notes

If the caller that opened the connection is not the owner of the queue table, then the caller must have Oracle Streams AQ enqueue/dequeue privileges on queues/topics in the queue table. Otherwise the queue-table is not returned.


Example
QueueSession              q_sess;
AQQueueTable              q_table;

 q_table = ((AQjmsSession)q_sess).getQueueTable("boluser",
                                                "bol_ship_queue_table");

Creating a Queue

This section contains these topics:

Creating a Point-to-Point Queue


Purpose

Creates a queue in a specified queue table.


Syntax
public javax.jms.Queue createQueue(
             oracle.AQ.AQQueueTable q_table,
             java.lang.String queue_name,
             oracle.jms.AQjmsDestinationProperty dest_property)
      throws JMSException

Parameters
q_table

Queue table in which the queue is to be created. The queue table must not be multiconsumer enabled.

queue_name

Name of the queue to be created.

dest_property

Queue properties.


Usage Notes

The queue table in which a queue is created must be a single-consumer queue table.


Example
QueueSession             q_sess;
AQQueueTable             q_table;
AqjmsDestinationProperty dest_prop;
Queue                    queue;

queue = ((AQjmsSession)q_sess).createQueue(q_table, "jms_q1", dest_prop);

Creating a Publish/Subscribe Topic


Purpose

Creates a topic in the publish/subscribe model.


Syntax
public javax.jms.Topic createTopic(
             oracle.AQ.AQQueueTable q_table,
             java.lang.String topic_name,
             oracle.jms.AQjmsDestinationProperty dest_property)
      throws JMSException

Parameters
q_table

Queue table in which the queue is to be created. The queue table must be multiconsumer enabled.

queue_name

Name of the queue to be created.

dest_property

Queue properties.


Example
TopicSession             t_sess;
AQQueueTable             q_table;
AqjmsDestinationProperty dest_prop;
Topic                    topic;

topic = ((AQjmsSessa)t_sess).createTopic(q_table, "jms_t1", dest_prop);

Granting and Revoking Privileges

This section contains these topics:

Granting Oracle Streams AQ System Privileges


Purpose

Grants Oracle Streams AQ system privileges to a user/roles.


Syntax
public void grantSystemPrivilege(java.lang.String privilege,
                                 java.lang.String grantee,
                                 boolean admin_option)
                          throws JMSException

Parameters
privilege

ENQUEUE_ANY, DEQUEUE_ANY or MANAGE_ANY.

grantee

Specifies the grantee. The grantee can be a user, role or the PUBLIC role.

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.


Usage Notes

The privileges are ENQUEUE_ANY, DEQUEUE_ANY and MANAGE_ANY. 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.


Example
TopicSession             t_sess;

((AQjmsSession)t_sess).grantSystemPrivilege("ENQUEUE_ANY", "scott", false);

Revoking Oracle Streams AQ System Privileges


Purpose

Revokes Oracle Streams AQ system privileges from user/roles.


Syntax
public void revokeSystemPrivilege(java.lang.String privilege,
                                  java.lang.String grantee)
                           throws JMSException

Parameters
privilege

ENQUEUE_ANY, DEQUEUE_ANY or MANAGE_ANY.

grantee

Specifies the grantee. The grantee can be a user, role or the PUBLIC role.


Usage Notes

The privileges are ENQUEUE_ANY, DEQUEUE_ANY and MANAGE_ANY. 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.


Example
TopicSession             t_sess;

((AQjmsSession)t_sess).revokeSystemPrivilege("ENQUEUE_ANY", "scott");

Granting Publish/Subscribe Topic Privileges


Purpose

Grants a topic privilege in the publish/subscribe model.


Syntax
public void grantTopicPrivilege(javax.jms.Session session,
                                java.lang.String privilege,
                                java.lang.String grantee,
                                boolean grant_option)
                         throws JMSException

Parameters
session

JMS session.

privilege

Privilege being granted. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.

grantee

Database user being granted the privilege.

grant_option

If set to true, then the grantee can grant the privilege to other users.


Usage Notes

Initially only the queue table owner can use this procedure to grant privileges on the topic.


Example
TopicSession             t_sess;
Topic                    topic;

((AQjmsDestination)topic).grantTopicPrivilege(t_sess, 
                                             "ENQUEUE", 
                                             "scott", 
                                              false);

Revoking Publish/Subscribe Topic Privileges


Purpose

Revokes a topic privilege in the publish/subscribe model.


Syntax
public void revokeTopicPrivilege(javax.jms.Session session,
                                 java.lang.String privilege,
                                 java.lang.String grantee)
                          throws JMSException

Parameters
session

JMS session.

privilege

The privilege being revoked. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.

grantee

Database user from whom the privilege is being revoked.


Example
TopicSession             t_sess;
Topic                    topic;

((AQjmsDestination)topic).revokeTopicPrivilege(t_sess, "ENQUEUE", "scott");

Granting Point-to-Point Queue Privileges


Purpose

Grants a queue privilege in the point-to-point model.


Syntax
public void grantQueuePrivilege(javax.jms.Session session,
                                java.lang.String privilege,
                                java.lang.String grantee,
                                boolean grant_option)
                         throws JMSException

Parameters
session

JMS session.

privilege

The privilege being granted. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.

grantee

Database user being granted the privilege.

grant_option

If set to true, then the grantee can grant the privilege to other users.


Usage Notes

Initially only the queue table owner can use this procedure to grant privileges on the queue.


Example
QueueSession             q_sess;
Queue                    queue;

((AQjmsDestination)queue).grantQueuePrivilege(q_sess, 
                                             "ENQUEUE", 
                                             "scott", 
                                              false);

Revoking Point-to-Point Queue Privileges


Purpose

Revokes queue privilege in the point-to-point model.


Syntax
public void revokeQueuePrivilege(javax.jms.Session session,
                                 java.lang.String privilege,
                                 java.lang.String grantee)
                          throws JMSException

Parameters
session

JMS session.

privilege

The privilege being revoked. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.

grantee

Database user from whom the privilege is being revoked.


Usage Notes

To revoke a privilege, the revoker must be the original grantor of the privilege. The privileges propagated through the GRANT option are revoked if the grantors privilege is also revoked.


Example
QueueSession             q_sess;
Queue                    queue;

((AQjmsDestination)queue).revokeQueuePrivilege(q_sess, "ENQUEUE", "scott");

Managing Destinations

This section contains these topics:

Starting a Destination


Purpose

Starts a destination.


Syntax
public void start(javax.jms.Session session,
                  boolean enqueue,
                  boolean dequeue)
           throws JMSException

Parameters
session

JMS session

enqueue

Determines whether enqueue should be enabled or not.

dequeue

Determines whether dequeue should be enabled or not.


Usage Notes

After creating a destination, the administrator must use the start method to enable the destination. If enqueue is set to TRUE, then the destination is enabled for enqueue. If enqueue is set to FALSE, then the destination is disabled for enqueue. Similarly, if dequeue is set to TRUE, then the destination is enabled for dequeue. If dequeue is set to FALSE, then the destination is disabled for dequeue.


Example
TopicSession t_sess;
QueueSession q_sess;
Topic        topic;
Queue        queue;

(AQjmsDestination)topic.start(t_sess, true, true);
(AQjmsDestination)queue.start(q_sess, true, true);

Stopping a Destination


Purpose

Stops a destination.


Syntax
public void stop(javax.jms.Session session,
                 boolean enqueue,
                 boolean dequeue,
                 boolean wait)
          throws JMSException

Parameters
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


Usage Notes

If dequeue is set to TRUE, then the destination is disabled for dequeue. If dequeue is set to FALSE, then the current setting is not altered. Similarly, if enqueue is set to TRUE, then the destination is disabled for enqueue. If enqueue is set to FALSE, then the current setting is not altered.


Example
TopicSession t_sess;
Topic        topic;

((AQjmsDestination)topic).stop(t_sess, true, false);

Altering a Destination


Purpose

Alters a destination.


Syntax
public void alter(javax.jms.Session session,
                  oracle.jms.AQjmsDestinationProperty dest_property)
           throws JMSException

Parameters
session

JMS session.

dest_property

New properties of the queue or topic.


Example
QueueSession q_sess;
Queue        queue;
TopicSession t_sess;
Topic        topic;

AQjmsDestionationProperty dest_prop1, dest_prop2;

((AQjmsDestination)queue).alter(dest_prop1);
((AQjmsDestination)topic).alter(dest_prop2);

Dropping a Destination


Purpose

Drops a destination.


Syntax
public void drop(javax.jms.Session session)
          throws JMSException

Parameters
session

JMS session.


Example
QueueSession q_sess;
Queue        queue;
TopicSession t_sess;
Topic        topic;

((AQjmsDestionation)queue).drop(q_sess);
((AQjmsDestionation)topic).drop(t_sess);

Propagation Schedules

This section contains these topics:

Scheduling a Propagation


Purpose

Schedules a propagation.


Syntax
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

Parameters
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 must be started.

duration

Duration of propagation.

next_time

Next time propagation must be accomplished.

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.


Usage Notes

Messages can be propagated to other topics in the same database by specifying a NULL destination. If the message has multiple recipients at the same destination in either the same or different queues, then the message is propagated to all of them at the same time.


Example
TopicSession t_sess;
Topic        topic;

((AQjmsDestination)topic).schedulePropagation(t_sess, 
                                              null, 
                                              null, 
                                              null, 
                                              null, 
                                              new Double(0));

Enabling a Propagation Schedule


Purpose

Enables a propagation schedule.


Syntax
public void enablePropagationSchedule(javax.jms.Session session,
                                      java.lang.String destination)
                               throws JMSException

Parameters
session

JMS session

destination

Database link of the destination database.


Usage Notes

NULL destination indicates that the propagation is to the local database.


Example
TopicSession             t_sess;
Topic                    topic;

 ((AQjmsDestination)topic).enablePropagationSchedule(t_sess, "dbs1");

Altering a Propagation Schedule


Purpose

Alters a propagation schedule.


Syntax
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

Parameters
session

JMS session

destination

Database link of the destination database.

duration

The new duration.

next_time

The new next time for propagation.

latency

The new latency.


Usage Notes

NULL destination indicates that the propagation is to the local database


Example
TopicSession             t_sess;
Topic                    topic;

 ((AQjmsDestination)topic).alterPropagationSchedule(t_sess, 
                                                    null, 
                                                    30, 
                                                    null, 
                                                    new Double(30));

Disabling a Propagation Schedule


Purpose

Disables a propagation schedule.


Syntax
public void disablePropagationSchedule(javax.jms.Session session,
                                       java.lang.String destination)
                                throws JMSException

Parameters
session

JMS session

destination

Database link of the destination database.


Usage Notes

NULL destination indicates that the propagation is to the local database


Example
TopicSession             t_sess;
Topic                    topic;

 ((AQjmsDestination)topic).disablePropagationSchedule(t_sess, "dbs1");

Unscheduling a Propagation


Purpose

Unschedules a previously scheduled propagation.


Syntax
public void unschedulePropagation(javax.jms.Session session,
                                  java.lang.String destination)
                           throws JMSException

Parameters
session

JMS session

destination

Database link of the destination database.


Example
TopicSession   t_sess;
Topic          topic;

((AQjmsDestination)topic).unschedulePropagation(t_sess, "dbs1");