11
Java Message Service

This chapter describes the Java Message Service (JMS) provided as part of Oracle9iAS Containers for J2EE (OC4J). This chapter contains these topics:

Overview

Java clients and Java middle-tier services must be capable of using enterprise messaging systems. The Java Message Service (JMS) provides a common way for Java programs to access these systems. JMS is the standard messaging API for passing data asynchronously between application components, allowing business integration in heterogeneous and legacy environments.JMS provides two programming models:

Point-to-Point (Queue) --messages are sent to one consumer only.
Publish and Subscribe (Topics) --messages are broadcast to all registered listeners.

JMS queues and topics are bound to the JNDI environment and made available to J2EE applications.

The OC4J JMS implementation is fast, lightweight, and fully compliant with the JMS 1.0.1 specification. OC4J applications (application-client programs, servlets, EJBs, and so on) can access queues and topics using the JMS API. OC4J applications can also use an OC4J-specific JNDI namespace to look up JMS ConnectionFactories and Destinations.

OC4J defines a ResourceProvider interface for plugging in message providers and provides the implementation classes for Oracle's Advanced Queuing (a.k.a. OracleJMS), as well as for third-party messaging systems such as MQSeries, SonicMQ and SwiftMQ. The implementation classes and the connection factories make the message providers known in the OC4J namespace (java:comp/env/jms) for JMS consumers such as Java clients and Message-Driven Beans. OC4J's ResourceProvider interface allows switching between message providers transparently to the JMS client.

The JMS Examples

The OC4J JMS implementation comes with two examples, JMS-Chat and Coffeemaker. JMS-Chat demonstrates topics; Coffeemaker demonstrates queues.

Running JMS-Chat

JMS-Chat is a small chat example that demonstrates topics.

To run the example:

If JMS is not activated, activate it by editing server.xml to remove the comments around <jms-config ... />.
Start the OC4J server. Change to the $J2EE_HOME directory and issue the command:
```
java -jar oc4j.jar 
```
Change to the $J2EE_HOME/demo/jms directory and start two chat clients in different console windows. In each window, issue the command
```
java -Djava.naming.security.credentials=<admin password> -jar jmschat.jar
```
Type a message into one console window and press RETURN; the message appears in the other window.

Running Coffeemaker

The coffeemaker example demonstrates queues. Each service is a coffee machine, which takes approximately 25 seconds to make a cup of coffee. You can plug in as many makers and as many order units as you wish.

To run the example:

If JMS is not activated, edit server.xml and uncomment the <jms-config ... /> tag to activate the JMS service.
Start the OC4J server. Change to the $J2EE_HOME directory and issue the command:
```
java -jar oc4j.jar 
```
Change to the $J2EE_HOME/demo/jms directory and start the coffee maker.
```
java -jar coffeemaker.jar
```

Change to the $J2EE_HOME/demo/jms directory and start the coffee requester.

java -Djava.naming.security.credentials=<admin password> -jar coffeemaker.jar -order

The coffee requestor prompts Brand? Type in a brand of coffee and press RETURN. The coffee maker prints "Making yourbrand coffee..."

Configuration Issues

This section discusses configuring OC4J to support various deployment methods and messaging systems.

Deploying JMS Clients Across Nodes

To deploy clients across multiple nodes, you must edit the jms.xml file for the client. For example, you would edit the queue-connection-factory property to look like:

<queue-connection-factory host="hostname.domain.com|123.124.125.126|[ALL]" 
   location="jms/QueueConnectionFactory" password="123" port="9127" 
username="myUser" />

The attribute values for this property are:

host - The host/IP this factory connects to. By default, host is the local server.
location - The JNDI name the client should bind to.
password - The password for the specified username.
port - The target port. The default is 9127.
username - The username the client should use to connect.

Message-Driven Beans

OC4J JMS supports message-driven beans (EJBs that process JMS messages asynchronously), as specified in EJB2.0. Message-driven beans can either use container-managed transactions (commit only) or bean-managed transactions. For details, see the documentation for the messagelogger example.

