Red Hat Application Server: JOnAS User Guide
Prev	Chapter 3. JOnAS Configuration	Next

3.7. Configuring JMS Resource Adapters

Instead of using the JOnAS "JMS Service" for configuring a JMS platform, it is possible to use the JOnAS "Resource Service" and JMS adapters that are compliant with the J2EE Connector Architecture specification. The provided functionalities are the same, with the extra benefit of allowing the deployment of 2.1 MDBs.

JMS connections are obtained from a JMS Resource Adapter (RA), which is configured to identify a JMS server and access it. Multiple JMS RAs can be deployed, either via the jonas.properties file, or via the JonasAdmin tool, or included in the autoload directory of the resource service. For complete information about RAs in JOnAS, refer to Chapter 25 JOnAS and the Connector Architecture.

3.7.1. JORAM Resource Adapter

This section describes how JMS Resource Adapters should be configured to provide messaging functionalities to JOnAS components and applications.

The JORAM resource adapter archive (joram_for_jonas_ra.rar) is provided with the JOnAS distribution. It can be found in the $JONAS_ROOT/rars directory. To deploy it, you can declare the archive file in the jonas.properties file as follows:

jonas.service.resource.resources	joram_for_jonas_ra

jms must be removed from the list of services:

jonas.services	registry,jmx,jtm,dbm,security,resource,ejb,web,ear

The archive can also be deployed by putting it in the JOnAS rars/autoload directory.

The JORAM RA may be seen as the central authority to go through for connecting and using a JORAM platform. The RA is provided with a default deployment configuration that:

Starts a collocated JORAM server in non-persistent mode, with id 0 and name s0, on host localhost and using port 16010; for doing so it relies on an a3servers.xml file located in the $JONAS_ROOT/conf directory.
Creates managed JMS ConnectionFactory instances and binds them with the names CF, QCF, and TCF.
Creates administered objects for this server (JMS destinations and non-managed factories) as described by the joram-admin.cfg file, located in the $JONAS_ROOT/conf directory; those objects are bound with the names sampleQueue, sampleTopic, JCF, JQCF, and JTCF

This default behavior is strictly equivalent to the default JMS service's behavior.

Of course, you can modify the default configuration.

3.7.1.1. Configuring the JORAM Adapter

jonas-ra.xml is the JOnAS specific deployment descriptor that configures the JORAM adapter. Changing the configuration of the RA requires you to extract the deployment descriptor, edit it, and update the archive file. The RAConfig utility is provided for doing this (refer to Section 6.7 RAConfig for a complete description). To extract the jonas-ra.xml file, use:

RAConfig joram_for_jonas_ra.rar

Then, to update the archive, use:

RAConfig -u jonas-ra.xml joram_for_jonas_ra.rar

The jonas-ra.xml file sets the central configuration of the adapter, defines and sets managed connection factories for outbound communication, and defines a listener for inbound communication.

The following properties are related to the central configuration of the adapter:

Property Name	Description	Possible Values
CollocatedServer	Running mode of the JORAM server to which the adapter gives access.	True: when deploying, the adapter starts a collocated JORAM server. False: when deploying, the adapter connects to a remote JORAM server. Nothing (default True value is then set).
PlatformConfigDir	Directory where the `a3servers.xml` and `joram-admin.cfg` files are located.	Any String describing an absolute path (for example: /myHome/myJonasRoot/conf). Empty String, files will be searched in `$JONAS_ROOT/conf`. Nothing (default empty string is then set).
PersistentPlatform	Persistence mode of the collocated JORAM server (not taken into account if the JORAM server is set as non collocated).	True: starts a persistent JORAM server. False: starts a non-persistent JORAM server. Nothing (default False value is then set).
ServerId	Identifier of the JORAM server to start (not taken into account if the JORAM server is set as non collocated).	Identifier corresponding to the server to start described in the `a3servers.xml` file (ex: 1). Nothing (default 0 value is then set).
ServerName	Name of the JORAM server to start (not taken into account if the JORAM server is set as non collocated).	Name corresponding to the server to start described in the `a3servers.xml` file (ex: s1). Nothing (default s0 name is then set).
AdminFile	Name of the file describing the administration tasks to perform; if the file does not exist, or is not found, no administration task is performed.	Name of the file (ex: myAdminFile.cfg). Nothing (default joram-admin.cfg name is then set).
HostName	Name of the host where the JORAM server runs, used for accessing a remote JORAM server (non collocated mode), and for building appropriate connection factories.	Any host name (ex: myHost). Nothing (default localhost name is then set).
ServerPort	Port the JORAM server is listening on, used for accessing a remote JORAM server (non collocated mode), and for building appropriate connection factories.	Any port value (ex: 16030). Nothing (default 16010 value is then set).

