2.7. Configuring JMS Resource Adapters
Prev  Chapter 2. Configuring a JOnAS instance  Next

2.7. Configuring JMS Resource Adapters

JMS Resource adapters can be deployed, either via the jonas.properties file, or via the JonasAdmin tool, or included in the autoload directory of the resource service.

JMS connections are obtained from a JMS RA, which is configured to identify and access a JMS server.

The JORAM resource adapter archive (joram_ra_for_jonas-{joram.version}.rar) is provided with the JOnAS distribution. It is located in the $JONAS_BASE/repositories/maven2-internal/org/objectweb/joram/joram_ra_for_jonas/{joram.version}/joram_ra_for_jonas-{joram.version}.rar directory. This file has to be changed if a particular configuration is needed for JORAM.

By default, the joram.xml file, a deployment plan related to JORAM, is present in the $JONAS_BASE/deploy directory. This deployment plan is used to deploy JORAM. It declares among others the JORAM resource adapter archive to deploy.

2.7.1. JORAM Resource Adapter configuration files

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

  • 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 both an a3server.xml file located in the $JONAS_BASE/conf directory and the jonas-ra.xml file located within the RA.

  • 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 joramAdmin.xml, located in the $JONAS_BASE/conf directory; those objects are bound with the names sampleQueue, sampleTopic, JCF, JQCF, and JTCF.

The default configuration may, of course, be modified.

The JORAM integration into JOnAS is composed of 3 different parts: server, RA, and administration. Each part contains its own configuration files:

  • a3servers.xml is the JORAM platform configuration file, i.e. the server part. The file is located in the $JONAS_BASE/conf directory.

  • ra.xml and jonas-ra.xml are the resource adapter configuration files. They are embedded in the resource adapter (META-INF directory).

  • joramAdmin.xml contains the administration tasks to be performed by the JORAM server such as the JMS objects creation. It is located in the $JONAS_BASE/conf directory.

2.7.1.1. JORAM server configuration : a3servers.xml

The a3server.xml ($JONAS_BASE/conf/a3server.xml) file describes the JORAM platform, i.e., the network domain, the used transport protocol, and the reachable JORAM servers. It is used by a JORAM server at start time. By default, only one collocated JORAM server is defined (s0) based on the tcp/ip protocol. A distributed configuration example is provided in the how-to document and other examples are available in JORAM's user guide.

<config>
  <property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/> 1
   <server id="0" name="S0" hostname="localhost"> 2
    <service class="org.objectweb.joram.mom.proxies.ConnectionManager"
             args="root root"/>
    <service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService"
             args="16010"/> 3

   </server>
</config>

1

This property means that the non persistent mode for JMS is choosen. In order to use persistent mode, the value must be changed to "fr.dyade.aaa.util.NTransaction"

2

Here can be set the server id and the host where the server run

3

args specifies the port number the JORAM server is listening on

The above configuration describes a JORAM platform made up 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 it will build improper connection factories.

The joram_raconfig command allows to modify these parameters in all the configuration files.

If used in non-collocated mode, joram can be started with the JmsServer command which loads the $JONAS_BASE/conf/a3server.xml configuration file.

2.7.1.2. Resource Adapter configuration: ra.xml, jonas-ra.xml

The ra.xml file is the standard deployment descriptor for the JORAM adapter and the jonas-ra.xml file is the JOnAS-specific deployment descriptor for the JORAM adapter. These files set the central configuration of the adapter, define and set managed connection factories for outbound communication, and define a listener for inbound communication. jonas-ra.xml contains specific parameters such as pool parameters or jndi names, but also may redefine the parameters of some ra.xml files and override their values. Globally, a good way to proceed is to keep the original ra.xml file with the default values and to customize the configuration only in the jonas-ra.xml file.