Resource Providers

The ResourceProvider interface allows you to plug in third-party message providers (such as Oracle Advanced Queuing, MQSeries and SonicMQ) as JMS resource providers. This allows EJBs, servlets, and OC4J clients to access many different queue implementations. The third-party message providers are accessed through the ResourceProvider interface.

Note:

Except as noted here, you configure OC4J JMS as you would any other JMS implementation.

Plugging In Resource Providers

To add a custom resource provider to OC4J, you must add the <resource-provider> tag to orion-application.xml. This section describes how to add one such ResourceProvider.

An example ResourceProvider, ContextScanningResourceProvider, is bundled with OC4J. To use this ResourceProvider, you would add the following tag to orion-application.xml:

<resource-provider
  class="com.evermind.server.deloyment.ContextScanningResourceProvider"
  display-name="SwiftMQ"> 
   <description> 
      SwiftMQ resource provider. 
   </description> 
   <property name="java.naming.factory.initial"
      value="com.swiftmq.jndi.InitialContextFactoryImpl"> 
   <property name="java.naming.provider.url" 
      value="smqp://localhost:4001"> 
</resource-provider>

This example makes SwiftMQ the default ResourceProvider for JMS connections -- the first <resource-provider> tag in orion-application.xml becomes the default resource provider for the types it handles. Adding this tag makes the resource available in the Orion JNDI under java:comp/resource/, as well as making SwiftMQ the default JMS resource for such actions as deploying a message-driven bean.

Configuring Message Providers

Install and configure the message provider according to the instructions in its documentation, then verify the installation by running any examples or tools supplied by the vendor.
Register the message provider in some JNDI-accessible store (a file system, an LDAP OiD, or the like.) Use JMS provider tools to configure and populate this JNDI store with, for instance, the provider's QueueConnectionFactory and the queues of interest.

Make the JNDI store accessible to OC4J by adding a <resource-provider> entity to orion-application.xml pointing to the JNDI store. This example demonstrates using SonicMQ as the message provider and the file system as the JNDI store:


<resource-provider     
class="com.evermind.server.deployment.ContextScanningResourceProvider" 
   name="SonicJMS"> 
 <property name="java.naming.factory.initial" 
     value="com.sun.jndi.fscontext.RefFSContextFactory" /> 
 <property name="java.naming.provider.url" 
     value="file:/private/jndi-directory" /> 
</resource-provider>

Copy the required JNDI files (for a file-system JNDI, fscontext.jar and providerutils.jar) to $J2EE_HOME/lib.
Restart OC4J. Whenever you add, delete, or reconfigure a resource provider, you must restart OC4J.

JNDI Resource Provider Names

OC4J resource provider extensions create resources under the java:comp/resource JNDI name tree. OJMS resource names take the form:

java:comp/resource/ProviderName/ResourceType/ResourceName

where:

ProviderName

is the user-chosen name of the resource provider.

ResourceType

(required for Oracle AQ/OJMS resource providers only) is a fixed string that can take one of four values: QueueConnectionFactories, TopicConnectionFactories, Queues, or Topics. The specified value identifies the JMS resource as being of the appropriate administered object type.

ResourceName

is a user-chosen name for a JMS connection factory or a valid AQ queue name for a JMS destination. Valid Oracle AQ names conform to the [schema.]queue_name scheme.

Accessing Message Queues

OC4J applications can now access the message queues. Message queues can be accessed in one of two ways:

Through their names, as in

java:comp/resource/<Provider_Name>/<Queue_Name>

An application would access the queue like this:

queueConnectionFactory=(QueueConnectionFactory) 
jndiContext.lookup("java:comp/resource/SonicJMS/QueueConnectionFactory");

By binding message-driven beans to queues in orion-ejb-jar.xml

To bind message-driven beans to queues in orion-ejb-jar, you would add a tag like:

