<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" 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" xml:id="commands.raconfig">
  <title>RAConfig command</title>

  <para>Generate a <xi:include href="../variables.xml" xpointer="appserver"/> specific resource adapter configuration file or a
  resource adapter file</para>

  <section>
    <title>Synopsis</title>

    <cmdsynopsis>
      <command>RAConfig</command>

      <arg rep="repeat">options</arg>

      <arg choice="plain" rep="norepeat">InputFileName</arg>

      <arg>OutputFileName</arg>
    </cmdsynopsis>
  </section>

  <section>
    <title>Description</title>

    <para>The <emphasis>RAConfig </emphasis>utility provides the capability to
    create a <xi:include href="../variables.xml" xpointer="appserver"/> specific resource adapter configuration file (jonas-ra.xml)
    from a ra.xml file, or update a resource adapter file.</para>

    <para>With this command it is possible to :</para>

    <itemizedlist>
      <listitem>
        <para>extract a <xi:include href="../variables.xml" xpointer="appserver"/> specific resource adapter configuration file
        (<emphasis>jonas-ra.xml)</emphasis> from an <emphasis>ra.xml
        </emphasis>file (see option <emphasis role="bold">-path)</emphasis></para>
      </listitem>

      <listitem>
        <para>create a new <xi:include href="../variables.xml" xpointer="appserver"/> specific resource adapter configuration file
        (<emphasis>jonas-ra.xml)</emphasis> from an <emphasis>ra.xml
        f</emphasis>ile (see option <emphasis role="bold">-new)</emphasis></para>
      </listitem>

      <listitem>
        <para>create a resource adapater file (<emphasis>.rar file)</emphasis>
        from a dataSource.properties file (see option <emphasis role="bold">-p)</emphasis></para>
      </listitem>

      <listitem>
        <para>update a resource adapter file with a <emphasis>jonas-ra.xml
        </emphasis>(see option <emphasis role="bold">-u</emphasis>)</para>
      </listitem>
    </itemizedlist>

    <para>The <emphasis>InputFileName </emphasis>is the file name of a the
    resource adapter.</para>

    <para>The <emphasis>OutputFileName</emphasis> is the file name of an
    output resource adapter. This parameter is used with the <emphasis role="bold">-p </emphasis>(required) or <emphasis role="bold">-u
    </emphasis>(optional) options.</para>
  </section>

  <section>
    <title>Options</title>

    <variablelist>
      <varlistentry>
        <term>-? or -help</term>

        <listitem>
          <para>Give a summary of the options.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-p or -property database_properties_file_name</term>

        <listitem>
          <para>Specifie the name of the &lt;database&gt;.properties file to
          process. The result of this processing will be a jonas-ra.xml file
          that will update the /META-INF/jonas-ra.xml file in the output
          rar.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-dm, -ds, -cp, -xa</term>

        <listitem>
          <para>These options are related to the option <emphasis role="bold">-p</emphasis> above.</para>

          <para>They specify the rarlink value to configure respectively
          DriverManager, DataSource, ConnectionPoolDataSource and
          XAConnection. If <emphasis role="bold">-dm </emphasis>is used, then
          the conversion will be a direct reflection of the values specified
          in the <emphasis role="bold">-p
          </emphasis>&lt;database&gt;.properties file. If any of the other
          values are specified, then the jonas-ra.xml created will reflect
          options from the <emphasis role="bold">-p
          </emphasis>&lt;database&gt;.properties file and the user must edit
          the file based on information from the database provider for the
          specified type of datasource. Each database provider may have
          different config properties that need to be set and will be included
          in the database provider's documentation.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-path output_directory</term>

        <listitem>
          <para>Specify the directory name to place the extracted jonas-ra.xml
          file.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-new</term>

        <listitem>
          <para>Don't extract jonas-ra.xml but create a new one. The default
          value is the system property for
          <constant>java.io.tmpdir</constant>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-update or -u inputname</term>

        <listitem>
          <para>Specify the name of the XML file to process. This file will
          update the <emphasis>/META-INF/jonas-ra.xml </emphasis>file in the
          rar. If this argument is used, it is the only argument
          executed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-rarlink rarlink</term>

        <listitem>
          <para>Specify the jndi name of an rar file with which to link. This
          option can be used when this rar file will inherit all attributes
          associated with the specified jndi name. If this option is specified
          in the jonas-ra.xml file, it is the only file needed in the rar, and
          the ra.xml file will be processed from the rarlink file.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-securityfile security_file_to_process</term>

        <listitem>
          <para>Specify the security property file to process and add security
          information to jonas-ra.xml. This will map the specified principal
          name to the user on the EIS system. The specified file must be in
          the following form: <emphasis>principal = user::password
          </emphasis>. When used in conjunction with the <emphasis role="bold">-encrypt</emphasis> option, then the resulting
          information will be encrypted in jonas-ra.xml.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-encrypt</term>

        <listitem>
          <para>Used with <emphasis role="bold">-securityfile</emphasis> to
          encrypt the specified passwords.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-jndiname jndiname</term>

        <listitem>
          <para>This option is deprecated with 1.5 Resource Adapter.</para>

          <para>For 1.0 Resource Adapter, this specifies the JNDI name of the
          connection factory. This name corresponds to the name of the
          &lt;jndi-name&gt; element of the &lt;jonas-resource&gt; element in
          the <xi:include href="../variables.xml" xpointer="appserver"/> specific deployment descriptor. This name is used by the
          resource service for registering in JNDI the connection factory
          corresponding to this resource adapter.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-novalidation</term>

        <listitem>
          <para>Turn off the xml dtd/schema validation.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>Examples</title>

    <variablelist>
      <varlistentry>
        <term>RAConfig -dm -p MySQL1 $JONAS_ROOT/repositories/maven2-internal/org/ow2/jonas/jonas-jca-jdbc-dm/&lt;jonas-version&gt;/jonas-jca-jdbc-dm-&lt;jonas-version&gt;
        MySQL_dm</term>

        <listitem>
          <para>Generate a MySQL_dm.rar file linked to <filename>jonas-jca-jdbc-dm-&lt;jonas-version&gt;.rar</filename>.</para>
          <para>The jonas-ra.xml file inserted is created with values coming from the
          ra.xml file of the <filename>jonas-jca-jdbc-dm-&lt;jonas-version&gt;.rar </filename>
          and values from the MySQL1.properties file</para>
          <para>This rar file can then be deployed and will replace the
          configured MySQL1 datasource.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RAConfig -path . XX.rar</term>

        <listitem>
          <para>Extract the jonas-ra.xml of XX.rar in the working
          directory</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RAConfig -u jonas-ra.xml MyRA.rar</term>

        <listitem>
          <para>Update/insert the jonas-ra.xml file into the MyRA.rar
          file</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
</section>
