j2ee connector programmer's guide.htm

本人收集的关于Java Connector Architecture的资料

      <jdbc-test-statement>select 1</jdbc-test-statement>
    </jdbc-conn-params>
    <jonas-config-property>
      <jonas-config-property-name>url</jonas-config-property-name>
      <jonas-config-property-value>jdbc:oracle:thin:@test:1521:DB1</jonas-config-property-value>
    </jonas-config-property>
    .
    .
  &lt;/jonas-resource&gt;</PRE>
<H2><A name=PG_Connector-Packaging></A>Resource Adapter (RAR) Packaging</H2>
<P>Resource Adapters are packaged for deployment in a standard Java programming 
language Archive file called an <EM>RAR</EM> file (Resource Adapter ARchive). 
This file can contain the following:</P>
<DL>
  <DT><STRONG>Resource Adapters' deployment descriptor</STRONG> 
  <DD>The RAR file must contain the deployment descriptors, which are made up 
  of: 
  <UL>
    <LI>The standard xml deployment descriptor, in the format defined in the 
    J2EE 1.4 specification. Refer to 
    <CODE>$JONAS_ROOT/xml/connector_1_5.xsd</CODE>&nbsp;or&nbsp; <A 
    href="http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd">http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd</A>. 
    This deployment descriptor must be stored with the name 
    <EM>META-INF/ra.xml</EM> in the RAR file. 
    <LI>The JOnAS-specific XML deployment descriptor in the format defined in 
    <EM>$JONAS_ROOT/xml/jonas-ra_X_Y.xsd</EM>. This JOnAS deployment descriptor 
    must be stored with the name <EM>META-INF/jonas-ra.xml</EM> in the RAR file. 
    </LI></UL></DD></DL>
<DL>
  <DT><STRONG>Resource adapter components (jar)</STRONG> 
  <DD>One or more jars which contain the java interfaces, implementation, and 
  utility classes required by the resource adapter. 
  <DT><STRONG>Platform-specific native libraries</STRONG> 
  <DD>One or more native libraries used by the resource adapter 
  <DT><STRONG>Misc</STRONG> 
  <DD>One or more html, image files, or locale files used by the resource 
  adapter. </DD></DL>
<P>Before deploying an RAR file, the JOnAS-specific XML must be configured and 
added. Refer to the <CODE><B><A 
href="http://jonas.objectweb.org/current/doc/PG_Connector.html#PG_Connector-RAConfig">RAConfig 
section</A></B></CODE> for information.</P>
<H2><A name=PG_Connector-Use></A>Use and Deployment of a Resource Adapter</H2>
<P>Accessing Resource Adapter involves the following steps:</P>
<UL>
  <LI>The bean provider must specify the connection factory requirements by 
  declaring a <I>resource manager connection factory reference</I> in its EJB 
  deployment descriptor. For example: <PRE>      &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;
    </PRE>The mapping to the actual JNDI name of the <I>connection factory</I> 
  (here <CODE>adapt_1</CODE>) is done in the JOnAS-specific deployment 
  descriptor with the following element: <PRE>      &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;</PRE>
  <P>This means that the bean programmer will have access to a <I>connection 
  factory</I> instance using the JNDI interface via the 
  <EM>java:comp/env/eis/MyEIS</EM> name:</P><PRE>     // 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");</PRE>The bean 
  programmer can then get a connection by calling the method 
  <CODE>getConnection</CODE> on the <I>connection factory</I>. <PRE>      javax.resource.cci.Connection cx = cxf.getConnection();
    </PRE>The returned connection instance represents an application-level 
  handle to a physical connection for accessing the underlying EIS. <BR>After 
  finishing with the connection, it must be closed using the <CODE>close</CODE> 
  method on the <CODE>Connection</CODE> interface: <PRE>         cx.close();
    </PRE>
  <LI>
  <UL>
    <LI><A name=PG_Connector-RAConfig></A>The resource adapter must be deployed 
    before being used by the application. Deploying the resource adapter 
    requires the following: 
    <UL>
      <LI>
      <P>Build a <I>JOnAS-specific resource adapter configuration</I> file that 
      will be included in the resource adapter. <BR>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 <CODE><B><A 
      href="http://jonas.objectweb.org/current/doc/Tools.html#Tools-raconfig">RAConfig</A></B></CODE> 
      that is capable of building this XML file from an RA deployment descriptor 
      inside an RAR file. Example:</P><PRE>           RAConfig -j adap_1 ra
        </PRE>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). 
      <P>After configuring the jonas-ra.xml file created above, it can be added 
      to the resource adapter by executing the following:</P><PRE>           RAConfig -u jonas-ra.xml ra
        </PRE>This will add the xml file to the ra.rar file, which is now 
      ready for deployment. </LI></UL>
    <LI>The JOnAS <I>resource service</I> must be configured and started at 
    JOnAS launching time: <BR>In the <CODE>jonas.properties</CODE> file: 
    <UL>
      <LI>Verify that the name <CODE>resource</CODE> is included in the 
      <CODE>jonas.services</CODE> property. 
      <LI>Use one of the following methods to deploy an RAR file: 
      <UL>
        <LI>The names of the <I>resource adapter</I> 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. <PRE>         jonas.service.resource.resources  MyEIS.rar, MyEIS1
      </PRE>
        <LI>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. 
        <LI>Add the RAR via the "<CODE>jonas admin -a xxx.rar</CODE>" command. 
        <LI>Add the RAR via the JonasAdmin console. 
</LI></UL></LI></UL></LI></UL></LI></UL>
<H2><A name=PG_Connector-JDBC></A>JDBC Resource Adapters</H2>
<P>These generic JDBC resource adapters are supplied by JOnAS and are a 
replacement for the DBM service. Refer to <CODE><B><A 
href="http://jonas.objectweb.org/current/doc/Config.html#Config-JDBC-RAs">Configuring 
JDBC Resource Adapters</A></B></CODE> for a complete description and usage 
guide.</P>
<H2><A name=PG_Connector-JCA></A>Appendix: Connector Architecture 
Principles</H2>
<P>The Java Connector Architecture allows the connection of different Enterprise 
Information Systems (EIS) to an application server such as JOnAS. It defines a 
way for enterprise applications (based on EJB, servlet, JSP or J2EE clients) to 
communicate with existing EIS. This requires the use of a third party software 
component called "Resource Adapter" for each type of EIS, which should be 
previously deployed on the application server. The Resource Adapter is an 
architecture component comparable to a software driver, which connects the EIS, 
the application server, and the enterprise application (J2EE components in the 
case of JOnAS as application server). The RA provides an interface (the Common 
Client Interface or CCI) to the enterprise application (J2EE components) for 
accessing the EIS. The RA also provides standard interfaces for plugging into 
the application server, so that they can collaborate to keep all system-level 
mechanisms (transactions, security, and connection management) transparent from 
the application components.</P><IMG height=540 alt="JCA Architecture" 
src="J2EE Connector Programmer's Guide.files/jcaarch.gif" width=720 border=0> 
<P>The resource adapter plugs into JOnAS and provides connectivity between the 
EIS, JOnAS, and the application. The application performs "business logic" 
operations on the EIS data using the RA client API (CCI), while transactions, 
connections (including pooling), and security on the EIS is managed by JOnAS 
through the RA (system contract).</P></BODY></HTML>