<message-driven-deployment 
connection-factory-location="java:comp/resource/SonicJMS/QueueConnectionFactory" 
 destination-location="java:comp/resource/SonicJMS/SampleQ1" 
 name="MessageBean">

Using Oracle AQ as a Resource Provider

To access Oracle AQ queues through JMS, you must do the following:

Create an RDBMS user through which the JMS application will connect to the back-end database. The user should have the necessary privileges to perform AQ operations. AQ allows any database user to access queues in any schema, provided the user has and the schema exports the appropriate access privileges.
Configure an OC4J resource provider with information about the back-end database. Create data sources or LDAP directory entries, if needed.
Access the resource using Oracle AQ/OJMS resource names, which include the ResourceName name component.

Configuration

The OC4J resource provider for OJMS is implemented by the class oracle.jms.OjmsContext. Each OJMS resource provider instance is a <resource-provider ...> XML element (a child element of the orion-application element) in the $J2EE_HOME/config/application.xml file.

There are 3 ways of configuring the OJMS resource provider.

Inline configuration (all relevant information for accessing the back-end database is specified within the resource-provider element in application.xml).
Data Source configuration (the resource-provider element in application.xml refers to a data-source element configured in data-sources.xml which contains information on accessing the back-end database).
LDAP configuration (the resource provider contains information to access an OID/LDAP directory which contains information on accessing the back-end database).

This section describes only the inline and data source configuration methods.

Inline Configuration

An inline resource provider configuration consists of a resource provider instance name (user-chosen, but unique among all resource providers configured in OC4J), a JDBC URL to connect to the back-end database, and the user/password to connect as. For example:

    <resource-provider class="oracle.jms.OjmsContext" name="MyContext1">
        <description>OJMS Context using thin JDBC</description>
        <property name="url" 
value="jdbc:oracle:thin:@myhost.foo.com:1521:mydb"></property>
        <property name="username" value="myuser"></property>
        <property name="password" value="mypass"></property>
    </resource-provider>

    <resource-provider class="oracle.jms.OjmsContext" name="MyContext2">
        <description>OJMS Context using OCI JDBC</description>
        <property name="url" value="jdbc:oracle:oci:@mydb.foo.com"></property>
        <property name="username" value="myuser"></property>
        <property name="password" value="mypass"></property>
    </resource-provider>

This creates 2 resource providers, MyContext1 and MyContext2, that log in as myuser/mypass to the back-end database mydb using the thin and OCI JDBC drivers respectively.

Data Source Configuration

A data source resource provider configuration consists of a resource provider instance name (user-chosen, but unique among all resource providers configured in OC4J), a data source name, and the data source configuration (in data-sources.xml). For example:


    <resource-provider class="oracle.jms.OjmsContext" name="MyContext3">
        <description>OJMS Context using a datasource</description>
        <property name="datasource" value="jdbc/MyDS3"></property>
    </resource-provider>

    <resource-provider class="oracle.jms.OjmsContext" name="MyContext4">
        <description>OJMS Context using a datasource</description>
        <property name="datasource" value="jdbc/MyDS4"></property>
    </resource-provider>

in application.xml and the following data sources in data-sources.xml:

    <data-source
        class="oracle.jdbc.pool.OracleDataSource"
        name="MyDS3"
        location="jdbc/MyDS3"
        xa-location="jdbc/xa/MyXADS3"
        ejb-location="jdbc/MyEjbDS3"
        url="jdbc:oracle:thin:@myhost.foo.com:1521:mydb"
        username="myuser"
        password="myuser"
        inactivity-timeout="30"
    />

    <data-source
        class="oracle.jdbc.pool.OracleDataSource"
        name="MyDS4"
        location="jdbc/MyDS4"
        xa-location="jdbc/xa/MyXADS4"
        ejb-location="jdbc/MyEjbDS4"
        url="jdbc:oracle:oci:@mydb.foo.com"
        username="myuser"
        password="myuser"
        inactivity-timeout="30"
    />

