Oracle JMS Key Concepts 1

Oracle JMS Key Concepts


  • What is JMS

Java Message Service (JMS) is a messaging standard defined by Sun Microsystems, Oracle, IBM, and other vendors. JMS is a set of interfaces and associated semantics that define how a JMS client accesses the facilities of an enterprise messaging product.

  • What is Oracle JMS

Oracle Java Message Service (Oracle JMS) provides a Java API for Oracle Database Advanced Queuing based on the JMS standard. Oracle JMS supports the standard JMS interfaces and has extensions to support administrative operations and other features that are not a part of the standard.

  • Publishing/Subscribing Architecture

The set of interfaces defined by JMS allow different architectures to be used in order to establish the communication between applications (PTP, Pub/Sub). The below diagram focus in the Publishing/Subscribing architecture and intends to provide a very high level view of the concepts.

  • Fig. 1 – JMS architecture for Publishing/Subscribing mechanism implies the existence of a JMS provider. In this case Oracle JMS, part of Oracle Database, is the JMS provider.
  • Fig. 2 – Details the basic concept of application clients connecting to the JMS provider in order to publish and consume messages.

Clients connect to the JMS provider by means of ConnectionFactories and Destinations. In Oracle JMS, two approaches can be used:

  • Obtained by using the AQjmsFactory and AQjmsSession classes (Client n+1). These classes are part of the aqapi.jar library.
  • Obtained by accessing the definition of JNDI resources (Client n) from a server in which the administration has created the JNDI bindings. Referencing the aqapi.jar library is still required.


HermesJMS setup – Connecting directly to Oracle AQ JMS

this scenario, a HermesJMS client will connect directly to the Oracle AO JMS.
Internally to HermesJMS, the ConnectionFactory and Destinations will be obtained by using the AQjmsFactory and AqjmsSession objects from aqapi.jar.


  • RIB is installed (meaning the desired Topics and permissions are created in the Oracle AQ JMS Database)
  • Hermes JMS is installed in the OS (Windows/Unix)
  • A good option is to install SoapUI 5.4 which will include HermesJMS as part of its bundle
  • The OS CLASS_PATH points to the intended JRE (e.g.: C:\Program Files\Java\jre1.8.0_131)
  • The following LIBs are available
  • aqapi.jar (must be taken from the AQ Database Server under ORACLE_HOME/rdbms/jlib)
  • ojdbc.7.jar (must be taken from the AQ Database Server under ORACLE_HOME/jdbc/lib)
  • hermes-aq.jar (available in HermesJMS lib folder)

Steps covered in the following paragraphs

  • Create a new session under HermesJMS
  • Find Destinations Automatically
  • Manually Add Destinations (Optional)
  • Browse the Destination and Open/Write a Message
  • What is happening behind


STEP 1 Create a new jms session under HermesJMS

  • Expand the “jms” tree
  • Right click “sessions” and select “New session

  •  In the Preferences window that appears (by default you should be in tab “Sessions”)
  • Under section “Session” provide a meaningful name (e.g. “JMSAQ_Direct”)
  • Under section “Plug In” leave the default value “Default

  • tab “Providers
  • Under “Library” add the following JAR(s) by right clicking and selecting “Add JAR(s)”
  • hermes-ad.jar (when adding this library click “Scan the JAR(s) for JMS Connection Factories in the dialog box that appears”)
  • aqapi.jar and ojdbc7.jar (click Don’t scan)

  • In the Preferences window click and change to tab “Sessions
  • Execute the next steps in the following order:
  • Under section “Connection Factory
  • Select Loader as the name given to the new Group in the tab “ClasspathGroups”. In this example named as “aqjms_libs
  • Select “Class” as “” from the drop down list;
  • Under section “Plug In” select from the list “Oracle AQ

  • In the Preferences window tab “Sessions
  • Under section “Connection Factory” in the Property table add a new property (right click) named url (its the only option available for this Connection Factory class)
  • Fill the details of the url with the AQ JMS Database details using the jdbc driver with the following

pattern: jdbc:oracle:thin:[User/Pass]@[Server]:[Port]/[Service Name]

E.g.: jdbc:oracle:thin:R***Q/D***7@******.com:1***0/s***b


STEP 2 Find Destinations Automatically

  • Having the new JMS Session created in HermesJMS (in this sample named as “JMSAQ_Direct”) its possible to automatically discover the available Queues and Topics
  • Select the JMSAQ_Direct session, right click and choose the Discover… option
  • A new dialog box will appear detailing how many destinations have been found. Add to the current set of destinations (which at the time HermesJMS session was created was empty)


STEP 3 Manually Add Destinations (Optional)

Its possible to add manually JMS Destinations (instead off adding them automatically by using HermesJMS functionality Discover).

  • In jms sessions tree, right click the session “JMSAQ_Direct”. From the menu that appears select New > Add topic.
  • Provide the below information:
  • Name: <name of the Queue or Topic in the AQ JMS Database. E.g.: ETITEMSFROMRMS>
  • Domain: <TOPIC or QUEUE>
  • Durable: <Boolean indicating if the Subscriber created when connecting to the Topic should be Durable>
  • DurableName: <Name used when creating a Durable Subscriber>


STEP 4 Browse the Destination / Open a Message

  • Clicking “Browse…” under Topic “ETUDASFROMRMS” and verifying that a new subscriber has been created. On the left HermesJMS and right the AQ JMS database in SQL Developer where subscribers for the topic are listed.

  • Modifying an UDA description in RMS so a message is published and consumed by the HermesJMS subscriber.
  • Record in RMS before commit the changes (RIB-RMS will pick the change and publish to AQ JMS)
  • HermesJMS after commit the changes.
  • Message is consumed and its content available
  • Sending some content to the AQ JMS.
  • Click “Read file and send as text message”. For the purposes of the test a new HelloHermesJMS.txt file was created. Click Send file


STEP 5 What is happening behind

  • To communicate between applications using JMS, a ConnectionFactory is required.
  • Each JMS provider has its own implementation of the ConnectionFactory which must obey to the JMS ConnectionFactory interface.
  • The ConnectionFactory can be obtained from a JNDI resource (which defines all the details on how to reach the JMS Provider (AQ JMS in this case)) or manually created by using the class AQjmsFactory to create the ConnectionFactory.
  • In this approach particular classes have been developed as part of HermesJMS to obtain the ConnectionFactory based in the Oracle JMS (aqapi) AQjmsFactory. Those are delivered as part of the jar file hermes-aq.jar. The server details are obtained from the parameters defined in the jms session setup.
  • The hermes-aq.jar file is composed of 5 classes
    • AQAdmin
    • AQConnectionFactory (implements ConnectionFactory)
    • AQTopicBrowser
    • HermesShutdownHook
    • OracleAQAdminFactory
  • The AQConnectionFactory basically uses the aqapi.jar and creates a ConnectionFactory based in method getConnectionFactory from the class AQjmsFactory.
  • HermesJMS application will then make use of the OracleAQAdminFactory to create a JMS Session using the ConntectionFactory object (instance of AQjmsConnectionFactory). The session object returned implements TopicSession and QueueSession (JMS API).
  • Once a session is opened HermesJMS allows the user to Subscribe to a particular Topic and start to Consume / Publish messages.

The diagram below demonstrates the architecture.