Changing the configuration of the RA requires extracting and editing the deployment descriptor and updating the archive file. There are several possible ways to do this:

  • With the RAConfig command to extract jonas-ra.xml, do the following:

    RAConfig -path . joram_for_jonas_ra.rar

    Then, to update the archive, do the following:

    RAConfig -u jonas-ra.xml joram_for_jonas_ra.rar

  • Through the jonasAdmin console (refer to Administration guide for a complete description).

    In the jonasAdmin's tree, the Resource Adapter Module node (under the deployment node) contains a configure tab that allows editing of both the ra.xml file and the jonas-ra.xml file of the undeployed RA.

  • Through the joram_raconfig utility (refer to joram_raconfig description for a complete description).

    This tool allows easy modification to the network parameters of the JORAM server in all the configuration files.

The following properties are related to the central configuration of the adapter; they are set via some <jonas-config-property> elements:

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 joramAdmin.xml files are located.

  • Any String describing an absolute path (ex: /myHome/myJonasRoot/conf).

  • Empty String, files will be searched in $JONAS_BASE/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. - If true, set the property 'Transaction' to 'fr.dyade.aaa.util.NTransaction' before launching the JORAM server. - If false, set the property 'Transaction' to 'fr.dyade.aaa.util.NullTransaction' before launching the JORAM server. - Warning, if the 'Transaction' property is set in the a3server.xml file, this value is ignored.

  • 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 Logical name of the JORAM server to start.In the collocated case, this parameter specifies the storage path of the persistent mode (absolute or relative path). If the JORAM server is non-collocated, it must be set to the name of the already started JORAM server (this is necessary for management purpose).

  • Storage path of the persistent mode for the collocated case (ex: /tmp/s0).

  • Name of the started server as described in the a3servers.xml in the non collocated case (ex: s1)

  • Nothing (default s0 name is then set and the current directory is used for storing the persistent data).
AdminFileXML Name of the file describing the administration tasks to be performed by the JORAM server, i.e., JMS destinations to create, users to create, ... If the file does not exist, or is not found, no administration task is performed.

  • Name of the file (ex: myAdminFile.xml).

  • Nothing (default joramAdmin.xml 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).
ConnectingTimer Duration in seconds during which connecting is attempted (connecting might take time if the server is temporarily not reachable)

  • 0 : set for connecting only once and aborting if connecting failed (default value)

  • n : duration in seconds
CnxPendingTimer Period in milliseconds between two ping requests sent by the client connection to the server;

  • 0 means "notimer" (default value)

  • n: duration in milliseconds
TxPendingTimer Duration in seconds during which a JMS transacted (non XA) session might be pending; above that duration the session is rolled back and closed.

  • 0 value means "no timer".

  • n: duration in seconds
DeleteDurableSubscription Indicates the durable Subscriptions must be deleted when the consumer is closed

  • True (previous behaviour)

  • False (default value)

The <jonas-connection-definition> elements wrap properties related to the managed connection factories:

There are three managed connection factories:

  • A Queue managed connection factory registered in JNDI with the name QCF

  • A Topic managed connection factory registered in JNDI with the name TCF

  • A managed connection factory registered in JNDI with the name CF

Here are the properties that can be configured for each managed connection factory:

property name description possible values
jndi-name Name used for binding the constructed connection factory.

Any name (ex: myQueueConnectionFactory). Default values are

  • QCF for the Queue managed connection factory

  • TCF for the Topic managed connection factory

  • CF for the managed connection factory
UserName Default user name that will be used for opening JMS connections.

  • Any name (ex: myName).

  • Nothing (default anonymous name will be set).
