[jboss-cvs] JBossAS SVN: r97865 - projects/docs/enterprise/EWP_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 18:09:33 EST 2009
Author: laubai
Date: 2009-12-15 18:09:33 -0500 (Tue, 15 Dec 2009)
New Revision: 97865
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_JBoss.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_Open_Source.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
Log:
Corrected tags in EWP5 Admin and Config Guide.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_JBoss.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_JBoss.xml 2009-12-15 22:19:13 UTC (rev 97864)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_JBoss.xml 2009-12-15 23:09:33 UTC (rev 97865)
@@ -11,13 +11,13 @@
<para>
<indexterm><primary>JBoss</primary><secondary>and Professional Open Source</secondary></indexterm>
<indexterm><primary>Professional Open Source</primary><secondary>JBoss</secondary></indexterm>
- JBoss, pioneered the disruptive Professional Open Source model, which combines the best of the open source and proprietary software worlds to make open source a safe choice for the enterprise and give CIOs peace of mind. This includes the royalty-free software, transparent development and active community inherent in open source and the accountability and professional support services expected of a traditional software vendor. The company finds innovative open source projects and professionalizes the project from a hobby into a livelihood by hiring the lead developer(s), often the founders themselves. JBoss provides the resources, core development and support services to enable popular open source projects to scale into enterprise-class software.
+ JBoss pioneered the disruptive Professional Open Source model, which combines the best of the open source and proprietary software worlds to make open source a safe choice for the enterprise and give CIOs peace of mind. This includes the royalty-free software, transparent development and active community inherent in open source and the accountability and professional support services expected of a traditional software vendor. The company finds innovative open source projects and professionalizes the project from a hobby into a livelihood by hiring the lead developer(s), often the founders themselves. JBoss provides the resources, core development and support services to enable popular open source projects to scale into enterprise-class software.
</para>
<para>
- <emphasis>Coverage:</emphasis> North America and Europe on a direct basis. JBoss provides coverage worldwide via our extensive authorized partner network.
+ <emphasis>Coverage:</emphasis> North America and Europe on a direct basis. JBoss provides coverage worldwide via our extensive authorized partner network.
</para>
<para>
- <emphasis>Mission Statement:</emphasis> <indexterm><primary>Mission Statement</primary></indexterm> JBoss' mission is to revolutionize the way enterprise middleware software is built, distributed, and supported through the Professional Open Source model. We are committed to delivering innovative and high quality technology and services that make JBoss the safe choice for enterprises and software providers.
+ <emphasis>Mission Statement:</emphasis> <indexterm><primary>Mission Statement</primary></indexterm> The JBoss mission is to revolutionize the way enterprise middleware software is built, distributed, and supported through the Professional Open Source model. We are committed to delivering innovative and high quality technology and services that make JBoss the safe choice for enterprises and software providers.
</para>
<para>
<emphasis>Customers:</emphasis> Enterprise customers deploying JBoss technologies in mission-critical applications with professional services support from JBoss include Aviva Canada, Continental Airlines, La Quinta, NLG, MCI, Nielsen Media Research and Travelocity. For a current list of customer success stories, please visit the <ulink url="http://www.jboss.com/customers/index">Customers</ulink> section of our website.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_Open_Source.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_Open_Source.xml 2009-12-15 22:19:13 UTC (rev 97864)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/About_Open_Source.xml 2009-12-15 23:09:33 UTC (rev 97865)
@@ -15,6 +15,6 @@
Open Source Initiative exists to make this case to the commercial world.
</para>
<para>
- Open source software is an idea whose time has finally come. For twenty years it has been building momentum in the technical cultures that built the Internet and the World Wide Web. Now it's breaking out into the commercial world, and that's changing all the rules. Are you ready?
+ Open source software is an idea whose time has finally come. For twenty years it has been building momentum in the technical cultures that built the Internet and the World Wide Web. Now it's breaking out into the commercial world, and changing all the rules. Are you ready?
</para>
</section></section>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2009-12-15 22:19:13 UTC (rev 97864)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2009-12-15 23:09:33 UTC (rev 97865)
@@ -20,13 +20,13 @@
<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>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>
@@ -43,30 +43,30 @@
<screen><command>sp_dboption db_name, "allow nulls by default", true</command></screen>
- Refer the sybase manuals for more options.
+ 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:
+ 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.
+ 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.
+ 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.
+ Refer to the <application>installjava</application> manual in Sybase for more options.
</para>
</formalpara>
@@ -75,17 +75,17 @@
<orderedlist>
<listitem>
<para>
- You have to be a super-user with required privileges to install java classes.
+ 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.
+ 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.
+ 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>
@@ -99,7 +99,7 @@
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" />.
+ 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>
@@ -110,40 +110,60 @@
</mediaobject>
</figure>
<para>
- Multiple datasource configurations may be specified in a configuration deployment file. The child elements of the datasources root are:
+ Multiple datasource configurations may be specified in a configuration deployment file. The child elements of the datasource 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>
+ <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>
@@ -187,235 +207,249 @@
<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>
+ <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>
+ </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>
@@ -423,227 +457,263 @@
<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>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>
+ <title>General</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal><![CDATA[<mbean>]]></literal></term>
+ <listitem>
+ <para>
+ A standard JBoss MBean deployment.
+ </para>
+ </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>
<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>
+ <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
+ 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>
- <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>
+ <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>
+ <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>
- <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.)
+ 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>
- <!--<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>
-
+ </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 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>
+ <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>
<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 <literal>${jboss.dist}/docs/examples/jms/${database}-persistence-service.xml</literal> 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,7 +722,7 @@
</note>-->
</section>
-
+ <!--HAJIME-->
<section>
<title>Support Foreign Keys in CMP Services</title>
More information about the jboss-cvs-commits
mailing list