[jboss-cvs] JBossAS SVN: r77942 - projects/docs/community/5/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Sep 3 23:45:00 EDT 2008
Author: skittoli at redhat.com
Date: 2008-09-03 23:45:00 -0400 (Wed, 03 Sep 2008)
New Revision: 77942
Added:
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/General_Configuration.xml
Modified:
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JMS.xml
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml
projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Messaging.xml
Log:
updates and jira fixes
Modified: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml 2008-09-04 03:31:40 UTC (rev 77941)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Administration_And_Configuration_Guide.xml 2008-09-04 03:45:00 UTC (rev 77942)
@@ -25,6 +25,7 @@
<part id="Application_Configuration" label="II">
<title>JBoss Application Server 5 Configuration</title>
<xi:include href="Deploy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!--<xi:include href="General_Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />-->
<xi:include href="Microcontainer.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Web_Services.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Virtual_Deployment_Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
@@ -35,6 +36,7 @@
<xi:include href="Remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Messaging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Alternative_DBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
@@ -53,9 +55,10 @@
<xi:include href="Clustering_Guide_JBoss_Cache_JGroups.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
- <part id="Perfomance" label="IV">
+ <!--<part id="Perfomance" label="IV">
<title>Performance Tuning</title>
<xi:include href="Performance_Tuning.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- </part>
- <xi:include href="Alternative_DBs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </part>-->
+
+
</book>
Modified: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2008-09-04 03:31:40 UTC (rev 77941)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Alternative_DBs.xml 2008-09-04 03:45:00 UTC (rev 77942)
@@ -1,4 +1,8 @@
-<appendix id="alternative_DBs">
+<?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 AS</title>
<section>
<title>How to Use Alternative Databases</title>
@@ -83,16 +87,338 @@
</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>
+ <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 default 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>
</section>
-
-
- <section>
+
+<section>
<title>Creating a DataSource for the External Database</title>
<para>JBoss AS 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>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 <literal><JBoss_Home>/docs/examples/jca</literal> directory.</para>
+</note>
+
<itemizedlist>
<listitem><para>MySQL: <literal>mysql-ds.xml</literal></para></listitem>
<listitem><para>PostgreSQL: <literal>postgres-ds.xml</literal></para></listitem>
@@ -104,43 +430,189 @@
<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>
- <programlisting>
-<![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>
- 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 -
- MySQLValidConnectionChecker is preferred for newer drivers
- <check-valid-connection-sql>some arbitrary sql</check-valid-connection-sql>
- -->
+<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>
+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>
+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 -
+ MySQLValidConnectionChecker is preferred for newer drivers
+<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>
+
+</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>
+</section>
- <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
- <metadata>
- <type-mapping>mySQL</type-mapping>
- </metadata>
- </local-tx-datasource>
+<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 AS 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>
+ <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. NOTE: 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>
-</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>
+</section>
+
+
+
+
+
</section>
<section>
@@ -169,12 +641,8 @@
<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 Application Server. This file configures the database connection settings for the EJB2 CMP beans deployed in the JBoss AS.</para>
- <programlisting>
-<![CDATA[
-<fk-constraint>true</fk-constraint>
-]]>
- </programlisting>
-
+<programlisting role="XML"><fk-constraint>true</fk-constraint></programlisting>
+
</section>
<section>
@@ -236,17 +704,14 @@
<para>In the <literal>jms/*-jdbc2-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-jdbc2-service.xml</literal> file, we change the <literal>MySqlDS</literal> to <literal>DefaultDS</literal>.</para>
- <programlisting>
-<![CDATA[
+<programlisting role="XML">.. ...
+<mbean code="org.jboss.mq.pm.jdbc2.PersistenceManager"
+ name="jboss.mq:service=PersistenceManager"%gt;
+ <depends optional-attribute-name="ConnectionManager">
+ jboss.jca:service=DataSourceBinding,name=DefaultDS
+ </depends>
... ...
-<mbean code="org.jboss.mq.pm.jdbc2.PersistenceManager"
- name="jboss.mq:service=PersistenceManager">
- <depends optional-attribute-name="ConnectionManager">
- jboss.jca:service=DataSourceBinding,name=DefaultDS
- </depends>
- ... ...
-]]>
- </programlisting>
+</programlisting>
</section>
@@ -282,7 +747,7 @@
</section>
- </section>
+</section>
<section>
<title>A Special Note About Oracle DataBases</title>
@@ -291,48 +756,467 @@
<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 AS 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_Home>/server/all/deploy/ejb-deployer.xml</literal> file to change the table name from <literal>TIMERS</literal> to something like <literal>schemaname2.tablename</literal>.</para>
- <programlisting>
-<![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">
- org.jboss.ejb.txtimer.GeneralPurposeDatabasePersistencePlugin
- </attribute>
- <!-- The timers table name -->
- <attribute name="TimersTable">TIMERS</attribute>
- </mbean>
-]]>
- </programlisting>
+<programlisting role="XML"><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">
+org.jboss.ejb.txtimer.GeneralPurposeDatabasePersistencePlugin
+</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>
- <programlisting>
-<![CDATA[
-... ...
- <!-- HiLoKeyGeneratorFactory -->
- <mbean code="org.jboss.ejb.plugins.keygenerator.hilo.HiLoKeyGeneratorFactory"
- name="jboss:service=KeyGeneratorFactory,type=HiLo">
-
- <depends>jboss:service=TransactionManager</depends>
+<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>
- <!-- Attributes common to HiLo factory instances -->
+
+ </section>
+
+<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>
+
+</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>
- <!-- DataSource JNDI name -->
- <depends optional-attribute-name="DataSource">jboss.jca:service=DataSourceBinding,name=DefaultDS</depends>
+<programlisting role="XML"><connection-property name="char.encoding">UTF-8</connection-property></programlisting>
+
- <!-- table name -->
- <attribute name="TableName">HILOSEQUENCES</attribute>
-
- ... ...
-]]>
- </programlisting>
+</section>
- </section>
-
-</appendix>
+ <section>
+ <title>Parameters specific for javax.sql.XADataSource usage</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <xa-datasource-class> - the class implementing the XADataSource
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <xa-datasource-property> - properties 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> - set to false to fix problems with Oracle
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <track-connection-by-tx/> - set to fix problems with Oracle (not necessarily in JBoss-5.x where it is enabled by default and the element is deprecated)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <no-tx-separate-pools/> - Pool Transactional and non-Transactional connections separately. Using this option will cause your total pool size to be twice max-pool-size because two actual pools will be created. Used to fix problems with Oracle.
+ </para>
+ </listitem>
+</itemizedlist>
+</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 AS 3.2.6 and above, <literal>track-statements</literal> has a new option:
+ </para>
+<programlisting role="XML"><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>
+<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>
+</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
+getConnection(usr,pw) but rely on user/pw specified above,
+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/>
+
+<!--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>
+
+<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>
+-->
+
+<!-- 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
+getConnection(usr,pw) but rely on user/pw specified above,
+don't specify anything here -->
+
+<!-- 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/>
+
+</xa-datasource>
+
+</datasources></programlisting>
+
+ </section>
+
+
+<section>
+ <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:
+</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>
+</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>
+...
+<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">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>
+
+</section>
+
+
+
+
+</chapter>
Modified: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JMS.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JMS.xml 2008-09-04 03:31:40 UTC (rev 77941)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JMS.xml 2008-09-04 03:45:00 UTC (rev 77942)
@@ -2,354 +2,77 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="clustering-jms">
- <title>Clustered JMS Services</title>
-
- <para>JBoss AS 3.2.4 and above support high availability JMS (HA-JMS) services in the <literal>all</literal>
- server configuration. In the current production release of JBoss AS, the HA-JMS service is implemented
- as a clustered singleton fail-over service.
- </para>
-<note>
- <para>If you are willing to configure HA-JMS yourself, you can get it to work with earlier versions of JBoss AS. We have a customer who uses HA-JMS successfully in JBoss AS 3.0.7. Please contact JBoss support for more questions.
- </para>
-</note>
- <note>
- <para>
- The HA-JMS in JBoss AS 4.2.2 and earlier is based on the JBoss MQ messaging product. In later releases of the AS, JBoss MQ will be replaced by the newer JBoss Messaging project. JBoss Messaging's clustering implementation is considerably different from HA-JMS based on JBoss MQ; most notably it is not based on a singleton service only running on one node in the cluster.
- </para>
- </note>
-
-
-
-
-<section id="clustering-jms-singleton">
- <title>High Availability Singleton Fail-over</title>
- <para>The JBoss HA-JMS service (i.e., message queues topics and supporting services) only runs on a single node (i.e., the master node) in the cluster at any given time. If that node fails, the cluster simply elects another node to run the JMS service, and the queues, topics and supporting services are deployed on that server (fail-over). This setup provides redundancy against server failures but does not reduce the work load on the JMS server node.</para>
- <note>
- <para>While you cannot load balance HA-JMS queues (there is only one master node that runs the
- queues), you can load balance the MDBs that process messages from those queues (see <xref linkend="clustering-jms-loadbalanced"/>).</para>
- </note>
+ <title>JBoss Messaging Clustering Notes</title>
+
+ <section><title>Unique server peer id</title>
+ <para>
+ JBoss Messaging clustering should work out of the box in the <emphasis>all</emphasis> configuration with no configuration changes. It is however crucial that every node is assigned a unique server id.
+ </para>
+ <para>
+ Every node deployed must have a unique id, including those in a particular LAN cluster, and also those only linked by message bridges.
+ </para>
+ <para>
+ <xref linkend="messaging"/> outlines, specific messaging configuration settings referenced in this chapter.
+ </para>
+ </section>
+
+ <section><title>Clustered destinations</title>
+ <para>
+ JBoss Messaging clusters JMS queues and topics transparently across the cluster. Messages sent to a distributed queue or topic on one node are consumable on other nodes. To designate that a particular destination is clustered simply set the clustered attribute in the destination deployment descriptor to true.
+ </para>
+ <para>
+ JBoss Messaging balances messages between nodes, catering for faster or slower consumers to efficiently balance processing load across the cluster.
+ </para>
+ <para>
+ If you do not want message redistribution between nodes, but still want to retain the other characteristics of clustered destinations, you can specify the attribute <literal>ClusterPullConnectionFactoryName</literal> on the server peer.
+ </para>
+ </section>
+
+ <section><title>Clustered durable subs</title>
+
+ <para>
+ JBoss Messaging durable subscriptions can also be clustered. This means multiple subscribers can consume from the same durable subscription from different nodes of the cluster. A durable subscription will be clustered if it's topic is clustered.
+ </para>
+ </section>
+ <section><title>Clustered temporary destinations</title>
+
+ <para>
+ JBoss Messaging also supports clustered temporary topics and queues. All temporary topics and queues will be clustered if the post office is clustered.
+ </para>
+ </section>
+
+
+ <section><title>Non clustered servers</title>
+
+
+ <para>If you don't want your nodes to participate in a cluster, or only have one non clustered server you can set the clustered attribute on the postoffice to <literal>false</literal>.
+ </para>
+ </section>
+ <section><title>Message ordering in the cluster</title>
+
+ <para>
+ If you wish to apply strict JMS ordering to messages, such that a particular JMS consumer consumes messages in the same order as they were produced by a particular producer, you can set the <literal>DefaultPreserveOrdering</literal> attribute in the server peer to <literal>true</literal>. By default this is false.
+ </para>
+<note><title>Note</title><para>The side effect of setting this to true is that messages cannot be distributed as freely around the cluster.</para></note>
+</section>
-<section id="clustering-jms-singleton-server">
- <title>Server Side Configuration</title>
-
- <para>
- The biggest configuration difference between HA-JMS in the all configuration and the non-HA version found in the default configuration is the location of most configuration files. For HA-JMS, most configuration files are found in the deploy-hasingleton/jms directory, not in deploy/jms. Your queues and topics must be deployed in deploy-hasingleton (or a subdirectory of it like deploy-hasingleton/jms.) Application components that act as clients to HA-JMS (e.g., MDBs and other JMS clients) do not need to be deployed in deploy-hasingleton. They should only be deployed there if you only want them running on one node in the cluster at a time.
- </para>
- <para>
- To use the singleton fail-over HA-JMS service, you must configure JMS services identically on all nodes in the cluster. That includes all JMS related service MBeans and all deployed queues and topics. However, applications that use JMS (e.g., MDBs and other JMS clients) do not need to be deployed identically across the cluster.
- </para>
-
-
-
- <para>
- The JMS server is configured to persist its data in the <literal>DefaultDS</literal>. By default, that is the embedded HSQLDB. However, for the HA-JMS service fail-over to work, the newly started HA-JMS server needs to be able to find the data persisted by the old server. That's not likely to happen if the data is persisted in files written by the old servers' HSQLDB. In almost any cluster environments, all nodes need to persist data against a shared database. So, the first thing to do before you start clustered JMS is to setup a shared database for JMS. You need to do the following:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Configure <literal>DefaultDS</literal> to point to the database server of your choice.
- That is to replace the <literal>deploy/hsqlsb-ds.xml</literal> file with the
- <literal>xxx-ds.xml</literal> file in the <literal>docs/examples/jca</literal>
- directory, where <literal>xxx</literal> is the name of the target shared database (e.g.,
- <literal>mysql-ds.xml</literal>).</para>
- </listitem>
- <listitem>
- <para>Replace the <literal>hsqldb-jdbc2-service.xml</literal> file under the
- <literal>server/all/deploy-hasingleton/jms</literal> directory with one tuned to the
- specific database. For example if you use MySQL the file is
- <literal>mysql-jdbc2-service.xml</literal>. Configuration files for a number of
- RDBMS are bundled with the JBoss AS distribution. They can be found under
- <literal>docs/examples/jms</literal>.</para>
- </listitem>
- </itemizedlist>
- <note>
- <para>There is no need to replace the <literal>hsqldb-jdbc-state-service.xml</literal> file
- under the <literal>server/all/deploy-hasingleton/jms</literal> directory. Despite the
- <literal>hsql</literal> in its name, it works with all SQL92 compliant databases,
- including HSQL, MySQL, SQL Server, and more. It automatically uses the
- <literal>DefaultDS</literal> for storage, which we configured above.</para>
- </note>
- </section>
-
-
-
- <section id="clustering-jms-singleton-client">
- <title>Non-MDB HA-JMS Clients </title>
-
- <para>The HA-JMS client is different from regular JMS clients in two important aspects.</para>
-
- <itemizedlist>
- <listitem>
- <para>
- The HA-JMS client must look up JMS connection factories as well as queues and topicsusing HA-JNDI (the default port is 1100). This ensures the factory/queue/topic can be found no matter which cluster node is running the HA-JMS server.
- </para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>
- If the client is a J2EE component (session bean or web application) running inside the AS, the lookup via HA-JNDI can be configured using the component's deployment descriptors: In the standard deployment descriptor (ejb-jar.xml or web.xml):
- </para>
- </listitem>
-
- </itemizedlist>
-
-
-<programlisting><![CDATA[
-<resource-ref>
- <res-ref-name>jms/ConnectionFactory</res-ref-name>
- <res-type>javax.jms.QueueConnectionFactory</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-
-<resource-ref>
- <res-ref-name>jms/Queue</res-ref-name>
- <res-type>javax.jms.Queue</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-]]></programlisting>
-<para>
-And in the JBoss-specific descriptor (jboss.xml or jboss-web.xml):
-</para>
-
-<programlisting><![CDATA[
-<resource-ref>
- <res-ref-name>jms/ConnectionFactory</res-ref-name>
- <!-- Use the JMS Resource Adapter, let it deal
- with knowing where the JMS server is -->
- <jndi-name>java:/JmsXA</jndi-name>
- </resource-ref>
-
-<resource-ref>
- <res-ref-name>jms/Queue</res-ref-name>
- <!-- Use HA-JNDI so we can find the queue on any node -->
- <jndi-name>jnp://localhost:1100/queue/A</jndi-name>
-</resource-ref>]]>
-</programlisting>
-
-
- <itemizedlist>
- <listitem>
- <para>
- The HA-JMS client must deal with exceptions that will occur on the JMS connection if server failover occurs. Unlike, for example, clustered EJB proxies, the JMS connection object does not include automatic failover logic. If the HA-JMS service fails over to a different master node, all client operations on the current connection will fail with a JMSException. To deal with this:
- </para>
- </listitem>
- </itemizedlist>
-
- <itemizedlist>
- <listitem>
- <para>If the client is running inside the application server, the client should obtain the ConnectionFactory by looking up java:/JmsXAin JNDI. This will find the JBoss JMS Resource Adapter; the resource adapter will handle the task of detecting server failover and reconnecting to the new server when it starts.
- </para>
- </listitem>
- <listitem>
- <para>For clients outside the application server, the best approach is to register an ExceptionListener with the connection; the listener will get a callback if there is an exception on the connection. The callback should then handle the task of closing the old connection and reconnecting. Following is a example application that continuously sends messages to a queue, handling any exceptions that occur:
- </para>
- </listitem>
- </itemizedlist>
-
-
-<programlisting><![CDATA[
-package com.test.hajms.client;
-
-import javax.naming.InitialContext;
-import javax.jms.ConnectionFactory;
-import javax.jms.Destination;
-import javax.jms.Connection;
-import javax.jms.Session;
-import javax.jms.MessageProducer;
-import javax.jms.Message;
-import javax.jms.ExceptionListener;
-import javax.jms.JMSException;
-import javax.jms.DeliveryMode;
-
-import org.apache.commons.logging.Log;
-import org.apache.commons.logging.LogFactory;
-
-public class FailoverJMSClient
-{
-private static final Log log = LogFactory.getLog(FailoverJMSClient.class);
-
-public static final int NUM_RETRIES = 3;
-
-volatile boolean doSend = true;
-ConnectionFactory connectionFactory;
-Destination queue;
-Connection connection;
-Session session;
-MessageProducer producer;
-
-
-public static void main(String[] args) throws Exception
-{
-FailoverJMSClient jmsClient = new FailoverJMSClient();
-jmsClient.setUpJMS();
-jmsClient.sendMessages();
-}
-
-
-public boolean setUpJMS()
-{
-InitialContext ic;
-try
-{
-// assume jndi.properties is configured for HA-JNDI
-ic = new InitialContext();
-connectionFactory = (ConnectionFactory)ic.lookup("ConnectionFactory");
-queue = (Destination)ic.lookup("queue/FailoverTestQueue");
-connection = connectionFactory.createConnection();
-try
-{
-log.debug("Connection created ...");
-
-// KEY - register for exception callbacks
-connection.setExceptionListener(new ExceptionListenerImpl());
-
-session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
-log.debug("Session created ...");
-producer = session.createProducer(queue);
-
-producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
-log.debug("Producer created ...");
-
-return true;
-}
-catch (Exception e)
-{
-// We failed so close the connection
-try
-{
-connection.close();
-}
-catch (JMSException ignored)
-{
-// Pointless
-}
-// Rethrow the initial problem to where we will log it
-throw e;
-}
-finally
-{
-// And close the initial context
-// We don't want to wait for the garbage collector to close it
-// otherwise we'll have useless hanging network connections
-ic.close();
-}
-}
-catch (Exception e)
-{
-log.error("Error setting up JMS", e);
-return false;
-}
-}
-
-public void sendMessages()
-{
-int cnt = 0;
-while(doSend)
-{
-try
-{
-Thread.sleep(100);
-
-Message m = session.createObjectMessage(new Integer(cnt++));
-producer.send(m);
-
-log.trace("message " + cnt + " sent");
-
-}
-catch(Exception e)
-{
-cnt--;
-log.error(e.getMessage());
-}
-}
-}
-
-
-
-private class ExceptionListenerImpl implements ExceptionListener
-{
-public void onException(JMSException e)
-{
-
-for(int i = 0; i < NUM_RETRIES; i++)
- {
- log.warn("Connection has problems, trying to re-create it, attempt " +
- (i + 1) + " ...");
-
- try
- {
- connection.close(); // unregisters the ExceptionListener
- }
- catch(Exception e2) {
- // I will get an Exception anyway, since the connection to the
- //server is broken, but close() frees up resources associated
- // with the connection
- }
-
- boolean setupOK = setUpJMS();
-
- if (setupOK)
- {
- log.info("Connection re-established");
- return;
- }
- else
- {
- log.warn("Re-creating connection failed, retrying ...");
- }
- }
-
- log.error("Cannot re-establish connection, giving up ...");
- doSend = false;
- }
- }
-}
-]]>
-</programlisting>
-
-
-
-<section><title>MDBs and HA-JMS Failover</title>
- <para>
- When you deploy an MDB in JBoss, JBoss' MDB container handles for you all issues associated with finding the cluster singleton HA-JMS server and with reconnecting to it if it fails over.
- </para>
+<section><title>Idempotent operations</title>
+ <para>
+ If the call to send a persistent message to a persistent destination returns successfully with no exception, then you can be sure that the message was persisted. However if the call doesn't return successfully e.g. if an exception is thrown, then you <emphasis>can't be sure the message wasn't persisted</emphasis>. This is because the failure might have occurred after persisting the message but before writing the response to the caller. This is a common attribute of any RPC type call: You can't tell by the call not returning that the call didn't actually succeed. Whether it's a web services call, a HTTP get request, an EJB invocation the same applies. The trick is to code your application so your operations are <emphasis>idempotent</emphasis> i.e. they can be repeated without getting the system into an inconsistent state. With a message system you can do this on the application level, by checking for duplicate messages, and discarding them if they arrive. Duplicate che!
cking is a very powerful technique that can remove the need for XA transactions in many cases.
+ </para>
+
+<section><title>Clustered connection factories</title>
+ <para>
+ If the supportsLoadBalancing attribute of the connection factory is set to true then consecutive create connection attempts will round robin between available servers. The first node to try is chosen randomly.
+ </para>
+ <para>
+ If the supportsFailover attribute of the connection factory is set to true then automatic failover is enabled. This will automatically failover from one server to another, transparently to the user, in case of failure.
+ </para>
+ <para>
+ If automatic failover is not required or you wish to do manual failover (JBoss MQ style) this can be set to false, and you can supply a standard JMS ExceptionListener on the connection which will be called in case of connection failure. You would then need to manually close the connection, lookup a new connection factory from HA JNDI and recreate the connection.
+ </para>
</section>
- </section>
-
-
-
- <section id="clustering-jms-loadbalanced">
- <title>Load Balanced HA-JMS MDBs</title>
- <para>While the HA-JMS queues and topics only run on a single node at a time, MDBs on multiple nodes
- can receive and process messages from the HA-JMS master node. The contested queues and topics
- result in load balancing behavior for MDBs. To enable loading balancing for MDBs, you can
- specify a receiver for the queue. The receiver records which node is waiting for a message and
- in which order the messages should be processed. JBoss provides three receiver implementations.</para>
- <itemizedlist>
- <listitem>
- <para>The <literal>org.jboss.mq.server.ReceiversImpl</literal> is the default implementation
- using a <literal>HashSet</literal>.</para>
- </listitem>
- <listitem>
- <para>The <literal>org.jboss.mq.server.ReceiversImplArrayList</literal> is the implementation
- using an <literal>ArrayList</literal>.</para>
- </listitem>
- <listitem>
- <para>The <literal>org.jboss.mq.server.ReceiversImplLinkedList</literal> is the
- implementation using a <literal>LinkedList</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>You can specify the receiver implementation class name as an attribute in the MBean that
- defines the permanent JMS <literal>Queue</literal> or <literal>DestinationManager</literal> on
- each node. For best load balancing performance, we suggest you
- to use the <literal>ReceiversImplArrayList</literal> or
- <literal>ReceiversImplLinkedList</literal> implementations due to an undesirable implementation
- detail of <literal>HashSet</literal> in the JVM.</para>
- </section>
- </section>
-
- </chapter>
+</section>
+</chapter>
Modified: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml 2008-09-04 03:31:40 UTC (rev 77941)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JNDI.xml 2008-09-04 03:45:00 UTC (rev 77942)
@@ -169,31 +169,89 @@
<para>
If you want to access HA-JNDI from inside the application server, you must explicitly get an InitialContext by passing in JNDI properties. The following code shows how to create a naming Context bound to HA-JNDI:
</para>
-<programlisting>
- Properties p = new Properties();
- p.put(Context.INITIAL_CONTEXT_FACTORY,
- "org.jnp.interfaces.NamingContextFactory");
- p.put(Context.URL_PKG_PREFIXES, "jboss.naming:org.jnp.interfaces");
- p.put(Context.PROVIDER_URL, "localhost:1100"); // HA-JNDI port.
- return new InitialContext(p);
-</programlisting>
+<programlisting role="JAVA">Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY,
+"org.jnp.interfaces.NamingContextFactory");
+p.put(Context.URL_PKG_PREFIXES, "jboss.naming:org.jnp.interfaces");
+p.put(Context.PROVIDER_URL, "localhost:1100"); // HA-JNDI port.
+return new InitialContext(p);</programlisting>
<para>
The Context.PROVIDER_URL property points to the HA-JNDI service configured in the HANamingService MBean (see the section called “JBoss configuration”).
</para>
+
<para>
+ However, this does not work in all cases, especially when running a multihomed cluster (several JBoss instances on one machine bound to different IPs). A safer method is not to specify the Context.PROVIDER_URL (which does not work in all scenarios) but the partition name property:
+</para>
+<programlisting role="JAVA">Properties p = new Properties();
+p.put(Context.INITIAL_CONTEXT_FACTORY, "org.jnp.interfaces.NamingContextFactory");
+p.put(Context.URL_PKG_PREFIXES, "jboss.naming:org.jnp.interfaces");
+p.put("jnp.partitionName", "DefaultPartition"); // partition name.
+return new InitialContext(p);</programlisting>
+
+<para>
Do not attempt to simplify things by placing a jndi.properties file in your deployment or by editing the AS's conf/jndi.properties file. Doing either will almost certainly break things for your application and quite possibly across the application server. If you want to externalize your client configuration, one approach is to deploy a properties file not named jndi.properties, and then programatically create a Properties object that loads that file's contents.
</para>
+<section><title>Accessing HA-JNDI Resources from EJBs and WARs -- Environment Naming Context</title>
+ <para>If your HA-JNDI client is an EJB or servlet, the least intrusive way to configure the lookup of resources is to bind the resources to the environment naming context of the bean or webapp performing the lookup. The binding can then be configured to use HA-JNDI instead of a local mapping. Following is an example of doing this for a JMS connection factory and queue (the most common use case for this kind of thing.</para>
+ <para>Within the bean definition in the ejb-jar.xml or in the war's web.xml you will need to define two resource-ref mappings, one for the connection factory and one for the destination.</para>
+<programlisting role="XML"><resource-ref>
+ <res-ref-name>jms/ConnectionFactory</res-ref-name>
+ <res-type>javax.jms.QueueConnectionFactory</res-type>
+ <res-auth>Container</res-auth>
+</resource-ref>
+
+<resource-ref>
+ <res-ref-name>jms/Queue</res-ref-name>
+ <res-type>javax.jms.Queue</res-type>
+ <res-auth>Container</res-auth>
+</resource-ref></programlisting>
+
+<para>
+ Using these examples the bean performing the lookup can obtain the connection factory by looking up 'java:comp/env/jms/ConnectionFactory' and can obtain the queue by looking up 'java:comp/env/jms/Queue'.
+</para>
+<para>
+Within the JBoss-specific deployment descriptor (jboss.xml for EJBs, jboss-web.xml for a WAR) these references need to mapped to a URL that makes use of HA-JNDI.
+</para>
+<programlisting role="XML"><resource-ref>
+ <res-ref-name>jms/ConnectionFactory</res-ref-name>
+ <jndi-name>jnp://localhost:1100/ConnectionFactory</jndi-name>
+</resource-ref>
+
+<resource-ref>
+ <res-ref-name>jms/Queue</res-ref-name>
+ <jndi-name>jnp://localhost:1100/queue/A</jndi-name>
+ </resource-ref></programlisting>
+
+<para>The URL should be the URL to the HA-JNDI server running on the same node as the bean; if the bean is available the local HA-JNDI server should also be available. The lookup will then automatically query all of the nodes in the cluster to identify which node has the JMS resources available.
+</para>
+
</section>
+<section><title>Why do this programmatically and not just put this in a jndi.properties file?</title>
+<para>
+ The JBoss application server's internal naming environment is controlled by the <filename>conf/jndi.properties</filename> file, which should not be edited.
+</para>
+<para>
+ No other jndi.properties file should be deployed inside the application server because of the possibility of its being found on the classpath when it shouldn't and thus disrupting the internal operation of the server. For example, if an EJB deployment included a jndi.properties configured for HA-JNDI, when the server binds the EJB proxies into JNDI it will likely bind them into the replicated HA-JNDI tree and not into the local JNDI tree where they belong.
+</para>
+
+</section>
+
+<section><title>How can I tell if things are being bound into HA-JNDI that shouldn't be?</title>
+ <para>Go into the the jmx-console and execute the <literal>list</literal> operation on the <literal>jboss:service=JNDIView</literal> mbean. Towards the bottom of the results, the contents of the "HA-JNDI Namespace" are listed. Typically this will be empty; if any of your own deployments are shown there and you didn't explicitly bind them there, there's probably an improper jndi.properties file on the classpath. Please visit the following link for an example: <ulink url="http://www.jboss.com/index.html?module=bb&op=viewtopic&t=104715">Problem with removing a Node from Cluster</ulink> </para>
+
+</section>
+
+</section>
+
+
<section><title>For clients running outside the application server</title>
<para>The JNDI client needs to be aware of the HA-JNDI cluster. You can pass a list of JNDI servers (i.e., the nodes in the HA-JNDI cluster) to the <literal>java.naming.provider.url</literal> JNDI setting in the <literal>jndi.properties</literal> file. Each server node is identified by its IP address and the JNDI port number. The server nodes are separated by commas (see <xref linkend="clustering-jndi-jboss"/> for how to configure the servers and ports).</para>
-<programlisting>
-java.naming.provier.url=server1:1100,server2:1100,server3:1100,server4:1100
- </programlisting>
+<programlisting>java.naming.provier.url=server1:1100,server2:1100,server3:1100,server4:1100</programlisting>
<para>When initialising, the JNP client code will try to get in touch with each server node from the
list, one after the other, stopping as soon as one server has been reached. It will then download
the HA-JNDI stub from this node.</para>
@@ -251,14 +309,13 @@
<title>JBoss configuration</title>
<para>The <literal>cluster-service.xml</literal> file in the <literal>all/deploy</literal> directory
includes the following MBean to enable HA-JNDI services.</para>
- <programlisting>
-<mbean code="org.jboss.ha.jndi.HANamingService"
- name="jboss:service=HAJNDI">
- <depends optional-attribute-name="ClusterPartition"
- proxy-type="attribute">jboss:service=${jboss.partition.name:DefaultPartition}</depends>
+<programlisting role="XML"><mbean code="org.jboss.ha.jndi.HANamingService"
+name="jboss:service=HAJNDI">
+<depends optional-attribute-name="ClusterPartition"
+proxy-type="attribute">jboss:service=${jboss.partition.name:DefaultPartition}</depends>
-<mbean>
- </programlisting>
+<mbean></programlisting>
+
<para>You can see that this MBean depends on the <literal>DefaultPartition</literal> MBean defined above it (discussed earlier in this chapter). In other configurations, you can put that
element in the <literal>jboss-service.xml</literal> file or any other JBoss configuration files in
the <literal>/deploy</literal> directory to enable HA-JNDI services. The available attributes for
Added: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/General_Configuration.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/General_Configuration.xml (rev 0)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/General_Configuration.xml 2008-09-04 03:45:00 UTC (rev 77942)
@@ -0,0 +1,55 @@
+<?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="general_config">
+<title>General Configuration</title>
+<para>This chapter covers general configuration issues for the JBoss Application Server.
+</para>
+
+<section><title>Configuring Multiple JBoss Instances On One Machine</title>
+<para>
+
+</para>
+</section>
+
+<section><title>Hosting multiple domains with your JBoss Application Server</title>
+<para>
+This section discusses how you can use your application server to host multiple applications for multiple domains.
+</para>
+<para>
+In this section we use a scenario where a company has three domains with the DNS server pointing to the JBoss AS server:
+<orderedlist>
+<listitem>
+<para>www.domainA11.net</para>
+</listitem>
+<listitem>
+<para>www.domainB12.net</para>
+</listitem>
+<listitem>
+<para>www.domainC13.net</para>
+</listitem>
+</orderedlist>
+
+The company has developed three applications to service the above domains which serve its 3 main services:
+<orderedlist>
+<listitem>
+<para>applicationA.war</para>
+</listitem>
+<listitem>
+<para>applicationB.war</para>
+</listitem>
+<listitem>
+<para>applicationC.war</para>
+</listitem>
+</orderedlist>
+
+</para>
+
+
+
+
+
+</section>
+
+
+</chapter>
\ No newline at end of file
Modified: projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Messaging.xml
===================================================================
--- projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Messaging.xml 2008-09-04 03:31:40 UTC (rev 77941)
+++ projects/docs/community/5/Administration_And_Configuration_Guide/en-US/Messaging.xml 2008-09-04 03:45:00 UTC (rev 77942)
@@ -1,7 +1,7 @@
<?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><title>JBoss Messaging 1.4.1</title>
+<chapter id="messaging"><title>JBoss Messaging</title>
<para>JBoss Messaging is the new enterprise messaging system from JBoss. It is a complete rewrite of JBossMQ, the legacy JBoss JMS provider. It is the default JMS provider on JBoss AS 5. Production support is already available through JBoss EAP 4.3, and we offer developer support for JBoss 4.2.x.</para>
<para>JBoss Messaging is a high Performance JMS 1.1 compliant implementation integrated with JBoss Transactions. It also offers:
More information about the jboss-cvs-commits
mailing list