User: tobyallsopp
Date: 01/04/16 01:59:48
Modified: src/docs howtojca.xml
Log:
Updated JBossCX docs.
Revision Changes Path
1.5 +130 -135 manual/src/docs/howtojca.xml
Index: howtojca.xml
===================================================================
RCS file: /cvsroot/jboss/manual/src/docs/howtojca.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- howtojca.xml 2001/04/08 03:32:58 1.4
+++ howtojca.xml 2001/04/16 08:59:48 1.5
@@ -1,5 +1,5 @@
<?xml version = "1.0" encoding = "UTF-8"?>
-<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"docbookx/docbookx.dtd"> -->
+<!-- $Id: howtojca.xml,v 1.5 2001/04/16 08:59:48 tobyallsopp Exp $ -->
<section>
<sectioninfo>
@@ -37,38 +37,35 @@
components through JNDI.
</para>
</section>
+
<section>
<title>Contents</title>
<itemizedlist>
<listitem>
<para>
- <link linkend = "jca1">Terminology</link>
+ <xref linkend="jca1" endterm="jca1.title"/>
</para>
</listitem>
-
<listitem>
<para>
- <link linkend = "jca2">JBoss Configuration</link>
+ <xref linkend="jca2" endterm="jca2.title"/>
</para>
</listitem>
-
<listitem>
<para>
- <link linkend = "jca3">Example - Black Box Example Adapter
- from Sun</link>
+ <xref linkend="jca3" endterm="jca3.title"/>
</para>
</listitem>
-
<listitem>
<para>
- <link linkend = "jca4">Implementation Status</link>
+ <xref linkend="jca4" endterm="jca4.title"/>
</para>
</listitem>
-
</itemizedlist>
</section>
- <section id = "jca1">
- <title>Terminology</title>
+
+ <section id="jca1">
+ <title id="jca1.title">Terminology</title>
<table>
<title>Terminology</title>
@@ -124,8 +121,8 @@
</section>
- <section id = "jca2">
- <title>JBoss Configuration</title>
+ <section id="jca2">
+ <title id="jca2.title">JBoss Configuration</title>
<para>
There are two steps that must be performed to provide access to
a connection factory in JBoss:
@@ -133,7 +130,8 @@
<orderedlist>
<listitem>
- <para>Configure a connection factory in jboss.jcml</para>
+ <para>Configure a connection factory in
+ <filename>jboss.jcml</filename></para>
</listitem>
<listitem>
<para>Deploy the resource adapter</para>
@@ -145,9 +143,10 @@
<para>
Connection factories are created by the
- ConnectionFactoryLoader MBean, so an <![CDATA[<mbean> section
- must be added to jboss.jcml for each connection factory that
- is required. The format for this entry is as follows.]]>
+ <classname>ConnectionFactoryLoader</classname> MBean, so an
+ <literal><![CDATA[<mbean>]]></literal> section must be added
+ to <filename>jboss.jcml</filename> for each connection factory
+ that is required. The format for this entry is as follows.
</para>
<programlisting><![CDATA[
@@ -191,8 +190,9 @@
<entry>
The name of the resource adapter for which this
connection factory will create connections. This is
- the name given in the resource adapter's <![CDATA[
- <display-name>]]> deployment descriptor element
+ the name given in the resource adapter's
+ <literal><![CDATA[ <display-name>]]></literal>
+ deployment descriptor element
</entry>
</row>
<row>
@@ -200,8 +200,9 @@
<entry>
The properties to set on the resource adapter to
configure it to connect to a particular resource
- instance. This is in java.util.Properties.load format
- (essentially one property per line, name=value)
+ instance. This is in
+ <methodname>java.util.Properties.load</methodname>
+ format (essentially one property per line, name=value)
</entry>
</row>
<row>
@@ -209,138 +210,131 @@
<entry>
The name of the connection manager factory to
use. This is the name given in a previously defined
- ConnectionManagerFactoryLoader MBean. Currently there
- are two choices: MinervaSharedLocalCMFactory and
- MinervaXACMFactory. The former should be used for
- resource adapters that support local transactions and
- the latter for those that support XA transactions.
+ <classname>ConnectionManagerFactoryLoader</classname>
+ MBean. Currently there are two choices:
+ <classname>MinervaSharedLocalCMFactory</classname> and
+ <classname>MinervaXACMFactory</classname>. The former
+ should be used for resource adapters that support
+ local transactions and the latter for those that
+ support XA transactions.
</entry>
</row>
<row>
<entry>ConnectionManagerProperties</entry>
<entry>
- The properties (in java.util.Properties.load format)
- to set on the connection manager for this connection
- factory. These properties control things such as
- connection pooling parameters. The example connection
- factory in jboss.jcml shows the possible properties
- for the Minerva connection managers
+ The properties (in
+ <methodname>java.util.Properties.load</methodname>
+ format) to set on the connection manager for this
+ connection factory. These properties control things
+ such as connection pooling parameters. The example
+ connection factory in <filename>jboss.jcml</filename>
+ shows the possible properties for the Minerva
+ connection managers
</entry>
</row>
</tbody>
</tgroup>
</table>
- <!-- <simplelist type="horiz" columns="2">
- <member>NAME</member>
- <member>DESCRIPTION</member>
-
- <member>FactoryName</member>
- <member>The name of the connection factory. This is the name under which the
- connection factory will be bound in JNDI</member>
-
- <member>RARDeployerName</member>
- <member>The name of the MBean that will deploy the resource adapter that this
- connection factory relates to.</member>
- <member>ResourceAdapterName</member>
- <member>The name of the resource adapter for which this connection factory will
- create connections. This is the name given in the resource adapter's
- <![CDATA[ <display-name>]]> deployment descriptor element</member>
- <member>Properties</member>
- <member>The properties to set on the resource adapter to configure it to
connect to a
- particular resource instance. This is in java.util.Properties.load format
- (essentially one property per line, name=value)</member>
- <member>ConnectionManagerFactoryName</member>
- <member>The name of the connection manager factory to use. This is the name
given
- in a previously defined ConnectionManagerFactoryLoader MBean.
- Currently there are two choices: MinervaSharedLocalCMFactory and
- MinervaXACMFactory. The former should be used for resource adapters that
- support local transactions and the latter for those that support XA
- transactions.</member>
- <member>ConnectionManagerProperties</member>
- <member>The properties (in java.util.Properties.load format) to set on the
- connection manager for this connection factory. These properties control
- things such as connection pooling parameters. The example connection
- factory in jboss.jcml shows the possible properties for the Minerva
- connection managers.</member>
- </simplelist> -->
-
- <para>Security Attributes</para>
- <para>TBD - no interesting options yet</para>
+ <table>
+ <title>Security Attributes</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>PrincipalMappingClass</entry>
+ <entry>
+ The name of the class that maps from the principal on
+ behalf of whom the application component method is
+ executing to the principal that will be used for
+ access to the resource. This class must implement the
+ <classname>org.jboss.resource.security.PrincipalMapping</classname>
+ interface.
+ </entry>
+ </row>
+ <row>
+ <entry>PrincipalMappingProperties</entry>
+ <entry>
+ The properties (in
+ <methodname>java.util.Properties.load</methodname>
+ format) to pass to the principal mapping
+ implementation specified above.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
</section>
<section>
<title>Deploying the Resource Adapter</title>
<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.
+ adapters, so it is not possible to deploy them as part of an
+ EAR. This functionality will be added at a later date.
</para>
-
<para>
- To deploy a resource adapter, and thus activate any connection
- factories configured for it, invoke the deploy(String)
- operation on the RARDeployer 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.
+ However, the <classname>AutoDeployer</classname> service is
+ configured to automatically deploy resource adapters whose RAR
+ files are placed in the <filename>deploy</filename> directory.
+ So, to deploy a resource adapter, simply place the RAR file
+ containing it into the <filename>deploy</filename> directory,
+ just as you would for an ejb-jar file.
</para>
-
- <para>
- The easiest way to invoke operations on MBeans is using the
- HTML adapter that is, by default, accessible on port 8082,
- i.e. point a browser at http://localhost:8082 if running the
- browser on the machine running JBoss. Then find the
- RARDeployer MBean and it should be self explanatory from
- there.
- </para>
</section>
</section>
-
- <section id = "jca3">
- <title>Example - Black Box Example Adapter from Sun</title>
- <para>
- For this example you will need Sun's example resource adapter,
- available from the files section under documentation at <ulink
- url="http://www.jboss.org/">jboss.org</ulink>. We will use the
- local transaction version, named
- <filename>blackbox-tx.rar</filename>. The source code for this
- resource adapter is also available, under the name
- <filename>connector-1_0-ea-src.zip</filename> - this is useful
- if writing your own adapter.
- </para>
- <para>
- This resource adapter accesses a JDBC 2.0 compliant
- database. The advantage of this is that you don't need any weird
- or wacky resource to access and that you can compare the
- behaviour with a straight JDBC connection pool.
+ <section id="jca3">
+ <title id="jca3.title">Example - Minerva JDBC Resource
+ Adapter</title>
+ <para>
+ Included with JBoss are two resource adapters, part of the
+ Minerva project, that implement JDBC
+ <classname>DataSource</classname>s. These resource adpaters are
+ installed in the <filename>deploy/lib</filename> directory and
+ are therefore deployed when JBoss starts up.
+ </para>
+ <para>
+ In this example we will use the local transaction version of the
+ resource adapter, <filename>minerva-jdbc-1.0b3.rar</filename>.
+ This resource adapter accesses a JDBC 2.0 compliant database.
+ The advantage of this is that you don't need any weird or wacky
+ resource to access and that you can compare the behaviour with a
+ straight JDBC connection pool.
</para>
<para>
In order to make a connection factory from this resource adapter
available to application components, we need to add the
- ConnectionFactoryLoader MBean that will create the connection
- factory from the resource adapter when it is deployed. We will
- create a connection factory called BlackBoxDS that will appear
- in JNDI at java:/BlackBoxDS. Below is the MBean definition that
- we will use (this is taken from the default jboss.jcml.
+ <classname>ConnectionFactoryLoader</classname> MBean that will
+ create the connection factory from the resource adapter when it
+ is deployed. We will create a connection factory called
+ <literal>MinervaDS</literal> that will appear in JNDI at
+ <literal>java:/BlackBoxDS</literal>. Below is the MBean
+ definition that we will use (this is taken from the default
+ <filename>jboss.jcml</filename>).
</para>
-
<programlisting><![CDATA[
-<!-- Example connection factory for the example "Black Box" resource
- adapter. This points at the same database as DefaultDS. -->
+<!-- Connection factory for the Minerva JDBC resource adapter. This
+ points at the same database as DefaultDS. -->
<mbean code="org.jboss.resource.ConnectionFactoryLoader"
- name="JCA:service=ConnectionFactoryLoader,name=BlackBoxDS">
- <attribute name="FactoryName">BlackBoxDS</attribute>
+ name="JCA:service=ConnectionFactoryLoader,name=MinervaDS">
+ <attribute name="FactoryName">MinervaDS</attribute>
<attribute name="RARDeployerName">JCA:service=RARDeployer</attribute>
- <attribute name="ResourceAdapterName">Black Box LocalTx Adapter</attribute>
+ <attribute name="ResourceAdapterName">
+ Minerva JDBC LocalTransaction ResourceAdapter
+ </attribute>
<attribute name="Properties">
ConnectionURL=jdbc:HypersonicSQL:hsql://localhost:1476
</attribute>
- <attribute name="ConnectionManagerFactoryName"
- >MinervaSharedLocalCMFactory</attribute>
+ <attribute name="ConnectionManagerFactoryName">
+ MinervaSharedLocalCMFactory
+ </attribute>
<!-- See the documentation for the specific connection manager
implementation you are using for the properties you can set -->
<attribute name="ConnectionManagerProperties">
@@ -363,8 +357,9 @@
</attribute>
<!-- Principal mapping configuration -->
- <attribute name="PrincipalMappingClass"
- >org.jboss.resource.security.ManyToOnePrincipalMapping</attribute>
+ <attribute name="PrincipalMappingClass">
+ org.jboss.resource.security.ManyToOnePrincipalMapping
+ </attribute>
<attribute name="PrincipalMappingProperties">
userName=sa
password=
@@ -372,7 +367,6 @@
</mbean>
]]></programlisting>
-
<para>
Note that the connection manager we have chosen is the Minerva
local transaction connection manager. It is important to choose
@@ -380,28 +374,29 @@
resource adapter. This choice should be automated in the future.
</para>
<para>
- Once jboss.jcml is set up with the desired connection factory
- loaders, start JBoss and bring up the HTML JMX connector which
- lives on port 8082 by default. If your browser is running on the
- same box as JBoss then you can just go to
- http://localhost:8082. Then find the RARDeployer MBean and
- invoke the deploy operation, passing it the URL to the resource
- adapter you want to deploy. In this case it is the path to
- blackbox-tx.rar which you should save somewhere local.
+ Once <filename>jboss.jcml</filename> is set up with the desired
+ connection factory loaders, start JBoss and the connection
+ factory <literal>java:/MinervaDS</literal> should be created.
</para>
-
<para>
Assuming that the deployment was successful, you should now have
- a connection factory bound in JNDI at java:/BlackBoxDS that you
- can use just like a normal JDBC DataSource.
+ a connection factory bound in JNDI at
+ <literal>java:/MinervaDS</literal> that you can use just like a
+ normal JDBC <classname>DataSource</classname>.
</para>
</section>
- <section id = "jca4">
- <title>Implementation Status</title>
+ <section id="jca4">
+ <title id="jca4.title">Implementation Status</title>
<para>
See the JBossCX project page on <ulink
url="http://www.jboss.org/">jboss.org</ulink>
</para>
</section>
</section>
+
+<!--
+Local Variables:
+sgml-parent-document: ("jbossdocs.xml" "book" "chapter" "section")
+End:
+-->
_______________________________________________
Jboss-development mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/jboss-development
