DBA Tips Archive for Oracle

  


Using Oracle's Advanced Queuing with JMS - (AQ-JMS)

by Jeff Hunter, Sr. Database Administrator


Contents

  1. Overview
  2. Format of the EAR File
  3. Download the EAR File
  4. Pre-requisites
  5. Deployment Process


Overview

This article provides a complete working example of how to use Oracle's Advanced Queuing implementation for JMS (AQ-JMS). We will be creating a J2EE application that utilizes the Servlet, Message Driven Bean, and Java Message Service (JMS) API's. Instructions are provided for how to develop, assemble, configure, and deploy the application to the standalone version of Oracle Containers for J2EE (OC4J).

This example will include an Enterprise Application Archive (EAR) consisting of two modules:

Format of the EAR File

The format of the EAR file is as follows:


OracleJmsApp(.ear) | |- META-INF | | | |- application.xml | |- OracleJmsEJB(.jar) | | | |- META-INF | | | | | |- ejb-jar.xml | | |- orion-ejb-jar.xml | | | |- parallelMDBBean.class | |- OracleJmsWeb(.war) | |-WEB-INF | |- web.xml |- orion-web.xml | |- classes | |- jobSubmit.class |- listDataSet

Download the EAR File

You can download the test Enterprise Archive (EAR) file from the following link: OracleJmsApp.ear

NOTE:

