User: allsopp
Date: 01/01/15 00:50:33
Added: documentation jca_config.html
Log:
Initial documentation for the JCA implementation.
Revision Changes Path
1.1 newsite/documentation/jca_config.html
Index: jca_config.html
===================================================================
<html>
<head>
<title>JBoss PRE-2.1: J2EE Connector Architecture Configuration</title>
<link rel="stylesheet" type="text/css" href="HowTo.css" title="style"/>
</head>
<body><div class="page">
<h1>JBoss PRE-2.1: J2EE Connector Architecture Configuration</h1>
<div class="para">
This section describes the configuration changes necessary in
order to use a resource adapter conforming to the J2EE Connector
Architecture (JCA) in your application.
</div>
<div class="para">
The JCA specifies how J2EE application components can access
resources other than those explicitly specified in the J2EE 1.2
specification. It will be part of the J2EE 1.3
specification. You can read more about the JCA at its <a
href="http://java.sun.com/j2ee/connector/">official home
page</a>.
</div>
<h2>Terminology</h2>
<div class="para">
<dl>
<dt>Resource</dt>
<dd>an external system that provides some service to
application components. Examples include JDBC databases
and mainframe systems.
<dt>Resource adapter</dt>
<dt>Connector</dt>
<dd>an application component that implements access to a
resource</dd>
<dt>Resource instance</dt>
<dd>a particular configuration of a resource, e.g. an Oracle
database running on machine "foo" at port "1234".</dd>
<dt>Connection factory</dt>
<dd>an object, available through JNDI, that provides access to
connections to a particular resource instance</dd>
</dl>
</div>
<h2>JBoss Configuration</h2>
<div class="para">
There are two steps that must be performed to provide access to
a connection factory in JBoss:
<ol>
<li>Configure a connection factory in <code>jboss.jcml</code>
<li>Deploy the resource adapter
</ol>
</div>
<h3>Connection Factory Configuration</h3>
<div class="para">Connection factories are created by the
<code>ConnectionFactoryLoader</code> MBean, so an
<code><mbean></code> section must be added to
<code>jboss.jcml</code> for each connection factory that is
required. The format for this entry is as follows.</div>
<pre class="code">
<mbean code="org.jboss.resource.ConnectionFactoryLoader"
name="J2EE:service=ConnectionFactoryLoader">
<!-- General attributes -->
<attribute name="name">value</attribute>
<!-- Security attributes -->
<attribute name="name">value</attribute>
<!-- Connection pooling attributes -->
<attribute name="name">value</attribute>
</mbean>
</pre>
<h4>General Attributes</h4>
<div class="para">
<table border="1">
<caption>General <code>ConnectionFactoryLoader</code> attributes</caption>
<thead>
<tr>
<th>Name</th> <th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>FactoryName</td> <td>The name of the connection
factory. This is the name under
which the connection factory will
be bound in JNDI</td>
</tr>
<tr>
<td>RARDeployerName</td> <td>The name of the MBean that will
deploy the resource adapter
that this connection factory
relates to.</td>
</tr>
<tr>
<td>ResourceAdapterName</td> <td>The name of the resource
adapter for which this
connection factory will
create connections. This is
the name given in the
resource adapter's
<code><display-name></code>
deployment descriptor
element.</td>
</tr>
<tr>
<td>Properties</td> <td>The properties to set on the
resource adapter to configure it to
connect to a particular resource
instance. This is in
<code>java.util.Properties.load</code>
format (essentially one property per
line, name=value).</td>
</tr>
</tbody>
</table>
</div>
<h4>Security Attributes</h4>
<div class="para">TBD - no interesting options yet</div>
<h4>Connection Pooling Attributes</h4>
<div class="para">TBD - mostly the same as for JDBC connection pools</div>
<h3>Deploying the Resource Adapter</h3>
<div class="para">
Currently the J2EE deployer does not recognise resource
adapters, so it is not possible to deploy them with the auto
deployer or as part of an EAR. This functionality will be added
at a later date.
</div>
<div class="para">
To deploy a resource adapter, and thus activate any connection
factories configured for it, invoke the
<code>deploy(String)</code> operation on the
<code>RARDeployer</code> MBean, passing it a URL pointing to the
RAR file containing the resource adapter. The RAR deployer can
also deploy directories that are structured like a RAR
file.
</div>
<h2>Example - BlackBox Example Adapter from Sun</h2>
<div class="para">TBD - see <code>jboss.jcml</code> for now.</div>
<h2>Implementation Status</h2>
<div class="para">
<em>Note that this section is likely to lag the latest
developments in CVS. When a stable release including the JCA is
made then this section should reflect the status of the released
implementation.</em>
</div>
<h3>Unimplemented Features</h3>
<ul>
<li>Local transaction optimisation</li>
</ul>
<h3>Limitations</h3>
<ul>
<li>Transaction association doesn't work properly unless the
transaction is started <strong>before</strong> the connection
is obtained.</li>
</ul>
<div class="footer">
Author: <a href="mailto:[EMAIL PROTECTED]">Toby Allsopp</a><br/>
Revision: $Id: jca_config.html,v 1.1 2001/01/15 08:50:33 allsopp Exp $
</div>
</div></body>
</html>
<!-- LocalWords: PRE EE HowTo css JCA JDBC JNDI MBean ConnectionFactoryLoader
-->
<!-- LocalWords: TBD recognise URL RAR RAR CVS
-->