Table 3-5. Adapter Configuration Properties

The jonas-connection-definition tags wrap properties related to the managed connection factories:

Property Name	Description	Possible Values
jndi-name	Name used for binding the constructed connection factory.	Any name (such as myQueueConnectionFactory).
UserName	Default user name that will be used for opening JMS connections.	Any name (such as myName). Nothing (default anonymous name will be set).
UserPassword	Default user password that will be used for opening JMS connections.	Any name (such as myPass). Nothing (default anonymous password will be set).
Collocated	Specifies if the connections that will be created from the factory should be TCP or local-optimized connections (the collocated mode can only be set if the JORAM server is collocated; such factories will only be usable from within JOnAS).	True (for building local-optimized connections). False (for building TCP connections). Nothing (default TCP mode will be set).

Table 3-6. jonas-connection-definition Tags

The jonas-activationspec tag wraps a property related to inbound messaging:

Property Name	Description	Possible Values
jndi-name	Binding name of a JORAM object to be used by 2.1 MDBs.	Any name (such as joramActivationSpec).

Table 3-7. jonas-activationspec Tag

3.7.1.2. Configuring a Collocated JORAM Server

The a3servers.xml file describes a JORAM platform configuration and is used by a starting JORAM server (thus, it is never used if JORAM is in non-collocated mode).

The default file provided with JOnAS is the following:

<?xml version="1.0"?>
<config>
    <server id="0" name="S0" hostname="localhost">
      <service class="org.objectweb.joram.mom.proxies.ConnectionManager"
                  args="root root"/>
      <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService" 
                  args="16010"/>
    </server>
</config>

The above configuration describes a JORAM platform made of one unique JORAM server (id 0, name s0), running on localhost, listening on port 16010. Those values are taken into account by the JORAM server when starting. However they should match the values set in the deployment descriptor of the RA, otherwise the adapter either will not connect to the JORAM server, or will build improper connection factories.

3.7.1.3. Specifying Administration Tasks

The joram-admin.cfg file describes administered objects to be (optionally) created when deploying the adapter.

The default file provided with JOnAS creates a queue bound with the name sampleQueue, creates a topic bound with the name sampleTopic, sets the anonymous user, and creates and binds non-managed connection factories named JCF, JQCF, and JTCF. It also defines a host name and server port, which have the same meanings as the parameters set in the jonas-ra.xml file. Their goal is to make it easy to change the host and port values without having to edit the deployment descriptor.

To request the creation of a queue with the name "myQueueName", add the line:

Queue	myQueueName

To request the creation of a topic with the name "myTopicName", add the line:

Topic	myTopicName

To request the creation of the user "myName" - "myPass", add the line:

User	myName myPass

To request the creation of a non-managed ConnectionFactory to be bound with the name "myCF", add the line:

CF	myCF

To request the creation of a non-managed QueueConnectionFactory to be bound with the name "myQCF", add the line:

QCF	myQCF

To request the creation of a non-managed TopicConnectionFactory, to be bound with the name "myTCF", add the line:

TCF	myTCF

	Note:
	All administration tasks are performed locally (that is, on the JORAM server to which the adapter is connected). If a queue, a topic, or a user already exists on the JORAM server (for example because the server is in persistent mode and has re-started after a crash, or because the adapter has been deployed, undeployed, and is re-deployed giving access to a remote JORAM server), it will be retrieved instead of being re-created.

Note:

All administration tasks are performed locally (that is, on the JORAM server to which the adapter is connected).
If a queue, a topic, or a user already exists on the JORAM server (for example because the server is in persistent mode and has re-started after a crash, or because the adapter has been deployed, undeployed, and is re-deployed giving access to a remote JORAM server), it will be retrieved instead of being re-created.

3.7.1.4. Undeploying and Redeploying a JORAM Adapter

Undeploying a JORAM adapter either stops the collocated JORAM server, or disconnects from a remote JORAM server. It is then possible to deploy the same adapter again:

If set for running a collocated server, it will re-start it.
If the running mode is persistent, then server will be retrieved in its pre-undeployed state (with the existing destinations, users, and possibly messages).
If set for connecting to a remote server, the adapter will reconnect and access the destinations it previously created.

In the collocated persistent case, if you want to start a new JORAM server, remove its persistence directory. This directory is located in JOnAS' running directory, and has the same name as the JORAM server (for example s0/ for server "s0").

Prev	Home	Next
Configuring the DB Service (hsql)	Up	Configuring JDBC DataSources