User: tobyallsopp Date: 01/04/01 00:18:45 Modified: src/docs howtojca.xml Log: Corrected my name and email address. Reformatted the source so that I can maintain it in the future. Revision Changes Path 1.3 +423 -341 manual/src/docs/howtojca.xml Index: howtojca.xml =================================================================== RCS file: /cvsroot/jboss/manual/src/docs/howtojca.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- howtojca.xml 2001/03/21 08:30:20 1.2 +++ howtojca.xml 2001/04/01 08:18:45 1.3 @@ -1,343 +1,425 @@ <?xml version = "1.0" encoding = "UTF-8"?> +<!-- <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx/docbookx.dtd"> --> + <section> - <title>JBossCX Configuration</title> - <para> Author:<author> - <firstname>Toby</firstname> - <surname>Allsop</surname> - </author> - <email>[EMAIL PROTECTED]</email> - </para> - - - <section> - <title>Introduction</title> - - <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. </para> - <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 <ulink url = "http://java.sun.com/j2ee/connector"> - <citetitle>official home page</citetitle> - </ulink> - </para> - - - <para> JBossCX is the name of the JBoss module that provides RAR deployment and connects a resource adapter to - a connection manager to create a connection factory accessible by application components through JNDI. </para> - </section> - <section> - <title>Contents</title> - <itemizedlist> - <listitem> - <para> - <link linkend = "jca1">Terminology</link> - </para> - </listitem> - - <listitem> - <para> - <link linkend = "jca2">JBoss Configuration</link> - </para> - </listitem> - - <listitem> - <para> - <link linkend = "jca3">Example - Black Box Example Adapter from Sun</link> - </para> - </listitem> - - <listitem> - <para> - <link linkend = "jca4">Implementation Status</link> - </para> - </listitem> - - </itemizedlist> - </section> - <section id = "jca1"> - <title>Terminology</title> - - <table> - <title>Terminology</title> - <tgroup cols = "2"> - <thead> - <row> - <entry>Concept</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>Resource</entry> - <entry>an external system that provides some service to application components. Examples include JDBC - databases and mainframe systems</entry> - </row> - <row> - <entry>Resource adapter Connector</entry> - <entry>an application component that implements access to a resource</entry> - </row> - <row> - <entry>Resource instance</entry> - <entry>a particular configuration of a resource, e.g. an Oracle database running on machine "foo" at port - "1234"</entry> - </row> - <row> - - <entry>Connection factory</entry> - <entry>an object, available through JNDI, that provides access to connections to a particular resource - instance</entry> - </row> - <row> - - <entry>Connection manager</entry> - <entry>an object that implements the javax.resource.spi.ConnectionManager interface - provides connection - pooling, transaction association, security and other "quality of services"</entry> - </row> - </tbody> - </tgroup> - </table> - - - </section> - <section id = "jca2"> - <title>JBoss Configuration</title> - <para> There are two steps that must be performed to provide access to a connection factory in JBoss: </para> - - <orderedlist> - <listitem> - <para>Configure a connection factory in jboss.jcml </para> - </listitem> - <listitem> - <para>Deploy the resource adapter </para> - </listitem> - </orderedlist> - <section> - <title>Connection Factory Configuration</title> - - <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.]]></para> - <programlisting><![CDATA[ - <mbean code="org.jboss.resource.ConnectionFactoryLoader" - name="JCA:service=ConnectionFactoryLoader,name=name"> - <!-- General attributes --> - <attribute name="name">value</attribute> - - <!-- Security attributes --> - <attribute name="name">value</attribute> - </mbean> - ]]></programlisting> - - <para>General Attributes</para> - - <table> - <title>General Attributes</title> - <tgroup cols = "2"> - <thead> - <row> - <entry>Name</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry>FactoryName</entry> - <entry>The name of the connection factory. This is the name under which the - connection factory will be bound in JNDI</entry> - </row> - <row> - <entry>RARDeployerName</entry> - <entry>The name of the MBean that will deploy the resource adapter that this - connection factory relates to</entry> - </row> - <row> - <entry>ResourceAdapterName</entry> - <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]]></entry> - </row> - <row> - <entry>Properties</entry> - <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)</entry> - </row> - <row> - <entry>ConnectionManagerFactoryName</entry> - <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.</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</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> - </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.</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.</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 here. The source code for this - resource adapter is also available - 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. </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.</para> - - - <programlisting><![CDATA[ - <!-- Example connection factory for the example "Black Box" 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> - <attribute name="RARDeployerName">JCA:service=RARDeployer</attribute> - <attribute name="ResourceAdapterName">Black Box LocalTx Adapter</attribute> - <attribute name="Properties"> - ConnectionURL=jdbc:HypersonicSQL:hsql://localhost:1476 - </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"> - # Pool type - uncomment to force, otherwise it is the default - #PoolConfiguration=per-factory - - # Connection pooling properties - see - # org.opentools.minerva.pool.PoolParameters - MinSize=0 - MaxSize=10 - Blocking=true - GCEnabled=false - IdleTimeoutEnabled=false - InvalidateOnError=false - TrackLastUsed=false - GCIntervalMillis=120000 - GCMinIdleMillis=1200000 - IdleTimeoutMillis=1800000 - MaxIdleTimeoutPercent=1.0 - </attribute> - - <!-- Principal mapping configuration --> - <attribute name="PrincipalMappingClass" - >org.jboss.resource.security.ManyToOnePrincipalMapping</attribute> - <attribute name="PrincipalMappingProperties"> - userName=sa - password= - </attribute> - </mbean> - - ]]></programlisting> - - - <para> Note that the connection manager we have chosen is the Minerva local transaction connection manager. It is - important to choose the connection manager that matches the capabilities of the 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. </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. </para> - </section> - - <section id = "jca4"> - <title>Implementation Status</title> - <para> Note that this section is likely to lag the latest developments in CVS. When a stable release including JBossCX - is made then this section should reflect the status of the released implementation. </para> - <section> - <title>Unimplemented Features</title> - <itemizedlist> - <listitem> - <para>Automatic connection manager selection based on resource adapter capabilities. </para> - </listitem> - <listitem> - <para>Mapping to more than one resource principal per connection factory.</para> - </listitem> - - </itemizedlist> - - </section> - <section> - <title>Limitations</title> - <para> Transaction association doesn't work properly unless the transaction is started before the connection - is obtained. </para> - </section> - - </section> -</section> \ No newline at end of file + <sectioninfo> + <author> + <firstname>Toby</firstname> + <surname>Allsopp</surname> + <affiliation> + <address><email>[EMAIL PROTECTED]</email></address> + </affiliation> + </author> + </sectioninfo> + + <title>JBossCX Configuration</title> + + <section> + <title>Introduction</title> + + <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. + </para> + <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 <ulink + url="http://java.sun.com/j2ee/connector"><citetitle>official + home page</citetitle></ulink> + </para> + <para> + JBossCX is the name of the JBoss module that provides RAR + deployment and connects a resource adapter to a connection + manager to create a connection factory accessible by application + components through JNDI. + </para> + </section> + <section> + <title>Contents</title> + <itemizedlist> + <listitem> + <para> + <link linkend = "jca1">Terminology</link> + </para> + </listitem> + + <listitem> + <para> + <link linkend = "jca2">JBoss Configuration</link> + </para> + </listitem> + + <listitem> + <para> + <link linkend = "jca3">Example - Black Box Example Adapter + from Sun</link> + </para> + </listitem> + + <listitem> + <para> + <link linkend = "jca4">Implementation Status</link> + </para> + </listitem> + + </itemizedlist> + </section> + <section id = "jca1"> + <title>Terminology</title> + + <table> + <title>Terminology</title> + <tgroup cols = "2"> + <thead> + <row> + <entry>Concept</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>Resource</entry> + <entry> + an external system that provides some service to + application components. Examples include JDBC databases + and mainframe systems + </entry> + </row> + <row> + <entry>Resource adapter Connector</entry> + <entry> + an application component that implements access to a + resource + </entry> + </row> + <row> + <entry>Resource instance</entry> + <entry> + a particular configuration of a resource, e.g. an Oracle + database running on machine "foo" at port "1234" + </entry> + </row> + <row> + <entry>Connection factory</entry> + <entry> + an object, available through JNDI, that provides access + to connections to a particular resource instance + </entry> + </row> + <row> + <entry>Connection manager</entry> + <entry> + an object that implements the + javax.resource.spi.ConnectionManager interface - + provides connection pooling, transaction association, + security and other "quality of services" + </entry> + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section id = "jca2"> + <title>JBoss Configuration</title> + <para> + There are two steps that must be performed to provide access to + a connection factory in JBoss: + </para> + + <orderedlist> + <listitem> + <para>Configure a connection factory in jboss.jcml</para> + </listitem> + <listitem> + <para>Deploy the resource adapter</para> + </listitem> + </orderedlist> + + <section> + <title>Connection Factory Configuration</title> + + <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.]]> + </para> + + <programlisting><![CDATA[ +<mbean code="org.jboss.resource.ConnectionFactoryLoader" + name="JCA:service=ConnectionFactoryLoader,name=name"> + <!-- General attributes --> + <attribute name="name">value</attribute> + + <!-- Security attributes --> + <attribute name="name">value</attribute> +</mbean> + ]]></programlisting> + + <table> + <title>General Attributes</title> + <tgroup cols = "2"> + <thead> + <row> + <entry>Name</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>FactoryName</entry> + <entry> + The name of the connection factory. This is the name + under which the connection factory will be bound in + JNDI + </entry> + </row> + <row> + <entry>RARDeployerName</entry> + <entry> + The name of the MBean that will deploy the resource + adapter that this connection factory relates to + </entry> + </row> + <row> + <entry>ResourceAdapterName</entry> + <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 + </entry> + </row> + <row> + <entry>Properties</entry> + <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) + </entry> + </row> + <row> + <entry>ConnectionManagerFactoryName</entry> + <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. + </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 + </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> + </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. + </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. + </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 here. The source code for this resource adapter is + also available - 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. + </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. + </para> + + <programlisting><![CDATA[ +<!-- Example connection factory for the example "Black Box" 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> + <attribute name="RARDeployerName">JCA:service=RARDeployer</attribute> + <attribute name="ResourceAdapterName">Black Box LocalTx Adapter</attribute> + <attribute name="Properties"> + ConnectionURL=jdbc:HypersonicSQL:hsql://localhost:1476 + </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"> + # Pool type - uncomment to force, otherwise it is the default + #PoolConfiguration=per-factory + + # Connection pooling properties - see + # org.opentools.minerva.pool.PoolParameters + MinSize=0 + MaxSize=10 + Blocking=true + GCEnabled=false + IdleTimeoutEnabled=false + InvalidateOnError=false + TrackLastUsed=false + GCIntervalMillis=120000 + GCMinIdleMillis=1200000 + IdleTimeoutMillis=1800000 + MaxIdleTimeoutPercent=1.0 + </attribute> + + <!-- Principal mapping configuration --> + <attribute name="PrincipalMappingClass" + >org.jboss.resource.security.ManyToOnePrincipalMapping</attribute> + <attribute name="PrincipalMappingProperties"> + userName=sa + password= + </attribute> +</mbean> + ]]></programlisting> + + + <para> + Note that the connection manager we have chosen is the Minerva + local transaction connection manager. It is important to choose + the connection manager that matches the capabilities of the + 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. + </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. + </para> + </section> + + <section id = "jca4"> + <title>Implementation Status</title> + <para> + Note that this section is likely to lag the latest developments + in CVS. When a stable release including JBossCX is made then + this section should reflect the status of the released + implementation. + </para> + <section> + <title>Unimplemented Features</title> + <itemizedlist> + <listitem> + <para>Automatic connection manager selection based on + resource adapter capabilities. </para> + </listitem> + <listitem> + <para>Mapping to more than one resource principal per + connection factory.</para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Limitations</title> + <para> + Transaction association doesn't work properly unless the + transaction is started before the connection is obtained. + </para> + </section> + + </section> +</section> _______________________________________________ Jboss-development mailing list [EMAIL PROTECTED] http://lists.sourceforge.net/lists/listinfo/jboss-development
