[jboss-cvs] JBossAS SVN: r93110 - projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Sep 1 21:11:22 EDT 2009
Author: irooskov at redhat.com
Date: 2009-09-01 21:11:22 -0400 (Tue, 01 Sep 2009)
New Revision: 93110
Modified:
projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml
Log:
updated chapter to make new additions build correctly
Modified: projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml
===================================================================
--- projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml 2009-09-02 00:01:15 UTC (rev 93109)
+++ projects/docs/enterprise/5.0/Administration_And_Configuration_Guide/en-US/Performance_Tuning.xml 2009-09-02 01:11:22 UTC (rev 93110)
@@ -17,7 +17,7 @@
Application design, hardware/network profile, operating system, application software development, testing and deployment all play a major role in performance tuning. A bottleneck in performance therefore could be caused by these factors not just your application. Recent studies show that most performance problems are the result of the applications not the middleware or the operating systems. This could be associated with the technological developments in computer software, hardware and networking which has increased their reliability.
</para>
<para>
- Improvement of application design and undertaking performance review of your applications before implementation is vital to avoiding bottlenecks after implementation. To undertake a performance review you need to setup a test environment undertake and analyse the test results. To effectively undertake a review, you also need to identify peak application workload times and the difference from normal workload periods. Peak workload times could be during the day, week, certain periods of the month, quarter or year. In understanding peaks workloads it is advisable not to go by averages as the peaks may be much more than the averages calculated over a period. The system requirements are bound by the peaks in the workload not the averages. On undertaking tuning it is recommended to carry out a few more tests and tuning of your system until a satisfactory performance is achieved.
+ Improvement of application design and undertaking performance review of your applications before implementation is vital to avoiding bottlenecks after implementation. To undertake a performance review you need to setup a test environment undertake and analyze the test results. To effectively undertake a review, you also need to identify peak application workload times and the difference from normal workload periods. Peak workload times could be during the day, week, certain periods of the month, quarter or year. In understanding peaks workloads it is advisable not to go by averages as the peaks may be much more than the averages calculated over a period. The system requirements are bound by the peaks in the workload not the averages. On undertaking tuning it is recommended to carry out a few more tests and tuning of your system until a satisfactory performance is achieved.
</para>
</section>
@@ -25,7 +25,7 @@
<section id="Hardware_Tuning">
<title>Hardware tuning</title>
<para>
- To develop a suitable hardware configuration that suits the performance of your applications on the JBoss Enterprise Application Platform, you need to understand the impact the selected hardware configuration may have on other applications and overall operating system performance.
+ To develop a suitable hardware configuration that suits the performance of your applications on the JBoss Enterprise Application Platform, you need to understand the impact that the selected hardware configuration may have on other applications and overall operating system performance.
</para>
<para>
To understand hardware performance tuning issues, it is also very critical to understand the hardware architecture of your system.
@@ -96,7 +96,7 @@
<section id="OS_Tuning"><title>Operating System Performance Tuning</title>
<para>
- Most modern operating systems now ship with performance tuning or profiling tools that can help you monitor CPU, memory, hard disk and network usage in realtime.
+ Most modern operating systems now ship with performance tuning or profiling tools that can help you monitor CPU, memory, hard disk and network usage in real-time.
</para>
<para>
On Windows the task manager and performance monitor can be helpful in identifying system performance bottlenecks while in unix based operating systems <literal>top</literal> and <literal>ps</literal> are used for the same purpose. Linux distributions such as Red Hat Enterprise Linux and Fedora provide a graphical user interface <literal>System Monitor</literal> that is useful to monitor system performance.
@@ -105,14 +105,14 @@
Operating system performance tuning is about resource management to respond to individual requests. Managing operating system scalability on the other hand involves managing resource consumption with varying volumes (low to very high) of requests.
</para>
<para>
- Overall operational performance metrics that are critical for the business such as response time to user requests, database, network, CPU and memory performance among other metrics should be identified and tested and logged in realtime where possible or with system rollouts
+ Overall operational performance metrics that are critical for the business such as response time to user requests, database, network, CPU and memory performance among other metrics should be identified and tested and logged in real-time where possible or with system deployments
</para>
<para>
For clustered environments, understanding and monitoring your cluster's performance and identifying overloads early is critical to system failure prevention.
</para>
<section><title>Networking</title>
<para>
- Network configurations may contribute to performance bottlenecks and may be hard to detect. For example a user may get an error on their browser when trying to load a web application on a dialup connection while the same page may load on a broadband internet connection. The main issue in this scenario may be bandwidth and may not be obviosly displayed in the error message displayed.
+ Network configurations may contribute to performance bottlenecks and may be hard to detect. For example a user may get an error on their browser when trying to load a web application on a dial up connection while the same page may load on a broadband internet connection. The main issue in this scenario may be bandwidth and may not be obviously displayed in the error message displayed.
</para>
<para>
Identifying network architecture and infrastructure is therefore critical in performance tuning and fixing system bottlenecks.
@@ -121,10 +121,10 @@
Most modern operating systems provide you with network hardware configuration tools while some hardware manufacturers may also provide extended network hardware configuration tools with their drivers.
</para>
<para>
- Most operating systems support different communication protocols which you can tweak. Factors such as TCP buffer memory space, connection buffer limits and acknowledgement options among others should be take into account in your network design.
+ Most operating systems support different communication protocols which you can tweak. Factors such as TCP buffer memory space, connection buffer limits and acknowledgment options among others should be take into account in your network design.
</para>
<para>
- Deciding to turn DNS lookups on or off in your web servers can also affect your performance but may be necessary to turn on for high security environments. Factoring this and allocating necessary resources or hardware can help improve system performance.
+ Deciding to turn DNS lookup on or off in your web servers can also affect your performance but may be necessary to turn on for high security environments. Factoring this and allocating necessary resources or hardware can help improve system performance.
</para>
</section>
@@ -134,7 +134,7 @@
<section id="JVM_Tuning">
<title>Tuning the JVM</title>
<para>
- For java based applications, it is recommended to also be familiar with tuning of your Java Virtual Machine (JVM). Some key aspects of your JVM that need tweaking include managing out of memory exceptions, java heap settings and garbage collection. Please refer to the JDK 5 documentation on <ulink url="http://java.sun.com/j2se/1.5.0/docs/">http://java.sun.com/j2se/1.5.0/docs/</ulink> for further discussions on this.
+ For java based applications, it is recommended to also be familiar with tuning of your Java Virtual Machine (JVM). Some key aspects of your JVM that need tweaking include managing out of memory exceptions, java heap settings and garbage collection. Please refer to the JDK 6 documentation on <ulink url="http://java.sun.com/j2se/1.6.0/docs/">http://java.sun.com/j2se/1.6.0/docs/</ulink> for further discussions on this.
</para>
@@ -147,7 +147,7 @@
Good application design and development practices are critical to ensuring satisfactory application performance. Data reads or writes and processing by your applications may cause performance bottlenecks due to factors such as timeouts on remote servers memory allocation or network issues among other factors. Understanding how each application works is therefore crucial in identifying performance bottlenecks. Setting expected time duration each code part is expected to take can help develop realistic benchmarks against which the applications can be reviewed. These benchmarks should take into account high and low peak usage times for the applications and not averages as these may highly vary from the peak times.
</para>
<para>
- In addition, using benchmarking tools to test your applications may be a quick way to pinpoint issues in your code which can often be causes for performance bottlenecks. Iterative tests are recommended to identify cache and other hardware issues that may arise due to startup or other factors.
+ In addition, using bench-marking tools to test your applications may be a quick way to pinpoint issues in your code which can often be causes for performance bottlenecks. Iterative tests are recommended to identify cache and other hardware issues that may arise due to start up or other factors.
</para>
<para>
The JBoss Application Server web console <ulink url="http://localhost:8080/web-console/">http://localhost:8080/web-console/</ulink> provides you with monitoring tools starting with the JVM Hardware environment statistics on the default page and access to monitoring tools and snapshots.
@@ -166,12 +166,16 @@
<section>
<title>Instrumentation</title>
<para>
- Applications should always be instrumented for performance analysis. In most cases, it is evident that performance requirements and peak workloads examined before production are incorrect compared to during production. Without instrumentation of your applications, you will lack accurate tracking data. Workloads on your applications can also change over time, as the business size, models or environment changes.
+ Applications should be instrumented for performance analysis. In most cases, the actual production workload is different than the expected workload. Without instrumentation of your applications, you will lack accurate tracking data. Workloads on your applications can also change over time, as the business size, models or environment changes.
</para>
<para>
Instrumentation in the past would have had to be embedded in the application. Today, there are many solutions for instrumentation that do not require developers to code. Commercial products, and the JBoss AOP framework can be used for just this purpose. You can also turn on call statistics in the containers, and Hibernate statistics. For more on this please refer to the AOP and Hibernate project pages.
</para>
+<para>
+ Taking successive thread dumps (includes the current call stack for each Java application server thread) can give the application developers enough information to get a sense for what is going on in the application. This is something that you might do after the application has hit a performance wall. If the performance problem lasts for five minutes, you might generate a thread dump one a minute. You can use the JVM "jps -l" command to get a list of running Java applications and the process ids for each. Note the process id for the "org.jboss.Main" application. You will then run the "jstack ProcessID" command (replacing ProcessID with the "org.jboss.Main" process id) and that will generate the thread dump. Of course, you should redirect the output of the jstack command to save the output ("jstack ProcessID > threaddump1.txt").
+</para>
+
</section>
</section>
@@ -184,43 +188,213 @@
<section id="Memory_Usage_Tuning"><title>Memory usage</title>
<para>
- Memory usage of Java applications including the JBoss Enterprise Application Platform is dictated by the heap space allocated. You could therefore as an example, reduce 1GB heap space you currently have allocated to 800MB to save space.
+ Memory usage of Java applications including the JBoss Enterprise Application Platform is dictated by the heap space allocated. You could therefore as an example, reduce 1GB heap space you currently have allocated to 800MB to reduce memory footprint (if you have enough headroom).
</para>
<para>
- There are several instances where the Java Virtual Machine (JVM) may report <literal>OutOfMemoryError</literal> even when it is not really out of its available memory. The JVM may report an out of memory error when it is really out of memory or when only a segment or generation of the heap space is exhausted as most modern JVM's divide the heap space into generations/segments. Another example could be inability of the operating system (occurs on Linux/Unix systems)to create new threads for the JVM.
+ The Java Virtual Machine (JVM) manages segments (generations) of memory. If a segment of the heap space is exhausted, you will see a Java OutOfMemoryError (OOME). All bets are off, when you get a Java OutOfMemoryError. The application should be restarted to correct any bad state. Part of tuning is checking how much memory headroom you have while under load. If available memory is too low, you will need to increase the max Java memory size (possibly switching to a 64-bit JVM if needed).
+
</para>
<para>
- Running out of memory generates an Error that is not likely to be masked in a catch block because it is an Error rather than an Exception. This is important since one often sees theories expressed about OutOfMemoryError being reported erroneously. That is very unlikely, although OOMEs do occur when the heap has plenty of memory or plenty of recoverable memory. An OOME is also thrown when the permanent memory is exhausted and that is not part of the heap per se. That is a JVM specific area of memory where information on loaded classes is maintained. If you have a mountain of classes (e.g, a lot of EJBs and JSP pages) you can easily exhaust this area. Oftentimes an application will fail to deploy or fail to redeploy. Increase your permanent memory space as follows to avoid OOMEs. The default with the <literal>-server</literal> switch is 64 megabytes:
-<screen>-XX:MaxPermSize?=128m</screen>
+ Running out of memory generates an Error that is not likely to be masked in a Java catch block because it is an Error rather than an Exception. An OOME is also thrown when the permanent memory is exhausted and that is not part of the heap per se. That is a JVM specific area of memory where information on loaded classes is maintained. If you have a mountain of classes (e.g, a lot of EJBs and JSP pages) you can easily exhaust this area. Oftentimes an application will fail to deploy or fail to redeploy. Increase your permanent memory space as follows to avoid OOMEs. The default with the <literal>-server</literal> switch is 64 megabytes:
+<screen>-XX:MaxPermSize?=256m</screen>
</para>
<para>
- Note this is in addition to the heap. In this case we have 512M heap, 128M permanent space for a total of 640 megabytes. Don't forget the JVM itself takes up a chunk of system memory and there is also two megs per thread of stack space. That can add up with a lot of HTTP/S processors.
+ Note this is in addition to the heap. In this case we have 512M heap, 256M permanent space for a total of 768 megabytes. Don't forget the JVM itself takes up a chunk of system memory and there is also per thread stack space (size varies based on OS). That can add up with a lot of HTTP/S processors.
</para>
<para>
- <literal>-XX:MaxPermSize?=128m -Xmx512m</literal> (total of 640 megabytes allocated from system - this is not the total size of the VM and does not include the space the VM allocates for the "C heap" or stack space)
+ <literal>-XX:MaxPermSize?=256m -Xmx512m</literal> (total of 768 megabytes allocated from system - this is not the total size of the VM and does not include the space the VM allocates for the "C heap" or stack space)
</para>
- <para>
- On Windows, you can set this in the <filename><JBOSS_HOME>\bin\run.bat</filename> file by setting
-<screen>JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -XX:MaxPermSize?=128m</screen>
- </para>
<para>
- The HotSpot Java Virtual Machine ships with J2SE 1.4.2 and above and consists of various garbage collection tools which you can use to collect garbage collection information that you can use to tune your applications. You can find more information on the HotSpot Virtual machine on <ulink url="http://java.sun.com/docs/hotspot/gc1.4.2/">http://java.sun.com/docs/hotspot/gc1.4.2/</ulink>.
+ The HotSpot Java Virtual Machine consists of various garbage collection tools which you can use to collect garbage collection information that you can use to tune your applications. You can find more information on the HotSpot Virtual machine on <ulink url="http://java.sun.com/javase/technologies/hotspot/">http://java.sun.com/javase/technologies/hotspot/</ulink>.
</para>
<para>
- The <ulink url="http://java.sun.com/performance/jvmstat/">jvmstat toolkit</ulink> is recommended for the Hotspot JVM and can help give you a precise picture of your permanent memory space and the other segments on the heap. Please visit the link above for more information on the toolkit.
+ Java 6 includes new tools that help monitor Java applications. Jmap can generate a heap dump file (<ulink url="http://java.sun.com/javase/6/docs/technotes/tools/share/jmap.html">http://java.sun.com/javase/6/docs/technotes/tools/share/jmap.html</ulink>) that can easily be read by the Eclipse Memory Analyzer tool (<ulink url="http://www.eclipse.org/mat/">http://www.eclipse.org/mat/</ulink>). The jstat tool (http://java.sun.com/javase/6/docs/technotes/tools/share/jstat.html) can help give you a precise picture of
+your permanent memory space and the other segments on the Java memory heap.
</para>
<section id="VFS_Tuning">
<title>VFS Tuning</title>
+ <para>
+When looking for various tuning options, most of the information that exists can be found in <classname>VFSUtils</classname> class.
+Its string constants point us to different possible system property settings we can use to configure VFS behavior:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <property>jboss.vfs.forceCopy</property> - has the options true and false, with the default being false.
+ </para>
+ <para>
+ This defines how nested jars should be handled. If forceCopy equals true, we create a temporary copy of the nested jar, and re-wire VFS accordingly. If forceCopy equals false, we handle nested jars in-memory, which doesn't create temporary copy, but is more memory consuming. Currently JBoss Enterprise Application Platform forces temporary copy by default.
+ </para>
+ <para>
+ If the <property>useCopyJarHandler</property> property is used as part of URI query, you can configure force-copy at runtime, per URI root (if it doesn't already exist).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>jboss.vfs.forceVfsJar</property> has the options true and false, with the default being false.
+ </para>
+ <para>
+ By setting this property to true, you can implement the old JAR handling. Set to false by default, old JAR handling was deprecated in favor of new ZIP handling code.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>jboss.vfs.forceNoReaper</property> has the options true and false, with the default being false.
+ </para>
+ <para>
+ To gain a bit on performance, we close JAR files asynchronously via the separate reaper thread. If you wish to close JAR files synchronously, you can force no usage of the reaper thread. This can also be defined using the URI query and the <literal>noReaper</literal> query section.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>jboss.vfs.forceCaseSensitive</property> has the options true and false, with the default being false.
+ </para>
+ <para>
+ With this enabled you can force differentiation between lower and upper cased file paths.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <property>jboss.vfs.optimizeForMemory</property> has the options true and false, with the default being false.
+ </para>
+ <para>
+ With this enabled we re-order in-memory JAR handling, to gain on memory consumption.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>jboss.vfs.cache</classname> (<classname>org.jboss.virtual.spi.cache.helpers.NoopVFSCache</classname>) class can be defined in order to re-use existing temporary files (in order not to re-do all unpacking and wiring). The VFS registry will use the defining of this class to keep its existing VFS roots.
+ </para>
+ <para>
+ Every <methodname>VirtualFile</methodname> lookup from the VFS class uses this <literal>singleton</literal> cache instance to check for an existing matching cache entry. By matching we also consider any existing <emphasis>ancestor</emphasis> from which you can use exact <methodname>VirtualFile</methodname> instance.
+ </para>
+ </listitem>
+ </itemizedlist>
<section>
<title>VFS Cache Tuning</title>
- <para>Magic about the caching settings...</para>
+ <para>
+As described before, VFS cache holds VFS roots, from which any VirtualFile lookup can access existing VirtualFile instances.
+This is a sepcially useful in the case of temporary files (created from nested JARs), meaning you don't have to do multiple unpackings for nested JAR file related resources.</para>
+<para>
+By default in VFS there is no caching involved as <classname>org.jboss.virtual.spi.cache.helpers.NoopVFSCache</classname> is used.
+But you can provide your own implementation or choose from existing VFS implementations.</para>
+
+<para>
+Cache implementations from the <literal>org.jboss.virtual.plugins.cache</literal> package are:</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ <classname>SoftRefVFSCache</classname>: uses soft reference as map's entry value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>WeakRefVFSCache</classname>: uses weak reference as map's entry value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>TimedVFSCache</classname>: evicts cache entries after defaultLifetime.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>LRUVFSCache</classname>: evicts cache entries based on LRU, keeping min and max entries.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <classname>CombinedVFSCache</classname>: holds few permanent roots, any other new root is cached in its realCache property.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+ In the JBoss Enterprise Application Platform we use <classname>CombinedVFSCache</classname> as we know which are our permanent roots to watch and keep.
+ This is how it's configured in MC's bean configuration file.
+</para>
+<programlisting><![CDATA[
+ <bean name="VFSCache">
+ <constructor factoryClass="org.jboss.virtual.spi.cache.VFSCacheFactory" factoryMethod="getInstance">
+ <!-- Use the CombinedVFSCache implementation -->
+ <parameter>org.jboss.virtual.plugins.cache.CombinedVFSCache</parameter>
+ </constructor>
+ <start ignored="true"/>
+ <property name="permanentRoots">
+ <map keyClass="java.net.URL" valueClass="org.jboss.virtual.spi.ExceptionHandler">
+ <entry>
+ <key>${jboss.lib.url}</key>
+ <value><null/></value>
+ </entry>
+ <entry>
+ <key>${jboss.common.lib.url}</key>
+ <value><inject bean="VfsNamesExceptionHandler"/></value>
+ </entry>
+ <entry>
+ <key>${jboss.server.lib.url}</key>
+ <value><inject bean="VfsNamesExceptionHandler"/></value>
+ </entry>
+ <entry>
+ <key>${jboss.server.home.url}deploy</key>
+ <value><inject bean="VfsNamesExceptionHandler"/></value>
+ </entry>
+ </map>
+ </property>
+ <property name="realCache">
+ <bean class="org.jboss.virtual.plugins.cache.IterableTimedVFSCache"/>
+ </property>
+ </bean>]]>
+</programlisting>
+ <para>
+Any new custom VFS root (for example, an additional <filename>deploy</filename> directory) should be added to this configuration.
+ </para>
</section>
<section>
- <title>Annotation Scaning Tuning</title>
- <para>Magic about controlling annotations scaning...</para>
+ <title>Annotation Scanning Tuning</title>
+ <para>
+There are currently three ways to limit resources scanning.</para>
+<itemizedlist>
+ <listitem>
+ <para>
+ Provide a <classname>ScanningMetaData</classname> through XML or programmaticaly.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add a new deployment filter to <classname>GenScanDeployer</classname> bean in <filename>deployers/metadata-deployer-jboss-beans</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Modify <classname>JBossCustomDeployDUFilter</classname> in <filename>deployers/metadata-deployer-jboss-beans</filename>.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+ScanningMetaData can come from the <filename>jboss-scanning.xml</filename> file placed in <filename>META-INF</filename> directory. This is a simple example of this file:</para>
+<programlisting><![CDATA[
+<scanning xmlns="urn:jboss:scanning:1.0">
+ <path name="myejbs.jar">
+ <include name="com.acme.foo"/>
+ <exclude name="com.acme.foo.bar"/>
+ </path>
+ <path name="my.war/WEB-INF/classes">
+ <include name="com.acme.foo"/>
+ </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>
+
+<programlisting><![CDATA[
+<scanning xmlns="urn:jboss:scanning:1.0">
+<!-- Purpose: Disable scanning for annotations in contained deployment. -->
+</scanning> ]]>
+</programlisting>
+<para>
+Another way to limit scanning is to provide the <filename>jboss-classloading.xml</filename> file. More information about this can be found in the Class Loader documentation section as it covers a lot of other details as well, not just scanning. </para>
</section>
</section>
</section>
@@ -232,7 +406,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 read's and writes.
</para>
<para>
- Resource limits set by your operating system may also set limits on your database management system. A database administrator can analyse 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 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.
</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 Application Platform by default queues the request for a default of 30,000 milliseconds (30 seconds) before cancellation and throwing an exception.
@@ -252,127 +426,14 @@
<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 application server to recognize it as a <emphasis>data source file</emphasis>. The Hypersonic database data source file for example is named <filename>hsqldb-ds.xml</filename>.
+ Please note that the name of the file must end with <filename>-ds.xml</filename> in order for the JBoss application server to recognize it as a <emphasis>data source file</emphasis>. The Postgres database data source file for example is named <filename>postgres-ds.xml</filename>.
</para>
</note>
-<para>
- The example below is a sample Hypersonic database data source file. Please note that this file contains more comments or descriptions for the respective tags. For a full view of this file, and its comments, please refer to the <filename>hsqldb-ds.xml</filename> in the <filename>deploy</filename> directory of your configuration.
-</para>
-<note><title>More examples</title>
- <para>More examples of datasource definition files for supported external databases can be found in the <literal><JBoss_Home>/docs/examples/jca</literal> directory.</para>
+<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>
</note>
-<programlisting role="XML">...
-<datasources>
- <local-tx-datasource>
-
- <!-- The jndi name of the DataSource, it is prefixed with java:/ -->
- <!-- Datasources are not available outside the virtual machine -->
- <jndi-name>DefaultDS</jndi-name>
-
- <!-- For server mode db, allowing other processes to use hsqldb over tcp.
- This requires the org.jboss.jdbc.HypersonicDatabase mbean.
- <connection-url>jdbc:hsqldb:hsql://${jboss.bind.address}:1701</connection-url>
- -->
- <!-- For totally in-memory db, not saved when jboss stops.
- The org.jboss.jdbc.HypersonicDatabase mbean is required for proper db shutdown
- <connection-url>jdbc:hsqldb:.</connection-url>
- -->
- <!-- For in-process persistent db, saved when jboss stops.
- The org.jboss.jdbc.HypersonicDatabase mbean is required for proper db shutdown
- -->
- <connection-url>jdbc:hsqldb:${jboss.server.data.dir}${/}hypersonic${/}localDB</connection-url>
-
- <!-- The driver class -->
- <driver-class>org.hsqldb.jdbcDriver</driver-class>
-
- <!-- The login and password. Do not enter plain text for production databases. Please see Security section for more information -->
- <user-name>sa</user-name>
- <password></password>
-
- <!--example of how to specify class that determines if exception means connection should be destroyed-->
- <!--exception-sorter-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyExceptionSorter</exception-sorter-class-name-->
-
- <!-- this will be run before a managed connection is removed from the pool for use by a client-->
- <!--<check-valid-connection-sql>select * from something</check-valid-connection-sql> -->
-
- <!-- The minimum database connections managed in a pool/sub-pool. Pools are lazily constructed on first use -->
- <min-pool-size>5</min-pool-size>
-
- <!-- The maximum database connections managed in a pool/sub-pool -->
- <max-pool-size>20</max-pool-size>
-
- <!-- The time before an unused connection is destroyed -->
- <!-- NOTE: This is the check period. It will be destroyed somewhere between 1x and 2x this timeout after last use -->
- <!-- TEMPORARY FIX! - Disable idle connection removal, HSQLDB has a problem with not reaping threads on closed connections -->
- <idle-timeout-minutes>0</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>
- -->
-
- <!-- example of how to specify a class that determines a connection is valid before it is handed out from the pool
- <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.DummyValidConnectionChecker</valid-connection-checker-class-name>
- -->
-
- <!-- Whether to check all statements are closed when the connection is returned to the pool,
- this is a debugging feature that should be turned off in production -->
- <track-statements/>
-
- <!-- Use the getConnection(user, pw) for logins
- <application-managed-security/>
- -->
-
- <!-- Use the security domain defined in conf/login-config.xml -->
- <security-domain>HsqlDbRealm</security-domain>
-
- <!-- Use the security domain defined in conf/login-config.xml or the
- getConnection(user, pw) for logins. The security domain takes precedence.
- <security-domain-and-application>HsqlDbRealm</security-domain-and-application>
- -->
-
- <!-- HSQL DB benefits from prepared statement caching which stores recent prepared statements for future use. The prepared-statement-cache-size indicates the number of prepared statements to store in the cache. -->
- <prepared-statement-cache-size>32</prepared-statement-cache-size>
-
- <!-- corresponding type-mapping in the standardjbosscmp-jdbc.xml (optional) -->
- <metadata>
- <type-mapping>Hypersonic SQL</type-mapping>
- </metadata>
-
- <!-- When using in-process (standalone) mode -->
- <depends>jboss:service=Hypersonic,database=localDB</depends>
- <!-- Uncomment when using hsqldb in server mode
- <depends>jboss:service=Hypersonic</depends>
- -->
- </local-tx-datasource>
-
- <!-- Uncomment if you want hsqldb accessed over tcp (server mode)
- <mbean code="org.jboss.jdbc.HypersonicDatabase"
- name="jboss:service=Hypersonic">
- <attribute name="Port">1701</attribute>
- <attribute name="BindAddress">${jboss.bind.address}</attribute>
- <attribute name="Silent">true</attribute>
- <attribute name="Database">default</attribute>
- <attribute name="Trace">false</attribute>
- <attribute name="No_system_exit">true</attribute>
- </mbean>
- -->
-
- <!-- For hsqldb accessed from jboss only, in-process (standalone) mode -->
- <mbean code="org.jboss.jdbc.HypersonicDatabase"
- name="jboss:service=Hypersonic,database=localDB">
- <attribute name="Database">localDB</attribute>
- <attribute name="InProcessMode">true</attribute>
-</mbean>
-
-</datasources>
-</programlisting>
-
</section>
<section id="Other_Tuning">
@@ -387,6 +448,9 @@
</para>
<para>
+ The new administration console can be used for configuring and managing different aspects of the application server environment.
+</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.
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.
More information about the jboss-cvs-commits
mailing list