|
2 | 2 | archetype = "page"
|
3 | 3 | title = "Queue Management"
|
4 | 4 | weight = 2
|
5 |
| -+++ |
| 5 | ++++ |
| 6 | + |
| 7 | +This section covers the management of Transactional Event Queues, including the grants and roles required to use queues, hsteps to create, start, and stop queues across different programming languages and APIs. |
| 8 | + |
| 9 | +* [Database Permissions for Transactional Event Queues](#database-permissions-for-transactional-event-queues) |
| 10 | + * [Permissions for SQL Packages](#permissions-for-sql-packages) |
| 11 | + * [Permissions for Users of Kafka APIs](#permissions-for-users-of-kafka-apis) |
| 12 | +* [Creating, Starting, and Stopping Queues](#creating-starting-and-stopping-queues) |
| 13 | + * [DBMS_AQADM SQL Package](#dbms_aqadm-sql-package) |
| 14 | + * [Kafka APIs](#kafka-apis) |
| 15 | + * [Java with JMS](#java-with-jms) |
| 16 | + * [Python](#python) |
| 17 | + * [.NET](#net) |
| 18 | + * [JavaScript](#javascript) |
| 19 | + * [Oracle REST Data Services](#oracle-rest-data-services) |
| 20 | + |
| 21 | + |
| 22 | + |
| 23 | +### Database Permissions for Transactional Event Queues |
| 24 | + |
| 25 | +#### Permissions for SQL Packages |
| 26 | + |
| 27 | +For management of queues using Transactional Event Queue APIs in SQL or other languages, the following permissions are recommended for users managing queues: |
| 28 | + |
| 29 | +```sql |
| 30 | +grant resource, connect, unlimited tablespace to testuser; |
| 31 | +grant aq_user_role to testuser; |
| 32 | +grant execute on dbms_aq to testuser; |
| 33 | +grant execute on dbms_aqadm to testuser; |
| 34 | +grant execute ON dbms_aqin TO testuser; |
| 35 | +grant execute ON dbms_aqjms TO testuser; |
| 36 | +grant execute on dbms_teqk to testuser; |
| 37 | +``` |
| 38 | + |
| 39 | +#### Permissions for Users of Kafka APIs |
| 40 | + |
| 41 | +If your database user is interacting with Transactional Event Queues via Kafka APIs and the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka), the following permissions are recommended for users managing topics: |
| 42 | + |
| 43 | +```sql |
| 44 | +grant resource, connect, unlimited tablespace to testuser; |
| 45 | +grant aq_user_role to testuser; |
| 46 | +grant execute on dbms_aq to testuser; |
| 47 | +grant execute on dbms_aqadm to testuser; |
| 48 | +grant select on gv_$session to testuser; |
| 49 | +grant select on v_$session to testuser; |
| 50 | +grant select on gv_$instance to testuser; |
| 51 | +grant select on gv_$listener_network to testuser; |
| 52 | +grant select on sys.dba_rsrc_plan_directives to testuser; |
| 53 | +grant select on gv_$pdbs to testuser; |
| 54 | +grant select on user_queue_partition_assignment_table to testuser; |
| 55 | +exec dbms_aqadm.grant_priv_for_rm_plan('testuser'); |
| 56 | +``` |
| 57 | + |
| 58 | +### Creating, Starting, and Stopping Queues |
| 59 | + |
| 60 | +#### DBMS_AQADM SQL Package |
| 61 | + |
| 62 | +The [`DBMS_AQADM` SQL package](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html) provides procedures for the management of Transactional Event Queues. |
| 63 | + |
| 64 | +A queue can be created using the [`DBMS_AQADM.CREATE_TRANSACTIONAL_EVENT_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-6841A667-1021-4E5C-8567-F71913AA4773). Queues must be started with the [`DBMS_AQADM.START_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-EED83332-40B1-4B0A-9E50-AC006A1A0615) before they can be used for enqueue and dequeue. |
| 65 | + |
| 66 | +Below is an example of creating and starting a queue using DBMS_AQADM procedures. |
| 67 | + |
| 68 | +```sql |
| 69 | +begin |
| 70 | + -- create the Transactional Event Queue |
| 71 | + dbms_aqadm.create_transactional_event_queue( |
| 72 | + queue_name => 'my_queue', |
| 73 | + -- when multiple_consumers is true, this will create a pub/sub "topic" - the default is false. |
| 74 | + multiple_consumers => false |
| 75 | + ); |
| 76 | + |
| 77 | + -- start the Transactional Event Queue |
| 78 | + dbms_aqadm.start_queue( |
| 79 | + queue_name => 'my_queue' |
| 80 | + ); |
| 81 | +end; |
| 82 | +/ |
| 83 | +``` |
| 84 | + |
| 85 | +Use the [`DBMS_AQADM.STOP_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-14EADFE9-D7C3-472D-895D-861BB5570EED) to stop a queue. A queue must be stopped before it can be dropped using the [`DBMS_AQADM.DROP_QUEUE` procedure](https://docs.oracle.com/en/database/oracle/oracle-database/23/arpls/DBMS_AQADM.html#GUID-167A1A71-C8CB-48B4-B1B0-C98825BDE25F). |
| 86 | + |
| 87 | +```sql |
| 88 | +begin |
| 89 | + dbms_aqadm.stop_queue( |
| 90 | + queue_name => 'my_queue' |
| 91 | + ); |
| 92 | + dbms_aqadm.drop_queue( |
| 93 | + queue_name => 'my_queue' |
| 94 | + ); |
| 95 | +end; |
| 96 | +/ |
| 97 | +``` |
| 98 | + |
| 99 | +#### Kafka APIs |
| 100 | + |
| 101 | +You can use standard Kafka APIs to create a topic with the [Kafka Java Client for Oracle Database Transactional Event Queues](https://github.com/oracle/okafka). The following code configures connection properties for Oracle Database and creates a topic using the [`org.oracle.okafka.clients.admin.AdminClient` class](https://mvnrepository.com/artifact/com.oracle.database.messaging/okafka), which implements the `org.apache.kafka.clients.admin.Admin` interface. |
| 102 | + |
| 103 | +```java |
| 104 | +// Oracle Database Connection properties |
| 105 | +Properties props = new Properties(); |
| 106 | +// Use your database service name |
| 107 | +props.put("oracle.service.name", "freepdb1"); |
| 108 | +// Choose PLAINTEXT or SSL as appropriate for your database connection |
| 109 | +props.put("security.protocol", "SSL"); |
| 110 | +// Your database server |
| 111 | +props.put("bootstrap.servers", "my-db-server"); |
| 112 | +// Path to directory containing ojdbc.properties |
| 113 | +// If using Oracle Wallet, this directory must contain the unzipped wallet |
| 114 | +props.put("oracle.net.tns_admin", "/my/path/"); |
| 115 | +NewTopic topic = new NewTopic("my_topic", 1, (short) 1); |
| 116 | +try (Admin admin = AdminClient.create(props)) { |
| 117 | + admin.createTopics(Collections.singletonList(topic)) |
| 118 | + .all() |
| 119 | + .get(); |
| 120 | +} catch (ExecutionException | InterruptedException e) { |
| 121 | + // Handle topic creation exception |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +#### Java with JMS |
| 126 | + |
| 127 | +The [`oracle.jms` Java package](https://docs.oracle.com/en/database/oracle/oracle-database/23/jajms/index.html) includes several APIs for managing queues, enqueuing, and dequeuing messages using JMS. The [Oracle Spring Boot Starter for AqJms](https://mvnrepository.com/artifact/com.oracle.database.spring/oracle-spring-boot-starter-aqjms) provides a comprehensive set of dependencies to get started using the Java JMS API with Transactional Event Queues. You may also use the following guide to get started, which implements a simple [producer consumer example using AqJms for Transcational Event Queues](https://medium.com/@anders.swanson.93/use-jms-for-asynchronous-messaging-in-spring-boot-d67f8349c7c4). |
| 128 | + |
| 129 | +#### Python |
| 130 | + |
| 131 | +When using Python, the [`python-oracledb` package](https://python-oracledb.readthedocs.io/en/latest/api_manual/aq.html#aq) is helpful for enqueuing and dequeuing messages. Queue creation and management should be handled by the Python Database Driver or a SQL script run by a database administrator. |
| 132 | + |
| 133 | +#### .NET |
| 134 | + |
| 135 | +Before you can use Transactional Event queues from .NET, you need to create and start queues using the appropriate PL/SQL procedures. The [OracleAQMessage class](https://docs.oracle.com/en/database/oracle/oracle-database/23/odpnt/aq-classes.html#ODPNT-GUID-4DBB419A-BCE1-467C-BA28-3611F3E012CA) can be used to enqueue and dequeue messages from queues. |
| 136 | + |
| 137 | +#### JavaScript |
| 138 | + |
| 139 | +Using the [`node-oracledb` package](https://node-oracledb.readthedocs.io/en/latest/api_manual/aq.html), an AqQueue class can be created from a connection for enqueuing and dequeuing messages. Queue creation and management should be handled by the node-oracledb Database Driver or a SQL script run by a database administrator. |
| 140 | + |
| 141 | +#### Oracle REST Data Services |
| 142 | + |
| 143 | +Oracle REST Data Services (ORDS) is a Java Enterprise Edition (Java EE) based data service that provides enhanced security, file caching features, and RESTful Web Services. Oracle REST Data Services also increases flexibility through support for deployment in standalone mode, as well as using servers like Oracle WebLogic Server and Apache Tomcat. |
| 144 | + |
| 145 | +With ORDS, [REST APIs can be used to manage Transactional Event Queues](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/24.3/orrst/api-oracle-transactional-event-queues.html), including creating queues, producing and consuming messages. |
0 commit comments