Helidon Messaging with Oracle AQ
Oracle Advanced Queueing (AQ) is the message queueing service used by the Oracle database. By providing PLSQL and JMS APIs in Advanced Queueing, Helidon is now uniquely positioned to interact with database events and benefit from Oracle database’s durability and high availability.
We are pleased to announce that Helidon 2.2.0, a first class citizen in the Oracle ecosystem, now comes with a specialized connector for reactive messaging.
Setting Up a Local Oracle Database with AQ
A simple script for setting up a local docker container within Oracle 18 XE is available in Helidon messaging examples. To build and run the script, simply execute buildAndRun.sh. Note that the first start of the container may take a few minutes. The database is when “DATABASE IS READY TO USE” appears in the output of command:
docker logs oracle-aq-example There are 5 example AQ queues for you to try:
- example_queue_1, example_queue_2 and example_queue_3 — storing text messages
- example_queue_bytes — storing raw byte messages
- example_queue_map — storing map messages
Along with buildAndRun.sh, you can also find examples.sql with PLSQL examples for enqueueing different types of messages. And, in case you want to create your own queue, take a look in the example database’s init.sql.
AQ Messaging with Helidon MP
To connect with Helidon MP, we are going to need MicroProfile Reactive Messaging implementation, Helidon’s AQ messaging connector, and the Helidon support for Oracle Universal Connection Pool (UCP) data source.
Why Oracle UCP? We need a datasource to connect to the Oracle DB and UCP is a natural fit. Configuration is straightforward. First prepare the UCP datasource, and then reference it from AQ connector configuration with mp.messaging.connector.helidon-aq.data-source config property.
Once the UCP datasource is set up, we can prepare reactive messaging methods. We will prepare one method for publishing messages to an outgoing channel called to-aq every 2 seconds. And a second method for consuming the incoming channel called from-aq.
Both channels are configured for example-queue-1 destination. So we should see our produced messages consumed immediately after a short trip to and from the Oracle database.
As you can see in the example below, messages are coming through just fine.
You can find this working example project here.
Message Acknowledgement
The AQ connector fully integrates with MicroProfile Reactive Messaging Acknowledgement feature.
The Default ack mode is AUTO_ACKNOWLEDGE, which means that every received message is acknowledged immediately upon reception by the connector. But in case there is some catastrophic failure during processing of a message, such as an error between the connector and phase once the message is considered successfully consumed, then the message won’t be resent.
To move the actual acknowledgement control to the business code, just set up acknowledge-mode to CLIENT_ACKNOWLEDGE.
mp:
messaging:
connector:
helidon-aq:
data-source: local-example-ds
acknowledge-mode: CLIENT_ACKNOWLEDGENow we can leave the acknowledgement to messaging itself, as every messaging method has a clearly defined default acknowledgement strategy or call Message.ack() manually.
When we run our purposely flawed microservice now, everything goes well until Message 5 is consumed. Manual acknowledgement is never reached and Message 5 is not acknowledged.
Received: Message 0
Received: Message 1
Received: Message 2
Received: Message 3
Received: Message 4
Received: Message 5
2020.12.17 14:50:19 SEVERE ...
Caused by: java.lang.RuntimeException: 5th message exception!
...When we run our service again, we can see that last unacknowledged message 5, has been resent as expected.
Received: Message 5
Received: Message 0
Received: Message 1
Received: Message 2
...No messages are lost, even if the server with our pod crashes.
AQ Messaging with Helidon SE
As with all the other Helidon connectors, AQ connector also works with Helidon SE reactive messaging API.
All you need is the AQ connector dependency:
<dependency>
<groupId>io.helidon.messaging.aq</groupId>
<artifactId>helidon-messaging-aq</artifactId>
<version>2.2.0</version>
</dependency>And you can use the AQ connector with SE messaging anywhere you want. Just try adding the following snippet directly in the main method:
It’s all there in one snippet, Abracadabra!✨
Connecting to Oracle Database Provisioned in OCI
Let’s start with provisioning Oracle database in OCI. You will need to create a free, eligible OCI account. Once you have logged into your account, use the OCI console to navigate to the hamburger menu and select Autonomous Transaction Processing.
Click Create Autonomous Database.
Specify your compartment, database name and admin password.
The rest of the form should stay as default, most notably allow secure access from everywhere is important for our example.
Confirm the form and wait a few minutes while is the database provisioned. When the database detail shows AVAILABLE, we are ready to proceed.
Click DB Connection.
And then click Download Wallet.
When you are prompted, enter your secret wallet password twice and continue with the download. After Wallet_helidonaq.zip is downloaded, unzip its content to the folder accessible by your app, for example /home/kec/wallets/Wallet_helidonaq.
To prepare the database for AQ click Service Console.
Enter the ADMIN user name and provide the password you used for database creation (not the wallet password).
Click Development>SQL Developer Web.
Again sign in with user ADMIN and password selected during database creation.
When connected as ADMIN to SQL Developer Web console, create a new user called `frank`, who can also connect over SQL Developer Web console with extra AQ privileges.
Now sign out from ADMIN user.
Log back in as user frank. Note that the url to SQL Developer Web differs for every user.
As user frank you can finally create example queues.
While still connected as frank, lets enque some messages over PLSQL now.
While our first AQ message waits in the Autonomous Database’s queue, we can deque it with Helidon’s AQ connector.
Notice in the snippet above that we have finally used our secret wallet password.
As you see, AQ connector opens the door to a very interesting messaging mechanism in Oracle database. One of the extremely beneficial aspects of such integration is the possibility of consuming database events directly — such as messages generated by database triggers and much more.
What’s Next?
Helidon AQ connector supports standard non-LCR JMS types SYS.AQ$_JMS_TEXT_MESSAGE ,SYS.AQ$_JMS_MAP_MESSAGE ,SYS.AQ$_JMS_OBJECT_MESSAGE and SYS.AQ$_JMS_BYTES_MESSAGE. But this is more like ADT user objects and LCR XmlType.
So stay tuned, more exciting stuff will be coming with future versions of Helidon.
Happy messaging!
For more info about Reactive Messaging in Helidon, check out the following resources:
