Skip to content

Commit 947dca8

Browse files
anders-swansonanders-swanson
authored
Managing queues (#1006)
Signed-off-by: Anders Swanson <anders.swanson@oracle.com>
1 parent 4d79c02 commit 947dca8

File tree

2 files changed

+149
-1
lines changed

2 files changed

+149
-1
lines changed

‎docs-source/transactional-event-queues/content/getting-started/core-concepts.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,14 @@ weight = 1
66

77
This section provides the basic concepts of Transactional Event Queues, including the difference between queues and topics, how to create queues using SQL, and the available message payload types.
88

9+
* [What are queues and topics?](#what-are-queues-and-topics)
10+
* [Message Payload Types](#message-payload-types)
11+
* [DBMS_AQADM.JMS_TYPE](#dbms_aqadmjms_type)
12+
* [Raw](#raw)
13+
* [JSON](#json)
14+
* [Object](#object)
15+
* [Kafka Message Payloads](#kafka-message-payloads)
16+
917
### What are queues and topics?
1018

1119
Queues and topics both provide high-throughput, asynchronous application communication, but have a few key differences that are relevant for developers and architects.

‎docs-source/transactional-event-queues/content/getting-started/queue-management.md

Lines changed: 141 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,144 @@
22
archetype = "page"
33
title = "Queue Management"
44
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

Comments
 (0)