<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" 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:lang="en" xml:id="resource.connector.using"><info><title>Use and Deployment of a Resource Adapter</title></info>
    
    <para>
      Accessing Resource Adapter involves the following steps:
    </para>
    <orderedlist>
      <listitem><para>
        The bean provider must specify the connection factory requirements by declaring a 
        resource manager connection factory reference
         in its EJB deployment descriptor. For example:     
        <screen>
      &lt;resource-ref&gt;
        &lt;res-ref-name&gt;eis/MyEIS&lt;/res-ref-name&gt;
        &lt;res-type&gt;javax.resource.cci.ConnectionFactory&lt;/res-type&gt;
        &lt;res-auth&gt;Container&lt;/res-auth&gt;
      &lt;/resource-ref&gt;
            </screen>
             The mapping to the actual JNDI name of the 
        connection factory
             (here 
        <code>
          adapt_1
        </code>
        ) is done in the JOnAS-specific deployment     descriptor with the following element:     
        <screen>
      &lt;jonas-resource&gt;
        &lt;res-ref-name&gt;eis/MyEIS&lt;/res-ref-name&gt;
        &lt;jndi-name&gt;adapt_1&lt;/jndi-name&gt;
      &lt;/jonas-resource&gt;        </screen>
          This means that the bean programmer will have access to a     
          connection factory
           instance using the JNDI interface via the     
          java:comp/env/eis/MyEIS
           name:
        <screen>
     // obtain the initial JNDI naming context
     Context inictx = new InitialContext();

     // perform JNDI lookup to obtain the connection factory
     javax.resource.cci.ConnectionFactory cxf =
             (javax.resource.cci.ConnectionFactory)
                  inictx .lookup("java:comp/env/eis/MyEIS");        </screen>
             The bean programmer can then get a connection by calling the method     
        <code>
          getConnection
        </code>
         on the 
        connection factory
        .     
        <screen>
      javax.resource.cci.Connection cx = cxf.getConnection();
            </screen>
             The returned connection instance represents an application-level handle     to a physical connection for accessing the underlying EIS. 
             After finishing with the connection, it must be closed using the     
        <code>
          close
        </code>
         method on the 
        <code>
          Connection
        </code>
         interface:     
        <screen>
         cx.close();
            </screen>
      </para></listitem>
      <listitem><para>
            The resource adapter must be deployed before being used by the       application. Deploying the resource adapter requires the following:</para> 
                <para>
                  Build a 
                  JOnAS-specific resource adapter configuration
                             file that will be included in the resource adapter. 
                             This jonas-ra XML file is used to configure the resource adapter in           the operational environment and reflects the values of all           properties declared in the deployment descriptor for the resource           adapter, plus additional JOnAS-specific configuration properties.           JOnAS provides a deployment tool 
                    <link xlink:href="command_guide.html#commands.raconfig">
                      RAConfig
                    </link>
                   that is           capable of building this XML file from an RA deployment descriptor           inside an RAR file. Example:
                </para>
                <screen>
           RAConfig -path . -j adap_1 ra
                        </screen><para>
                           These properties may be specific for each resource adapter and its           underlying EIS. They are used to configure the resource adapter via           its 
                <code>
                  managedConnectionFactory
                </code>
                 class. It is mandatory           that this class provide getter and setter method for each of its           supported properties (as it is required in the Connector           Architecture specification).  </para>         
                <para>
                  After configuring the jonas-ra.xml file created above, it can be           added to the resource adapter by executing the following:
                </para>
                <screen>
           RAConfig -u jonas-ra.xml ra
                        </screen><para>
                           This will add the xml file to the ra.rar file, which is now ready           for deployment.
          </para></listitem>
          <listitem><para>
            The JOnAS 
            resource service
             must be configured and started at       JOnAS launching time: 
                   In the 
            <code>
              jonas.properties
            </code>
             file:       
            <itemizedlist>
              <listitem><para>
                Verify that the name 
                <code>
                  resource
                </code>
                 is included in the           
                <code>
                  jonas.services
                </code>
                 property.
              </para></listitem>
              <listitem><para>
                Use one of the following methods to deploy an RAR file:           
                <itemizedlist>
                  <listitem><para>
                    The names of the 
                    resource adapter
                     files (the '.rar'               suffix is optional) must be added in the list of Resource               Adapters to be used in the               
                    <code>
                      jonas.service.resource.resources
                    </code>
                     property. If the               '.rar' suffix is not used on the property, it will be used when               trying to allocate the specified Resource Adapter.               
                    <screen>
         jonas.service.resource.resources  MyEIS.rar, MyEIS1
                          </screen>
                  </para></listitem>
                  <listitem><para>
                    Place the RAR file in the connectors autoload directory of               $JONAS_BASE, default value is $JONAS_BASE/rars/autoload. Note               that it may be different if               
                    <code>
                      jonas.service.resource.autoload
                    </code>
                     in               jonas.properties is configured differently.
                  </para></listitem>
                  <listitem><para>
                    Add the RAR via the 
                    <code>
                      jonas admin -a xxx.rar
                    </code>
                                   command.
                  </para></listitem>
                  <listitem><para>
                    Add the RAR via the JonasAdmin console.
                  </para></listitem>
                </itemizedlist>
              </para></listitem>
            </itemizedlist>
      </para></listitem>
    </orderedlist>
  </section>