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.
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:
jms must be removed from the list of services:
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.
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:
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:
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.
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:
To request the creation of a topic with the name "myTopicName", add the line:
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:
To request the creation of a non-managed QueueConnectionFactory to be bound with the name "myQCF", add the line:
To request the creation of a non-managed TopicConnectionFactory, to be bound with the name "myTCF", add the line:
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").