12 Oracle Java Message Service Basic Operations
The following topics describe the basic operational Java Message Service (JMS) administrative interface to Oracle Database Advanced Queuing (AQ).
12.1 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; 12.2 Registering a ConnectionFactory
You can register a ConnectionFactory four ways:
12.2.1 Registering Through the Database Using JDBC Connection Parameters
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 |
|---|---|
|
|
JDBC connection used in registration |
|
|
Name of the connection to be registered |
|
|
Name of the host running Oracle Database Advanced Queuing |
|
|
Oracle system identifier |
|
|
Port number |
|
|
JDBC driver type |
|
|
Connection factory type ( |
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");
12.2.2 Registering Through the Database Using a JDBC URL
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 |
|---|---|
|
|
JDBC connection used in registration |
|
|
Name of the connection to be registered |
|
|
URL to connect to |
|
|
Properties information |
|
|
Port number |
|
|
Connection factory type ( |
The database connection passed to registerConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE. After registration, you can look up the connection factory using JNDI.
Example 12-2 Registering Through the Database Using a JDBC URL
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");
12.2.3 Registering Through LDAP Using JDBC Connection Parameters
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 |
|---|---|
|
|
Environment of LDAP connection |
|
|
Name of the connection to be registered |
|
|
Name of the host running Oracle Database Advanced Queuing |
|
|
Oracle system identifier |
|
|
Port number |
|
|
JDBC driver type |
|
|
Connection factory type ( |
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");12.2.4 Registering Through LDAP Using a JDBC URL
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 |
|---|---|
|
|
Environment of LDAP connection |
|
|
Name of the connection to be registered |
|
|
URL to connect to |
|
info |
Properties information |
|
|
Connection factory type ( |
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");12.3 Unregistering a Queue/Topic ConnectionFactory
You can unregister a queue/topic ConnectionFactory in LDAP two ways:
12.3.1 Unregistering Through the Database
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 |
|---|---|
|
|
JDBC connection used in registration |
|
|
Name of the connection to be registered |
The database connection passed to unregisterConnectionFactory() must be granted AQ_ADMINISTRATOR_ROLE.
Example 12-5 Unregistering Through the Database
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");
12.3.2 Unregistering Through LDAP
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 |
|---|---|
|
|
Environment of LDAP connection |
|
|
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");12.4 Getting a QueueConnectionFactory or TopicConnectionFactory
This section contains these topics:
12.4.1 Getting a QueueConnectionFactory with JDBC URL
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 |
|---|---|
|
|
URL to connect to |
|
info |
Properties information |
Example 12-7 Getting a QueueConnectionFactory with JDBC URL
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);12.4.2 Getting a QueueConnectionFactory with JDBC Connection Parameters
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 |
|---|---|
|
|
Name of the host running Oracle Database Advanced Queuing |
|
|
Oracle system identifier |
|
|
Port number |
|
|
JDBC driver type |
Example 12-8 Getting a QueueConnectionFactory with JDBC Connection Parameters
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);
12.4.3 Getting a TopicConnectionFactory with JDBC URL
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
java.lang.String jdbc_url,
java.util.Properties info)
throws JMSException
This method gets a TopicConnectionFactory with a JDBC URL. It is static and has the following parameters:
| Parameter | Description |
|---|---|
|
|
URL to connect to |
|
info |
Properties information |
Example 12-9 Getting a TopicConnectionFactory with JDBC URL
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);12.4.4 Getting a TopicConnectionFactory with JDBC Connection Parameters
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 |
|---|---|
|
|
Name of the host running Oracle Database Advanced Queuing |
|
|
Oracle system identifier |
|
|
Port number |
|
|
JDBC driver type |
Example 12-10 Getting a TopicConnectionFactory with JDBC Connection Parameters
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);
12.4.5 Getting a QueueConnectionFactory or TopicConnectionFactory in LDAP
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");12.5 Getting a Queue or Topic in LDAP
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");12.6 Creating a Non-Sharded Queue Table
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 |
|---|---|
|
|
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 Database Advanced Queuing object type load. However, only CLOB and BLOB can be propagated using Oracle Database Advanced Queuing propagation in Oracle8i and after.
Note:
Currently JMS Sharded Queues can be created and dropped only through the DBMS_AQADM PL/SQL APIs.
Example 12-13 Creating a Queue Table
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);12.7 Creating a Queue
This section contains these topics:
12.7.1 Creating a Point-to-Point Queue
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 |
|---|---|
|
|
Queue table in which the queue is to be created. The queue table must be single-consumer. |
|
|
Name of the queue to be created |
|
|
Queue properties |
This method is specific to Oracle JMS. You cannot use standard Java javax.jms.Session objects with it. Instead, you must cast the standard type to the Oracle JMS concrete class oracle.jms.AQjmsSession.
Example 12-14 Creating a Point-to-Point Queue
QueueSession q_sess; AQQueueTable q_table; AqjmsDestinationProperty dest_prop; Queue queue; queue = ((AQjmsSession)q_sess).createQueue(q_table, "jms_q1", dest_prop);
12.7.2 Creating a Publish/Subscribe Topic
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 |
|---|---|
|
|
Queue table in which the queue is to be created. The queue table must be multiconsumer. |
|
|
Name of the queue to be created |
|
|
Queue properties |
This method is specific to Oracle JMS. You cannot use standard Java javax.jms.Session objects with it. Instead, you must cast the standard type to the Oracle JMS concrete class oracle.jms.AQjmsSession.
In Example 12-16, 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-15 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);
Example 12-16 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;
}12.7.3 Creating a Sharded Queue for Point-to-Point Queue and Publish/Subscribe Topic
AQ JMS has defined a new APIs to create and drop sharded queues. There is no alter queue API in JMS. The signatures are as follows:
/**
* Create a JMS sharded queue. It also internally creates the related queue
* objects (table, indexes) based on this name.
*
* @param queueName name of the queue to be created, format is schema.queueName
* (where the schema. is optional
* @param isMultipleConsumer flag to indicate whether the queue is a
* multi-consumer or single-consumer queue
* @return javax.jms.Destination
* @throws JMSException if the queue could not be created
*/
public synchronized javax.jms.Destination createJMSShardedQueue(String queueName,
boolean isMultipleConsumer) throws JMSException {
return createJMSShardedQueue(queueName, isMultipleConsumer, null, 0, null);
}
/**
* Create a JMS sharded queue. It also internally creates the related queue
* objects (table, indexes) based on this name.
*
* @param queueName name of the queue to be created, format is schema.queueName
* (where the schema. is optional
* @param isMultipleConsumer flag to indicate whether the queue is a
* multi-consumer or single-consumer queue
* @param storageClause additional storage clause
* @param maxRetries retry count before skip the message while dequeue
* @param comment comment for the queue
* @return javax.jms.Destination
* @throws JMSException if the queue could not be created
*/
public Destination createJMSShardedQueue(java.lang.String queueName,
boolean isMultipleConsumer,
java.lang.String storageClause,
int maxRetries,
java.lang.String comment)
throws JMSException12.8 Getting a Non-Sharded Queue Table
public oracle.AQ.AQQueueTable getQueueTable(java.lang.String owner,
java.lang.String name)
throws JMSException
This method gets a queue table for a non-sharded queue. It has the following parameters:
| Parameter | Description |
|---|---|
|
|
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 Database Advanced Queuing enqueue/dequeue privileges on queues/topics in the queue table. Otherwise the queue table is not returned.
Example 12-17 Getting a Queue Table
QueueSession q_sess; AQQueueTable q_table; q_table = ((AQjmsSession)q_sess).getQueueTable( "boluser", "bol_ship_queue_table");
12.9 Granting and Revoking Privileges
This section contains these topics:
12.9.1 Granting Oracle Database Advanced Queuing System Privileges
public void grantSystemPrivilege(java.lang.String privilege,
java.lang.String grantee,
boolean admin_option)
throws JMSException
This method grants Oracle Database Advanced Queuing system privileges to a user or role.
| Parameter | Description |
|---|---|
|
|
|
|
|
Grantee (user, role, or |
|
|
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.
Example 12-18 Granting Oracle Database Advanced Queuing System Privileges
TopicSession t_sess;
((AQjmsSession)t_sess).grantSystemPrivilege("ENQUEUE_ANY", "scott", false);12.9.2 Revoking Oracle Database Advanced Queuing System Privileges
public void revokeSystemPrivilege(java.lang.String privilege,
java.lang.String grantee)
throws JMSException
This method revokes Oracle Database Advanced Queuing system privileges from a user or role. It has the following parameters:
| Parameter | Description |
|---|---|
|
|
|
|
|
Grantee (user, role, or |
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 12-19 Revoking Oracle Database Advanced Queuing System Privileges
TopicSession t_sess;
((AQjmsSession)t_sess).revokeSystemPrivilege("ENQUEUE_ANY", "scott");12.9.3 Granting Publish/Subscribe Topic Privileges
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 |
|---|---|
|
|
|
|
|
|
|
|
Grantee (user, role, or |
|
|
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 |
Example 12-20 Granting Publish/Subscribe Topic Privileges
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).grantTopicPrivilege( t_sess, "ENQUEUE", "scott", false);
12.9.4 Revoking Publish/Subscribe Topic Privileges
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 |
|---|---|
|
|
JMS session |
|
|
|
|
|
Revoked grantee (user, role, or |
Example 12-21 Revoking Publish/Subscribe Topic Privileges
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).revokeTopicPrivilege(t_sess, "ENQUEUE", "scott");
12.9.5 Granting Point-to-Point Queue Privileges
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 |
|---|---|
|
|
JMS session |
|
|
|
|
|
Grantee (user, role, or |
|
|
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 |
Example 12-22 Granting Point-to-Point Queue Privileges
QueueSession q_sess; Queue queue; ((AQjmsDestination)queue).grantQueuePrivilege( q_sess, "ENQUEUE", "scott", false);
12.9.6 Revoking Point-to-Point Queue Privileges
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 |
|---|---|
|
|
JMS session |
|
|
|
|
|
Revoked grantee (user, role, or |
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.
Example 12-23 Revoking Point-to-Point Queue Privileges
QueueSession q_sess; Queue queue; ((AQjmsDestination)queue).revokeQueuePrivilege(q_sess, "ENQUEUE", "scott");
12.10 Managing Destinations
This section contains these topics:
Note:
Currently JMS Sharded Queues can be managed only through the DBMS_AQADM PL/SQL APIs.
12.10.1 Starting a Destination
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 |
|---|---|
|
|
JMS session |
|
|
If set to |
|
dequeue |
If set to |
Example 12-24 Starting a Destination
TopicSession t_sess; QueueSession q_sess; Topic topic; Queue queue; (AQjmsDestination)topic.start(t_sess, true, true); (AQjmsDestination)queue.start(q_sess, true, true);
12.10.2 Stopping a Destination
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 |
|---|---|
|
|
JMS session |
|
|
If set to |
|
dequeue |
If set to |
|
|
If set to true, then pending transactions on the queue/topic are allowed to complete before the destination is stopped |
Example 12-25 Stopping a Destination
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).stop(t_sess, true, false);
12.10.3 Altering a Destination
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 |
|---|---|
|
|
JMS session |
|
dest_property |
New properties of the queue or topic |
Example 12-26 Altering a Destination
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);
12.10.4 Dropping a Destination
public void drop(javax.jms.Session session)
throws JMSException
This method drops a destination. It has the following parameter:
| Parameter | Description |
|---|---|
|
|
JMS session |
Example 12-27 Dropping a Destination
QueueSession q_sess; Queue queue; TopicSession t_sess; Topic topic; ((AQjmsDestionation)queue).drop(q_sess); ((AQjmsDestionation)topic).drop(t_sess);
12.11 Propagation Schedules
This section contains these topics:
Note:
JMS Sharded Queues are currently managed only through the DBMS_AQADM PL/SQL APIs and do not support propagation.
12.11.1 Scheduling a Propagation
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 |
|---|---|
|
|
JMS session |
|
|
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. |
|
|
Time propagation starts |
|
|
Duration of propagation |
|
|
Next time propagation starts |
|
|
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.
Example 12-28 Scheduling a Propagation
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).schedulePropagation( t_sess, null, null, null, null, new Double(0));
12.11.2 Enabling a Propagation Schedule
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 |
|---|---|
|
|
JMS session |
|
|
Database link of the destination database. A null string means that propagation is to the local database. |
Example 12-29 Enabling a Propagation Schedule
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).enablePropagationSchedule(t_sess, "dbs1");
12.11.3 Altering a Propagation Schedule
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 |
|---|---|
|
|
JMS session |
|
|
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 of propagation |
|
|
Next time propagation starts |
|
|
Latency in seconds that can be tolerated. Latency is the difference between the time a message was enqueued and the time it was propagated. |
Example 12-30 Altering a Propagation Schedule
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).alterPropagationSchedule( t_sess, null, 30, null, new Double(30));
12.11.4 Disabling a Propagation Schedule
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 |
|---|---|
|
|
JMS session |
|
|
Database link of the destination database. A null string means that propagation is to the local database. |
Example 12-31 Disabling a Propagation Schedule
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).disablePropagationSchedule(t_sess, "dbs1");
12.11.5 Unscheduling a Propagation
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 |
|---|---|
|
|
JMS session |
|
|
Database link of the destination database. A null string means that propagation is to the local database. |
Example 12-32 Unscheduling a Propagation
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).unschedulePropagation(t_sess, "dbs1");