[jboss-cvs] JBossAS SVN: r97868 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Dec 15 22:41:13 EST 2009
Author: laubai
Date: 2009-12-15 22:41:13 -0500 (Tue, 15 Dec 2009)
New Revision: 97868
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
Log:
Corrected tags in Alternative_DBs.xml.
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2009-12-16 02:19:14 UTC (rev 97867)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2009-12-16 03:41:13 UTC (rev 97868)
@@ -1,6 +1,6 @@
<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
- ]>
+ ]>
<chapter id="alternative_DBs">
<title>Use Alternative Databases with JBoss Enterprise Application Platform</title>
@@ -10,640 +10,710 @@
<indexterm><primary>Configuration</primary><secondary>databases</secondary></indexterm>
JBoss utilizes the Hypersonic database as its default database. While this is good for development and prototyping, you or your company will probably require another database to be used for production. This chapter covers configuring JBoss Enterprise Application Platform to use alternative databases. We cover the procedures for all officially supported databases on the JBoss Enterprise Application Platform. They include: MySQL 5.0, MySQL 5.1, PostgreSQL 8.2.4, PostgreSQL 8.3.5, Oracle 10g, Oracle 11g R2, Oracle 11g R2 RAC, DB2 9.7, Sybase ASE 15.0, and MS SQL 2005 and 2008.
</para>
-
+
<para>Please note that in this chapter, we explain how to use alternative databases to support all services in JBoss Enterprise Application Platform. This includes all the system level services such as EJB and JMS. For individual applications (e.g., WAR or EAR) deployed in JBoss Enterprise Application Platform, you can still use any backend database by setting up the appropriate data source connection. </para>
<para>We assume that you have already installed the external database server, and have it running. You should create an empty database named <literal>jboss</literal>, accessible via the username / password pair <literal>jbossuser / jbosspass</literal>. The <literal>jboss</literal> database is used to store JBoss Enterprise Application Platform internal data -- JBoss Enterprise Application Platform will automatically create tables and data in it.</para>
-
+
</section>
-
+
<section>
<title>Install JDBC Drivers</title>
- <para>For the JBoss Enterprise Application Platform and our applications to use the external database, we also need to install the database's JDBC driver. The JDBC driver is a JAR file, which you'll need to copy into your JBoss Enterprise Application Platform's <literal><JBoss_Home>/server/all/lib</literal> directory. Replace <literal>all</literal> with the server configuration you are using if needed. This file is loaded when JBoss starts up. So if you have the JBoss Enterprise Application Platform running, you'll need to shut down and restart. The availability of JDBC drivers for different databases are as follows.
+ <para>For the JBoss Enterprise Application Platform and our applications to use the external database, we also need to install the database's JDBC driver. The JDBC driver is a JAR file, which you'll need to copy into your JBoss Enterprise Application Platform's <filename>$JBOSS_HOME/server/$PROFILE/lib</filename> directory, where <literal>$PROFILE</literal> is the server profile you are using. This file is loaded when JBoss starts up, so if you have the JBoss Enterprise Application Platform running, you'll need to shut down and restart. The availability of JDBC drivers for different databases are as follows.
</para>
<itemizedlist>
- <listitem><para>MySQL JDBC drivers can be downloaded from the MySQL web site <ulink url="http://www.mysql.com/products/connector/">http://www.mysql.com/products/connector/</ulink>.</para></listitem>
- <listitem><para>Postgres JDBC drivers can be downloaded from the Postgres web site <ulink url="http://jdbc.postgresql.org/">http://jdbc.postgresql.org/</ulink>.</para></listitem>
- <listitem><para>Oracle JDBC drivers can be downloaded from the Oracle web site <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html">http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html </ulink>.</para></listitem>
- <listitem><para>IBM DB2 JDBC drivers can be downloaded from the IBM web site <ulink url="http://www-306.ibm.com/software/data/db2/java/">http://www-306.ibm.com/software/data/db2/java/</ulink>.
- </para></listitem>
+ <listitem><para>MySQL JDBC drivers can be downloaded from the MySQL web site <ulink url="http://www.mysql.com/products/connector/">http://www.mysql.com/products/connector/</ulink>.</para></listitem>
+ <listitem><para>PostgreSQL JDBC drivers can be downloaded from the Postgres web site <ulink url="http://jdbc.postgresql.org/">http://jdbc.postgresql.org/</ulink>.</para></listitem>
+ <listitem><para>Oracle JDBC drivers can be downloaded from the Oracle web site <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html">http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html </ulink>.</para></listitem>
+ <listitem><para>IBM DB2 JDBC drivers can be downloaded from the IBM web site <ulink url="http://www-306.ibm.com/software/data/db2/java/">http://www-306.ibm.com/software/data/db2/java/</ulink>.
+ </para></listitem>
<listitem><para>Sybase JDBC drivers can be downloaded from the Sybase jConnect product page <ulink url="http://www.sybase.com/products/allproductsa-z/softwaredeveloperkit/jconnect">http://www.sybase.com/products/allproductsa-z/softwaredeveloperkit/jconnect</ulink></para></listitem>
<listitem><para>MS SQL Server JDBC drivers can be downloaded from the MSDN web site <ulink url="http://msdn.microsoft.com/data/jdbc/">http://msdn.microsoft.com/data/jdbc/</ulink>.</para></listitem>
</itemizedlist>
-
- <section><title>Special notes on Sybase</title>
- <para>
- Some of the services in JBoss uses null values for the default tables that are created.
- Sybase Adaptive Server should be configured to allow nulls by default.
+
+ <section><title>Special notes on Sybase</title>
+ <para>
+ Some of the services in JBoss uses null values for the default tables that are created.
+ Sybase Adaptive Server should be configured to allow nulls by default.
<screen><command>sp_dboption db_name, "allow nulls by default", true</command></screen>
-
- Refer the sybase manuals for more options.
- </para>
- <formalpara><title>Enable JAVA services</title>
- <para>
- To use any java service like JMS, CMP, timers etc. configured with Sybase, java should be enabled on Sybase Adaptive Server. To do this use:
+
+ Refer to the Sybase manuals for more options.
+ </para>
+ <formalpara><title>Enable JAVA services</title>
+ <para>
+ To use any Java service like JMS, CMP, timers etc. configured with Sybase, Java should be enabled on Sybase Adaptive Server. To do this use:
<screen><command>sp_configure "enable java",1</command></screen>
- Refer to the sybase manuals for more information.
- </para>
- </formalpara>
- <para>
- If java is not enabled you might see this exception being thrown when you try to use any of the above services.
-<screen>com.sybase.jdbc2.jdbc.SybSQLException: Cannot run this command because Java services are not enabled. A user with System Administrator (SA) role must reconfigure the system to enable Java</screen>
- </para>
-
-
+ Refer to the sybase manuals for more information.
+ </para>
+ </formalpara>
+ <para>
+ If Java is not enabled you might see this exception being thrown when you try to use any of the above services.
+<screen>com.sybase.jdbc2.jdbc.SybSQLException: Cannot run this command because Java services are not enabled. A user with System Administrator (SA) role must reconfigure the system to enable Java</screen>
+ </para>
+
+
<formalpara><title>CMP Configuration</title>
- <para>
- To use Container Managed Persistence for user defined Java objects with Sybase Adaptive Server Enterprise the java classes should be installed in the database. The system table 'sysxtypes' contains one row for each extended, Java-SQL datatype. This table is only used for Adaptive Servers enabled for Java. Install java classes using the installjava program.
-
-
+ <para>
+ To use Container Managed Persistence for user defined Java objects with Sybase Adaptive Server Enterprise, the Java classes should be installed in the database. The system table <literal>sysxtypes</literal> contains one row for each extended Java-SQL datatype. This table is only used for Adaptive Servers enabled for Java. Install Java classes using the <application>installjava</application> program.
+
+
<screen><command>installjava -f <jar-file-name> -S<sybase-server> -U<super-user> -P<super-pass> -D<db-name></command></screen>
-
- Refer the installjava manual in Sybase for more options.
- </para>
- </formalpara>
-
- <note><title>Installing Java Classes</title>
-
- <orderedlist>
- <listitem>
- <para>
- You have to be a super-user with required privileges to install java classes.
- </para>
- </listitem>
- <listitem>
- <para>
- The jar file you are trying to install should be created without compression.
- </para>
- </listitem>
- <listitem>
- <para>
- Java classes that you install and use in the server must be compiled with JDK 1.2.2. If you compile a class with a later JDK, you will be able to install it in the server using the installjava utility, but you will get a java.lang.ClassFormatError exception when you attempt to use the class. This is because Sybase Adaptive Server uses an older JVM internally, and hence requires the java classes to be compiled with the same.
- </para>
- </listitem>
- </orderedlist>
-
- </note>
+
+ Refer to the <application>installjava</application> manual in Sybase for more options.
+ </para>
+ </formalpara>
+
+ <note><title>Installing Java Classes</title>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ You have to be a super-user with required privileges to install Java classes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The JAR file you are trying to install should be created without compression.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Java classes that you install and use in the server must be compiled with JDK 1.2.2. If you compile a class with a later JDK, you will be able to install it in the server using the <application>installjava</application> utility, but you will get a <errorname>java.lang.ClassFormatError</errorname> exception when you attempt to use the class. This is because Sybase Adaptive Server uses an older JVM internally, and requires the Java classes to be compiled with the same.
+ </para>
+ </listitem>
+ </orderedlist>
+
+ </note>
</section>
<section id="Configuring_JDBC_DataSources">
- <title>Configuring JDBC DataSources</title>
-<!-- <para>
- Rather than configuring the connection manager factory related MBeans discussed in the previous section via a mbean services deployment descriptor, JBoss provides a simplified datasource centric descriptor. This is transformed into the standard <literal>jboss-service.xml</literal> MBean services deployment descriptor using a XSL transform applied by the <literal>org.jboss.deployment.XSLSubDeployer</literal> included in the <literal>jboss-jca.sar</literal> deployment. The simplified configuration descriptor is deployed the same as other deployable components. The descriptor must be named using a <literal>*-ds.xml</literal> pattern in order to be recognized by the <literal>XSLSubDeployer</literal>.
- </para> -->
- <para>
- The schema for the top-level datasource elements of the <literal>*-ds.xml</literal> configuration deployment file is shown in <xref linkend="Configuring_JDBC_DataSources-The_simplified_JCA_DataSource_configuration_descriptor_top_level_schema_elements" />.
- </para>
- <figure id="Configuring_JDBC_DataSources-The_simplified_JCA_DataSource_configuration_descriptor_top_level_schema_elements">
- <title>The simplified JCA DataSource configuration descriptor top-level schema elements</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jboss_ds.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- Multiple datasource configurations may be specified in a configuration deployment file. The child elements of the datasources root are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">mbean</emphasis>: Any number mbean elements may be specified to define MBean services that should be included in the <literal>jboss-service.xml</literal> descriptor that results from the transformation. This may be used to configure services used by the datasources.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">no-tx-datasource</emphasis>: This element is used to specify the (<literal>org.jboss.resource.connectionmanager</literal>) <literal>NoTxConnectionManager</literal> service configuration. <literal>NoTxConnectionManager</literal> is a JCA connection manager with no transaction support. The <literal>no-tx-datasource</literal> child element schema is given in <xref linkend="Configuring_JDBC_DataSources-The_non_transactional_DataSource_configuration_schema" />.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">local-tx-datasource</emphasis>: This element is used to specify the (<literal>org.jboss.resource.connectionmanager</literal>) <literal>LocalTxConnectionManager</literal> service configuration. <literal>LocalTxConnectionManager</literal> implements a <literal>ConnectionEventListener</literal> that implements <literal>XAResource</literal> to manage transactions through the transaction manager. To ensure that all work in a local transaction occurs over the same <literal>ManagedConnection</literal>, it includes a xid to <literal>ManagedConnection</literal> map. When a Connection is requested or a transaction started with a connection handle in use, it checks to see if a <literal>ManagedConnection</literal> already exists enrolled in the global transaction and uses it if found. Otherwise, a free <literal>ManagedConnection</literal> has its <literal>LocalTransaction</literal> started and is used. The <literal>local-tx-datasource</literal> child element!
schema is given in <xref linkend="Configuring_JDBC_DataSources-The_non_XA_DataSource_configuration_schema" />
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">xa-datasource</emphasis>: This element is used to specify the (<literal>org.jboss.resource.connectionmanager</literal>) <literal>XATxConnectionManager</literal> service configuration. <literal>XATxConnectionManager</literal> implements a <literal>ConnectionEventListener</literal> that obtains the <literal>XAResource</literal> to manage transactions through the transaction manager from the adaptor <literal>ManagedConnection</literal>. To ensure that all work in a local transaction occurs over the same <literal>ManagedConnection</literal>, it includes a xid to <literal>ManagedConnection</literal> map. When a <literal>Connection</literal> is requested or a transaction started with a connection handle in use, it checks to see if a <literal>ManagedConnection</literal> already exists enrolled in the global transaction and uses it if found. Otherwise, a free <literal>ManagedConnection</literal> has its <literal>LocalTransaction</literal> started and is !
used. The <literal>xa-datasource</literal> child element schema is given in <xref linkend="Configuring_JDBC_DataSources-The_XA_DataSource_configuration_schema" />.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ha-local-tx-datasource</emphasis>: This element is identical to <literal>local-tx-datasource</literal>, with the addition of the experimental datasource failover capability allowing JBoss to failover to an alternate database in the event of a database failure.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">ha-xa-datasource</emphasis>: This element is identical to <literal>xa-datasource</literal>, with the addition of the experimental datasource failover capability allowing JBoss to failover to an alternate database in the event of a database failure.
- </para>
- </listitem>
- </itemizedlist>
- <figure id="Configuring_JDBC_DataSources-The_non_transactional_DataSource_configuration_schema">
- <title>The non-transactional DataSource configuration schema</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jboss_ds_no_tx.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <figure id="Configuring_JDBC_DataSources-The_non_XA_DataSource_configuration_schema">
- <title>The non-XA DataSource configuration schema</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jboss_ds_local_tx.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <figure id="Configuring_JDBC_DataSources-The_XA_DataSource_configuration_schema">
- <title>The XA DataSource configuration schema</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jboss_ds_xa.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <figure id="Configuring_JDBC_DataSources-The_schema_for_the_experimental_non_XA_DataSource_with_failover">
- <title>The schema for the experimental non-XA DataSource with failover</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jboss_ds_ha_local.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <figure id="Configuring_JDBC_DataSources-The_schema_for_the_experimental_XA_Datasource_with_failover">
- <title>The schema for the experimental XA Datasource with failover</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jboss_ds_ha_xa.jpg" />
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- Elements that are common to all datasources include:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">jndi-name</emphasis>: The JNDI name under which the <literal>DataSource</literal> wrapper will be bound. Note that this name is relative to the <literal>java:/</literal> context, unless <literal>use-java-context</literal> is set to false. <literal>DataSource</literal> wrappers are not usable outside of the server VM, so they are normally bound under the <literal>java:/</literal>, which isn't shared outside the local VM.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">use-java-context</emphasis>: If this is set to false the the datasource will be bound in the global JNDI context rather than the <literal>java:</literal> context.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">user-name</emphasis>: This element specifies the default username used when creating a new connection. The actual username may be overridden by the application code <literal>getConnection</literal> parameters or the connection creation context JAAS Subject.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">password</emphasis>: This element specifies the default password used when creating a new connection. The actual password may be overridden by the application code <literal>getConnection</literal> parameters or the connection creation context JAAS Subject.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">application-managed-security</emphasis>: Specifying this element indicates that connections in the pool should be distinguished by application code supplied parameters, such as from <literal>getConnection(user, pw)</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">security-domain</emphasis>: Specifying this element indicates that connections in the pool should be distinguished by JAAS Subject based information. The content of the <literal>security-domain</literal> is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS <literal>login-config.xml</literal> descriptor <literal>application-policy/name</literal> attribute.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">security-domain-and-application</emphasis>: Specifying this element indicates that connections in the pool should be distinguished both by application code supplied parameters and JAAS Subject based information. The content of the <literal>security-domain</literal> is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS <literal>login-config.xml</literal> descriptor <literal>application-policy/name</literal> attribute.
- </para>
- </listitem>
- <listitem>
+ <title>Configuring JDBC DataSources</title>
+<!-- <para>
+ Rather than configuring the connection manager factory related MBeans discussed in the previous section via a mbean services deployment descriptor, JBoss provides a simplified datasource centric descriptor. This is transformed into the standard <literal>jboss-service.xml</literal> MBean services deployment descriptor using a XSL transform applied by the <literal>org.jboss.deployment.XSLSubDeployer</literal> included in the <literal>jboss-jca.sar</literal> deployment. The simplified configuration descriptor is deployed the same as other deployable components. The descriptor must be named using a <literal>*-ds.xml</literal> pattern in order to be recognized by the <literal>XSLSubDeployer</literal>.
+ </para> -->
+ <para>
+ The schema for the top-level datasource elements of the <filename>*-ds.xml</filename> configuration deployment file is shown in <xref linkend="Configuring_JDBC_DataSources-The_simplified_JCA_DataSource_configuration_descriptor_top_level_schema_elements" />.
+ </para>
+ <figure id="Configuring_JDBC_DataSources-The_simplified_JCA_DataSource_configuration_descriptor_top_level_schema_elements">
+ <title>The simplified JCA DataSource configuration descriptor top-level schema elements</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jboss_ds.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Multiple datasource configurations may be specified in a configuration deployment file. The child elements of the datasource root are:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>mbean</literal></term>
+ <listitem>
+ <para>
+ Any number of <literal>mbean</literal> elements may be specified to define MBean services that should be included in the <filename>jboss-service.xml</filename> descriptor that results from the transformation. This may be used to configure services used by the datasources.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>no-tx-datasource</literal></term>
+ <listitem>
+ <para>
+ This element is used to specify the <classname>NoTxConnectionManager</classname> service configuration (<classname>org.jboss.resource.connectionmanager</classname>). <classname>NoTxConnectionManager</classname> is a JCA connection manager with no transaction support. The <literal>no-tx-datasource</literal> child element schema is given in <xref linkend="Configuring_JDBC_DataSources-The_non_transactional_DataSource_configuration_schema" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>local-tx-datasource</term>
+ <listitem>
+ <para>
+ This element is used to specify the <classname>LocalTxConnectionManager</classname> service configuration (<classname>org.jboss.resource.connectionmanager</classname>). <classname>LocalTxConnectionManager</classname> implements a <classname>ConnectionEventListener</classname> that implements <classname>XAResource</classname> to manage transactions through the transaction manager. To ensure that all work in a local transaction occurs over the same <classname>ManagedConnection</classname>, it includes a <literal>xid</literal> to <classname>ManagedConnection</classname> map. When a connection is requested or a transaction started with a connection handle in use, it checks to see if a <classname>ManagedConnection</classname> already exists enrolled in the global transaction and uses it if found. Otherwise, a free <classname>ManagedConnection</classname> has its <classname>LocalTransaction</classname> started and is used. The <literal>local-tx-datasource</literal> ch!
ild element schema is given in <xref linkend="Configuring_JDBC_DataSources-The_non_XA_DataSource_configuration_schema" />
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>xa-datasource</literal></term>
+ <listitem>
+ <para>
+ This element is used to specify the <classname>XATxConnectionManager</classname> service configuration (<classname>org.jboss.resource.connectionmanager</classname>). <classname>XATxConnectionManager</classname> implements a <classname>ConnectionEventListener</classname> that obtains the <classname>XAResource</classname> to manage transactions through the transaction manager from the adaptor <classname>ManagedConnection</classname>. To ensure that all work in a local transaction occurs over the same <classname>ManagedConnection</classname>, it includes a <literal>xid</literal> to <classname>ManagedConnection</classname> map. When a <literal>Connection</literal> is requested or a transaction started with a connection handle in use, it checks to see if a <classname>ManagedConnection</classname> already exists enrolled in the global transaction and uses it if found. Otherwise, a free <classname>ManagedConnection</classname> has its <classname>LocalTransaction</clas!
sname> started and is used. The <literal>xa-datasource</literal> child element schema is given in <xref linkend="Configuring_JDBC_DataSources-The_XA_DataSource_configuration_schema" />.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ha-local-tx-datasource</literal></term>
+ <listitem>
+ <para>
+ This element is identical to <literal>local-tx-datasource</literal>, with the addition of the experimental datasource failover capability, allowing JBoss to failover to an alternate database in the event of a database failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ha-xa-datasource</literal></term>
+ <listitem>
+ <para>
+ This element is identical to <literal>xa-datasource</literal>, with the addition of the experimental datasource failover capability, allowing JBoss to failover to an alternate database in the event of a database failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+
+ <figure id="Configuring_JDBC_DataSources-The_non_transactional_DataSource_configuration_schema">
+ <title>The non-transactional DataSource configuration schema</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jboss_ds_no_tx.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure id="Configuring_JDBC_DataSources-The_non_XA_DataSource_configuration_schema">
+ <title>The non-XA DataSource configuration schema</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jboss_ds_local_tx.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure id="Configuring_JDBC_DataSources-The_XA_DataSource_configuration_schema">
+ <title>The XA DataSource configuration schema</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jboss_ds_xa.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure id="Configuring_JDBC_DataSources-The_schema_for_the_experimental_non_XA_DataSource_with_failover">
+ <title>The schema for the experimental non-XA DataSource with failover</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jboss_ds_ha_local.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <figure id="Configuring_JDBC_DataSources-The_schema_for_the_experimental_XA_Datasource_with_failover">
+ <title>The schema for the experimental XA Datasource with failover</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jboss_ds_ha_xa.jpg" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Elements that are common to all datasources include:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>jndi-name</literal></term>
+ <listitem>
+ <para>
+ The JNDI name under which the <classname>DataSource</classname> wrapper will be bound. Note that this name is relative to the <literal>java:/</literal> context, unless <literal>use-java-context</literal> is set to false. <classname>DataSource</classname> wrappers are not usable outside of the server VM, so they are normally bound under the <literal>java:/</literal>, which is not shared outside the local VM.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>use-java-context</literal></term>
+ <listitem>
+ <para>
+ If this is set to <literal>false</literal> then the datasource will be bound in the global JNDI context rather than the <literal>java:/</literal> context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>user-name</literal></term>
+ <listitem>
+ <para>
+ This element specifies the default username used when creating a new connection. The actual username may be overridden by the application code <varname>getConnection</varname> parameters or the connection creation context JAAS Subject.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>password</literal></term>
+ <listitem>
+ <para>
+ This element specifies the default password used when creating a new connection. The actual password may be overridden by the application code <varname>getConnection</varname> parameters or the connection creation context JAAS Subject.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>application-managed-security</literal></term>
+ <listitem>
+ <para>
+ Specifying this element indicates that connections in the pool should be distinguished by application code supplied parameters, such as from <varname>getConnection(user, pw)</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>security-domain</literal></term>
+ <listitem>
+ <para>
+ Specifying this element indicates that connections in the pool should be distinguished by JAAS Subject based information. The content of the <literal>security-domain</literal> is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS <filename>login-config.xml</filename> descriptor <varname>application-policy/name</varname> attribute.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>security-domain-and-application</literal></term><listitem>
+ <para>
+ Specifying this element indicates that connections in the pool should be distinguished both by application code supplied parameters and JAAS Subject based information. The content of the <literal>security-domain</literal> is the name of the JAAS security manager that will handle authentication. This name correlates to the JAAS <filename>login-config.xml</filename> descriptor <varname>application-policy/name</varname> attribute.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>use-strict-min</literal></term><listitem>
<para>
- <emphasis role="bold">use-strict-min</emphasis>: This element specifies whether idle connections that are below the minimum pool size should be closed.
+ This element specifies whether idle connections that are below the minimum pool size should be closed.
</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">min-pool-size</emphasis>: This element specifies the minimum number of connections a pool should hold. These pool instances are not created until an initial request for a connection is made. This defaults to 0.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">max-pool-size</emphasis>: This element specifies the maximum number of connections for a pool. No more than the <literal>max-pool-size</literal> number of connections will be created in a pool. This defaults to 20.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">blocking-timeout-millis</emphasis>: This element specifies the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is 5000.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">idle-timeout-minutes</emphasis>: This element specifies the maximum time in minutes a connection may be idle before being closed. The actual maximum time depends also on the <literal>IdleRemover</literal> scan time, which is 1/2 the smallest idle-timeout-minutes of any pool.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">new-connection-sql</emphasis>: This is a SQL statement that should be executed when a new connection is created. This can be used to configure a connection with database specific settings not configurable via connection properties.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">check-valid-connection-sql</emphasis>: This is a SQL statement that should be run on a connection before it is returned from the pool to test its validity to test for stale pool connections. An example statement could be: <literal>select count(*) from x</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">exception-sorter-class-name</emphasis>: This specifies a class that implements the <literal>org.jboss.resource.adapter.jdbc.ExceptionSorter</literal> interface to examine database exceptions to determine whether or not the exception indicates a connection error. Current implementations include:
- </para>
- <itemizedlist spacing="compact">
- <listitem>
- <para>
- org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
- </para>
- </listitem>
- <listitem>
- <para>
- org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
- </para>
- </listitem>
- <listitem>
- <para>
- org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter
- </para>
- </listitem>
- <listitem>
- <para>
- org.jboss.resource.adapter.jdbc.vendor.InformixExceptionSorte
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">valid-connection-checker-class-name</emphasis>: This specifies a class that implements the <literal>org.jboss.resource.adapter.jdbc.ValidConnectionChecker</literal> interface to provide a <literal>SQLException isValidConnection(Connection e)</literal> method that is called with a connection that is to be returned from the pool to test its validity. This overrides the <literal>check-valid-connection-sql</literal> when present. The only provided implementation is <literal>org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">track-statements</emphasis>: This boolean element specifies whether to check for unclosed statements when a connection is returned to the pool. If true, a warning message is issued for each unclosed statement. If the log4j category <literal>org.jboss.resource.adapter.jdbc.WrappedConnection</literal> has trace level enabled, a stack trace of the connection close call is logged as well. This is a debug feature that can be turned off in production.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">prepared-statement-cache-size</emphasis>: This element specifies the number of prepared statements per connection in an LRU cache, which is keyed by the SQL query. Setting this to zero disables the cache.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">depends</emphasis>: The <literal>depends</literal> element specifies the JMX <literal>ObjectName</literal> string of a service that the connection manager services depend on. The connection manager service will not be started until the dependent services have been started.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">type-mapping</emphasis>: This element declares a default type mapping for this datasource. The type mapping should match a <literal>type-mapping/name</literal> element from <literal>standardjbosscmp-jdbc.xml</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Additional common child elements for both <literal>no-tx-datasource</literal> and <literal>local-tx-datasource</literal> include:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">connection-url</emphasis>: This is the JDBC driver connection URL string, for example, <literal>jdbc:hsqldb:hsql://localhost:1701</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">driver-class</emphasis>: This is the fully qualified name of the JDBC driver class, for example, <literal>org.hsqldb.jdbcDriver</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">connection-property</emphasis>: The <literal>connection-property</literal> element allows you to pass in arbitrary connection properties to the <literal>java.sql.Driver.connect(url, props)</literal> method. Each <literal>connection-property</literal> specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Elements in common to the <literal>local-tx-datasource</literal> and <literal>xa-datasource</literal> are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">transaction-isolation</emphasis>: This element specifies the <literal>java.sql.Connection</literal> transaction isolation level to use. The constants defined in the Connection interface are the possible element content values and include:
- </para>
- <itemizedlist spacing="compact">
- <listitem>
- <para>
- TRANSACTION_READ_UNCOMMITTED
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_READ_COMMITTED
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_REPEATABLE_READ
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_SERIALIZABLE
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_NONE
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">no-tx-separate-pools</emphasis>: The presence of this element indicates that two connection pools are required to isolate connections used with JTA transaction from those used without a JTA transaction. The pools are lazily constructed on first use. Its use case is for Oracle (and possibly other vendors) XA implementations that don't like using an XA connection with and without a JTA transaction.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The unique <literal>xa-datasource</literal> child elements are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">track-connection-by-tx</emphasis>: Specifying a true value for this element makes the connection manager keep an xid to connection map and only put the connection back in the pool when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, we never suspend and resume the xid on the connection's <literal>XAResource</literal>. This is the same connection tracking behavior used for local transactions.
- </para>
- <para>
- The XA spec implies that any connection may be enrolled in any transaction using any xid for that transaction at any time from any thread (suspending other transactions if necessary). The original JCA implementation assumed this and aggressively delisted connections and put them back in the pool as soon as control left the EJB they were used in or handles were closed. Since some other transaction could be using the connection the next time work needed to be done on the original transaction, there is no way to get the original connection back. It turns out that most <literal>XADataSource</literal> driver vendors do not support this, and require that all work done under a particular xid go through the same connection.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">xa-datasource-class</emphasis>: The fully qualified name of the <literal>javax.sql.XADataSource</literal> implementation class, for example, <literal>com.informix.jdbcx.IfxXADataSource</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">xa-datasource-property</emphasis>: The <literal>xa-datasource-property</literal> element allows for specification of the properties to assign to the <literal>XADataSource</literal> implementation class. Each property is identified by the name attribute and the property value is given by the <literal>xa-datasource-property</literal> element content. The property is mapped onto the <literal>XADataSource</literal> implementation by looking for a JavaBeans style getter method for the property name. If found, the value of the property is set using the JavaBeans setter with the element text translated to the true property type using the <literal>java.beans.PropertyEditor</literal> for the type.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">isSameRM-override-value</emphasis>: A boolean flag that allows one to override the behavior of the <literal>javax.transaction.xa.XAResource.isSameRM(XAResource xaRes)</literal> method behavior on the XA managed connection. If specified, this value is used unconditionally as the <literal>isSameRM(xaRes)</literal> return value regardless of the <literal>xaRes</literal> parameter.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- The failover options common to <literal>ha-xa-datasource</literal> and <literal>ha-local-tx-datasource</literal> are:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">url-delimeter</emphasis>: This element specifies a character used to separate multiple JDBC URLs.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">url-property</emphasis>: In the case of XA datasources, this property specifies the name of the <literal>xa-datasource-property</literal> that contains the list of JDBC URLs to use.
- </para>
- </listitem>
- </itemizedlist>
-
- </section>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>min-pool-size</literal></term><listitem>
+ <para>
+ This element specifies the minimum number of connections a pool should hold. These pool instances are not created until an initial request for a connection is made. This defaults to <literal>0</literal>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>max-pool-size</literal></term><listitem>
+ <para>
+ This element specifies the maximum number of connections for a pool. No more than the <literal>max-pool-size</literal> number of connections will be created in a pool. This defaults to <literal>20</literal>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>blocking-timeout-millis</literal></term><listitem>
+ <para>
+ This element specifies the maximum time in milliseconds to block while waiting for a connection before throwing an exception. Note that this blocks only while waiting for a permit for a connection, and will never throw an exception if creating a new connection takes an inordinately long time. The default is <literal>5000</literal>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>idle-timeout-minutes</literal></term><listitem>
+ <para>
+ This element specifies the maximum time in minutes that a connection can be idle before it is closed. The actual maximum time also depends on the <classname>IdleRemover</classname> scan time, which is half the smallest <literal>idle-timeout-minutes</literal> of any pool.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>new-connection-sql</literal></term><listitem>
+ <para>
+ This is a SQL statement that should be executed when a new connection is created. This can be used to configure a connection with database-specific settings not configurable via connection properties.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>check-valid-connection-sql</literal></term><listitem>
+ <para>
+ This is a SQL statement that should be run on a connection before it is returned from the pool to test for stale pool connections. An example statement could be: <literal>select count(*) from x</literal>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>exception-sorter-class-name</literal></term><listitem>
+ <para>
+ This specifies a class that implements the <classname>org.jboss.resource.adapter.jdbc.ExceptionSorter</classname> interface to examine database exceptions to determine whether or not the exception indicates a connection error. Current implementations include:
+ </para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+<classname>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para> <classname>org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para> <classname>org.jboss.resource.adapter.jdbc.vendor.SybaseExceptionSorter</classname>
+ </para>
+ </listitem>
+ <listitem>
+ <para> <classname>org.jboss.resource.adapter.jdbc.vendor.InformixExceptionSorter</classname>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>valid-connection-checker-class-name</literal></term><listitem>
+ <para>
+ This specifies a class that implements the <classname>org.jboss.resource.adapter.jdbc.ValidConnectionChecker</classname> interface to provide a <literal>SQLException isValidConnection(Connection e)</literal> method that is called with a connection that is to be returned from the pool to test its validity. This overrides the <literal>check-valid-connection-sql</literal> when present. The only provided implementation is <classname>org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker</classname>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>track-statements</literal></term><listitem>
+ <para>
+ This boolean element specifies whether to check for unclosed statements when a connection is returned to the pool. If true, a warning message is issued for each unclosed statement. If the log4j category <classname>org.jboss.resource.adapter.jdbc.WrappedConnection</classname> has trace level enabled, a stack trace of the connection close call is logged as well. This is a debug feature that can be turned off in production.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>prepared-statement-cache-size</literal></term><listitem>
+ <para>
+ This element specifies the number of prepared statements per connection in an LRU cache, which is keyed by the SQL query. Setting this to zero disables the cache.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>depends</literal></term><listitem>
+ <para>
+ The <literal>depends</literal> element specifies the JMX <literal>ObjectName</literal> string of a service that the connection manager services depend on. The connection manager service will not be started until the dependent services have been started.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>type-mapping</literal></term><listitem>
+ <para>
+ This element declares a default type mapping for this DataSource. The type mapping should match a <literal>type-mapping/name</literal> element from <filename>standardjbosscmp-jdbc.xml</filename>.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ <para>
+ Additional common child elements for both <literal>no-tx-datasource</literal> and <literal>local-tx-datasource</literal> include:
+ </para>
+ <variablelist>
+ <varlistentry><term><literal>connection-url</literal></term><listitem>
+ <para>
+ This is the JDBC driver connection URL string, for example, <literal>jdbc:hsqldb:hsql://localhost:1701</literal>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>driver-class</literal></term><listitem>
+ <para>
+ This is the fully qualified name of the JDBC driver class, for example, <classname>org.hsqldb.jdbcDriver</classname>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>connection-property</literal></term><listitem>
+ <para>
+ The <literal>connection-property</literal> element allows you to pass in arbitrary connection properties to the <literal>java.sql.Driver.connect(url, props)</literal> method. Each <literal>connection-property</literal> specifies a string name/value pair with the property name coming from the name attribute and the value coming from the element content.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ <para>
+ Elements in common to the <literal>local-tx-datasource</literal> and <literal>xa-datasource</literal> are:
+ </para>
+ <variablelist>
+ <varlistentry><term><literal>transaction-isolation</literal></term><listitem>
+ <para>
+ This element specifies the <classname>java.sql.Connection</classname> transaction isolation level to use. The constants defined in the <classname>Connection</classname> interface are the possible element content values and include:
+ </para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ TRANSACTION_READ_UNCOMMITTED
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ TRANSACTION_READ_COMMITTED
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ TRANSACTION_REPEATABLE_READ
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ TRANSACTION_SERIALIZABLE
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ TRANSACTION_NONE
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>no-tx-separate-pools</literal></term><listitem>
+ <para>
+ The presence of this element indicates that two connection pools are required to isolate connections used with a JTA transaction from those used without a JTA transaction. The pools are lazily constructed on first use. Its use case is for Oracle (and possibly other vendors) XA implementations that are unable to use an XA connection with and without a JTA transaction.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ <para>
+ The unique <literal>xa-datasource</literal> child elements are:
+ </para>
+ <variablelist>
+ <varlistentry><term><literal>track-connection-by-tx</literal></term><listitem>
+ <para>
+ Specifying a true value for this element makes the connection manager keep an <literal>xid</literal> to connection map and only return the connection to the pool when the transaction completes and all the connection handles are closed or disassociated (by the method calls returning). As a side effect, we never suspend and resume the <literal>xid</literal> on the connection's <classname>XAResource</classname>. This is the same connection tracking behavior used for local transactions.
+ </para>
+ <para>
+ The XA specification implies that any connection may be enrolled in any transaction using any <literal>xid</literal> for that transaction at any time from any thread (suspending other transactions if necessary). The original JCA implementation assumed this and aggressively delisted connections and returned them to the pool as soon as control left the EJB they were used in or handles were closed. Since some other transaction could be using the connection the next time work needed to be done on the original transaction, there was no way to get the original connection back. It turns out that most <classname>XADataSource</classname> driver vendors do not support this, and require that all work done under a particular <literal>xid</literal> go through the same connection.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>xa-datasource-class</literal></term><listitem>
+ <para>
+ The fully qualified name of the <classname>javax.sql.XADataSource</classname> implementation class, for example, <literal>com.informix.jdbcx.IfxXADataSource</literal>.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>xa-datasource-property</literal></term><listitem>
+ <para>
+ The <literal>xa-datasource-property</literal> element lets you specify the properties to assign to the <classname>XADataSource</classname> implementation class. Each property is identified by the name attribute and the property value is given by the <literal>xa-datasource-property</literal> element content. The property is mapped onto the <literal>XADataSource</literal> implementation by looking for a JavaBeans style getter method for the property name. If found, the value of the property is set using the JavaBeans setter with the element text translated to the true property type using the <classname>java.beans.PropertyEditor</classname> for the type.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>isSameRM-override-value</literal></term><listitem>
+ <para>
+ A boolean flag that allows a user to override the behavior of the <methodname>javax.transaction.xa.XAResource.isSameRM(XAResource xaRes)</methodname> method behavior on the XA managed connection. If specified, this value is used unconditionally as the <literal>isSameRM(xaRes)</literal> return value regardless of the <varname>xaRes</varname> parameter.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ <para>
+ The failover options common to <literal>ha-xa-datasource</literal> and <literal>ha-local-tx-datasource</literal> are:
+ </para>
+ <variablelist>
+ <varlistentry><term><literal>url-delimiter</literal></term><listitem>
+ <para>
+ This element specifies a character used to separate multiple JDBC URLs.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal>url-property</literal></term><listitem>
+ <para>
+ In the case of XA DataSources, this property specifies the name of the <literal>xa-datasource-property</literal> that contains the list of JDBC URLs to use.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+
+ </section>
</section>
<section>
<title>Creating a DataSource for the External Database</title>
- <para>JBoss Enterprise Application Platform connects to relational databases via datasources. These datasource definitions can be found in the <literal><JBoss_Home>/server/all/deploy</literal> directory. The datasource definitions are deployable just like WAR and EAR files. The datasource files can be recognized by looking for the XML files that end in <literal>*-ds.xml</literal>.</para>
+ <para>JBoss Enterprise Application Platform connects to relational databases via DataSources. These DataSource definitions can be found in the <filename>$JBOSS_HOME/server/$PROFILE/deploy</filename> directory. The DataSource definitions are deployable just like WAR and EAR files. The DataSource files can be recognized by looking for the XML files that end in <filename>*-ds.xml</filename>.</para>
-<note><title>Datasource definition files</title>
-<para>The datasource definition files for all supported external databases can be found in the <literal><JBoss_Home>/docs/examples/jca</literal> directory.</para>
+<note>
+ <title>DataSource definition files</title>
+ <para>The DataSource definition files for all supported external databases can be found in the <filename>$JBOSS_HOME/docs/examples/jca</filename> directory.</para>
</note>
<itemizedlist>
- <listitem><para>MySQL: <literal>mysql-ds.xml</literal></para></listitem>
- <listitem><para>PostgreSQL: <literal>postgres-ds.xml</literal></para></listitem>
- <listitem><para>Oracle: <literal>oracle-ds.xml</literal></para></listitem>
- <listitem><para>DB2: <literal>db2-ds.xml</literal></para></listitem>
- <listitem><para>Sybase: <literal>sybase-ds.xml</literal></para></listitem>
- <listitem><para>MS SQL Server: <literal>mssql-ds.xml</literal></para></listitem>
+ <listitem><para>MySQL: <filename>mysql-ds.xml</filename></para></listitem>
+ <listitem><para>PostgreSQL: <filename>postgres-ds.xml</filename></para></listitem>
+ <listitem><para>Oracle: <filename>oracle-ds.xml</filename></para></listitem>
+ <listitem><para>DB2: <filename>db2-ds.xml</filename></para></listitem>
+ <listitem><para>Sybase: <filename>sybase-ds.xml</filename></para></listitem>
+ <listitem><para>MS SQL Server: <filename>mssql-ds.xml</filename></para></listitem>
</itemizedlist>
- <para>The following code snippet shows the <literal>mysql-ds.xml</literal> file as an example. All the other <literal>*-ds.xml</literal> files are very similiar. You will need to change the <literal>connection-url</literal>, as well as the <literal>user-name</literal> / <literal>password</literal>, to fit your own database server installation.</para>
+ <para>The following code snippet shows the <filename>mysql-ds.xml</filename> file as an example. All the other <filename>*-ds.xml</filename> files are very similiar. You will need to change the <literal>connection-url</literal>, as well as the <literal>user-name</literal> and <literal>password</literal>, to fit your own database server installation.</para>
-<programlisting role="XML"><datasources>
-<local-tx-datasource>
-<jndi-name>MySqlDS</jndi-name>
-<connection-url>jdbc:mysql://localhost:3306/jboss</connection-url>
-<driver-class>com.mysql.jdbc.Driver</driver-class>
-<user-name>jbossuser</user-name>
-<password>jbosspass</password>
-<exception-sorter-class-name>
+<programlisting role="XML"><![CDATA[
+<datasources>
+<local-tx-datasource>
+<jndi-name>MySqlDS</jndi-name>
+<connection-url>jdbc:mysql://localhost:3306/jboss</connection-url>
+<driver-class>com.mysql.jdbc.Driver</driver-class>
+<user-name>jbossuser</user-name>
+<password>jbosspass</password>
+<exception-sorter-class-name>
org.jboss.resource.adapter.jdbc.vendor.MySQLExceptionSorter
-</exception-sorter-class-name>
-<!-- should only be used on drivers after 3.22.1 with "ping" support
-<valid-connection-checker-class-name>
+</exception-sorter-class-name>
+<!-- should only be used on drivers after 3.22.1 with "ping" support
+<valid-connection-checker-class-name>
org.jboss.resource.adapter.jdbc.vendor.MySQLValidConnectionChecker
-</valid-connection-checker-class-name>
--->
-<!-- sql to call when connection is created
-<new-connection-sql>some arbitrary sql</new-connection-sql>
--->
-<!-- sql to call on an existing pooled connection when it is obtained from pool -
+</valid-connection-checker-class-name>
+-->
+<!-- sql to call when connection is created
+<new-connection-sql>some arbitrary sql</new-connection-sql>
+-->
+<!-- sql to call on an existing pooled connection when it is obtained from pool -
MySQLValidConnectionChecker is preferred for newer drivers
-<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
- -->
+<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
+ -->
-<!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
- <metadata>
- <type-mapping>mySQL</type-mapping>
- </metadata>
- </local-tx-datasource>
+<!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
+ <metadata>
+ <type-mapping>mySQL</type-mapping>
+ </metadata>
+ </local-tx-datasource>
-</datasources></programlisting>
+</datasources>]]>
+</programlisting>
-<para>Once you customized the <literal>*-ds.xml</literal> file to connect to your external database, you need to copy it to the <literal><JBoss_Home>/server/all/deploy</literal> directory. The database connection is now available through the JNDI name specified in the <literal>*-ds.xml</literal> file.</para>
+<para>Once you customized the <filename>*-ds.xml</filename> file to connect to your external database, you need to copy it to the <filename>$JBOSS_HOME/server/$PROFILE/deploy</filename> directory. The database connection is now available through the JNDI name specified in the <filename>*-ds.xml</filename> file.</para>
</section>
-<section><title>Common configuration for DataSources and ConnectionFactorys</title>
-
- <section><title>General</title>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><mbean></emphasis> - a standard jboss mbean deployment
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><depends></emphasis> - the ObjectName of an MBean service this ConnectionFactory or DataSource deployment depends upon
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><jndi-name></emphasis> - the jndi name where it is bound. This is prefixed with java by default:
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><use-java-context></emphasis> - set this to false to drop the java: context from the jndi name
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>XA</title>
- <para>
- <emphasis><xa-resource-timeout></emphasis> - the number of seconds passed to
- <screen>XAResource.setTranasctionTimeout()</screen>
- when not zero. This feature is available on JBoss Enterprise Application Platform 4.0.3 and above.
- </para>
- </section>
-
-
- <section><title>Security parameters</title>
- <para>
-
- JCA Login Modules - are used to inject security configuration into the connection when configured
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>nothing</emphasis> - uses the user/password specified in <filename>-ds.xml</filename> for DataSources or the <literal>getConnection/createConnection</literal> method without a <literal>user/password</literal> (the default).
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><application-managed-security></emphasis> - uses the user/password passed on the <literal>getConnection</literal> or <literal>createConnection</literal> request by the application.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><security-domain></emphasis> - uses the identified login module configured in <filename>conf/login-module.xml</filename>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><security-domain-and-application></emphasis> - uses the identified login module configured in <filename>conf/login-module.xml</filename> and other connection request information supplied by the application, e.g. queue or topic in JMS.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <section><title>Pooling parameters</title>
-
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><no-tx-separate-pools></emphasis> - whether separate subpools should be created for connections inside and outside JTA transactions (default false).
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><min-pool-size></emphasis> - the minimum number of connections in the pool (default 0 - zero)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><max-pool-size></emphasis> - the maximum number of connections in the pool (default 20)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><blocking-timeout-millis></emphasis> - the length of time to wait for a connection to become available when all the connections are checked out (default 5000 == 5 seconds, from 3.2.4 it is 30000 == 30 seconds)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><idle-timeout-minutes></emphasis> - the number of minutes after which unused connections are closed (default 15 minutes)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><track-connection-by-tx></emphasis> - whether the connection should be <emphasis>"locked"</emphasis> to the transaction, returning it to the pool at the end of the transaction; in pre-JBoss-5.x releases the default value for Local connection factories is true and false for XA; since JBoss-5.x the default value is true for both Local and XA and the element is deprecated.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><interleaving/></emphasis> - enables interleaving for XA connection factories (this feature was added in JBoss-5.x)
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><prefill></emphasis> - whether to attempt to prefill the connection pool to the minimum number of connections. NOTE: only supporting pools (OnePool) support this feature. A warning can be found in the logs if the pool does not support this. This feature is available in JBoss 4.0.5 and above.
- </para>
- </listitem>
- <listitem>
+<section>
+ <title>Common configuration for DataSources and ConnectionFactorys</title>
+
+ <section>
+ <title>General</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal><![CDATA[<mbean>]]></literal></term>
+ <listitem>
<para>
- <emphasis><background-validation-millis></emphasis> - background connection validation reduces the overall load on the RDBMS system when validating a connection. Setting this parameter means that JBoss will attempt to validate the current connections in the pool as a separate thread (<classname>ConnectionValidator</classname>). This parameter's value defines the interval, in milliseconds, for which the <classname>ConnectionValidator</classname> will run. (This value should not be the same as your <emphasis><idle-timeout-minutes></emphasis> value.)
+ A standard JBoss MBean deployment.
</para>
- </listitem>
- <!--<listitem>
- <para>
- <emphasis><background-validation></emphasis> - In JBoss 4.0.5, background connection validation was added to reduce the overall load on the RDBMS system when validating a connection. When using this feature, JBoss will attempt to validate the current connections in the pool as a seperate thread (ConnectionValidator).
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis><background-validation-minutes></emphasis> - The interval, in minutes, that the ConnectionValidator will run. It is prudent to set this value to something greater or less than the <emphasis><idle-timeout-minutes></emphasis>
- </para>
- </listitem>-->
- <listitem>
- <para>
- <emphasis><use-fast-fail></emphasis> - Whether or not to continue to attempt to acquire a connection from the pool even if the nth attempt has failed. False by default. This is to address performance issues where SQL validation may take significant time and resources to execute.
- </para>
- </listitem>
- </itemizedlist>
-
- </section>
-
- <section><title>Security and Pooling</title>
- <para>
- Unless the ResourceAdapter has <emphasis><reauthentication-support></emphasis> using multiple security identities will create subpools for each identity.
- </para>
-<note><title>Note</title>
-<para>
- The min and max pool size are per subpool so be careful with these parameters if you have lots of identities.
-</para>
-</note>
-
- </section>
-
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<depends>]]></literal></term>
+ <listitem>
+ <para>
+ The <literal>ObjectName</literal> of an MBean service this <classname>ConnectionFactory</classname> or <classname>DataSource</classname> deployment depends upon.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<jndi-name>]]></literal></term>
+ <listitem>
+ <para>
+ The JNDI name where it is bound. This is prefixed with <literal>java:\</literal> by default.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<use-java-context>]]></literal></term>
+ <listitem>
+ <para>
+ Set this to <literal>false</literal> to drop the <literal>java:\</literal> context from the JNDI name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
-</section>
-
+ <section>
+ <title>XA</title>
+ <variablelist>
+ <varlistentry>
+ <term><literal><![CDATA[<xa-resource-timeout]]></literal></term>
+ <listitem>
+ <para>
+ The number of seconds passed to <methodname>XAResource.setTransactionTimeout()</methodname> when not zero. This feature is available on JBoss Enterprise Application Platform 4.0.3 and higher.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
-
-
-
+ <section><title>Security parameters</title>
+ <para>
+
+ JCA Login Modules are used to inject security configuration into the connection when configured. When no parameters are set, the module uses the username and password specified in <filename>*-ds.xml</filename> for DataSources, or uses the <methodname>getConnection</methodname> or <methodname>createConnection</methodname> method without a username or password by default.
+ </para>
+ <para>
+ The following parameters can be set:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal><![CDATA[<application-managed-security>]]></literal></term>
+ <listitem>
+ <para>
+ Uses the username and password passed on the <methodname>getConnection</methodname> or <methodname>createConnection</methodname> request by the application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<security-domain>]]></literal></term>
+ <listitem>
+ <para>
+ Uses the identified login module configured in <filename>conf/login-module.xml</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[security-domain-and-application]]></literal></term>
+ <listitem>
+ <para>
+ Uses the identified login module configured in <filename>conf/login-module.xml</filename> and other connection request information supplied by the application, for example JMS Queues and Topics.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+
+ <section>
+ <title>Pooling parameters</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal><![CDATA[<no-tx-separate-pools>]]></literal></term>
+ <listitem>
+ <para>
+ Defines whether separate subpools should be created for connections inside and outside JTA transactions (default false).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<min-pool-size>]]></literal></term>
+ <listitem>
+ <para>
+ The minimum number of connections in the pool. The default is <literal>0</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<max-pool-size>]]></literal></term><listitem>
+ <para>
+ The maximum number of connections in the pool. The default is <literal>20</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<blocking-timeout-millis>]]></literal></term><listitem>
+ <para>
+ The length of time to wait for a connection to become available when all the connections are checked out. The default is <literal>5000</literal> (5 seconds). From 3.2.4 and higher, the default is <literal>30000</literal> (30 seconds).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<idle-timeout-minutes>]]></literal></term><listitem>
+ <para>
+ The number of minutes after which unused connections are closed. The default is <literal>15</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<track-connection-by-tx>]]></literal></term><listitem>
+ <para>
+ Whether the connection should be locked to the transaction, instead of returning it to the pool at the end of the transaction. In previous releases, this was true for local connection factories and false for XA connection factories. The default is now true for both local and XA connection factories, and the element has been deprecated.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal><![CDATA[<interleaving/>]]></literal></term><listitem>
+ <para>
+ Enables interleaving for XA connection factories. This feature was added in JBoss AS 5.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<prefill>]]></literal></term><listitem>
+ <para>
+ Whether to attempt to prefill the connection pool to the minimum number of connections. Only supporting pools (OnePool) support this feature. A warning will appear in the log if the pool does not support this functionality. This feature is available in JBoss AS 4.0.5 or higher.
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal><![CDATA[<background-validatidon-millis>]]></literal></term><listitem>
+ <para>
+ Background connection validation reduces the overall load on the RDBMS system when validating a connection. Setting this parameter means that JBoss will attempt to validate the current connections in the pool as a separate thread (<classname>ConnectionValidator</classname>). This parameter's value defines the interval, in milliseconds, for which the <classname>ConnectionValidator</classname> will run. (This value should not be the same as your <literal><![CDATA[<idle-timeout-minutes]]></literal> value.)
+ </para>
+ </listitem></varlistentry>
+ <!--<varlistentry><term><literal><![CDATA[]]></literal></term><listitem>
+ <para>
+ <emphasis><background-validation></emphasis> - In JBoss 4.0.5, background connection validation was added to reduce the overall load on the RDBMS system when validating a connection. When using this feature, JBoss will attempt to validate the current connections in the pool as a seperate thread (ConnectionValidator).
+ </para>
+ </listitem></varlistentry>
+ <varlistentry><term><literal><![CDATA[]]></literal></term><listitem>
+ <para>
+ <emphasis><background-validation-minutes></emphasis> - The interval, in minutes, that the ConnectionValidator will run. It is prudent to set this value to something greater or less than the <emphasis><idle-timeout-minutes></emphasis>
+ </para>
+ </listitem></varlistentry>-->
+ <varlistentry><term><literal><![CDATA[<use-fast-fail>]]></literal></term><listitem>
+ <para>
+ Whether or not to continue to attempt to acquire a connection from the pool even if the nth attempt has failed. False by default. This is to address performance issues where SQL validation may take significant time and resources to execute.
+ </para>
+ </listitem></varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Security and Pooling</title>
+ <para>
+ Unless the <classname>ResourceAdapter</classname> has <literal><![CDATA[<reauthentication-support>]]></literal>, using multiple security identities will create subpools for each identity.
+ </para>
+ <note><title>Note</title>
+ <para>
+ The min and max pool size are per subpool, so be careful with these parameters if you have lots of identities.
+ </para>
+ </note>
+ </section>
+ </section>
</section>
<section>
<title>Change Database for the JMS Services</title>
- <para>The JMS service in the JBoss Enterprise Application Platform uses relational databases to persist its messages. For improved performance, we should change the JMS service to take advantage of the external database. To do that, we need to replace the file <literal>{jboss.dist}/server/${server}/deploy/messaging/${database}-persistence-service.xml</literal> with the file <literal>${jboss.dist}/docs/examples/jms/${database}-persistence-service.xml</literal> depending on your external database.
+ <para>The JMS service in the JBoss Enterprise Application Platform uses relational databases to persist its messages. For improved performance, we should change the JMS service to take advantage of the external database. To do that, we need to replace the file <filename>$JBOSS_HOME/server/$PROFILE/deploy/messaging/$DATABASE-persistence-service.xml</filename> with the file <filename>$JBOSS_HOME/docs/examples/jms/$DATABASE-persistence-service.xml</filename> depending on your external database.
<!--To do that, we need to replace the file <literal><JBoss_Home>/server/all/deploy/jms-singleton/hsqldb-jdbc2-service.xml</literal> with a file in <literal><JBoss_Home>/docs/examples/jms/</literal> depending on your external database. Notice that if you are using the <literal>default</literal> server profile, the file path is <literal><JBoss_Home>/server/default/deploy/jms/hsqldb-jdbc2-service.xml</literal>.--></para>
-
+
<itemizedlist>
- <listitem><para>MySQL: <literal>mysql-persistence-service.xml</literal></para></listitem>
- <listitem><para>PostgreSQL: <literal>postgresql-persistence-service.xml</literal></para></listitem>
- <listitem><para>Oracle: <literal>oracle-persistence-service.xml</literal></para></listitem>
- <listitem><para>DB2: <literal>db2-persistence-service.xml</literal></para></listitem>
- <listitem><para>Sybase: <literal>sybase-persistence-service.xml</literal></para></listitem>
- <listitem><para>MS SQL Server: <literal>mssql-persistence-service.xml</literal></para></listitem>
+ <listitem><para>MySQL: <filename>mysql-persistence-service.xml</filename></para></listitem>
+ <listitem><para>PostgreSQL: <filename>postgresql-persistence-service.xml</filename></para></listitem>
+ <listitem><para>Oracle: <filename>oracle-persistence-service.xml</filename></para></listitem>
+ <listitem><para>DB2: <filename>db2-persistence-service.xml</filename></para></listitem>
+ <listitem><para>Sybase: <filename>sybase-persistence-service.xml</filename></para></listitem>
+ <listitem><para>MS SQL Server: <filename>mssql-persistence-service.xml</filename></para></listitem>
</itemizedlist>
<!-- <note>
@@ -652,93 +722,94 @@
</note>-->
</section>
-
+
+<!--HAJIME-->
<section>
<title>Support Foreign Keys in CMP Services</title>
- <para>Next, we need to go change the <literal><JBoss_Home>/server/all/conf/standardjbosscmp-jdbc.xml</literal> file so that the <literal>fk-constraint</literal> property is <literal>true</literal>. That is needed for all external databases we support on the JBoss Enterprise Application Platform. This file configures the database connection settings for the EJB2 CMP beans deployed in the JBoss Enterprise Application Platform.</para>
-
-<programlisting role="XML"><fk-constraint>true</fk-constraint></programlisting>
+ <para>Next, we need to go change the <filename>$JBOSS_HOME/server/$PROFILE/conf/standardjbosscmp-jdbc.xml</filename> file so that the <varname>fk-constraint</varname> property is <literal>true</literal>. That is needed for all external databases we support on the JBoss Enterprise Application Platform. This file configures the database connection settings for the EJB2 CMP beans deployed in the JBoss Enterprise Application Platform.</para>
+
+<programlisting role="XML"><![CDATA[<fk-constraint>true</fk-constraint>]]></programlisting>
</section>
<section>
<title>Specify Database Dialect for Java Persistence API</title>
- <para>The Java Persistence API (JPA) entity manager can save EJB3 entity beans to any backend database. Hibernate provides the JPA implementation in JBoss Enterprise Application Platform. Hibernate has a dialect auto-detection mechanism that works for most databases including the dialects for databases referenced in this appendix which are listed below. If a specific dialect is needed for alternative databases, you can configure the database dialect in the <literal>${jboss.dist}/server/${server}/deployers/ejb3.deployer/META-INF/jpa-deployers-jboss-beans.xml</literal> file. To configure this file you need to uncomment the set of tags related to the map entry <literal>hibernate.dialect</literal> and change the values to the following based on the database you setup. <!--For a complete list of dialects, refer to the Hibernate Reference Guide, Chapter 3, Section 4.1 SQL Dialects.--></para>
+ <para>The Java Persistence API (JPA) entity manager can save EJB3 entity beans to any backend database. Hibernate provides the JPA implementation in JBoss Enterprise Application Platform. Hibernate has a dialect auto-detection mechanism that works for most databases including the dialects for databases referenced in this appendix which are listed below. If a specific dialect is needed for alternative databases, you can configure the database dialect in the <filename>$JBOSS_HOME/server/$PROFILE/deployers/ejb3.deployer/META-INF/jpa-deployers-jboss-beans.xml</filename> file. To configure this file you need to uncomment the set of tags related to the map entry <literal>hibernate.dialect</literal> and change the values to the following based on the database you setup. <!--For a complete list of dialects, refer to the Hibernate Reference Guide, Chapter 3, Section 4.1 SQL Dialects.--></para>
<itemizedlist>
- <listitem>
- <para>
- Oracle 10g: org.hibernate.dialect.Oracle10gDialect
- </para>
- </listitem>
- <listitem>
- <para>
- Oracle 11g: org.hibernate.dialect.Oracle10gDialect
- </para>
- </listitem>
- <listitem>
- <para>
- Microsoft SQL Server 2005: org.hibernate.dialect.SQLServerDialect
- </para>
- </listitem>
- <listitem>
- <para>
- Microsoft SQL Server 2008: org.hibernate.dialect.SQLServerDialect
- </para>
- </listitem>
- <listitem>
- <para>
- PostgresSQL 8.2.3: org.hibernate.dialect.PostgreSQLDialect
- </para>
- </listitem>
- <listitem>
- <para>
- PostgresSQL 8.3.7: org.hibernate.dialect.PostgreSQLDialect
- </para>
- </listitem>
- <listitem>
- <para>
- MySQL 5.0: org.hibernate.dialect.MySQL5InnoDBDialect
- </para>
- </listitem>
- <listitem>
- <para>
- MySQL 5.1: org.hibernate.dialect.MySQL5InnoDBDialect
- </para>
- </listitem>
- <listitem>
- <para>
- DB2 9.1: org.hibernate.dialect.DB2Dialect
- </para>
- </listitem>
- <listitem>
- <para>
- Sybase ASE 15: org.hibernate.dialect.SybaseDialect
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Oracle 10g: <literal>org.hibernate.dialect.Oracle10gDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Oracle 11g: <literal>org.hibernate.dialect.Oracle10gDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Microsoft SQL Server 2005: <literal>org.hibernate.dialect.SQLServerDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Microsoft SQL Server 2008: <literal>org.hibernate.dialect.SQLServerDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ PostgresSQL 8.2.3: <literal>org.hibernate.dialect.PostgreSQLDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ PostgresSQL 8.3.7: <literal>org.hibernate.dialect.PostgreSQLDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ MySQL 5.0: <literal>org.hibernate.dialect.MySQL5InnoDBDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ MySQL 5.1: <literal>org.hibernate.dialect.MySQL5InnoDBDialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ DB2 9.1: <literal>org.hibernate.dialect.DB2Dialect</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Sybase ASE 15: <literal>org.hibernate.dialect.SybaseDialect</literal>
+ </para>
+ </listitem>
</itemizedlist>
<!-- <note><title>DB2 7.2 with Universal JDBC Driver (Type 4)</title>
- <para>
- Large Objects (LOBs) are supported only with DB2 Version 8 servers and above with the universal JDBC driver.
- Hence JMS services which stores messages as BLOBS and Timer services which uses BLOB fields for storing objects do not work with the JDBC Type 4 driver and DB2 7.2.
- </para>
+ <para>
+ Large Objects (LOBs) are supported only with DB2 Version 8 servers and above with the universal JDBC driver.
+ Hence JMS services which stores messages as BLOBS and Timer services which uses BLOB fields for storing objects do not work with the JDBC Type 4 driver and DB2 7.2.
+ </para>
</note>
<note><title>DB2 7.2 with JDBC Type 2 driver</title>
- <para>
- All JBoss services work with the JDBC Type 2 driver and DB2 Version 7.2 servers.
- </para>
+ <para>
+ All JBoss services work with the JDBC Type 2 driver and DB2 Version 7.2 servers.
+ </para>
</note> -->
-
+
</section>
<section>
- <title>Change Other JBoss Enterprise Application Platform Services to Use the External Database</title>
+ <title>Change Other JBoss Enterprise Application Platform Services to use the External Database</title>
<para>Besides JMS, CMP, and JPA, we still need to hook up the rest of JBoss services with the external database. There are two ways to do it. One is easy but inflexible. The other is flexible but requires more steps. Now, let's discuss those two approaches respectively.</para>
@@ -746,20 +817,23 @@
<title>The Easy Way</title>
<para>
- The easy way is just to change the JNDI name for the external database to <literal>DefaultDS</literal>. Most JBoss services are hard-wired to use the <literal>DefaultDS</literal> by default. So, by changing the datasource name, we do not need to change the configuration for each service individually.
+ The easy way is just to change the JNDI name for the external database to <literal>DefaultDS</literal>. Most JBoss services are hard-wired to use the <literal>DefaultDS</literal> by default. So, by changing the DataSource name, we do not need to change the configuration for each service individually.
</para>
<para>
- To change the JNDI name, just open the <literal>*-ds.xml</literal> file for your external database, and change the value of the <literal>jndi-name</literal> property to <literal>DefaultDS</literal>. For instance, in <literal>mysql-ds.xml</literal>, you'd change MySqlDS to DefaultDS and so on. You will need to remove the <literal><JBoss_Home>/server/all/deploy/hsqldb-ds.xml</literal> file after you are done to avoid duplicated <literal>DefaultDS</literal> definition.
+ To change the JNDI name, just open the <filename>*-ds.xml</filename> file for your external database, and change the value of the <varname>jndi-name</varname> property to <literal>DefaultDS</literal>. For instance, in <filename>mysql-ds.xml</filename>, you would change <literal>MySqlDS</literal> to <literal>DefaultDS</literal> and so on. You will need to remove the <filename>$JBOSS_HOME/server/$PROFILE/deploy/hsqldb-ds.xml</filename> file after you are done to avoid duplicated <literal>DefaultDS</literal> definition.
</para>
<para>
- In the <literal>messaging/${database}-persistence-service.xml</literal> file, you should also change the datasource name in the <literal>depends</literal> tag for the <literal>PersistenceManagers</literal> MBean to <literal>DefaultDS</literal>. For instance, for <literal>mysql-persistence-service.xml</literal> file, we change the <literal>MySqlDS</literal> to <literal>DefaultDS</literal>.
-
+ In the <filename>messaging/$DATABASE-persistence-service.xml</filename> file, you should also change the datasource name in the <literal>depends</literal> tag for the <classname>PersistenceManagers</classname> MBean to <literal>DefaultDS</literal>. For instance, for <filename>mysql-persistence-service.xml</filename> file, we change the <literal>MySqlDS</literal> to <literal>DefaultDS</literal>.
+
</para>
-<programlisting role="XML">.. ...
-<mbean code="org.jboss.messaging.core.jmx.JDBCPersistenceManagerService" name="jboss.messaging:service=PersistenceManager" xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
-
-<depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+<programlisting role="XML"><![CDATA[
+...
+
+<mbean code="org.jboss.messaging.core.jmx.JDBCPersistenceManagerService" name="jboss.messaging:service=PersistenceManager" xmbean-dd="xmdesc/JDBCPersistenceManager-xmbean.xml">
+
+<depends>jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+]]>
</programlisting>
</section>
@@ -769,32 +843,32 @@
<para>Changing the external datasource to <literal>DefaultDS</literal> is convenient. But if you have applications that assume the <literal>DefaultDS</literal> always points to the factory-default HSQL DB, that approach could break your application. Also, changing <literal>DefaultDS</literal> destination forces all JBoss services to use the external database. What if you want to use the external database only on some services?</para>
- <para>A safer and more flexible way to hook up JBoss Enterprise Application Platform services with the external datasource is to manually change the <literal>DefaultDS</literal> in all standard JBoss services to the datasource JNDI name defined in your <literal>*-ds.xml</literal> file (e.g., the <literal>MySqlDS</literal> in <literal>mysql-ds.xml</literal> etc.). Below is a complete list of files that contain <literal>DefaultDS</literal>. You can update them all to use the external database on all JBoss services or update some of them to use different combination of datasources for different services.</para>
+ <para>A safer and more flexible way to hook up JBoss Enterprise Application Platform services with the external DataSource is to manually change the <literal>DefaultDS</literal> in all standard JBoss services to the DataSource JNDI name defined in your <filename>*-ds.xml</filename> file (e.g., the <literal>MySqlDS</literal> in <filename>mysql-ds.xml</filename> etc.). Below is a complete list of files that contain <literal>DefaultDS</literal>. You can update them all to use the external database on all JBoss services or update some of them to use different combination of DataSources for different services.</para>
<itemizedlist>
- <listitem><para><literal>${jboss.dist}/server/${server}/conf/login-config.xml</literal>: This file is used in Java EE container managed security services.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/conf/login-config.xml</filename>: This file is used in Java EE container managed security services.</para></listitem>
- <listitem><para><literal>${jboss.dist}/server/${server}/conf/standardjbosscmp-jdbc.xml</literal>: This file configures the CMP beans in the EJB container.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/conf/standardjbosscmp-jdbc.xml</filename>: This file configures the CMP beans in the EJB container.</para></listitem>
-<!-- <listitem><para><literal><JBoss_Home>/server/all/deploy/ejb-deployer.xml</literal>: This file configures the JBoss EJB deployer.</para></listitem>
+<!-- <listitem><para><literal><JBoss_Home>/server/all/deploy/ejb-deployer.xml</literal>: This file configures the JBoss EJB deployer.</para></listitem>
-->
- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/ejb2-timer-service.xml</literal>: This file configures the EJB timer services.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/deploy/ejb2-timer-service.xml</filename>: This file configures the EJB timer services.</para></listitem>
- <!-- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/snmp-adaptor.sar/attributes.xml</literal>: This file is used by the SNMP service.</para></listitem>
- -->
+ <!-- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/snmp-adaptor.sar/attributes.xml</literal>: This file is used by the SNMP service.</para></listitem>
+ -->
- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/juddi-service.sar/META-INF/jboss-service.xml</literal>: This file configures the UUDI service.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/deploy/juddi-service.sar/META-INF/jboss-service.xml</filename>: This file configures the UUDI service.</para></listitem>
- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/juddi-service.sar/juddi.war/WEB-INF/jboss-web.xml</literal>: This file configures the UUDI service.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/deploy/juddi-service.sar/juddi.war/WEB-INF/jboss-web.xml</filename>: This file configures the UUDI service.</para></listitem>
- <listitem><para><literal><JBoss_Home>/server/all/deploy/juddi-service.sar/juddi.war/WEB-INF/juddi.properties</literal>: This file configures the UUDI service.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/deploy/juddi-service.sar/juddi.war/WEB-INF/juddi.properties</filename>: This file configures the UUDI service.</para></listitem>
- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/uuid-key-generator.sar/META-INF/jboss-service.xml</literal>: This file configures the UUDI service.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/deploy/uuid-key-generator.sar/META-INF/jboss-service.xml</filename>: This file configures the UUDI service.</para></listitem>
- <listitem><para><literal>${jboss.dist}/server/${server}/deploy/messaging/messaging-jboss-beans.xml</literal> and <literal>${jboss.dist}/server/${server}/deploy/messaging/persistence-service.xml</literal>: Those files configure the JMS persistence service as we discussed earlier.</para></listitem>
+ <listitem><para><filename>$JBOSS_HOME/server/$PROFILE/deploy/messaging/messaging-jboss-beans.xml</filename> and <filename>$JBOSS_HOME/server/$PROFILE/deploy/messaging/persistence-service.xml</filename>: Those files configure the JMS persistence service as we discussed earlier.</para></listitem>
- <!-- ${jboss.dist}/server/${server}/deploy/schedule-manager-service.xml -->
+ <!-- ${jboss.dist}/server/${server}/deploy/schedule-manager-service.xml -->
</itemizedlist>
</section>
@@ -806,403 +880,509 @@
<para>In our setup discussed in this chapter, we rely on the JBoss Enterprise Application Platform to automatically create needed tables in the external database upon server startup. That works most of the time. But for databases like Oracle, there might be some minor issues if you try to use the same database server to back more than one JBoss Enterprise Application Platform instance.</para>
- <para>The Oracle database creates tables of the form <literal>schemaname.tablename</literal>. The <literal>TIMERS</literal> and <literal>HILOSEQUENCES</literal> tables needed by JBoss Enterprise Application Platform would not get created on a schema if the table already exists on a different schema. To work around this issue, you need to edit the <literal>${jboss.dist}/server/${server}/deploy/ejb2-timer-service.xml</literal> file to change the table name from <literal>TIMERS</literal> to something like <literal>schemaname2.tablename</literal>.</para>
+ <para>The Oracle database creates tables of the form <literal>schemaname.tablename</literal>. The <literal>TIMERS</literal> and <literal>HILOSEQUENCES</literal> tables needed by JBoss Enterprise Application Platform would not be created on a schema if the table already existed on a different schema. To work around this issue, you need to edit the <filename>$JBOSS_HOME/server/$PROFILE/deploy/ejb2-timer-service.xml</filename> file to change the table name from <literal>TIMERS</literal> to something like <literal>schemaname2.tablename</literal>.</para>
-<programlisting role="XML"><mbean code="org.jboss.ejb.txtimer.DatabasePersistencePolicy"
-name="jboss.ejb:service=EJBTimerService,persistencePolicy=database">
-<!-- DataSourceBinding ObjectName -->
-<depends optional-attribute-name="DataSource">
+<programlisting role="XML"><![CDATA[
+<mbean code="org.jboss.ejb.txtimer.DatabasePersistencePolicy"
+name="jboss.ejb:service=EJBTimerService,persistencePolicy=database">
+<!-- DataSourceBinding ObjectName -->
+<depends optional-attribute-name="DataSource">
jboss.jca:service=DataSourceBinding,name=DefaultDS
-</depends>
-<!-- The plugin that handles database persistence -->
-<attribute name="DatabasePersistencePlugin">
+</depends>
+<!-- The plugin that handles database persistence -->
+<attribute name="DatabasePersistencePlugin">
org.jboss.ejb.txtimer.GeneralPurposeDatabasePersistencePlugin
-</attribute>
-<!-- The timers table name -->
-<attribute name="TimersTable">TIMERS</attribute>
-</mbean> </programlisting>
+</attribute>
+<!-- The timers table name -->
+<attribute name="TimersTable">TIMERS</attribute>
+</mbean>
+]]></programlisting>
- <para>Similarly, you need to change the <literal><JBoss_Home>/server/all/deploy/uuid-key-generator.sar/META-INF/jboss-service.xml</literal> file to change the table name from <literal>HILOSEQUENCES</literal> to something like <literal>schemaname2.tablename</literal> as well.</para>
+ <para>Similarly, you need to change the <filename>$JBOSS_HOME/server/$PROFILE/deploy/uuid-key-generator.sar/META-INF/jboss-service.xml</filename> file to change the table name from <literal>HILOSEQUENCES</literal> to something like <literal>schemaname2.tablename</literal> as well.</para>
-<programlisting><!-- HiLoKeyGeneratorFactory -->
-<mbean code="org.jboss.ejb.plugins.keygenerator.hilo.HiLoKeyGeneratorFactory"
-name="jboss:service=KeyGeneratorFactory,type=HiLo">
-
-<depends>jboss:service=TransactionManager</depends>
-
-<!-- Attributes common to HiLo factory instances -->
-
-<!-- DataSource JNDI name -->
-<depends optional-attribute-name="DataSource">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
-
-<!-- table name -->
-<attribute name="TableName">HILOSEQUENCES</attribute></programlisting>
+<programlisting><![CDATA[
+<!-- HiLoKeyGeneratorFactory -->
+<mbean code="org.jboss.ejb.plugins.keygenerator.hilo.HiLoKeyGeneratorFactory"
+name="jboss:service=KeyGeneratorFactory,type=HiLo">
+
+<depends>jboss:service=TransactionManager</depends>
+
+<!-- Attributes common to HiLo factory instances -->
+
+<!-- DataSource JNDI name -->
+<depends optional-attribute-name="DataSource">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+
+<!-- table name -->
+<attribute name="TableName">HILOSEQUENCES</attribute>
+]]></programlisting>
</section>
-<section><title>DataSource configuration</title>
+ <section><title>DataSource configuration</title>
- <para>
- DataSources are defined inside a <datasources> element.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <no-tx-datasource> - a DataSource that does not take part in JTA transactions using a java.sql.Driver
- </para>
- </listitem>
- <listitem>
- <para>
- <local-tx-datasource> - a DataSource that does not support two phase commit using a java.sql.Driver
- </para>
- </listitem>
- <listitem>
- <para>
- <xa-datasource> - a DataSource that does support two phase commit using a javax.sql.XADataSource
- </para>
- </listitem>
- </itemizedlist>
+ <para>
+ DataSources are defined inside a <literal><![CDATA[<datasources>]]></literal> element.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><varname><![CDATA[<no-tx-datasource>]]></varname></term>
+ <listitem>
+ <para>
+ A DataSource that does not take part in JTA transactions using a <classname>java.sql.Driver</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<local-tx-datasource>]]></varname></term>
+ <listitem>
+ <para>
+ A DataSource that does not support two-phase commit using a <classname>java.sql.Driver</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<xa-datasource>]]></varname></term>
+ <listitem>
+ <para>
+ A DataSource that supports two-phase commit using a <classname>javax.sql.XADataSource</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ <section>
+ <title>Parameters specific for <classname>java.sql.Driver</classname> usage</title>
+ <variablelist>
+ <varlistentry>
+ <term><varname><![CDATA[<connection-url>]]></varname></term>
+ <listitem>
+ <para>
+ The JDBC driver connection URL string.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<driver-class>]]></varname></term>
+ <listitem>
+ <para>
+ The JDBC driver class implementing <classname>java.sql.Driver</classname>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<connection-property>]]></varname></term>
+ <listitem>
+ <para>
+ Used to configure the connections retrieved from the <classname>java.sql.Driver</classname>. For example:
+ </para>
+ <programlisting role="XML"><![CDATA[
+<connection-property name="char.encoding">UTF-8</connection-property>
+ ]]></programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
- <section><title>Parameters specific for java.sql.Driver usage</title>
-<para>
-<itemizedlist>
- <listitem>
- <para>
- <connection-url> - the JDBC driver connection url string
- </para>
- </listitem>
- <listitem>
- <para>
- <driver-class> - the JDBC driver class implementing java.sql.Driver
- </para>
- </listitem>
- <listitem>
- <para>
- <connection-property> - used to configure the connections retrieved from the java.sql.Driver. For example:
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
-<programlisting role="XML"><connection-property name="char.encoding">UTF-8</connection-property></programlisting>
-
-
-</section>
-
<section>
- <title>Parameters specific for javax.sql.XADataSource usage</title>
-
- <itemizedlist>
- <listitem>
- <para>
- <xa-datasource-class> - This is the class that implements the XADataSource
- </para>
- </listitem>
- <listitem>
- <para>
- <xa-datasource-property> - This contains that properties that are used to configure the XADataSource. For example:
- </para>
- </listitem>
- </itemizedlist>
-
-<programlisting role="XML"><xa-datasource-property name="IfxWAITTIME">10</xa-datasource-property>
-<xa-datasource-property name="IfxIFXHOST">myhost.mydomain.com</xa-datasource-property>
-<xa-datasource-property name="PortNumber">1557</xa-datasource-property>
-<xa-datasource-property name="DatabaseName">mydb</xa-datasource-property>
-<xa-datasource-property name="ServerName">myserver</xa-datasource-property>
-</programlisting>
-
-<itemizedlist>
- <listitem>
- <para>
- <isSameRM-override-value> - In order to fix issues with Oracle this property should be set to false
- </para>
- </listitem>
- <listitem>
- <para>
- <track-connection-by-tx/> - This property is deprecated and enabled by default in order to correct issues with Oracle
- </para>
- </listitem>
- <listitem>
- <para>
- <no-tx-separate-pools/> - This property will pool Transactional and non-Transactional connections separately and cause your total pool size to be twice the <literal>max-pool-size</literal>, as two pools will be created. This is used to fix issues with Oracle.
- </para>
- </listitem>
-</itemizedlist>
+ <title>Parameters specific for <classname>javax.sql.XADataSource</classname> usage</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname><![CDATA[<xa-datasource-class>]]></varname></term>
+ <listitem>
+ <para>
+ This is the class that implements the <classname>XADataSource</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<xa-datasource-property>]]></varname></term>
+ <listitem>
+ <para>
+ Contains that properties that are used to configure the <classname>XADataSource</classname>. For example:
+ </para>
+ <programlisting role="XML"><![CDATA[
+<xa-datasource-property name="IfxWAITTIME">10</xa-datasource-property>
+<xa-datasource-property name="IfxIFXHOST">myhost.mydomain.com</xa-datasource-property>
+<xa-datasource-property name="PortNumber">1557</xa-datasource-property>
+<xa-datasource-property name="DatabaseName">mydb</xa-datasource-property>
+<xa-datasource-property name="ServerName">myserver</xa-datasource-property>
+ ]]></programlisting>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<isSameRM-override-value>]]></varname></term>
+ <listitem>
+ <para>
+ In order to fix issues with Oracle this property should be set to <literal>false</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<track-connection-by-tx>]]></varname></term>
+ <listitem>
+ <para>
+ This property is deprecated and enabled by default in order to correct issues with Oracle.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<no-tx-separate-pools/>]]></varname></term>
+ <listitem>
+ <para>
+ This property will pool Transactional and non-Transactional connections separately and cause your total pool size to be twice the <varname>max-pool-size</varname>, as two pools will be created. This is used to fix issues with Oracle.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</section>
<section>
- <title>Common DataSource parameters</title>
-
- <itemizedlist>
- <listitem>
- <para>
- <jndi-name> - the JNDI name under which the DataSource should be bound.
- </para>
- </listitem>
- <listitem>
- <para>
- <use-java-context> - A boolean indicating if the jndi-name should be prefixed with java: which causes the DataSource to only be accessible from within the jboss server vm. The default is true.
- </para>
- </listitem>
- <listitem>
- <para>
- <user-name> - the user name used when creating the connection (not used when security is configured)
- </para>
- </listitem>
- <listitem>
- <para>
- <password> - the password used when creating the connection (not used when security is configured)
- </para>
- </listitem>
- <listitem>
- <para>
- <transaction-isolation> - the default transaction isolation of the connection (unspecified means use the default provided by the database):
- <itemizedlist>
- <listitem>
- <para>
- TRANSACTION_READ_UNCOMMITTED
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_READ_COMMITTED
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_REPEATABLE_READ
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_SERIALIZABLE
- </para>
- </listitem>
- <listitem>
- <para>
- TRANSACTION_NONE
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <new-connection-sql> - an sql statement that is executed against each new connection. This can be used to set the connection schema, etc.
- </para>
- </listitem>
- <listitem>
- <para>
- <check-valid-connection-sql> - an sql statement that is executed before it is checked out from the pool to make sure it is still valid. If the sql fails, the connection is closed and new ones created.
- </para>
- </listitem>
- <listitem>
- <para>
- <valid-connection-checker-class-name> - a class that can check whether a connection is valid using a vendor specific mechanism
- </para>
- </listitem>
- <listitem>
- <para>
- <exception-sorter-class-name> - a class that looks at vendor specific messages to determine whether sql errors are fatal and thus the connection should be destroyed. If none specified, no errors will be treated as fatal.
- </para>
- </listitem>
- <listitem>
- <para>
- <track-statements> - (a) whether to monitor for unclosed Statements and ResultSets and issue warnings when the user forgets to close them (default nowarn)
- </para>
- </listitem>
- <listitem>
- <para>
- <prepared-statement-cache-size> - the number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a LRU cache. The default is 0 (zero), meaning no cache.
- </para>
- </listitem>
- <listitem>
- <para>
- <share-prepared-statements> - (b) with prepared statement cache enabled whether two requests in the same transaction should return the same statement (from jboss-4.0.2 - default false).
- </para>
- </listitem>
- <listitem>
- <para>
- <set-tx-query-timeout> - whether to enable query timeout based on the length of time remaining until the transaction times out (default false - NOTE: This was NOT ported to 4.0.x until 4.0.3)
- </para>
- </listitem>
- <listitem>
- <para>
- <query-timeout> - a static configuration of the maximum of seconds before a query times out (since 4.0.3)
- </para>
- </listitem>
- <listitem>
- <para>
- <metadata/typemapping> - a pointer to the type mapping in conf/standardjbosscmp.xml (available from JBoss 4 and above)
- </para>
- </listitem>
- <listitem>
- <para>
- <validate-on-match> - Prior to JBoss 4.0.5, connection validation occurred when the JCA layer attempted to match a managed connection. With the addition of <background-validation> this is no longer required. Specifying <validate-on-match> forces the old behavior. NOTE: this is typically NOT used in conjunction with <background-validation>
- </para>
- </listitem>
- <listitem>
- <para>
- <prefill> - whether to attempt to prefill the connection pool to the minimum number of connections. NOTE: only supporting pools (OnePool) support this feature. A warning can be found in the logs if the pool does not support this. This feature will appear in JBoss 4.0.5.
- </para>
- </listitem>
- <listitem>
- <para>
- <background-validation> - In JBoss 4.0.5, background connection validation as been added to reduce the overall load on the RDBMS system when validating a connection. When using this feature, JBoss will attempt to validate the current connections in the pool is a seperate thread (ConnectionValidator). Default is False.
- </para>
- </listitem>
- <listitem>
- <para>
- <idle-timeout-minutes> - indicates the maximum time a connection may be idle before being closed. Default is 15 minutes.
- </para>
- </listitem>
- <listitem>
- <para>
- <background-validation-minutes> - The interval, in minutes, that the ConnectionValidator will run. Default is 10 minutes. NOTE: It is prudent to set this value to something greater or less than the <idle-timeout-minutes>
- </para>
- </listitem>
- <listitem>
- <para>
- <url-delimiter> - From JBoss5 database failover is part of the main datasource config
- </para>
- </listitem>
- <listitem>
- <para>
- <url-property> - From JBoss5 database failover is part of the main datasource config
- </para>
- </listitem>
- <listitem>
- <para>
- <url-selector-strategy-class-name> - From JBoss5 ONLY database failover is part of the main datasource config
- </para>
- </listitem>
- <listitem>
- <para>
- <stale-connection-checker-class-name> - An implementation of org.jboss.resource.adapter.jdbc.StateConnectionChecker that will decide whether SQLExceptions that notify of bad connections throw org.jboss.resource.adapter.jdbc.StateConnectionException (from JBoss5)
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- From JBoss Enterprise Application Platform 3.2.6 and above, <literal>track-statements</literal> has a new option:
- </para>
-<programlisting role="XML"><track-statements>nowarn</track-statements</programlisting>
+ <title>Common DataSource parameters</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname><![CDATA[<jndi-name>]]></varname></term>
+ <listitem>
+ <para>
+ The JNDI name under which the DataSource should be bound.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<use-java-context>]]></varname></term>
+ <listitem>
+ <para>
+ A boolean indicating if the <varname>jndi-name</varname> should be prefixed with <literal>java:\</literal>, which causes the DataSource to only be accessible from within the JBoss server VM. The default is <literal>true</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<user-name>]]></varname></term>
+ <listitem>
+ <para>
+ The user name used when creating the connection (not used when security is configured).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<password>]]></varname></term>
+ <listitem>
+ <para>
+ The password used when creating the connection (not used when security is configured).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<transaction-isolation>]]></varname></term>
+ <listitem>
+ <para>
+ The default transaction isolation of the connection (unspecified means use the default provided by the database):
+ </para>
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>TRANSACTION_READ_UNCOMMITTED</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>TRANSACTION_READ_COMMITTED</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>TRANSACTION_REPEATABLE_READ</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>TRANSACTION_SERIALIZABLE</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>TRANSACTION_NONE</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<new-connection-sql>]]></varname></term>
+ <listitem>
+ <para>
+ An SQL statement that is executed against each new connection. This can be used to set the connection schema, etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<check-valid-connection-sql>]]></varname></term>
+ <listitem>
+ <para>
+ An SQL statement that is executed before it is checked out from the pool to make sure it is still valid. If the SQL fails, the connection is closed and new ones created.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<valid-connection-checker-class-name>]]></varname></term>
+ <listitem>
+ <para>
+ A class that can check whether a connection is valid using a vendor-specific mechanism.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<exception-sorter-class-name>]]></varname></term>
+ <listitem>
+ <para>
+ A class that looks at vendor specific messages to determine whether SQL errors are fatal and thus the connection should be destroyed. If none are specified, no errors will be treated as fatal.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<track-statements>]]></varname></term>
+ <listitem>
+ <para>
+ Whether to monitor for unclosed <classname>Statement</classname>s and <classname>ResultSet</classname>s and issue warnings when the user forgets to close them. The default values is <literal>nowarn</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<prepared-statement-cache-size>]]></varname></term>
+ <listitem>
+ <para>
+ The number of prepared statements per connection to be kept open and reused in subsequent requests. They are stored in a LRU cache. The default is <literal>0</literal> (zero), meaning no cache.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<share-prepared-statements>]]></varname></term>
+ <listitem>
+ <para>
+ If prepared statement cache is enabled, this defines whether two requests in the same transaction should return the same statement. The default is <literal>false</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<set-tx-query-timeout>]]></varname></term>
+ <listitem>
+ <para>
+ Whether to enable query timeout based on the length of time remaining until the transaction times out. The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<query-timeout>]]></varname></term>
+ <listitem>
+ <para>
+ A static configuration of the maximum number of seconds before a query times out.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<metadata/typemapping>]]></varname></term>
+ <listitem>
+ <para>
+ A pointer to the type mapping in <filename>conf/standardjbosscmp.xml</filename>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<validate-on-match>]]></varname></term>
+ <listitem>
+ <para>
+ Prior to JBoss 4.0.5, connection validation occurred when the JCA layer attempted to match a managed connection. With the addition of <varname><![CDATA[<background-validation>]]></varname>, this is no longer required. Specifying <varname><![CDATA[<validate-on-match>]]></varname> forces the old behavior. This is typically NOT used in conjunction with <varname><![CDATA[<background-validation>]]></varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<prefill>]]></varname></term>
+ <listitem>
+ <para>
+ Whether to attempt to prefill the connection pool to the minimum number of connections. Only supporting pools (OnePool) support this feature. A warning will appear in the logs if the pool does not support this.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<background-validation>]]></varname></term>
+ <listitem>
+ <para>
+ Background connection validation has been added to reduce the overall load on the RDBMS system when validating a connection. When using this feature, JBoss will attempt to validate the current connections in the pool as a seperate thread (<classname>ConnectionValidator</classname>). The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<idle-timeout-minutes>]]></varname></term>
+ <listitem>
+ <para>
+ Indicates the maximum time in minutes that a connection can be idle before being closed. The default is <literal>15</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<background-validation-minutes>]]></varname></term>
+ <listitem>
+ <para>
+ The interval, in minutes, that the <classname>ConnectionValidator</classname> will run. The default is <literal>10</literal>. This value should be set to something greater or less than the <varname><![CDATA[<idle-timeout-minutes>]]></varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<url-delimiter>]]></varname></term>
+ <listitem>
+ <para>
+ As of JBoss 5.x, database failover is part of the main DataSource configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<url-property>]]></varname></term>
+ <listitem>
+ <para>
+ As of JBoss 5.x, database failover is part of the main DataSource configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<url-selector-strategy-class-name>]]></varname></term>
+ <listitem>
+ <para>
+ As of JBoss 5.x, database failover is part of the main DataSource configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><![CDATA[<stale-connection-checker-class-name>]]></varname></term>
+ <listitem>
+ <para>
+ An implementation of <classname>org.jboss.resource.adapter.jdbc.StateConnectionChecker</classname> that will decide whether a <exceptionname>SQLException</exceptionname> that notifies of bad connections throw <classname>org.jboss.resource.adapter.jdbc.StateConnectionException</classname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ From JBoss Enterprise Application Platform 3.2.6 and above, <varname>track-statements</varname> has a new option:
+ </para>
+<programlisting role="XML"><![CDATA[
+<track-statements>nowarn</track-statements>
+]]></programlisting>
-<para>This option closes Statements and ResultSets without a warning. It is also the new default value.</para>
-
- <para>
- The purpose is to workaround questionable driver behavior where the driver applies auto-commit semantics to local transactions.
- </para>
+<para>This <literal>nowarn</literal> option closes <classname>Statement</classname>s and <classname>ResultSet</classname>s without a warning. It is also the new default value.</para>
+
+ <para>
+ The purpose is to work around questionable driver behavior where the driver applies auto-commit semantics to local transactions:
+ </para>
<programlisting role="JAVA">Connection c = dataSource.getConnection(); // auto-commit == false
PreparedStatement ps1 = c.prepareStatement(...);
ResultSet rs1 = ps1.executeQuery();
PreparedStatement ps2 = c.prepareStatement(...);
ResultSet rs2 = ps2.executeQuery();</programlisting>
-
- <para>
- Assuming the prepared statements are the same. For some drivers, ps2.executeQuery() will automatically close rs1 so we actually need two real prepared statements behind the scenes. This *should* only be for the auto-commit semantic where re-running the query starts a new transaction automatically. For drivers that follow the spec, you can set it to true to share the same real prepared statement.
- </para>
+
+ <para>
+ This assumes that the prepared statements are the same. For some drivers, <methodname>ps2.executeQuery()</methodname> will automatically close <literal>rs1</literal>, so we actually need two real prepared statements behind the scenes. This should only be for the auto-commit semantic, where re-running the query starts a new transaction automatically. For drivers that follow the specification, you can set it to <literal>true</literal> to share the same real prepared statement.
+ </para>
</section>
-
-
+
+
<section><title>Generic Datasource Sample</title>
-
-<programlisting role="XML"><datasources>
-<local-tx-datasource>
-<jndi-name>GenericDS</jndi-name>
-<connection-url>[jdbc: url for use with Driver class]</connection-url>
-<driver-class>[fully qualified class name of java.sql.Driver implementation]</driver-class>
-<user-name>x</user-name>
-<password>y</password>
-<!-- you can include connection properties that will get passed in
-the DriverManager.getConnection(props) call-->
-<!-- look at your Driver docs to see what these might be -->
-<connection-property name="char.encoding">UTF-8</connection-property>
-<transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>
-
-<!--pooling parameters-->
-<min-pool-size>5</min-pool-size>
-<max-pool-size>100</max-pool-size>
-<blocking-timeout-millis>5000</blocking-timeout-millis>
-<idle-timeout-minutes>15</idle-timeout-minutes>
-<!-- sql to call when connection is created
-<new-connection-sql>some arbitrary sql</new-connection-sql>
--->
-
-<!-- sql to call on an existing pooled connection when it is obtained from pool
-<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
--->
-
-<set-tx-query-timeout/>
-<query-timeout>300</query-timeout> <!-- maximum of 5 minutes for queries -->
-
-<!-- pooling criteria. USE AT MOST ONE-->
-<!-- If you don't use JAAS login modules or explicit login
+
+<programlisting role="XML"><![CDATA[
+<datasources>
+<local-tx-datasource>
+<jndi-name>GenericDS</jndi-name>
+<connection-url>[jdbc: url for use with Driver class]</connection-url>
+<driver-class>[fully qualified class name of java.sql.Driver implementation]</driver-class>
+<user-name>x</user-name>
+<password>y</password>
+<!-- you can include connection properties that will get passed in
+the DriverManager.getConnection(props) call-->
+<!-- look at your Driver docs to see what these might be -->
+<connection-property name="char.encoding">UTF-8</connection-property>
+<transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>
+
+<!--pooling parameters-->
+<min-pool-size>5</min-pool-size>
+<max-pool-size>100</max-pool-size>
+<blocking-timeout-millis>5000</blocking-timeout-millis>
+<idle-timeout-minutes>15</idle-timeout-minutes>
+<!-- sql to call when connection is created
+<new-connection-sql>some arbitrary sql</new-connection-sql>
+-->
+
+<!-- sql to call on an existing pooled connection when it is obtained from pool
+<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
+-->
+
+<set-tx-query-timeout/>
+<query-timeout>300</query-timeout> <!-- maximum of 5 minutes for queries -->
+
+<!-- pooling criteria. USE AT MOST ONE-->
+<!-- If you don't use JAAS login modules or explicit login
getConnection(usr,pw) but rely on user/pw specified above,
-don't specify anything here -->
+don't specify anything here -->
-<!-- If you supply the usr/pw from a JAAS login module -->
-<security-domain>MyRealm</security-domain>
-
-<!-- if your app supplies the usr/pw explicitly getConnection(usr, pw) -->
-<application-managed-security/>
+<!-- If you supply the usr/pw from a JAAS login module -->
+<security-domain>MyRealm</security-domain>
+
+<!-- if your app supplies the usr/pw explicitly getConnection(usr, pw) -->
+<application-managed-security/>
-<!--Anonymous depends elements are copied verbatim into the ConnectionManager mbean config-->
-<depends>myapp.service:service=DoSomethingService</depends>
-
-</local-tx-datasource>
-
-<!-- you can include regular mbean configurations like this one -->
-<mbean code="org.jboss.tm.XidFactory"
-name="jboss:service=XidFactory">
-<attribute name="Pad">true</attribute>
-</mbean>
+<!--Anonymous depends elements are copied verbatim into the ConnectionManager mbean config-->
+<depends>myapp.service:service=DoSomethingService</depends>
+
+</local-tx-datasource>
+
+<!-- you can include regular mbean configurations like this one -->
+<mbean code="org.jboss.tm.XidFactory"
+name="jboss:service=XidFactory">
+<attribute name="Pad">true</attribute>
+</mbean>
-<!-- Here's an xa example -->
-<xa-datasource>
-<jndi-name>GenericXADS</jndi-name>
-<xa-datasource-class>[fully qualified name of class implementing javax.sql.XADataSource goes here]</xa-datasource-class>
-<xa-datasource-property name="SomeProperty">SomePropertyValue</xa-datasource-property>
-<xa-datasource-property name="SomeOtherProperty">SomeOtherValue</xa-datasource-property>
+<!-- Here's an xa example -->
+<xa-datasource>
+<jndi-name>GenericXADS</jndi-name>
+<xa-datasource-class>[fully qualified name of class implementing javax.sql.XADataSource goes here]</xa-datasource-class>
+<xa-datasource-property name="SomeProperty">SomePropertyValue</xa-datasource-property>
+<xa-datasource-property name="SomeOtherProperty">SomeOtherValue</xa-datasource-property>
-<user-name>x</user-name>
-<password>y</password>
-<transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>
+<user-name>x</user-name>
+<password>y</password>
+<transaction-isolation>TRANSACTION_SERIALIZABLE</transaction-isolation>
-<!--pooling parameters-->
-<min-pool-size>5</min-pool-size>
-<max-pool-size>100</max-pool-size>
-<blocking-timeout-millis>5000</blocking-timeout-millis>
-<idle-timeout-minutes>15</idle-timeout-minutes>
-<!-- sql to call when connection is created
-<new-connection-sql>some arbitrary sql</new-connection-sql>
--->
+<!--pooling parameters-->
+<min-pool-size>5</min-pool-size>
+<max-pool-size>100</max-pool-size>
+<blocking-timeout-millis>5000</blocking-timeout-millis>
+<idle-timeout-minutes>15</idle-timeout-minutes>
+<!-- sql to call when connection is created
+<new-connection-sql>some arbitrary sql</new-connection-sql>
+-->
-<!-- sql to call on an existing pooled connection when it is obtained from pool
-<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
--->
+<!-- sql to call on an existing pooled connection when it is obtained from pool
+<check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
+-->
-<!-- pooling criteria. USE AT MOST ONE-->
-<!-- If you don't use JAAS login modules or explicit login
+<!-- pooling criteria. USE AT MOST ONE-->
+<!-- If you don't use JAAS login modules or explicit login
getConnection(usr,pw) but rely on user/pw specified above,
-don't specify anything here -->
+don't specify anything here -->
-<!-- If you supply the usr/pw from a JAAS login module -->
-<security-domain/>
+<!-- If you supply the usr/pw from a JAAS login module -->
+<security-domain/>
-<!-- if your app supplies the usr/pw explicitly getConnection(usr, pw) -->
-<application-managed-security/>
+<!-- if your app supplies the usr/pw explicitly getConnection(usr, pw) -->
+<application-managed-security/>
-</xa-datasource>
+</xa-datasource>
-</datasources></programlisting>
-
- </section>
+</datasources>
+]]></programlisting>
+
+ </section>
<section>
<title>Datasource sample for Oracle RAC</title>
@@ -1257,73 +1437,77 @@
(HOST=YOUR_NODE_2)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=YOUR_SERVICE_NAME)))
</programlisting>
</section>
-
+
<section>
- <title>Configuring a DataSource for remote usage</title>
+ <title>Configuring a DataSource for remote usage</title>
<para>
- From JBoss-4.0.0 and above, there is support for accessing a DataSource from a remote client. The one change that is necessary for the client to be able to lookup the DataSource from JNDI is to specify use-java-context=false as shown here:
+ As of JBoss-4.0.0, there is support for accessing a DataSource from a remote client. The one change that is necessary for the client to be able to lookup the DataSource from JNDI is to specify <code>use-java-context=false</code>, as shown here:
</para>
-<programlisting role="XML"><datasources>
-<local-tx-datasource>
-<jndi-name>GenericDS</jndi-name>
-<use-java-context>false</use-java-context>
-<connection-url>...</connection-url>
-</programlisting>
-
- <para>
- This results in the DataSource being bound under the JNDI name "GenericDS" instead of the default of "java:/GenericDS" which restricts the lookup to the same VM as the jboss server.
- </para>
-<note><title>Note</title>
-<para>JBoss does not recommend using this feature on a production environment. It requires accessing a connection pool remotely and this is an anti-pattern as connections are not serializable. Besides, transaction propagation is not supported and it could lead to connection leaks if the remote clients are unreliable (i.e crashes, network failure). If you do need to access a datasource remotely, JBoss recommends accessing it via a remote session bean facade.</para>
+<programlisting role="XML"><![CDATA[
+<datasources>
+<local-tx-datasource>
+<jndi-name>GenericDS</jndi-name>
+<use-java-context>false</use-java-context>
+<connection-url>...</connection-url>
+]]></programlisting>
+
+ <para>
+ This results in the DataSource being bound under the JNDI name <literal>GenericDS</literal> instead of the default of <literal>java:/GenericDS</literal>, which restricts the lookup to the same VM as the JBoss server.
+ </para>
+<note>
+ <title>This feature is not recommended in a production environment.</title>
+ <para>
+ It requires accessing a connection pool remotely and this is an anti-pattern, as connections are not serializable. Additionally, transaction propagation is not supported and it could lead to connection leaks if the remote clients are unreliable (i.e crashes, network failure). If you do need to access a DataSource remotely, JBoss recommends accessing it via a remote session bean facade.
+ </para>
</note>
</section>
-
-
+
+
<section><title>Configuring a DataSource to use login modules</title>
- <para>
- Add the security-domain parameter to the *-ds.xml file.
- </para>
-
-<programlisting role="XML"><datasources>
-<local-tx-datasource>
+ <para>
+ Add the <varname>security-domain</varname> parameter to the <filename>*-ds.xml</filename> file.
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<datasources>
+<local-tx-datasource>
...
-<security-domain>MyDomain</security-domain>
+<security-domain>MyDomain</security-domain>
...
-</local-tx-datasource>
-</datasources>
-</programlisting>
-
- <para>
- Add an application-policy to the login-config.xml file. The authentication section should include the configuration for your login-module. For example, if you want to encrypt the database password, use the SecureIdentityLoginModule login module.
- </para>
-
-<programlisting role="XML"><application-policy name="MyDomain">
-<authentication>
-<login-module code="org.jboss.resource.security.SecureIdentityLoginModule" flag="required">
-<module-option name="username">scott</module-option>
-<module-option name="password">-170dd0fbd8c13748</module-option>
-<module-option name="managedConnectionFactoryName">
+</local-tx-datasource>
+</datasources>
+]]></programlisting>
+
+ <para>
+ Add an application-policy to the <filename>login-config.xml</filename> file. The authentication section should include the configuration for your login module. For example, if you want to encrypt the database password, use the <classname>SecureIdentityLoginModule</classname> login module.
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<application-policy name="MyDomain">
+<authentication>
+<login-module code="org.jboss.resource.security.SecureIdentityLoginModule" flag="required">
+<module-option name="username">scott</module-option>
+<module-option name="password">-170dd0fbd8c13748</module-option>
+<module-option name="managedConnectionFactoryName">
jboss.jca:service=LocalTxCM,name=OracleDSJAAS
-</module-option>
-</login-module>
-</authentication>
-</application-policy></programlisting>
-
- <para>
- In case you plan to fetch the data source connection from a web application, make sure authentication is turned on for the web application. This is in order for the Subject to be populated. If you wish for users to be able to connect anonymously, an additional login module needs to be added to the application-policy, in order to populate the security credentials. Add the UsersRolesLoginModule as the first login module in the chain. The usersProperties and rolesProperties parameters can be directed to dummy files.
- </para>
-
-<programlisting role="XML"><login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
-<module-option name="unauthenticatedIdentity">nobody</module-option>
-<module-option name="usersProperties">props/users.properties</module-option>
-<module-option name="rolesProperties">props/roles.properties</module-option>
-</login-module>
-</programlisting>
+</module-option>
+</login-module>
+</authentication>
+</application-policy>
+]]></programlisting>
+
+ <para>
+ In case you plan to fetch the DataSource connection from a web application, make sure authentication is turned on for the web application. This is in order for the <literal>Subject</literal> to be populated. If you wish for users to be able to connect anonymously, an additional login module needs to be added to the application policy, in order to populate the security credentials. Add the <classname>UsersRolesLoginModule</classname> as the first login module in the chain. The <varname>usersProperties</varname> and <varname>rolesProperties</varname> parameters can be directed to dummy files.
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required">
+<module-option name="unauthenticatedIdentity">nobody</module-option>
+<module-option name="usersProperties">props/users.properties</module-option>
+<module-option name="rolesProperties">props/roles.properties</module-option>
+</login-module>
+]]></programlisting>
</section>
-
-
-
-
-</chapter>
+</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list