<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="config.rajms" xml:lang="en"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Configuring JMS Resource Adapters</title>
  </info>

  <para>JMS Resource adapters can be deployed, either via the JOnAS administration console, 
        or via the <filename>jonas admin -a</filename> command,
        or by dropping the file in the <filename>$JONAS_BASE/deploy</filename> directory.</para>

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

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

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

  <section>
    <info>
      <title>JORAM Resource Adapter configuration files</title>
    </info>

    <para>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:</para>

    <itemizedlist>
      <listitem>
        <para>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 <filename>a3server.xml</filename> file located in
        the <filename class="directory">$JONAS_BASE/conf</filename> directory
        and the jonas-ra.xml file located within the RA.</para>
      </listitem>

      <listitem>
        <para>Creates managed JMS ConnectionFactory instances and binds them
        with the names <emphasis role="bold">CF</emphasis>, <emphasis
        role="bold">QCF</emphasis>, and <emphasis
        role="bold">TCF</emphasis>.</para>
      </listitem>

      <listitem>
        <para>Creates administered objects for this server (JMS destinations
        and non-managed factories) as described by the
        <filename>joramAdmin.xml</filename>, located in the <filename
        class="directory">$JONAS_BASE/conf </filename>directory; those objects
        are bound with the names <emphasis role="bold">sampleQueue</emphasis>,
        <emphasis role="bold">sampleTopic</emphasis>, <emphasis
        role="bold">JCF</emphasis>, <emphasis role="bold">JQCF</emphasis>, and
        <emphasis role="bold">JTCF.</emphasis></para>
      </listitem>
    </itemizedlist>

    <para>The default configuration may, of course, be modified.</para>

    <para>The JORAM integration into <xi:include href="../variables.xml"
    xpointer="appserver" /> is composed of 3 different parts: server, RA, and
    administration. Each part contains its own configuration files:</para>

    <itemizedlist>
      <listitem>
        <para><link linkend="a3servers.xml">a3servers.xml</link> is the JORAM
        platform configuration file, i.e. the server part. The file is located
        in the <filename class="directory">$JONAS_BASE/conf
        </filename>directory.</para>
      </listitem>

      <listitem>
        <para><filename>ra.xml </filename>and <filename>jonas-ra.xml
        </filename>are the resource adapter configuration files. They are
        embedded in the resource adapter (META-INF directory).</para>
      </listitem>

      <listitem>
        <para><filename>joramAdmin.xml </filename>contains the administration
        tasks to be performed by the JORAM server such as the JMS objects
        creation. It is located in the <filename
        class="directory">$JONAS_BASE/conf </filename>directory.</para>
      </listitem>
    </itemizedlist>

    <section xml:id="a3servers.xml">
      <info>
        <title>JORAM server configuration : a3servers.xml</title>
      </info>

      <para>The a3server.xml
      (<filename>$JONAS_BASE/conf/a3server.xml</filename>) 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.</para>

      <para><screen>&lt;config&gt;
  &lt;property name="Transaction" value="fr.dyade.aaa.util.NullTransaction"/&gt; <co
            xml:id="a3server.transaction" />
   &lt;server id="0" name="S0" hostname="localhost"&gt; <co
            xml:id="a3server.id" />
    &lt;service class="org.objectweb.joram.mom.proxies.ConnectionManager"
             args="root root"/&gt;
    &lt;service class="org.objectweb.joram.mom.proxies.tcp.TcpProxyService"
             args="16010"/&gt; <co xml:id="a3server.port" />

   &lt;/server&gt;