Save the file as OracleJmsApp.ear.

  • Netscape Users: Hold down the SHIFT key while linking on the link.

  • Internet Explorer Users: Right click on the link and in the pop-up menu, select "Save Target As...".
  • Pre-requisites

    To run the example in this article, you will need the following:

    Deployment Process

    Now let's take a look at how to deploy our J2EE application. The configuration changes in this section refer to a standalone OC4J instance. (i.e. one that is not being managed by the Distributed Component Management (DCM) component that comes with the full 9iAS release.)

    If you are using an OC4J instance being managed by the DCM (within the full release of 9iAS), then changes can be applied either:

    1. Configure an Oracle AQ table and queue for our application

      For the purpose of this example, the AQ table will be run by the Oracle user "AQ_ADMIN/AQ_ADMIN" created on a database named "O920NT":


      CONNECT system/manager CREATE USER aq_admin IDENTIFIED BY aq_admin DEFAULT TABLESPACE users TEMPORARY TABLESPACE temp; ALTER USER aq_admin QUOTA UNLIMITED ON users; GRANT aq_administrator_role TO aq_admin; GRANT connect TO aq_admin; GRANT create type TO aq_admin; EXECUTE dbms_aqadm.grant_type_access('aq_admin'); CONNECT aq_admin/aq_admin BEGIN DBMS_AQADM.CREATE_QUEUE_TABLE( queue_table => 'JMS_TEXT' , queue_payload_type => 'SYS.AQ$_JMS_TEXT_MESSAGE' , sort_list => '' , comment => '' , multiple_consumers => FALSE , message_grouping => DBMS_AQADM.NONE , non_repudiation => DBMS_AQADM.NONE , storage_clause => '' , compatible => '8.1' , primary_instance => '0' , secondary_instance => '0' ); COMMIT; END; / SHOW ERRORS BEGIN DBMS_AQADM.CREATE_QUEUE( queue_name => 'JOB_QUEUE' , queue_table => 'JMS_TEXT' , queue_type => DBMS_AQADM.NORMAL_QUEUE , max_retries => '5' , retry_delay => '0' , retention_time => '0' , comment => '' ); COMMIT; END; / SHOW ERRORS BEGIN DBMS_AQADM.START_QUEUE('aq_admin.job_queue', TRUE, TRUE); COMMIT; END; / SHOW ERRORS

      NOTE:

      • A special table named "JMS_TEXT" will be created in the designated schema in order to support the TextMessage type of JMS.
      • A JMS Queue, named "JMS_QUEUE" will then be created using the "JMS_TEXT" table as its queue table.
      • Lastly, the "JMS_QUEUE" queue will be started. (using its full schema.object notation)


    2. Create a Container Wide Datasource Definition

      Now, edit the data-sources.xml file located in $ORACLE_HOME/j2ee//config/data-sources.xml.
      (e.g. $ORACLE_HOME/j2ee/home/config/data-sources.xml)

      Add the following data-source, which should reference the schema containing the Queue defined above:


      <data-source class="com.evermind.sql.DriverManagerDataSource" name="aq_admin_o920nt" location="jdbc/aq_admin_o920nt" xa-location="jdbc/xa/aq_admin_o920nt" ejb-location="jdbc/aq_admin_o920nt" connection-driver="oracle.jdbc.driver.OracleDriver" username="aq_admin" password="aq_admin" url="jdbc:oracle:thin:@bartman:1521:O920NT" inactivity-timeout="30" />

      NOTE:

      • The username, password and JDBC URL must be correctly set to reference the database and schema where the queue was setup.
      • This entry will be mapped within the JNDI namespace at the path provided as the location attribute, which for this example is "aq_admin_o920nt". In this example application, the data source will be used as the target for SQL insert statements issued by the Message Driven Bean (MDB) to add rows to the "dataset" table. It will also be used by the listDataSet servlet to display the current contents of this table.


    3. Create a Container Wide Resource-Provider Definition

      Insert the following definition into the "application.xml" file. This file is located in $ORACLE_HOME/j2ee//config directory.
      (e.g. $ORACLE_HOME/j2ee/home/config/application.xml)


      <resource-provider class="oracle.jms.OjmsContext" name="ojms"> <description>OJMS Context Using a datasource</description> <property name="url" value="jdbc:oracle:thin:aq_admin/aq_admin@bartman:1521:O920NT" /> <property name="username" value="aq_admin" /> <property name="password" value="aq_admin" /> </resource-provider>

      NOTE:

      • The class "oracle.jms.OjmsContext" implements the Oracle AQ-JMS functionality and the name attribute will be used later to reference Oracle AQ-JMS resources such as Queue's and Queue Connection Factories from the JNDI namespace.
      • The value of the url, username and password attributes needs to be consistent with the database schema from step [1] where we create the Oracle AQ resources.


    4. (Optional) Propagating Configuration Changes to the DCM Repository

      This is an optional step and is only required if you are using an OC4J instance that is being managed by the Distributed Component Management (DCM) component that comes with the full 9iAS release.

      In the case of OC4J instances being managed by teh DCM, all configuration changes are maintained within a central configuration repository and it is necessary to use the "dcmctl updateConfig" command to propagate configuration changes to the central configuration repository:


      % dcmctl updateConfig -ct oc4j -co home -v -d

      For further information on the "dcmctl updateConfig" command line options, see:


    5. Download the OracleJmsApp Enterprise Archive (OracleJmsApp.ear) File

      You can download the test Enterprise Archive (EAR) file from the following link: OracleJmsApp.ear

      NOTE:

      Save the file as OracleJmsApp.ear.

    6. Netscape Users: Hold down the SHIFT key while linking on the link.

    7. Internet Explorer Users: Right click on the link and in the pop-up menu, select "Save Target As...".

    8. Deploy the Enterprise Archive OracleJmsApp.ear File

      After downloading the Enterprise Archive file, you will need to deploy it to the standalone OC4J application server using manual methods.

      1. Copy the OracleJmsApp.ear to the OC4J instance's application directory:

        (e.g $ORACLE_HOME/j2ee/home/applications)

      2. Define the new OC4J application by editing the server.xml file by adding a new XML <application> element as follows:


        <application name="OracleJmsApp" path="../applications/OracleJmsApp.ear" auto-start="true" />

      3. Define the new OC4J Web application by editing the http-web-site.xml file by adding a new XML <web-app> element as follows:


        <web-app application="OracleJmsApp" name="OracleJmsWeb" root="/OracleJms" />




    Copyright (c) 1998-2017 Jeffrey M. Hunter. All rights reserved.

    All articles, scripts and material located at the Internet address of http://www.idevelopment.info is the copyright of Jeffrey M. Hunter and is protected under copyright laws of the United States. This document may not be hosted on any other site without my express, prior, written permission. Application to host any of the material elsewhere can be made by contacting me at jhunter@idevelopment.info.

    I have made every effort and taken great care in making sure that the material included on my web site is technically accurate, but I disclaim any and all responsibility for any loss, damage or destruction of data or any other property which may arise from relying on it. I will in no case be liable for any monetary damages arising from such loss, damage or destruction.

    Last modified on
    Thursday, 17-Aug-2006 12:45:56 EDT
    Page Count: 11105