This creates 2 resource providers, MyContext3 and MyContext4, that use the data sources jdbc/MyDS3 and jdbc/MyDS4 respectively to connect to the back-end database. The data sources themselves contain the appropriate JDBC driver/connect information.

Using MQSeries As a Resource Provider

The Resource Provider interface provides support for plugging in third-party JMS implementations. This example demonstrates how to make MQSeries the default Resource Provider for JMS connections. The MQSeries resources are available in OC4J under java:comp/resource/MQSeries/ as well as from deployed message-driven beans.

Configuring

Install and configure MQSeries on your system, then verify the installation by running any examples or tools supplied by the vendor.
Use the <resource-provider> tag in orion-application.xml to add a custom Resource Provider. You can find an example of using this tag for SonicMQ integration in $J2EE_HOME/res_provider/sonicmq/orion-application.xml.

Add the following MQSeries JMS client jar files to $J2EE_HOME/lib:

com.ibm.mq.jar 
com.ibm.mqbind.jar 
com.ibm.mqjms.jar 
mqji.properties

Add a <library> element to $J2EE_HOME/config/server.xml, forcing the OC4J class loader to load the third party JMS client jar files:
```
<library path="../lib" /> 
```
Add $J2EE_HOME/oc4j.jar, $J2EE_HOME/jndi.jar, and $J2EE_HOME/ejb.jar to your CLASSPATH.

Using SonicMQ As A Resource Provider

SonicMQ is a Messaging Broker with a complete implementation of the JMS 1.0.1 Specification. The Resource Provider interface provides support for plugging in third-party JMS implementations. This example describes how to make SonicMQ the default Resource Provider for JMS connections. The SonicMQ resources will be available in OC4J under java:comp/resource/SonicMQ, as well as when a message-driven Bean is deployed.

Configuring

Note:

SonicMQ broker does not embed a JNDI service. Instead, it relies on an external directory server to register the administered objects. Administered objects, such as queues, are either created by an administrator using SonicMQ Explorer or programmatically using the Sonic Management API. We have arbitrarily chosen to register the administered objects from SonicMQ Explorer using the file system JNDI.

Install and configure SonicMQ on your system, then verify the installation by running any examples or tools supplied by the vendor.
In <install-dir>/SonicMQ/bin/explorer.sh, append the file system JNDI jar files to $SONICMQ_CLASSPATH.
Start the SonicMQ Explorer by invoking <install-dir>/SonicMQ/bin/explorer.sh.
Create a connection to SonicMQ broker by clicking on Message Brokers in the Explorer tree with Broker Host 'localhost:2506'. Click JMS Administered Object Stores and enter the following two properties under JNDI Directory Service section:
```
java.naming.factory.initial=com.sun.jndi.context.RefFSContextFactory,
java.naming.provider.utl=file:/private/jndi 
```
Under the Queue tab, create 'SampleQ1' and create 'QueueConnectionFactory' with URL tcp://localhost:2506.
Use the <resource-provider> tag in orion-application.xml to add a custom Resource Provider.
Add the SonicMQ JMS client jar file, $J2EE_HOME/jars/client.jar, to $J2EE_HOME/lib.
Add a <library> element to$J2EE_HOME/config/server.xml so that the third party JMS client jar files will be loaded by the OC4J class loader, as in:
```
<library path="../lib" /> 
```
Add $J2EE_HOME/oc4j.jar, $J2EE_HOME/jndi.jar, and $J2EE_HOME/ejb.jar to your CLASSPATH.

11Java Message Service

Overview

The JMS Examples

Running JMS-Chat

Running Coffeemaker

Configuration Issues

Deploying JMS Clients Across Nodes

Message-Driven Beans

Resource Providers

Plugging In Resource Providers

Configuring Message Providers

JNDI Resource Provider Names

ProviderName

ResourceType

ResourceName

Accessing Message Queues

Using Oracle AQ as a Resource Provider

Configuration

Inline Configuration

Data Source Configuration

Using MQSeries As a Resource Provider

Configuring

Using SonicMQ As A Resource Provider

Configuring

11
Java Message Service