[jboss-cvs] JBossAS SVN: r100380 - 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
Wed Feb 3 23:41:04 EST 2010
Author: laubai
Date: 2010-02-03 23:41:03 -0500 (Wed, 03 Feb 2010)
New Revision: 100380
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Pooling.xml
Log:
Corrected Pooling, Performance Tuning chapters.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml 2010-02-03 23:58:45 UTC (rev 100379)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml 2010-02-04 04:41:03 UTC (rev 100380)
@@ -394,7 +394,7 @@
Modify <classname>JBossCustomDeployDUFilter</classname> in <filename>deployers/metadata-deployer-jboss-beans.xml</filename>.
</para>
</listitem>
-</itemizedlist><!--hajime-->
+</itemizedlist>
<para>
<classname>ScanningMetaData</classname> can come from the <filename>jboss-scanning.xml</filename> file placed in your <filename>META-INF</filename> directory. This is a simple example of this file:
</para>
@@ -409,8 +409,7 @@
</path>
</scanning> ]]>
</programlisting>
-<para>
-Here you list the paths inside your deployment, and which packages to include or exclude. If there is no explicit include, everything that is not excluded is included. If there is no path element at all, everything is excluded, as in the following example.</para>
+<para>Here you list the paths inside your deployment, and which packages to include or exclude. If there is no explicit include, everything that is not excluded is included. If there is no path element at all, everything is excluded, as in the following example.</para>
<programlisting><![CDATA[
<scanning xmlns="urn:jboss:scanning:1.0">
@@ -430,7 +429,7 @@
Database performance tuning involves changing the initial database conceptual schema to improve performance. Irrespective of type, overall database management system performance tuning involves effective and efficient use of your hardware (hard disk, CPU and RAM) and improving database reads and writes.
</para>
<para>
- Resource limits set by your operating system may also set limits on your database management system. A database administrator can analyze a database and identify performance bottlenecks through taking the above factors into consideration and adjusting the necessary database management system parameters such as writing dirty buffers to disk, checkpoints and log file rotations. In some instances hardware upgrades may also be necessary to improve database performance.
+ Resource limits set by your operating system may also set limits on your database management system. A database administrator can analyze a database and identify performance bottlenecks by taking the above factors into consideration and adjusting the necessary database management system parameters such as writing dirty buffers to disk, checkpoints and log file rotations. In some instances hardware upgrades may also be necessary to improve database performance.
</para>
<para>
Database connections can be costly to establish and manage. Applications that create new connections to the database with every transaction or query and then close that connection add a great deal of overhead. Having a very small connection pool will also throttle the applications as the JBoss Enterprise Web Platform by default queues the request for a default of 30,000 milliseconds (30 seconds) before cancellation and throwing an exception.
@@ -439,15 +438,11 @@
We recommend reliance on data source definitions you can setup in the deploy directory of the JBoss Enterprise Web Platform and utilizing the connection pool settings. Connection pooling in the JBoss Enterprise Web Platform allows you to easily monitor your connection usage from the JMX console to determine proper sizing. Your database management system may also shipped with tools that allow you to monitor connections.
</para>
<para>
- Depending on the databases implemented, please ensure you create a data source file in the deploy directory of your configuration as shown below:
+ Depending on the databases implemented, please ensure you create a data source file in the deploy directory of your configuration as shown below:</para>
+<screen>$JBOSS_HOME/server/$PROFILE/deploy/</screen>
+<para>
+The filename should be of the form <filename>$DATABASE_NAME-ds.xml</filename>.</para>
-<screen><JBoss_Home>/server/<your_configuration>/deploy/</screen>
-
-The filename should be in the following formats:
-
-<screen><yourdatabasename>-ds.xml</screen>
-</para>
-
<note><title>Note</title>
<para>
Please note that the name of the file must end with <filename>-ds.xml</filename> in order for the JBoss Enterprise Web Platform to recognize it as a <emphasis>data source file</emphasis>. The PostgreSQL database data source file for example is named <filename>postgres-ds.xml</filename>.
@@ -455,7 +450,7 @@
</note>
<note><title>Examples</title>
- <para>Examples of datasource definition files for external databases can be found in the <literal><JBoss_Home>/docs/examples/jca</literal> directory.</para>
+ <para>Examples of datasource definition files for external databases can be found in the <filename>$JBOSS_HOME/docs/examples/jca</filename> directory.</para>
</note>
</section>
@@ -467,18 +462,30 @@
clear what change has what effect.</para>
<section>
- <title>Ensuring Adequate Network Buffers</title>
- <para>The standard clustered services in the Enterprise Web Platform use UDP for intra-cluster communication, in order to take advantage of UDP-based IP multicast.
- A downside to the use of UDP is some of the lossless transmission guarantees that are provided at the OS network level with TCP instead need to be implemented in Java code.
- In order to achieve peak performance it is important to reduce the frequency of UDP packets being dropped in the network layers. A frequent cause of lost
- packets is inadequately sized network buffers on the machines that are hosting the cluster nodes. The Enterprise Web Platform clustering code will <emphasis>request</emphasis>
- adequately sized read and write buffers from the OS when it opens sockets, but most operating systems (Windows seems to be an exception) will only <emphasis>provide</emphasis> buffers
- up to a maximum size. This maximum read and write buffer sizes are configurable at the OS level, and the default values are too low to allow peak performance. So, a simple tuning step
- is to configure your OS to allow buffers up to the size the Enterprise Web Platform clustering code will request.</para>
+ <title>Ensuring Adequate Network Buffers</title>
+ <para>
+ The standard clustered services in the Enterprise Web Platform use UDP for intra-cluster
+ communication, in order to take advantage of UDP-based IP multicast.
+ A downside to the use of UDP is some of the lossless transmission guarantees that are
+ provided at the OS network level with TCP instead need to be implemented in Java code.
+ In order to achieve peak performance it is important to reduce the frequency of UDP packets
+ being dropped in the network layers. A frequent cause of lost
+ packets is inadequately sized network buffers on the machines that are hosting the
+ cluster nodes. The Enterprise Web Platform clustering code will <emphasis>request</emphasis>
+ adequately sized read and write buffers from the OS when it opens sockets, but most
+ operating systems (Windows seems to be an exception) will only <emphasis>provide</emphasis> buffers
+ up to a maximum size. This maximum read and write buffer sizes are configurable at the OS
+ level, and the default values are too low to allow peak performance. So, a simple tuning step
+ is to configure your OS to allow buffers up to the size the Enterprise Web Platform clustering
+ code will request.
+ </para>
- <para>The specific configuration steps needed to increase the maximum allowed buffer sizes are OS specific. See your OS documentation for instructions
- on how to increase these. For Linux systems, maximum values for these buffers sizes that will survive machine restarts can be set by editing
- the <literal>/etc/sysctl.conf</literal> file:</para>
+ <para>
+ The specific configuration steps needed to increase the maximum allowed buffer sizes
+ are OS specific. See your OS documentation for instructions on how to increase these.
+ For Linux systems, maximum values for these buffers sizes that will survive machine
+ restarts can be set by editing the <filename>/etc/sysctl.conf</filename> file:
+ </para>
<programlisting><![CDATA[# Allow a 25MB UDP receive buffer for JGroups
net.core.rmem_max = 26214400
@@ -493,15 +500,15 @@
This requires multiple NICs on your server machines, with request traffic coming in on one NIC and intra-cluster traffic using another. Once you
have the hardware set up, it is easy to tell the Enterprise Web Platform nodes to use a different interface for the intra-cluster traffic:</para>
- <screen>./run.sh -c all -b 10.0.0.104 -Djgroups.bind_addr=192.168.100.104</screen>
+ <screen>./run.sh -c production -b 10.0.0.104 -Djgroups.bind_addr=192.168.100.104</screen>
- <para>In the above example, the <literal>-Djgroups.bind_addr</literal> setting tells the the Enterprise Web Platform to run intra-cluster JGroups traffic
- over the 192.168.100.104 interface, with <literal>-b</literal> specifying that all other traffic should use 10.0.0.104.</para>
+ <para>In the above example, the <varname>-Djgroups.bind_addr</varname> setting tells the the Enterprise Web Platform to run intra-cluster JGroups traffic
+ over the <literal>192.168.100.104</literal> interface. The <code>-b</code> switch specifies that all other traffic should use <literal>10.0.0.104</literal>.</para>
</section>
<section>
<title>JGroups Message Bundling</title>
- <para>The JGroups group communication library used by the Enterprise Web Platform provides a feature known as "message bundling". Message
+ <para>The JGroups group communication library used by the Enterprise Web Platform provides a feature known as <emphasis>message bundling</emphasis>. Message
bundling is similar to nagling on a TCP socket — small messages are queued before sending (for up to a configurable maximum time) until a configurable number
of bytes have accumulated, and then the queued messages are bundled and sent as one large message. Use of bundling can have significant performance benefits
for high-volume asynchronous session replication. However, it is not enabled by default, as bundling can add significant latency to other types of intra-cluster
@@ -509,7 +516,7 @@
<para>If your application uses high volume session replication (web sessions or EJB3 stateful session beans), you might be able to increase performance by configuring
the distributed caching layer to use a JGroups channel configured with message bundling enabled. This is done by editing the
- <literal><JBoss_Home>/server/<your_configuration>/deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-jboss-beans.xml</literal> file. For example, for the cache used by default for
+ <filename>$JBOSS_HOME/server/$PROFILE/deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-jboss-beans.xml</filename> file. For example, for the cache used by default for
web sessions:</para>
<programlisting><![CDATA[. . .
@@ -546,7 +553,7 @@
</para>
<para>Buddy replication is enabled done by editing the
- <literal><JBoss_Home>/server/<your_configuration>/deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-jboss-beans.xml</literal> file. For example, for the cache used by default for
+ <filename>$JBOSS_HOME/server/$PROFILE/deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-jboss-beans.xml</filename> file. For example, for the cache used by default for
web sessions:</para>
<programlisting><![CDATA[. . .
@@ -574,21 +581,18 @@
<section>
<title>Reducing the Volume of Web Session Replication</title>
- <para>If your application is configured for web session replication, reducing the amount data being replicated can obviously improve performance.
- This can be accomplished both by avoiding replication when a request hasn't actually updated the session
- and by limiting replication to only the session data that has actually changed. See
- the discussion of <emphasis role="bold">replication-trigger</emphasis> and
- <emphasis role="bold">replication-granularity</emphasis> in <xref linkend="clustering-http-state"/> for
- how to configure your application to limit the amount of data replicated.</para>
+ <para>If your application is configured for web session replication, reducing the amount of
+ data being replicated can obviously improve performance. You can do this by not replicating data
+ when a request has not updated the session, and by limiting replication only to the changed
+ session data. See <xref linkend="clustering-http-state"/> for a discussion on
+ <literal>replication-trigger</literal> and <literal>replication-granularity</literal> and
+ instructions for configuring your application to limit data replication.</para>
</section>
<section>
<title>Reducing the Volume of EJB3 Stateful Session Bean Replication</title>
- <para>If your application is configured for EJB3 Stateful Session Bean replication, avoiding replication after bean requests that haven't modified
- state can improve performance. This can be controlled by having your bean class implement the
- <literal>org.jboss.ejb3.cache.Optimized</literal> interface. See <xref linkend="clustering-session-sfsb30"/>
- for details.</para>
+ <para>If your application is configured for EJB3 Stateful Session Bean replication, you can improve performance by avoiding replication after bean requests that haven't modified state. This can be controlled by having your bean class implement the <classname>org.jboss.ejb3.cache.Optimized</classname> interface. See <xref linkend="clustering-session-sfsb30"/> for details.</para>
</section>
<section>
@@ -623,51 +627,51 @@
<variablelist>
<varlistentry>
- <term><emphasis role="bold">jboss.jgroups:cluster=<cluster_name>,protocol=UDP,type=protocol</emphasis></term>
+ <term><code>jboss.jgroups:cluster=<cluster_name>,protocol=UDP,type=protocol</code></term>
<listitem>
<para>Provides statistical information on the sending and receipt of messages over the network,
along with statistics on the behavior of the two thread pools used to carry incoming messages
up the channel's protocol stack.</para>
<para>Useful attributes directly related to the rate of transmission and receipt include
- <literal>MessagesSent</literal>, <literal>BytesSent</literal>, <literal>MessagesReceived</literal> and
- <literal>BytesReceived</literal>.</para>
+ <varname>MessagesSent</varname>, <varname>BytesSent</varname>, <varname>MessagesReceived</varname> and
+ <varname>BytesReceived</varname>.</para>
<para>Useful attributes related to the behavior of the thread pool used to carry ordinary
incoming messages up the protocol stack include
- <literal>IncomingPoolSize</literal> and <literal>IncomingQueueSize</literal>. Equivalent
+ <varname>IncomingPoolSize</varname> and <varname>IncomingQueueSize</varname>. Equivalent
attributes for the pool of threads used to carry special, unordered "out-of-band" messages
- up the protocol stack include <literal>OOBPoolSize</literal> and <literal>OOBQueueSize</literal>.
- Note that <literal>OOBQueueSize</literal> will typically be <literal>0</literal> as the standard
+ up the protocol stack include <varname>OOBPoolSize</varname> and <varname>OOBQueueSize</varname>.
+ Note that <varname>OOBQueueSize</varname> will typically be <literal>0</literal> as the standard
JGroups configurations do not use a queue for OOB messages.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">jboss.jgroups:cluster=<cluster_name>,protocol=UNICAST,type=protocol</emphasis></term>
+ <term><code>jboss.jgroups:cluster=<cluster_name>,protocol=UNICAST,type=protocol</code></term>
<listitem><para>Provides statistical information on the behavior of the protocol responsible for
- ensuring lossless, ordered delivery of unicast (i.e. point-to-point) messages.</para>
- <para>The ratio of <literal>NumRetransmissions</literal> to <literal>MessagesSent</literal>
+ ensuring lossless, ordered delivery of unicast (that is, point-to-point) messages.</para>
+ <para>The ratio of <varname>NumRetransmissions</varname> to <varname>MessagesSent</varname>
can be tracked to see how frequently messages are not being received by peers and need to be retransmitted.
- The <literal>NumberOfMessagesInReceiveWindows</literal> attribute can be monitored to track
+ The <varname>NumberOfMessagesInReceiveWindows</varname> attribute can be monitored to track
how many messages are queueing up on a receipient node waiting for a message with an earlier
sequence number to be received. A high number indicates messages are being dropped and
need to be retransmitted.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">jboss.jgroups:cluster=<cluster_name>,protocol=NAKACK,type=protocol</emphasis></term>
+ <term><code>jboss.jgroups:cluster=<cluster_name>,protocol=NAKACK,type=protocol</code></term>
<listitem><para>Provides statistical information on the behavior of the protocol responsible for
- ensuring lossless, ordered delivery of multicast (i.e. point-to-multipoint) messages.</para>
- <para>Use the <literal>XmitRequestsReceived</literal> attribute to track how often a node is being
- asked to retransmit a messages it sent; use <literal>XmitRequestsSent</literal> to track how
- often a node is needing to request retransmission of a message.</para>
+ ensuring lossless, ordered delivery of multicast (that is, point-to-multipoint) messages.</para>
+ <para>Use the <varname>XmitRequestsReceived</varname> attribute to track how often a node is being
+ asked to retransmit a messages it sent; use <varname>XmitRequestsSent</varname> to track how
+ often a node needs to request retransmission of a message.</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><emphasis role="bold">jboss.jgroups:cluster=<cluster_name>,protocol=FC,type=protocol</emphasis></term>
+ <term><code>jboss.jgroups:cluster=<cluster_name>,protocol=FC,type=protocol</code></term>
<listitem><para>Provides statistical information on the behavior of the protocol responsible for
ensuring fast message senders do not overwhelm slow receivers.</para>
<para>Attributes useful for monitoring whether threads seeking to send messages are having to
- block while waiting for credits from receivers include <literal>Blockings</literal>,
- <literal>AverageTimeBlocked</literal> and <literal>TotalTimeBlocked</literal>.</para>
+ block while waiting for credits from receivers include <varname>Blockings</varname>,
+ <varname>AverageTimeBlocked</varname> and <varname>TotalTimeBlocked</varname>.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -678,11 +682,11 @@
<section id="Other_Tuning">
<title>Other key configurations</title>
<para>
- Other key configurations required for performance tuning of your Enterprise Web Platform include the <filename><JBoss_Home>/server/<your_configuration>/deployers/jbossweb.deployer/server.xml</filename> file that sets your HTTP requests pool.
+ Other key configurations required for performance tuning of your Enterprise Web Platform include the <filename>$JBOSS_HOME/server/$PROFILE/deployers/jbossweb.deployer/server.xml</filename> file that sets your HTTP requests pool.
</para>
<para>
JBoss Enterprise Web Platform 5 has a robust thread pooling, that should be sized appropriately.
- The server has a <filename>jboss-service.xml</filename> file in the <filename><JBoss_Home>/server/<your_configuration>/conf</filename> directory that defines the system thread pool.
+ The server has a <filename>jboss-service.xml</filename> file in the <filename>$JBOSS_HOME/server/$PROFILE/conf</filename> directory that defines the system thread pool.
There is a setting that defines the behavior if there isn't a thread available in the pool for execution. The default is to allow the calling thread to execute the task. You can monitor the queue depth of the system thread pool through the JMX Console, and determine from that if you need to make the pool larger.
</para>
@@ -691,7 +695,7 @@
</para>
<para>
The <literal>default</literal> configuration is appropriate for development, but not necessarily for a production environment. In the default configuration, console logging is enabled. Console logging is ideal for development, especially within the IDE, as you get all the log messages to show in the IDE console view.
- In a production environment, console logging is very expensive and is not recommended.
+ In a <literal>production</literal> environment, console logging is very expensive and is not recommended.
Turn down the verbosity level of logging if its not necessary. Please note that the less you log, the less I/O will be generated, and the better the overall throughput will be.
</para>
@@ -703,6 +707,4 @@
</section>
-
-
</chapter>
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Pooling.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Pooling.xml 2010-02-03 23:58:45 UTC (rev 100379)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Pooling.xml 2010-02-04 04:41:03 UTC (rev 100380)
@@ -4,20 +4,21 @@
<chapter id="pooling">
<title>Pooling</title>
-<section><title>Strategy</title>
-<para>
+ <section>
+ <title>Strategy</title>
+ <para>
<indexterm><primary>Pooling</primary><secondary>JBossJCA</secondary></indexterm>
- <ulink url="http://www.jboss.org/community/wiki/JBossJCA">JBossJCA</ulink> uses a <literal>ManagedConnectionPool</literal> to perform the pooling. The <literal>ManagedConnectionPool</literal> is made up of subpools depending upon the strategy chosen and other pooling parameters.
+ <ulink url="http://www.jboss.org/community/wiki/JBossJCA">JBossJCA</ulink> uses a <classname>ManagedConnectionPool</classname> to perform the pooling. The <classname>ManagedConnectionPool</classname> is made up of subpools depending upon the strategy chosen and other pooling parameters.
</para>
<informaltable frame="all">
<tgroup cols="4"><tbody>
<row>
<entry>
-<para>xml</para>
+<para>XML</para>
</entry>
<entry>
-<para>mbean</para>
+<para>MBean</para>
</entry>
<entry>
<para>Internal Name</para>
@@ -51,7 +52,7 @@
<para>PoolByCRI</para>
</entry>
<entry>
-<para>Use the connection properties from allocateConnection()</para>
+<para>Use the connection properties from <methodname>allocateConnection()</methodname></para>
</entry>
</row>
<row>
@@ -65,15 +66,15 @@
<para>PoolBySubject</para>
</entry>
<entry>
-<para>A pool per Subject, e.g. preconfigured or EJB/Web login subjects</para>
+<para>A pool per Subject, for example, preconfigured or EJB/Web login subjects</para>
</entry>
</row>
<row>
<entry>
-<para><security-domain-and-applicaton/></para>
+<para><security-domain-and-application/></para>
</entry>
<entry>
-<para>ByContainerAndApplicaton</para>
+<para>ByContainerAndApplication</para>
</entry>
<entry>
<para>PoolBySubjectAndCri</para>
@@ -84,12 +85,12 @@
</row></tbody></tgroup>
</informaltable>
-<note><title>Note</title>
-<para>The xml names imply this is just about security. This is misleading. </para>
+<note>
+<para>Despite the XML names, these properties do not only relate to security.</para>
</note>
<para>
-For <security-domain-and-application/> the Subject always overrides any user/password from createConnection(user, password) in the CRI: </para>
+For <literal><security-domain-and-application/></literal> the Subject always overrides any user/password from createConnection(user, password) in the CRI: </para>
<screen>(
ConnectionRequestInfo
@@ -97,33 +98,37 @@
</section>
-<section><title>Transaction stickness</title>
+<section><title>Sticky Transactions</title>
+ <para>Transaction stickiness is enabled by default in JBOss Enterprise Web Platform. The <literal><track-connection-by-tx/></literal> flag, which forced a pool connection to be reused throughout a transaction, is deprecated. This is the only supported behavior for local transactions. XA users can explicitly enable interleaving with the <literal><interleaving/></literal> element.</para>
+
+<!--<section><title>Sticky Transactions</title>
<para>
-You can force the same connection from a (sub-)pool to get reused throughout a transaction with the <track-connection-by-tx/> flag
+You can force the same connection from a (sub-)pool to be reused throughout a transaction with the <literal><track-connection-by-tx/></literal> flag.
</para>
-<note><title>Note</title>
-<para>This is the only supported behaviour for <emphasis>"local"</emphasis> transactions. This element is deprecated in JBoss Enterprise Web Platform 5 where transaction stickiness is enabled by default. XA users can explicitly enable interleaving with <interleaving/> element.</para>
-</note>
+<note>
+<para>
+
+This is the only supported behaviour for <emphasis>local</emphasis> transactions. This element is deprecated in JBoss Enterprise Web Platform where transaction stickiness is enabled by default. XA users can explicitly enable interleaving with <interleaving/> element.</para>
+</note>-->
</section>
<section><title>Workaround for Oracle</title>
-<para>Oracle does not like XA connections getting used both inside and outside a JTA transaction. To workaround the problem you can create separate sub-pools for the different contexts using <no-tx-separate-pools/>.</para>
+<para>Oracle does not like XA connections getting used both inside and outside a JTA transaction. To work around the problem you can create separate sub-pools for the different contexts using <literal><no-tx-separate-pools/></literal>.</para>
</section>
<section><title>Pool Access</title>
<para>
The pool is designed for concurrent usage.
</para>
-
<para>
-Upto <max-pool-size/> threads can be inside the pool at the same time (or using connections from a pool).
+Up to <literal><max-pool-size/></literal> threads can be inside the pool at the same time (or using connections from a pool).
</para>
<para>
- Once this limit is reached, threads wait for the <blocking-timeout-seconds/> to use the pool before throwing a <ulink url="http://www.jboss.org/community/wiki/WhatDoesTheMessageNoManagedConnectionsAvailableMean">No Managed Connections Available</ulink>
+ Once this limit is reached, threads wait for a period defined by <literal><blocking-timeout-seconds/></literal> to use the pool before throwing a <exceptionname>NoManagedConnectionsAvailable</exceptionname> exception.
</para>
<para>
-You may want to use the <allocation-retry/> and <allocation-retry-wait-millis/> elements to have the pool retry to obtain a connection before throwing the exception.
+The <literal><allocation-retry/></literal> and <literal><allocation-retry-wait-millis/></literal> elements let the pool retry a connection attempt before throwing the exception.
</para>
</section>
@@ -131,91 +136,81 @@
<para>
The number of connections in the pool is controlled by the pool sizes.
</para>
-<itemizedlist>
-<listitem>
-<para><min-pool-size/> - When the number of connections falls below this size, new connections are created</para>
-</listitem>
-<listitem>
-<para><max-pool-size/> - No more than this number of connections are created</para>
-</listitem>
-<listitem>
-<para><prefill/> - Feature Request has been implemented for 4.0.5. Note: the only pooling strategy that supports this feature is OnePool?, or ByNothing? pooling criteria.</para>
-</listitem>
-</itemizedlist>
-<para>
-The pool filling is done by a separate "Pool Filler" thread rather than blocking application threads.</para>
+<variablelist>
+ <varlistentry>
+ <term><varname><min-pool-size/></varname></term>
+ <listitem><para>New connections are created when the number of connections falls below the number specified.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><max-pool-size/></varname></term>
+ <listitem><para>The maximum number of connections.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname><prefill/></varname></term><!--NEEDINFO-->
+ <listitem><para>Supported only by <literal>OnePool</literal> or <literal>ByNothing</literal> pooling strategies.</para></listitem>
+ </varlistentry>
+</variablelist>
+<para>Filling the thread pool is done by a separate <classname>PoolFiller</classname> thread to avoid blocking application threads.</para>
</section>
<section><title>Idle Connections</title>
<para>
-You can configure connections to be closed when they are idle. e.g. If you just had a peak period and now want to reap the unused ones. This is done via the <idle-timeout-minutes/>.</para>
+ You can configure connections to close when they are idle with the <literal><idle-timeout-minutes/></literal>.
+</para>
<para>
-Idle checking is done on a separate "Idle Remover" thread on an LRU (least recently used) basis. The check is done every idle-timeout-minutes divided by 2 for connections unused for idle-timeout-minutes.</para>
+ Idle checking is done on a separate <classname>IdleRemover</classname> thread on a LRU (least recently used) basis. The check is done twice per <varname>idle-timeout-minutes</varname> period for connections that have not been used for <varname>idle-timeout-minutes</varname>.</para>
<para>
-The pool itself operates on an MRU (most recently used) basis. This allows the excess connections to be easily identified.
+ The pool itself operates on an MRU (most recently used) basis. This allows the excess connections to be easily identified.
</para>
<para>
-Should closing idle connections cause the pool to fall below the min-pool-size, new/fresh connections are created.
+ Should closing idle connections cause the pool to fall below the <varname>min-pool-size</varname>, new connections are created.
</para>
-<note><title>Note</title>
-<para>If you have long running transactions and you use interleaving (i.e. don't track-connection-by-tx) make sure the idle timeout is greater than the transaction timeout. When interleaving the connection is returned to the pool for others to use. If however nobody does use it, it would be a candidate for removal before the transaction is committed.
+<note>
+<para>If you have long running transactions and you use interleaving (that is, do not enable <varname>track-connection-by-tx</varname>), make sure the idle timeout is greater than the transaction timeout. When interleaving, the connection is returned to the pool for others to use. If it remains unused, it still becomes a candidate for removal before the transaction is committed.
</para>
</note>
</section>
<section><title>Dead connections</title>
<para>
-The JDBC protocol does not provide a natural <literal>connectionErrorOccured()</literal> event when a connection is broken. To support dead/broken connection checking there are a number of plugins.</para>
+The JDBC protocol does not provide a natural <methodname>connectionErrorOccured()</methodname> event when a connection is broken. There are a number of plugins available to support dead/broken connection checking.</para>
<section><title>Valid connection checking</title>
-<para>
-The simplest format is to just run a "quick" sql statement:
-
+<para>The simplest option is to run an SQL statement like the following before handing the connection to the application.</para>
<screen><check-valid-connection-sql>select 1 from dual</check-valid-connection-sql></screen>
-
-before handing the connection to the application. If this fails, another connection is selected until there are no more connections at which point new connections are constructed.
+<para>
+ If this fails, another connection is selected until there are no more connections at which point new connections are constructed.
</para>
<para>
-The potentially more performant check is to use vendor specific features, e.g. Oracle's or MySQL's pingDatabase() via the
-<screen><valid-connection-checker-class-name/></screen>
+ The potentially more performant check is to use vendor specific features, such as Oracle's or MySQL's <methodname>pingDatabase()</methodname>, with the <varname><valid-connection-checker-class-name/></varname> element.
</para>
</section>
<section><title>Errors during SQL queries</title>
<para>
-You can check if a connection broke during a query by the looking the error codes or messages of the SQLException for FATAL errors rather than normal SQLExceptions. These codes/messages can be vendor specific, e.g.
+ You can check whether a connection broke during a query by looking for <literal>FATAL</literal> errors in the <exceptionname>SQLException</exceptionname>'s error messages. These messages can be vendor-specific, for example:</para>
<screen><exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter</exception-sorter-class-name></screen>
-
-For
-
-<screen>FATAL</screen>
-
-errors the connection will be closed.</para>
+<para>
+ <literal>FATAL</literal> errors will close the connection.
+</para>
</section>
<section><title>Changing/Closing/Flushing the pool</title>
-
-<itemizedlist>
-<listitem>
- <para><ulink url="http://www.jboss.org/community/wiki/HowDoIChangeThePoolingParameters">change or flush()</ulink> the pool</para>
-</listitem>
-<listitem>
-<para>closing/undeploying the pool will do a flush first</para>
-</listitem>
-</itemizedlist>
-
+<para>
+ Use JMX to change the attributes on the connection pool, like so:
+</para>
+<screen>jboss.jca:service=JBossManagedConnectionPool,name=<jndi-name></screen>
+<para>
+ Then use <methodname>flush()</methodname> to reset the pools. <methodname>flush()</methodname> closes all idle connections immediately. Any connections in use are closed after the application is finished with them. New connections are then created.
+</para>
</section>
-<section><title>Other pooling</title>
+<!--<section><title>Other pooling</title>
<para><ulink url="http://www.jboss.org/community/docs/DOC-10020?uniqueTitle=false">Thirdparty Pools</ulink> - only if you know what you are doing</para>
+</section>-->
</section>
-</section>
-
-
-
-
</chapter>
More information about the jboss-cvs-commits
mailing list