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:

Application Name = OracleJmsApp o Enterprise Java Bean Module - (OracleJmsEJB) This module will contain a single Message Driven Bean (MDB) named parallelMDBBean. The purpose of this bean is to accept incoming JMS messages that describe a task or job. Each job will use JDBC to insert a fixed number of rows into a database table. The quantity of rows inserted into the table and their field values will be communicated through attributes of the JMS message. The table name will be dataset and will be created dynamically by the application. The table will have the following fields:
Name INSERT_DT ID Type DATE NUMBER(4)

The Message Driven Mean will use the INSERT_DT value for all rows inserted by the same job. By doing this, the order in which job processing occurred and any parallelism whithin the concurrent execution of multiple MDB's can be observed.
o

Web Archive Module - (OracleJmsWeb) - (Context Root = /OracleJms) The Web module implements two servlets:

jobSubmit listDataSet

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: OC4J 9.0.3.0.0 Supported Oracle RDBMS Version
o o

Oracle9i Database 9.0.1.4 (Patch: 2517300) Oracle9i Database 9.2.0.2 (Patch: 2632931)

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:

Using the Web Administration screens of the Oracle Enterprise Manager (OEM) web site. By shutting down the OEM web site (emctl stop) and applying all changes to configuration files manually and on completion and then running the command:
dcmctl updateConfig -ct oc4j -co <OC4J Instance Name>

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:
o o

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:
o o

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 thelistDataSet 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:
o

The class "oracle.jms.OjmsContext" implements the Oracle AQJMS 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 options, see:

o

updateConfig"

command line

Oracle9i Application Server: Administrator's Guide Release 2 (9.0.2) May 2002 Part No. A92171-02 http://downloadwest.oracle.com/docs/cd/A97329_03/core.902/a92171.pdf Appendix F: DCM Command-Line Utility (dcmctl) "Managing Applications", ppF-9

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. 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...".

6. 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-website.xml file by adding a new XML <web-app> element as follows:

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