| Oracle® Streams Advanced Queuing User's Guide and Reference Release 10.1 Part Number B10785-01 |
|
|
View PDF |
| Oracle® Streams Advanced Queuing User's Guide and Reference Release 10.1 Part Number B10785-01 |
|
|
View PDF |
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 queue/topic connection factory four ways:
Registers a queue/topic connection factory through the database with JDBC connection parameters to a Lightweight Directory Access Protocol (LDAP) server.
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
JDBC connection used in registration.
Name of the connection to be registered.
Name of the host running Oracle Streams AQ.
Oracle system identifier.
Port number.
Type of JDBC driver.
QUEUE or TOPIC.
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).
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");
Registers a queue/topic connection factory through the database with a JDBC URL to LDAP.
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
JDBC connection used in registration.
Name of the connection to be registered.
URL to connect to.
Properties information.
QUEUE or TOPIC.
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.
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");
Registers a queue/topic connection factory through LDAP with JDBC connection parameters to LDAP.
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
Environment of LDAP connection.
Name of the connection to be registered.
Name of the host running Oracle Streams AQ.
Oracle system identifier.
Port number.
Type of JDBC driver.
QUEUE or TOPIC.
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.
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");
Registers a queue/topic connection factory through LDAP with JDBC connection parameters to LDAP.
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
Environment of LDAP connection.
Name of the connection to be registered.
URL to connect to.
Properties information.
QUEUE or TOPIC.
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.
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 connection factory in LDAP two ways:
Unregisters a queue/topic connection factory in LDAP.
public static int unregisterConnectionFactory(java.sql.Connection connection,
java.lang.String conn_name)
throws JMSException
JDBC connection used in registration.
Name of the connection to be unregistered.
unregisterConnectionFactory is a static method. To successfully unregister the connection factory, the database connection passed to unregisterConnectionFactory must be granted AQ_ADMINISTRATOR_ROLE.
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");
Unregisters a queue/topic connection factory in LDAP.
public static int unregisterConnectionFactory(java.util.Hashtable env,
java.lang.String conn_name)
throws JMSException
Environment of LDAP connection.
Name of the connection to be unregistered.
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).
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 Queue Connection Factory with JDBC Connection Parameters
Getting a Topic Connection Factory with JDBC Connection Parameters
Gets a queue connection factory with JDBC URL.
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
java.lang.String jdbc_url,
java.util.Properties info)
throws JMSException
URL to connect to.
Properties information.
getQueueConnectionFactory is a static method.
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);
Gets a queue connection factory 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
Name of the host running Oracle Streams AQ.
Oracle system identifier.
Port number.
Type of JDBC driver.
getQueueConnectionFactory is a static method.
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);
Gets a topic connection factory with a JDBC URL.
public static javax.jms.QueueConnectionFactory getQueueConnectionFactory(
java.lang.String jdbc_url,
java.util.Properties info)
throws JMSException
URL to connect to.
Properties information.
getTopicConnectionFactory is a static method.
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);
Gets a topic connection factory 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
Name of the host running Oracle Streams AQ.
Oracle system identifier.
Port number.
Type of JDBC driver.
getTopicConnectionFactory is a Static Method.
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);
Gets a queue/topic connection factory from 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");
Gets a queue/topic from 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");
Creates a queue table.
public oracle.AQ.AQQueueTable createQueueTable(
java.lang.String owner,
java.lang.String name,
oracle.AQ.AQQueueTableProperty property)
throws JMSException
Queue table owner (schema)
Queue table name
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 AQ object type load. However, only CLOB and BLOB can be propagated using Oracle Streams AQ propagation in Oracle8i and after.
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);
Gets a queue table.
public oracle.AQ.AQQueueTable getQueueTable(java.lang.String owner,
java.lang.String name)
throws JMSException
Queue table owner (schema)
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 AQ enqueue/dequeue privileges on queues/topics in the queue table. Otherwise the queue-table is not returned.
QueueSession q_sess;
AQQueueTable q_table;
q_table = ((AQjmsSession)q_sess).getQueueTable("boluser",
"bol_ship_queue_table");
This section contains these topics:
Creates a queue in a specified queue table.
public javax.jms.Queue createQueue(
oracle.AQ.AQQueueTable q_table,
java.lang.String queue_name,
oracle.jms.AQjmsDestinationProperty dest_property)
throws JMSException
Queue table in which the queue is to be created. The queue table must not be multiconsumer enabled.
Name of the queue to be created.
Queue properties.
The queue table in which a queue is created must be a single-consumer queue table.
QueueSession q_sess; AQQueueTable q_table; AqjmsDestinationProperty dest_prop; Queue queue; queue = ((AQjmsSession)q_sess).createQueue(q_table, "jms_q1", dest_prop);
Creates a topic in the publish/subscribe model.
public javax.jms.Topic createTopic(
oracle.AQ.AQQueueTable q_table,
java.lang.String topic_name,
oracle.jms.AQjmsDestinationProperty dest_property)
throws JMSException
Queue table in which the queue is to be created. The queue table must be multiconsumer enabled.
Name of the queue to be created.
Queue properties.
TopicSession t_sess; AQQueueTable q_table; AqjmsDestinationProperty dest_prop; Topic topic; topic = ((AQjmsSessa)t_sess).createTopic(q_table, "jms_t1", dest_prop);
This section contains these topics:
Grants Oracle Streams AQ system privileges to a user/roles.
public void grantSystemPrivilege(java.lang.String privilege,
java.lang.String grantee,
boolean admin_option)
throws JMSException
ENQUEUE_ANY, DEQUEUE_ANY or MANAGE_ANY.
Specifies the grantee. The grantee can be a user, role or the PUBLIC role.
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.
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.
TopicSession t_sess;
((AQjmsSession)t_sess).grantSystemPrivilege("ENQUEUE_ANY", "scott", false);
Revokes Oracle Streams AQ system privileges from user/roles.
public void revokeSystemPrivilege(java.lang.String privilege,
java.lang.String grantee)
throws JMSException
ENQUEUE_ANY, DEQUEUE_ANY or MANAGE_ANY.
Specifies the grantee. The grantee can be a user, role or the PUBLIC role.
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.
TopicSession t_sess;
((AQjmsSession)t_sess).revokeSystemPrivilege("ENQUEUE_ANY", "scott");
Grants a topic privilege in the publish/subscribe model.
public void grantTopicPrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee,
boolean grant_option)
throws JMSException
Privilege being granted. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.
Database user being granted the privilege.
If set to true, then the grantee can grant the privilege to other users.
Initially only the queue table owner can use this procedure to grant privileges on the topic.
TopicSession t_sess;
Topic topic;
((AQjmsDestination)topic).grantTopicPrivilege(t_sess,
"ENQUEUE",
"scott",
false);
Revokes a topic privilege in the publish/subscribe model.
public void revokeTopicPrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee)
throws JMSException
JMS session.
The privilege being revoked. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.
Database user from whom the privilege is being revoked.
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).revokeTopicPrivilege(t_sess, "ENQUEUE", "scott");
Grants a queue privilege in the point-to-point model.
public void grantQueuePrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee,
boolean grant_option)
throws JMSException
JMS session.
The privilege being granted. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.
Database user being granted the privilege.
If set to true, then the grantee can grant the privilege to other users.
Initially only the queue table owner can use this procedure to grant privileges on the queue.
QueueSession q_sess;
Queue queue;
((AQjmsDestination)queue).grantQueuePrivilege(q_sess,
"ENQUEUE",
"scott",
false);
Revokes queue privilege in the point-to-point model.
public void revokeQueuePrivilege(javax.jms.Session session,
java.lang.String privilege,
java.lang.String grantee)
throws JMSException
JMS session.
The privilege being revoked. The options are ENQUEUE, DEQUEUE, or ALL. ALL means both.
Database user from whom the privilege is being revoked.
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.
QueueSession q_sess; Queue queue; ((AQjmsDestination)queue).revokeQueuePrivilege(q_sess, "ENQUEUE", "scott");
This section contains these topics:
Starts a destination.
public void start(javax.jms.Session session,
boolean enqueue,
boolean dequeue)
throws JMSException
JMS session
Determines whether enqueue should be enabled or not.
Determines whether dequeue should be enabled or not.
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.
TopicSession t_sess; QueueSession q_sess; Topic topic; Queue queue; (AQjmsDestination)topic.start(t_sess, true, true); (AQjmsDestination)queue.start(q_sess, true, true);
Stops a destination.
public void stop(javax.jms.Session session,
boolean enqueue,
boolean dequeue,
boolean wait)
throws JMSException
JMS session.
If set to true, then enqueue is disabled.
If set to true, then dequeue is disabled.
If set to true, then pending transactions on the queue/topic are allowed to complete before the destination is stopped
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.
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).stop(t_sess, true, false);
Alters a destination.
public void alter(javax.jms.Session session,
oracle.jms.AQjmsDestinationProperty dest_property)
throws JMSException
JMS session.
New properties of the queue or topic.
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);
Drops a destination.
public void drop(javax.jms.Session session)
throws JMSException
JMS session.
QueueSession q_sess; Queue queue; TopicSession t_sess; Topic topic; ((AQjmsDestionation)queue).drop(q_sess); ((AQjmsDestionation)topic).drop(t_sess);
This section contains these topics:
Schedules 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
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 must be started.
Duration of propagation.
Next time propagation must be accomplished.
Latency in seconds that can be tolerated. Latency is the difference between the time a message was enqueued and the time it was propagated.
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.
TopicSession t_sess;
Topic topic;
((AQjmsDestination)topic).schedulePropagation(t_sess,
null,
null,
null,
null,
new Double(0));
Enables a propagation schedule.
public void enablePropagationSchedule(javax.jms.Session session,
java.lang.String destination)
throws JMSException
JMS session
Database link of the destination database.
NULL destination indicates that the propagation is to the local database.
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).enablePropagationSchedule(t_sess, "dbs1");
Alters 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
JMS session
Database link of the destination database.
The new duration.
The new next time for propagation.
The new latency.
NULL destination indicates that the propagation is to the local database
TopicSession t_sess;
Topic topic;
((AQjmsDestination)topic).alterPropagationSchedule(t_sess,
null,
30,
null,
new Double(30));
Disables a propagation schedule.
public void disablePropagationSchedule(javax.jms.Session session,
java.lang.String destination)
throws JMSException
JMS session
Database link of the destination database.
NULL destination indicates that the propagation is to the local database
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).disablePropagationSchedule(t_sess, "dbs1");
Unschedules a previously scheduled propagation.
public void unschedulePropagation(javax.jms.Session session,
java.lang.String destination)
throws JMSException
JMS session
Database link of the destination database.
TopicSession t_sess; Topic topic; ((AQjmsDestination)topic).unschedulePropagation(t_sess, "dbs1");
|
 Copyright © 1996, 2003 Oracle Corporation All Rights Reserved. |
|