&lt;/config&gt;</screen><calloutlist>
          <callout arearefs="a3server.transaction">
            <para>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"</para>
          </callout>

          <callout arearefs="a3server.id">
            <para>Here can be set the server id and the host where the server
            run</para>
          </callout>

          <callout arearefs="a3server.port">
            <para>args specifies the port number the JORAM server is listening
            on</para>
          </callout>
        </calloutlist></para>

      <para>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, <emphasis role="bold">they should match the values
      set in the deployment descriptor of the RA</emphasis>, otherwise the
      adapter either will not connect to the JORAM server, or it will build
      improper connection factories.</para>

      <para>The joram_raconfig command allows to modify these parameters in
      all the configuration files.</para>

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

    <section>
      <info>
        <title>Resource Adapter configuration: ra.xml, jonas-ra.xml</title>
      </info>

      <para>The <filename>ra.xml</filename> file is the standard deployment
      descriptor for the JORAM adapter and the <filename>jonas-ra.xml
      </filename>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. <filename>jonas-ra.xml
      </filename>contains specific parameters such as pool parameters or jndi
      names, but also may redefine the parameters of some <filename>ra.xml
      </filename>files and override their values. Globally, a good way to
      proceed is to keep the original <filename>ra.xml </filename>file with
      the default values and to customize the configuration only in the
      <filename>jonas-ra.xml </filename>file.</para>

      <para>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:</para>

      <itemizedlist>
        <listitem>
          <para>With the RAConfig command to extract jonas-ra.xml, do the
          following:</para>

          <screen>RAConfig -path . joram_for_jonas_ra.rar</screen>

          <para>Then, to update the archive, do the following:</para>

          <screen>RAConfig -u jonas-ra.xml joram_for_jonas_ra.rar</screen>
        </listitem>

        <listitem>
          <para>Through the jonasAdmin console (refer to Administration guide
          for a complete description).</para>

          <para>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.</para>
        </listitem>

        <listitem>
          <para>Through the joram_raconfig utility (refer to joram_raconfig
          description for a complete description).</para>

          <para>This tool allows easy modification to the network parameters
          of the JORAM server in all the configuration files.</para>
        </listitem>
      </itemizedlist>

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

      <informaltable>
        <tgroup cols="3">
          <tbody>
            <row>
              <entry align="center">property name</entry>

              <entry align="center">description</entry>

              <entry align="center">possible values</entry>
            </row>

            <row>
              <entry>CollocatedServer</entry>

              <entry>Running mode of the JORAM server to which the adapter
              gives access.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>True: when deploying, the adapter starts a
                    collocated JORAM server.</para>
                  </listitem>

                  <listitem>
                    <para>False: when deploying, the adapter connects to a
                    remote JORAM server.</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default True value is then set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>PlatformConfigDir</entry>

              <entry>Directory where the <filename>a3servers.xml</filename>
              and <filename>joramAdmin.xml </filename>files are
              located.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Any String describing an absolute path (ex:
                    /myHome/myJonasRoot/conf).</para>
                  </listitem>

                  <listitem>
                    <para>Empty String, files will be searched in
                    $JONAS_BASE/conf</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default empty string is then set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>PersistentPlatform</entry>

              <entry>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.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>True: starts a persistent JORAM server.</para>
                  </listitem>

                  <listitem>
                    <para>False: starts a non-persistent JORAM server.</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default False value is then set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>ServerId</entry>

              <entry>Identifier of the JORAM server to start (not taken into
              account if the JORAM server is set as non-collocated).</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Identifier corresponding to the server to start
                    described in the a3servers.xml file (ex: 1).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default 0 value is then set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>ServerName</entry>

              <entry>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).</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Storage path of the persistent mode for the
                    collocated case (ex: /tmp/s0).</para>
                  </listitem>

                  <listitem>
                    <para>Name of the started server as described in the
                    a3servers.xml in the non collocated case (ex: s1)</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default s0 name is then set and the current
                    directory is used for storing the persistent data).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>AdminFileXML</entry>

              <entry>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.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Name of the file (ex: myAdminFile.xml).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default joramAdmin.xml name is then
                    set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>HostName</entry>

              <entry>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.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Any host name (ex: myHost).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default localhost name is then set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>ServerPort</entry>

              <entry>Port the JORAM server is listening on, used for accessing
              a remote JORAM server (non-collocated mode), and for building
              appropriate connection factories.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Any port value (ex: 16030).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default 16010 value is then set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>ConnectingTimer</entry>

              <entry>Duration in seconds during which connecting is attempted
              (connecting might take time if the server is temporarily not
              reachable)</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>0 : set for connecting only once and aborting if
                    connecting failed (default value)</para>
                  </listitem>

                  <listitem>
                    <para>n : duration in seconds</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>CnxPendingTimer</entry>

              <entry>Period in milliseconds between two ping requests sent by
              the client connection to the server;</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>0 means "notimer" (default value)</para>
                  </listitem>

                  <listitem>
                    <para>n: duration in milliseconds</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>TxPendingTimer</entry>

              <entry>Duration in seconds during which a JMS transacted (non
              XA) session might be pending; above that duration the session is
              rolled back and closed.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>0 value means "no timer".</para>
                  </listitem>

                  <listitem>
                    <para>n: duration in seconds</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>DeleteDurableSubscription</entry>

              <entry>Indicates the durable Subscriptions must be deleted when
              the consumer is closed</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>True (previous behaviour)</para>
                  </listitem>

                  <listitem>
                    <para>False (default value)</para>
                  </listitem>
                </itemizedlist></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>The <property>&lt;jonas-connection-definition</property>&gt;
      elements wrap properties related to the managed connection
      factories:</para>

      <para>There are three managed connection factories:</para>

      <itemizedlist>
        <listitem>
          <para>A Queue managed connection factory registered in JNDI with the
          name <emphasis role="bold">QCF</emphasis></para>
        </listitem>

        <listitem>
          <para>A Topic managed connection factory registered in JNDI with the
          name <emphasis role="bold">TCF</emphasis></para>
        </listitem>

        <listitem>
          <para>A managed connection factory registered in JNDI with the name
          <emphasis role="bold">CF</emphasis></para>
        </listitem>
      </itemizedlist>

      <para>Here are the properties that can be configured for each managed
      connection factory:</para>

      <informaltable>
        <tgroup cols="3">
          <tbody>
            <row>
              <entry align="center">property name</entry>

              <entry align="center">description</entry>

              <entry align="center">possible values</entry>
            </row>

            <row>
              <entry>jndi-name</entry>

              <entry>Name used for binding the constructed connection
              factory.</entry>

              <entry><para>Any name (ex: myQueueConnectionFactory). Default
              values are</para><itemizedlist>
                  <listitem>
                    <para><emphasis role="bold">QCF </emphasis>for the Queue
                    managed connection factory</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">TCF</emphasis> for the Topic
                    managed connection factory</para>
                  </listitem>

                  <listitem>
                    <para><emphasis role="bold">CF </emphasis>for the managed
                    connection factory</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>UserName</entry>

              <entry>Default user name that will be used for opening JMS
              connections.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Any name (ex: myName).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default <emphasis>anonymous</emphasis> name
                    will be set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>Password</entry>

              <entry>Default user password that will be used for opening JMS
              connections.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Any name (ex: myPass).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default <emphasis>anonymous</emphasis>
                    password will be set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>

            <row>
              <entry>Collocated</entry>

              <entry>Specifies if the connections that will be created from
              the factory should be TCP or local-optimized connections</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>True (for building local-optimized
                    connections).</para>
                  </listitem>

                  <listitem>
                    <para>False (for building TCP connections).</para>
                  </listitem>

                  <listitem>
                    <para>Nothing (default TCP mode will be set).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para></para>

      <para>The &lt;jonas-activationspec&gt; element wraps a property related
      to inbound messaging:</para>

      <informaltable>
        <tgroup cols="3">
          <tbody>
            <row>
              <entry align="center">property name</entry>

              <entry align="center">description</entry>

              <entry align="center">possible values</entry>
            </row>

            <row>
              <entry>jndi-name</entry>

              <entry>Binding name of a JORAM object to be used by 2.1
              MDBs.</entry>

              <entry><itemizedlist>
                  <listitem>
                    <para>Any name (by default:joramActivationSpec).</para>
                  </listitem>
                </itemizedlist></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para></para>

      <para xml:id="jmsra.poolingtag">The Pooling Tags are the same than those
      for other RAs:</para>

      <para><informaltable>
          <tgroup cols="3">
            <tbody>
              <row>
                <entry align="center">property name</entry>

                <entry align="center">description</entry>

                <entry align="center">possible values</entry>
              </row>

              <row>
                <entry>pool-init</entry>

                <entry>Initial size of the managed connection pool</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 (default value)</para>
                    </listitem>

                    <listitem>
                      <para>n</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-min</entry>

                <entry>Minimum size of the managed connection pool.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 (default value)</para>
                    </listitem>

                    <listitem>
                      <para>n</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-max</entry>

                <entry>Maximum size of the managed connection pool.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>n</para>
                    </listitem>

                    <listitem>
                      <para>-1 = unlimited (default value)</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-max-age-minutes</entry>

                <entry>Maximum number of minutes to keep the managed
                connection in the pool.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 = an unlimited amount of time.</para>
                    </listitem>

                    <listitem>
                      <para>n in minutes</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pstmt-max</entry>

                <entry>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.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 = unlimited</para>
                    </listitem>

                    <listitem>
                      <para>n (default value = 10)</para>
                    </listitem>

                    <listitem>
                      <para>-1 = cache disabled</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-max-opentime</entry>

                <entry>Identifies the maximum number of minutes that a managed
                connection can be left busy.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 = an unlimited amount of time (default
                      value).</para>
                    </listitem>

                    <listitem>
                      <para>n in minutes</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-max-waiters:</entry>

                <entry>identifies the maximum number of waiters for a managed
                connection. Default value is 0.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 (default value)</para>
                    </listitem>

                    <listitem>
                      <para>n</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-max-waittime</entry>

                <entry>identifies the maximum number of seconds that a waiter
                will wait for a managed connection. Default value is
                0.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>0 (default value)</para>
                    </listitem>

                    <listitem>
                      <para>n in seconds</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>

              <row>
                <entry>pool-sampling-period:</entry>

                <entry>identifies the number of seconds that will occur
                between statistics samplings of the pool. Default is 30
                seconds.</entry>

                <entry><itemizedlist>
                    <listitem>
                      <para>n in seconds (default value = 30s)</para>
                    </listitem>
                  </itemizedlist></entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable></para>

      <para></para>
    </section>

    <section>
      <info>
        <title>JMS Applications Configuration</title>
      </info>

      <para><filename>joramAdmin.xml</filename> 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.</para>

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

      <para>The default file provided with <xi:include href="../variables.xml"
      xpointer="appserver" /> creates a queue bound with the name
      <emphasis>sampleQueue</emphasis>, a topic bound with the name
      <emphasis>sampleTopic</emphasis>, sets the
      <emphasis>anonymous</emphasis> user, and creates and binds non-managed
      connection factories named <emphasis>JCF,</emphasis>
      <emphasis>JQCF</emphasis> and <emphasis>JTCF</emphasis></para>

      <para><note>
          <para><itemizedlist>
              <listitem>
                <para>All administration tasks are performed by the server
                connected but may affect remote JORAM servers to which the
                adapter is connected through the <property>ServerId</property>
                attribute.</para>
              </listitem>

              <listitem>
                <para>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.</para>
              </listitem>
            </itemizedlist></para>
        </note></para>

      <para>The format of this file is XML. Here are some examples:</para>

      <itemizedlist>
        <listitem>
          <para>simple example:</para>

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

        <listitem>
          <para>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:</para>

          <screen>        &lt;Queue name="myQueue"&gt;
          &lt;freeReader/&gt;
          &lt;freeWriter/&gt;
          &lt;jndi name="myQueue"/&gt;
        &lt;/Queue&gt;</screen>
        </listitem>

        <listitem>
          <para>When the JORAM is not collocated, the AdminModule must be
          defined as follows:</para>

          <screen>      &lt;AdminModule&gt;
        &lt;connect host="localhost"
                 port="16020"
                 name="root"
                 password="root"/&gt;
      &lt;/AdminModule&gt;</screen>

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

        <listitem>
          <para>Possible parameters for a queue definition:</para>

          <screen>       &lt;Queue name=""
                 serverId=""
                 className=""
                 dmq=""
                 nbMaxMsg=""
                 threshold=""&gt;
         &lt;property name="" value=""/&gt;
         &lt;property name="" value=""/&gt;
         &lt;reader user=""/&gt;
         &lt;writer user=""/&gt;
         &lt;freeReader/&gt;
         &lt;freeWriter/&gt;
         &lt;jndi name=""/&gt;
         &lt;/Queue&gt;</screen>
        </listitem>

        <listitem>
          <para>Possible parameters for a topic definition:</para>

          <screen>      &lt;Topic name=""
                parent=""
                serverId=""
                className=""
                dmq=""&gt;
        &lt;property name="" value=""/&gt;
        &lt;property name="" value=""/&gt;
        &lt;reader user=""/&gt;
        &lt;writer user=""/&gt;
        &lt;freeReader/&gt;
        &lt;freeWriter/&gt;
        &lt;jndi name=""/&gt;
      &lt;/Topic&gt;</screen>
        </listitem>

        <listitem>
          <para>Example of a dead message queue definition:</para>

          <screen>      &lt;DMQueue name="DMQ"
                  serverId="0"&gt;
        &lt;reader user="anonymous"/&gt;
        &lt;writer user="anonymous"/&gt;
        &lt;freeReader/&gt;
        &lt;freeWriter/&gt;
        &lt;jndi name="DMQ"/&gt;
      &lt;/DMQueue&gt;</screen>
        </listitem>

        <listitem>
          <para>Example of a scheduler queue definition:</para>

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

        <listitem>
          <para>Example of a clustered queues destination:</para>

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

    <section>
      <info>
        <title>joram_raconfig command</title>
      </info>

      <para></para>

      <xi:include href="../command_guide.xml" xpointer="element(/1/5/3)" />
    </section>
  </section>

  <section>
    <info>
      <title>JORAM's Resource Adapter tuning</title>
    </info>

    <para></para>

    <section>
      <info>
        <title>ManagedConnection Pool</title>
      </info>

      <para>A pool of ManagedConnection is defined for each factory
      (connection definition) specified in the jonas-ra.xml file. See the pool
      parameters in the <xref linkend="jmsra.poolingtag" />.</para>
    </section>

    <section>
      <info>
        <title>Session/Thread pool in the JORAM RA</title>
      </info>

      <para>The JORAM RA manages a pool of session/thread for each connection
      and, by default, the maximum number of parallel sessions is set to
      10.</para>

      <para>When linked with an message-driven bean, this maximum number of
      entries in the pool corresponds to the maximum number of messages that
      can be processed in parallel per message-driven bean. A session is
      released to the pool just after the message processing (onMessage()).
      When the maximum is reached, the inquiries for a session creation are
      blocked until a session becomes available in the pool.</para>

      <para>The <property>maxNumberOfWorks </property>property can be set in
      the message-driven bean standard deployment descriptor. For example, the
      code below can be added to limit the number of parallel sessions to 100
      (default value is 10).</para>

      <screen>     &lt;activation-config-property&gt;
     &lt;activation-config-property-name&gt;maxNumberOfWorks&lt;/activation-config-property-name&gt;
     &lt;activation-config-property-value&gt;100&lt;/activation-config-property-value&gt;
     &lt;/activation-config-property&gt;</screen>

      <para>As this parameter set the max number of messages that can be
      treated simultaneously, the <property>max-cache-size </property>must be
      set accordingly in the specific deployment descriptor.</para>
    </section>
  </section>

  <section>
    <info>
      <title>Undeploying and Redeploying a JORAM Adapter</title>
    </info>

    <para>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 the server will be
    retrieved in its pre-undeployment 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.</para>

    <para>In the collocated persistent case, if the intent is to start a brand
    new JORAM server, its persistence directory should be removed. This
    directory is located in JOnAS' running directory and has the same name as
    the JORAM server (for example, s0/ for server "s0").</para>
  </section>
</section>