Password Default user password that will be used for opening JMS connections.

  • Any name (ex: 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

  • True (for building local-optimized connections).

  • False (for building TCP connections).

  • Nothing (default TCP mode will be set).

The <jonas-activationspec> element 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 (by default:joramActivationSpec).

The Pooling Tags are the same than those for other RAs:

property name description possible values
pool-init Initial size of the managed connection pool

  • 0 (default value)

  • n
pool-min Minimum size of the managed connection pool.

  • 0 (default value)

  • n
pool-max Maximum size of the managed connection pool.

  • n

  • -1 = unlimited (default value)
pool-max-age-minutes Maximum number of minutes to keep the managed connection in the pool.

  • 0 = an unlimited amount of time.

  • n in minutes
pstmt-max Maximum number of PreparedStatements per managed connection in the pool. Only needed with the JDBC RA of JOnAS or another database vendor's RAR. Value of 0 is unlimited and -1 disables the cache.

  • 0 = unlimited

  • n (default value = 10)

  • -1 = cache disabled
pool-max-opentime Identifies the maximum number of minutes that a managed connection can be left busy.

  • 0 = an unlimited amount of time (default value).

  • n in minutes
pool-max-waiters: identifies the maximum number of waiters for a managed connection. Default value is 0.

  • 0 (default value)

  • n
pool-max-waittime identifies the maximum number of seconds that a waiter will wait for a managed connection. Default value is 0.

  • 0 (default value)

  • n in seconds
pool-sampling-period: identifies the number of seconds that will occur between statistics samplings of the pool. Default is 30 seconds.

  • n in seconds (default value = 30s)

2.7.1.3. JMS Applications Configuration

joramAdmin.xml file describes the configuration related to the application. It describes the administration objects in the JORAM server such as the JMS objects, the users, or the non-managed factories. In other words, it defines the JORAM objects to be (optionally) created when deploying the adapter.

In earlier version the joram-admin.cfg was used for this same purpose but it is now deprecated.

The default file provided with JOnAS creates a queue bound with the name sampleQueue, a topic bound with the name sampleTopic, sets the anonymous user, and creates and binds non-managed connection factories named JCF, JQCF and JTCF

[Note] Note

  • All administration tasks are performed by the server connected but may affect remote JORAM servers to which the adapter is connected through the ServerId attribute.

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

The format of this file is XML. Here are some examples:

  • simple example:

    <?xml version="1.0"?>
      <JoramAdmin>
        <AdminModule>
          <collocatedConnect name="root" password="root"/>
        </AdminModule>
        <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TcpConnectionFactory">
          <tcp host="localhost"
                  port="16010"/>
          <jndi name="JCF"/>
        </ConnectionFactory>
        <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.QueueTcpConnectionFactory">
          <tcp host="localhost"
                  port="16010"/>
          <jndi name="JQCF"/>
        </ConnectionFactory>
        <ConnectionFactory className="org.objectweb.joram.client.jms.tcp.TopicTcpConnectionFactory">
          <tcp host="localhost"
                  port="16010"/>
          <jndi name="JTCF"/>
        </ConnectionFactory>
        <User name="anonymous"
                 password="anonymous"
                 serverId="0"/>
        <Queue name="sampleQueue">
          <freeReader/>
          <freeWriter/>
          <jndi name="sampleQueue"/>
        </Queue>
        <Topic name="sampleTopic">
          <freeReader/>
          <freeWriter/>
          <jndi name="sampleTopic"/>
        </Topic>
      </JoramAdmin>

  • For requesting the creation of a new object, simply add the element in the file. For example, to add a queue 'MyQueue', add the following XML element:

            <Queue name="myQueue">
          <freeReader/>
          <freeWriter/>
          <jndi name="myQueue"/>
        </Queue>

  • When the JORAM is not collocated, the AdminModule must be defined as follows:

          <AdminModule>
        <connect host="localhost"
                 port="16020"
                 name="root"
                 password="root"/>
      </AdminModule>

    The port number must be set with the server port number (defined in the a3servers.xml and in the JORAM's RAR configuration ra.xml and jonas-ra.xml files).

  • Possible parameters for a queue definition:

           <Queue name=""
                 serverId=""
                 className=""
                 dmq=""
                 nbMaxMsg=""
                 threshold="">
         <property name="" value=""/>
         <property name="" value=""/>
         <reader user=""/>
         <writer user=""/>
         <freeReader/>
         <freeWriter/>
         <jndi name=""/>
         </Queue>

  • Possible parameters for a topic definition:

          <Topic name=""
                parent=""
                serverId=""
                className=""
                dmq="">
        <property name="" value=""/>
        <property name="" value=""/>
        <reader user=""/>
        <writer user=""/>
        <freeReader/>
        <freeWriter/>
        <jndi name=""/>
      </Topic>

  • Example of a dead message queue definition:

          <DMQueue name="DMQ"
                  serverId="0">
        <reader user="anonymous"/>
        <writer user="anonymous"/>
        <freeReader/>
        <freeWriter/>
        <jndi name="DMQ"/>
      </DMQueue>

  • Example of a scheduler queue definition:

          <Destination type="queue"
                      serverId="0"
                      name="schedulerQueue"
                      className="com.scalagent.joram.mom.dest.scheduler.SchedulerQueue">
        <freeReader/>
        <freeWriter/>
        <jndi name="schedulerQueue"/>
      </Destination>

  • Example of a clustered queues destination:

            <Cluster>
          <Queue name="queue0"
                    serverId="0"
                    className="org.objectweb.joram.mom.dest.ClusterQueue">
            <freeReader/>
            <freeWriter/>
            <property name="period" value="10000"/>
            <property name="producThreshold" value="50"/>
            <property name="consumThreshold" value="2"/>
            <property name="autoEvalThreshold" value="false"/>
            <property name="waitAfterClusterReq" value="1000"/>
            <jndi name="queue0"/>
          </Queue>
          <Queue name="queue1"
                    serverId="1"
                    className="org.objectweb.joram.mom.dest.ClusterQueue">
            <freeReader/>
            <freeWriter/>
            <property name="period" value="10000"/>
            <property name="producThreshold" value="50"/>
            <property name="consumThreshold" value="2"/>
            <property name="autoEvalThreshold" value="false"/>
            <property name="waitAfterClusterReq" value="1000"/>
            <jndi name="queue1"/>
          </Queue>
          <Queue name="queue2"
                    serverId="2"
                    className="org.objectweb.joram.mom.dest.ClusterQueue">
            <freeReader/>
            <freeWriter/>
            <property name="period" value="10000"/>
            <property name="producThreshold" value="50"/>
            <property name="consumThreshold" value="2"/>
            <property name="autoEvalThreshold" value="false"/>
            <property name="waitAfterClusterReq" value="1000"/>
            <jndi name="queue2"/>
         </Queue>
         <freeReader/>
         <freeWriter/>
         <reader user="user0"/>
         <writer user="user0"/>
         <reader user="user1"/>
         <writer user="user1"/>
         <reader user="user2"/>
         <writer user="user2"/>
       </Cluster>

2.7.1.4. joram_raconfig command

2.7.1.4.1. joram_raconfig

Change the host and port parameters of a given JORAM server in the configuration files.

2.7.1.4.1.1. Options

joram_raconfig [-p port] [-h host] [-s serverId]

-p port

Set the listening port of the JORAM server (defaults to 16010).

-h host

Set the IP address of the JORAM server (defaults to localhost).

-s serverId

Set the server id of the JORAM server (defaults to 0).

2.7.1.4.1.2. Description

The joram_raconfig tool aims to facilitate consistent updates (accross multiple files) for the host and port parameters of a given JORAM server ID.

JORAM relies on several configuration files: a3servers.xml, joramAdmin.xml and ra.xml. With joram_raconfig, these configuration files are updated all together and thus the consistency is ensured.

Modified files:

  • $JONAS_BASE/conf/a3servers.xml

  • $JONAS_BASE/conf/joramAdmin.xml

  • META-INF/ra.xml (in the JORAM resource adapter) is updated.

Resource adapters files are looked up in the following places:

  • $JONAS_BASE/repositories/maven2-internal/org/objectweb/joram/joram_ra_for_jonas/{joram.version}/joram_ra_for_jonas-{joram.version}.rar

  • $JONAS_BASE/deploy/joram_ra_for_jonas.rar

2.7.1.4.1.3. Example
>$ joram_raconfig -h localhost -p 16012 -s 0
Target JORAM Resource Adapter: /home/ ... /joram/joram_ra_for_jonas/5.2.1a/joram_ra_for_jonas-5.2.1a.rar
Prev  Up  Next
2.6.5. Migration from dbm service to the JDBC RA  Home  2.7.2. JORAM's Resource Adapter tuning