[jboss-cvs] JBossAS SVN: r92466 - projects/docs/enterprise/5.0/Getting_Started_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Aug 17 22:59:08 EDT 2009
Author: irooskov at redhat.com
Date: 2009-08-17 22:59:07 -0400 (Mon, 17 Aug 2009)
New Revision: 92466
Modified:
projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Server_Configurations.xml
projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Start_Stop_Server.xml
projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml
projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Using_Other_Databases.xml
Log:
updated with new info
Modified: projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Server_Configurations.xml
===================================================================
--- projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Server_Configurations.xml 2009-08-17 23:32:45 UTC (rev 92465)
+++ projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Server_Configurations.xml 2009-08-18 02:59:07 UTC (rev 92466)
@@ -138,6 +138,103 @@
To start the server using an alternate profile refer to <xref linkend="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration"/>.
</para>
</note>
+<section id="Server_Directory_Structure">
+ <title>Server Directory Structure</title>
+ <para>
+ Installing JBoss Enterprise Application Platform creates a top level directory, which will be named <filename>jboss-eap-<version></filename> if you used the zip installation method, and will be named according to your specification if you used the GUI installer. Throughout this guide we refer to this top-level directory as the <filename>JBOSS_DIST</filename> directory.
+ </para>
+ <para>
+ <table id="JBOSS_DIST/jboss-as_directory_structure">
+ <title><filename>JBOSS_DIST/jboss-as</filename> directory structure</title>
+ <tgroup cols="3">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ Directory
+ </entry>
+ <entry>
+ Description
+ </entry>
+ <entry>
+ Important Notes
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ bin
+ </entry>
+ <entry>
+ Contains startup, shutdown and other system-specific scripts. Basically all the entry point JARs and start scripts included with the JBoss distribution are located in the bin directory. It also contains the configuration scripts which can be used to configure the JVM parameters.
+ </entry>
+ <entry>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ client
+ </entry>
+ <entry>
+ Stores configuration files and JAR files that may be used by a Java client application (running outside JBoss) or an external web container. You can select archives as required or use <filename>jbossall-client.jar</filename>.
+ </entry>
+ <entry>
+ Unlike the earlier 4.x versions of the JBoss Enterprise Application Platform, the <filename>jbossall-client.jar</filename> is now a <filename>MANIFEST</filename> only JAR file. So if the client application copies over the <filename>jbossall-client.jar</filename> to its classpath, then it also has to copy over all the other jar files listed in the <filename>META-INF/MANIFEST.MF</filename> file of <filename>jbossall-client.jar</filename>. Furthermore, all these JARs, including the <filename>jbossall-client.jar</filename>, must be placed in the same folder in the client classpath.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ common
+ </entry>
+ <entry>
+ This directory is meant to contains all the configurations and JAR files which are common for all the server configuration sets. The <filename>lib</filename> sub-directory within this <filename>common</filename> directory, contains all the JAR files which are common to the server configuration sets. The intention of having these JAR files in this one place, instead of the <filename>lib</filename> folder of each of the server configuration sets, is to reduce the size of the server. It also helps in maintainance; the lower the number of files to maintain, the better it is.
+ </entry>
+ <entry>
+ Like some of the other JBoss server configuration paths, this <filename>common</filename> and the <filename>common/lib</filename> directories are available as the system properties <filename>jboss.common.base.url</filename> (This holds the URL to <filename>JBOSS_DIST/common</filename> directory) and <filename>jboss.common.lib.url</filename> (This holds the URL to <filename>JBOSS_DIST/common/lib</filename> directory).
+ </entry>
+ </row>
+ <row>
+ <entry>
+ docs
+ </entry>
+ <entry>
+ Contains the XML DTDs, schemas used in JBoss for reference (these are also a useful source of documentation on JBoss configuration specifics). There are also example JCA (Java Connector Architecture) configuration files for setting up datasources for different databases (such as MySQL, Oracle, Postgres).
+ </entry>
+ <entry>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ lib
+ </entry>
+ <entry>
+ Contains startup JARs used by JBoss. There is also an <emphasis>endorsed</emphasis> sub-directory within this lib directory, which is used as one of the Java Endorsed directories. See the <ulink url="http://java.sun.com/javase/6/docs/technotes/guides/standards/">Java Endorsed Standards</ulink> for more details. Do not place your own JAR files in these directories.
+ </entry>
+ <entry>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ server
+ </entry>
+ <entry>
+ Contains the JBoss server configuration sets. Each of the subdirectories in here is a different server configuration. JBoss ships with minimal, default, production, standard, web and all configuration sets. The subdirectories and key configuration files contained in the <literal>default</literal> configuration set are discussed in more detail in subsequent sections.
+ </entry>
+ <entry>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <important>
+ <para>
+ Do not remove any configuration or JRA files from the <filename>common</filename> directory location. You may add your own JAR files in the <filename>common/lib</filename> directory <emphasis>if</emphasis> those JAR files are meant to be used by all the server configuration sets. If you want the JAR files to be available for all the applications deployed in a single server configuration set (for example, the <literal>production</literal> configuration), then the best location to place these JARs is the <filename>JBOSS_DIST/server/<server-configuration-set>/lib</filename> directory.
+ </para>
+ </important>
+</section>
<section id="Server_Configuration_Directory_Structure">
<title>Server Configuration Directory Structure</title>
<para>
@@ -165,7 +262,7 @@
<filename class="directory">conf</filename>
</entry>
<entry>
- The <filename class="directory">conf</filename> directory contains the <filename>bootstrap.xml</filename> bootstrap descriptor file for a given server configuration. This defines the core microcontainer beans that are fixed for the lifetime of the server.
+ The <filename class="directory">conf</filename> directory contains the <filename>jboss-service.xml<filename>, <filename>bootstrap.xml</filename> bootstrap descriptor file for a given server configuration. The <filename>bootstrap.xml</filename> inturn points to various other configuration files which comprise of the server bootstrap. This defines the core microcontainer beans that are fixed for the lifetime of the server.
</entry>
</row>
<row>
@@ -173,7 +270,7 @@
<filename class="directory">data</filename>
</entry>
<entry>
- The <filename class="directory">data</filename> directory is available for use by services that want to store content in the file system. It holds persistent data for services intended to survive a server restart. Serveral JBoss services, such as the embedded Hypersonic database instance, store data here.
+ The <filename class="directory">data</filename> directory is available for use by services that want to store content in the file system. It holds persistent data for services intended to survive a server restart. Serveral JBoss services, such as the embedded Hypersonic database instance, store data here. The admin-console that is based on the <classname>ProfileService</classname> API, also stores its content in this folder.
</entry>
</row>
<row>
@@ -181,11 +278,19 @@
<filename class="directory">deploy</filename>
</entry>
<entry>
- The <filename class="directory">deploy</filename> directory contains the hot-deployable services (those which can be added to or removed from the running server). It also contains applications for the current server configuration. You deploy your application code by placing application packages (JAR, WAR and EAR files) in the <filename class="directory">deploy</filename> directory. The directory is constantly scanned for updates, and any modified components will be re-deployed automatically.
+ The <filename class="directory">deploy</filename> directory contains the hot-deployable services (those which can be added to or removed from the running server). It also contains applications for the current server configuration. You deploy your application code by placing application packages (JAR, WAR and EAR files) in the <filename class="directory">deploy</filename> directory. The directory is constantly scanned for updates, and any modified components will be re-deployed automatically. This may be overridden through the <poperty>applicationURIs</property> property of the <classname>BootstrapProfileFactory</classname> bean configuration in the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/bootstrap/profile.xml</filename> file.
</entry>
</row>
<row>
<entry>
+ <filename class="directory">deployers</filename>
+ </entry>
+ <entry>
+ In the Enterprise Application Platform 5, unlike earlier versions, the deployers (which are responsible for parsing and deploying deployments) are located separately in the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deployers</filename> folder. This folder contains various deployer JAR files and their configurations in <filename>*-jboss-beans.xml</filename> files.
+ </entry>
+ </row>
+ <row>
+ <entry>
<filename class="directory">lib</filename>
</entry>
<entry>
@@ -213,13 +318,18 @@
<filename class="directory">work</filename>
</entry>
<entry>
- This directory is used by Tomcat for compilation of JSPs.
+ This directory is used by JBoss Web for compilation of JSPs.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
+ <important>
+ <para>
+ The configuration file used for configuring the default set of ports for the server is available in the <filename>bindingservice.beans/META-INF</filename> subfolder of the <filename>conf</filename> folder. The name of the file is <filename>bindings-jboss-beans.xml</filename>. See the port confiuration section for more details on how to use this file.
+ </para>
+ </important>
</section>
<section id="The_default_Server_Profile_File_Set">
<title>The <literal>default</literal> Server Profile File Set</title>
@@ -718,6 +828,12 @@
</row>
<row>
<entry>
+ <literal>admin-console.war</literal>
+ </entry>
+ <entry> This is the <literal>admin-console</literal> application which provides a web interface for admins of JBoss server. By default the admin-console is available at http://localhost:8080/admin-console</entry>
+ </row>
+ <row>
+ <entry>
<literal>cache-invalidation-service.xml</literal>
</entry>
<entry> This is a service that allows for custom
@@ -796,6 +912,10 @@
service configuration file. It sets up the embedded
database and related connection factories. </entry>
</row>
+ <row>
+ <entry><literal>http-invoker.sar</literal></entry>
+ <entry>contains the detached invoker that supports RMI over HTTP. It also contains the proxy bindings for accessing JNDI over HTTP.</entry>
+ </row>
<!-- <row>
<entry><literal>http-invoker.sar</literal></entry>
<entry>contains the detached invoker that supports RMI
@@ -845,6 +965,12 @@
<literal>jms-ra.rar</literal> JBoss JMS Resource
Adapter </entry>
</row>
+ <row>
+ <entry>
+ <literal>management/console-mgr.sar</literal>
+ </entry>
+ <entry>provides the Web Console. It is a web application/applet that provides a richer view of the JMX server management data than the JMX console. You may view the console using the URL http://localhost:8080/web-console/.</entry>
+ </row>
<!-- <row>
<entry>
<literal>messaging/connection-factories-service.xml</literal>
@@ -858,6 +984,12 @@
</entry>
<entry>configures the default Dead Letter queue and the Expiry queue.</entry>
</row>
+ <row>
+ <entry>
+ <literal>messaging/hsqldb-persistence-service.xml</literal>
+ </entry>
+ <entry>provides JMS state management using Hypersonic.</entry>
+ </row>
<!-- <row>
<entry>
<literal>messaging/jms-ds.xml</literal>
@@ -1026,6 +1158,14 @@
</row> -->
<row>
<entry>
+ <literal>schedule-manager-service.xml</literal>
+ </entry>
+ <entry> The <literal>schedule-manager-service.xml</literal>
+ contains sample scheduler configurations. Disabled by default. .
+ </entry>
+ </row>
+ <row>
+ <entry>
<literal>sqlexception-service.xml</literal>
</entry>
<entry> The <literal>sqlexception-service.xml</literal>
@@ -1058,6 +1198,20 @@
service provides a UUID-based key generation
facility. </entry>
</row>
+ <row>
+ <entry>
+ <literal>vfs-jboss-beans.xml</literal>
+ </entry>
+ <entry> The <literal>vfs-jboss-beans.xml</literal>
+ configures the Microcontainer bean exposing the JBoss VFS cache statistics. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>xnio-provider.jar</literal>
+ </entry>
+ <entry>XNIO is a centralized management point for network services.
+ </entry>
+ </row>
</tbody>
</tgroup>
</table>
Modified: projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Start_Stop_Server.xml
===================================================================
--- projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Start_Stop_Server.xml 2009-08-17 23:32:45 UTC (rev 92465)
+++ projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Start_Stop_Server.xml 2009-08-18 02:59:07 UTC (rev 92466)
@@ -7,9 +7,15 @@
<para>
Move to <filename class="directory">JBOSS_DIST/jboss-as/bin</filename> directory and execute the <literal>run.bat</literal> (for Windows) or <literal>run.sh</literal> (for Linux) script, as appropriate for your operating system.
</para>
-<important><title>Remote connection to the JBoss AS server</title>
- <para>JBoss AS now binds its services to localhost (127.0.0.1) by default, instead of binding to all available interfaces (0.0.0.0). This was primarily done for security reasons because of concerns of users going to production without having secured their servers properly. To enable remote access by binding JBoss services to a particular interface, simply run jboss with the <literal>-b</literal> option. To bind to all available interfaces and re-enable the legacy behaviour use <literal>-b 0.0.0.0</literal>. In any case, be aware you still need to secure your server properly.
+ <para>
+ There is no <literal>Server Started</literal> message shown at the console when the server is started using the <literal>production</literal> profile, which is the default profile used when no other is specified. This message can be found in the <filename>server.log</filename> file located in the <filename>JBOSS_DIST/jboss-as/server/production/log</filename> subdirectory.
+ </para>
+<important><title>Remote connection to the JBoss Enterprise Application Platform server</title>
+ <para>the JBoss JBoss Enterprise Application Platform now binds its services to localhost (127.0.0.1) by default, instead of binding to all available interfaces (0.0.0.0). This was primarily done for security reasons because of concerns of users going to production without having secured their servers correctly. To enable remote access by binding JBoss services to a particular interface, simply run jboss with the <command>-b</command> option. To bind to all available interfaces and re-enable the legacy behaviour use <command>./run.sh -b 0.0.0.0</command> on Linux and <command>run.bat -b 0.0.0.0</command>. In any case, be aware you still need to secure your server properly.
</para>
+ <para>
+ Using <command>-b</command> as part of the JBoss Server's command line is equivalent to setting these individual properties: <property>-Djboss.bind.address</property>, <property>-Djava.rmi.server.hostname</property>, <property>-Djgroups.bind_addr</property> and <property>-Dbind.address</property>. Passing <property>-Djboss.bind.address</property> to the Java process as part of the <varname>JAVA_OPTS</varname> variable in the run scripts will not work as it is a JBoss property not a JVM property.
+ </para>
</important>
<para>
For more information including setting up multiple JBoss server instances on one machine and hosting multiple domains with JBoss, please refer to the <ulink url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Server_Configuration_Guide/beta500/html-single/index.html">Administration and Configuration Guide</ulink>. <!--Some examples on binding are shipped in <filename><JBOSS_HOME>/docs/examples/binding-manager/sample-bindings.xml</filename>-->.
@@ -48,7 +54,7 @@
<section id="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration">
<title>Start the Server With Alternate Configuration</title>
<para>
- Using <literal>run.sh</literal> without any arguments starts the server using the <literal>default</literal> server configuration file set. To start with an alternate configuration file set, pass the name of the server configuration file set [same as the name of the server configuration directory under <literal>JBOSS_DIST/jboss-as/server</literal>] that you want to use, as the value to the <literal>-c</literal> command line option. For example, to start with the <literal>minimal</literal> configuration file set you should specify:
+ Using <literal>run.sh</literal> without any arguments starts the server using the <literal>production</literal> server configuration file set. To start with an alternate configuration file set, pass the name of the server configuration file set [same as the name of the server configuration directory under <literal>JBOSS_DIST/jboss-as/server</literal>] that you want to use, as the value to the <literal>-c</literal> command line option. For example, to start with the <literal>minimal</literal> configuration file set you should specify:
</para>
<programlisting>[bin]$ ./run.sh -c minimal
...
@@ -79,6 +85,7 @@
-P, --properties=<url> Load system properties from the given url
-b, --host=<host or ip> Bind address for all JBoss services.
-g, --partition=<name> HA Partition name (default=DefaultDomain)
+-m, --mcast_port=<ip> UDP multicast port; only used by JGroups
-u, --udp=<ip> UDP multicast address
-l, --log=<log4j|jdk> Specify the logger plugin type
</programlisting>
@@ -99,9 +106,9 @@
usage: shutdown [options] <operation>
options:
--h, --help Show this help message (default)
--D<name>[=<value>] Set a system property
--- Stop processing options
+-h, --help Show this help message (default)
+-D<name>[=<value>] Set a system property
+-- Stop processing options
-s, --server=<url> Specify the JNDI URL of the remote server
-n, --serverName=<url> Specify the JMX name of the ServerImpl
-a, --adapter=<name> Specify JNDI name of the MBeanServerConnection to use
@@ -109,7 +116,7 @@
-p, --password=<name> Specify the password for authentication
operations:
--S, --shutdown Shutdown the server
+-S, --shutdown Shutdown the server
-e, --exit=<code> Force the VM to exit with a status code
-H, --halt=<code> Force the VM to halt with a status code
</programlisting>
Modified: projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml
===================================================================
--- projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml 2009-08-17 23:32:45 UTC (rev 92465)
+++ projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml 2009-08-18 02:59:07 UTC (rev 92466)
@@ -45,9 +45,20 @@
<section id="The_JBoss_Server___A_Quick_Tour-The_JMX_Console">
<title>The JMX Console</title>
<para>
- When the JBoss Server is running, you can get a live view of the server by going to the JMX console application at <ulink url="http://localhost:8080/jmx-console"></ulink>. You should see something similar to <xref linkend="The_JMX_Console-View_of_the_JMX_Management_Console_Web_Application" />.
+ When the JBoss Server is running, you can get a live view of the server by going to the JMX console application at <ulink url="http://localhost:8080/jmx-console"></ulink>.<!-- You should see something similar to <xref linkend="The_JMX_Console-View_of_the_JMX_Management_Console_Web_Application" />.-->
</para>
<para>
+ By default, the JMX console is secured and not even a admin user can access it. If you want to allow access to the JMX console go to the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/props/</filename> directory and uncomment the admin <varname>userid</varname> and <varname>password</varname> code within the <filename>jmx-console-users.properties</filename> file.
+ </para>
+ <para>
+ This will allow the admin user to access the JMX console using the username and password combination specified within the <filename>jmx-console-users.properties</filename> file.
+ </para>
+ <important>
+ <para>
+ If you changed the <filename>jmx-console-users.properties</filename> file when the server was running, you will have to restart the server for the changes to take effect.
+ </para>
+ </important>
+ <para>
The JMX Console is the JBoss Management Console which provides a raw view of the JMX MBeans which make up the server. They can provide a lot of information about the running server and allow you to modify its configuration, start and stop components and so on.
</para>
<para>
@@ -73,16 +84,86 @@
<section id="The_JBoss_Server___A_Quick_Tour-Hot-deployment_of_services_in_JBoss">
<title>Hot-deployment of services in JBoss</title>
<para>
- Hot-deployable services are those which can be added to or removed from the running server. These are placed in the <literal>JBOSS_DIST/jboss-as/server/<instance-name>/deploy</literal> directory. Let’s have a look at a practical example of hot-deployment of services in JBoss before we go on to look at server configuration issues in more detail.
+ Hot-deployable services are those which can be added to or removed from the running server. These are placed in the <literal>JBOSS_DIST/jboss-as/server/<instance-name>/deploy</literal> directory. Let’s have a look at a practical example of hot-deployment of services in JBoss.
</para>
<para>
- Start JBoss if it isn’t already running and take a look at the <literal>server/production/deploy</literal> directory. Remove the <literal>mail-service.xml</literal> file and watch the output from the server:
-<programlisting>13:10:05,235 INFO [MailService] Mail service 'java:/Mail' removed from JNDI</programlisting>
+ Start JBoss if it isn’t already running and take a look at the <filename>server/production/deploy</filename> directory. Remove the <filename>mail-service.xml</filename> file and watch the output from the server:
+<programlisting>
+13:10:05,235 INFO [MailService] Mail service 'java:/Mail' removed from JNDI
+</programlisting>
</para>
<para>
- Then replace the file and watch JBoss re-install the service: <programlisting>13:58:54,331 INFO [MailService] Mail Service bound to java:/Mail</programlisting>
+ Then replace the file and watch JBoss re-install the service:
+<programlisting>
+13:58:54,331 INFO [MailService] Mail Service bound to java:/Mail
+</programlisting>
This is hot-deployment in action.
</para>
+ <section id="The_JBoss_Server___A_Quick_Tour-Hot-deployment_of_services_in_JBoss-Hot-deployment_configurations">
+ <title>Hot-deployment configurations</title>
+ <para>
+ Hot deployment of services in the server is controlled by the HDScanner MC bean configured in <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deploy/hdscanner-jboss-beans.xml</filename> file. For the <literal>production</literal> server configuration the <property>scanPeriod</property> is set to 60 seconds:
+ </para>
+<programlisting>
+<bean name="HDScanner" class="org.jboss.system.server.profileservice.hotdeploy.HDScanner">
+ <property name="deployer"><inject bean="ProfileServiceDeployer"/></property>
+ <property name="profileService"><inject bean="ProfileService"/></property>
+ <property name="scanPeriod">60000</property>
+ <property name="scanThreadName">HDScanner</property>
+</bean>
+</programlisting>
+ <para>
+ The <property>scanPeriod</property> attribute controls the interval for thread which picks up the hot deployable changes.
+ </para>
+ <note>
+ <para>
+ The changes to the <filename>hdscanner-jboss-beans.xml</filename> file itself are hot deployable. No server restart is needed.
+ </para>
+ </note>
+ </section>
+ <section id="The_JBoss_Server___A_Quick_Tour-Hot-deployment_of_services_in_JBoss-Adding_a_custom_deploy_folder">
+ <title>Adding a custom deploy folder</title>
+ <para>
+ JBoss server by default looks for deployments under the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deploy</filename> folder. However you can configure the server to even include your custom folder for scanning deployments. This can be done by configuring the <classname>BootstrapProfileFactory</classname> MC bean in <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/bootstrap/profile.xml</filename> file. The <property>applicationURIs</property> property of the <classname>BootstrapProfileFactory</classname> accepts a list of URLs which will be scanned for applications. You can add your custom deploy folder to this list. For example, if you want <filename>/home/me/myapps</filename> to be scanned for deployments, then you can add the following:
+ </para>
+<programlisting>
+<bean name="BootstrapProfileFactory" class="org.jboss.system.server.profileservice.repository.StaticProfileFactory">
+ ...
+ <property name="applicationURIs">
+ <list elementClass="java.net.URI">
+ <value>${jboss.server.home.url}deploy</value>
+ <value>file:///home/me/myapps</value>
+ </list>
+ ...
+</programlisting>
+ <important>
+ <para>
+ Modifying the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/bootstrap/profile.xml</filename> requires a server restart, for the changes to take effect.
+ </para>
+ </important>
+ <para>
+ For performance reasons, adding a new deployment folder to the <classname>BootstrapProfileFactory</classname> also requires the same URL to be added to the <classname>VFSCache</classname> MC bean configuration in <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/bootstrap/vfs.xml</filename>. For example:
+ </para>
+<programlisting>
+<bean name="VFSCache">
+ ...
+ <property name="permanentRoots">
+ <map keyClass="java.net.URL" valueClass="org.jboss.virtual.spi.ExceptionHandler">
+ ...
+ <entry>
+ <key>file:///home/me/myapps</key>
+ <value><inject bean="VfsNamesExceptionHandler"/></value>
+ </entry>
+ </map>
+ </property>
+ ...
+</programlisting>
+ <important>
+ <para>
+ Not adding the custom deployment folder to <classname>VFSCache</classname> might result in growing disk space usage by the server, over a period of time.
+ </para>
+ </important>
+ </section>
</section>
<section id="The_JBoss_Server___A_Quick_Tour-Basic_Configuration_Issues">
@@ -90,6 +171,41 @@
<para>
Now that we have examined the JBoss server, we will take a look at some of the main configuration files and what they are used for. All paths are relative to the server configuration directory (<filename class="directory">server/default</filename>, for example).
</para>
+ <section id="The_JBoss_Server___A_Quick_Tour-Setting_your_application_as_the_default_application_on_the_server">
+ <title>Setting your application as the default application on the server</title>
+ <para>
+ JBoss server by default configures <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deploy/ROOT.war</filename> as the default application on the server. So accessing <literal>http://localhost:8080/</literal> results in displaying the index page of this application. If you want your application to be available as the default application, then you will wish to follow these steps:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Rename <filename>ROOT.war</filename> in <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deploy</filename> to something else, for example, <filename>jboss.war</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In your WAR file (the one which you want to be the default application), add a <filename>jboss-web.xml</filename>, in the <filename>WEB-INF</filename> folder, with a configuration for the context-root:
+ </para>
+<programlisting>
+<?xml version="1.0"?>
+<!DOCTYPE jboss-web PUBLIC "-//JBoss//DTD Web Application 5.0//EN" "http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
+
+<jboss-web>
+ <context-root>/</context-root>
+ <!-- Other configurations as needed -->
+</jboss-web>
+</programlisting>
+ <para>
+ By setting the context-root to <filename>/</filename> you are making your application the default application. Your application will now be available at <literal>http://localhost:8080/</literal>.
+ </para>
+ <note>
+ <para>
+ Renaming the <filename>ROOT.war</filename> to <filename>jboss.war</filename> will make that application be available at <literal>http://localhost:8080/jboss</literal>
+ </para>
+ </note>
+ </listitem>
+ </itemizedlist>
+ </section>
<section id="The_JBoss_Server___A_Quick_Tour-Bootstrap_Configuration">
<title>Bootstrap Configuration</title>
<para>The microcontainer bootstrap configuration is described by the <filename>conf/bootstrap.xml</filename> and the <filename>conf/bootstrap/*.xml</filename> it references. Its expected that the number of bootstrap beans will be reduced in the future. Its not expected that you would need to edit the bootstrap configuration files for a typical installation.</para>
@@ -131,7 +247,7 @@
Logging is controlled from a central <filename>conf/jboss-log4j.xml</filename> file. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, JBoss produces output to both the console and a log file (<filename>log/server.log</filename>).
</para>
<para>
- There are 6 basic log levels used: <literal>TRACE</literal>, <literal>DEBUG</literal>, <literal>INFO</literal>, <literal>WARN</literal>, <literal>ERROR</literal> and <literal>FATAL</literal>. The logging threshold on the console is <literal>INFO</literal>, which means that you will see informational messages, warning messages and error messages on the console but not general debug messages. In contrast, there is no threshold set for the <filename>server.log</filename> file, so all generated logging messages will be logged there.
+ There are 6 basic log levels used: <literal>TRACE</literal>, <literal>DEBUG</literal>, <literal>INFO</literal>, <literal>WARN</literal>, <literal>ERROR</literal> and <literal>FATAL</literal>. The logging threshold on the console is <literal>INFO</literal>, which means that you will see informational messages, warning messages and error messages on the console but not general debug and trace messages. In contrast, there is no threshold set for the <filename>server.log</filename> file, so all generated logging messages will be logged there.
</para>
<para>
If things are going wrong and there doesn’t seem to be any useful information in the console, always check the <filename>server.log</filename> file to see if there are any debug messages which might help you to track down the problem. However, be aware that just because the logging threshold allows debug messages to be displayed, that doesn't mean that all of JBoss will produce detailed debug information for the log file. You will also have to boost the logging limits set for individual categories. Take the following category for example.
@@ -142,8 +258,37 @@
</category>
</programlisting>
<para>
- This limits the level of logging to <literal>INFO</literal> for all JBoss classes, apart from those which have more specific overrides provided. If you were to change this to <literal>DEBUG</literal>, it would produce much more detailed logging output.
+ This limits the level of logging to <literal>INFO</literal> for all JBoss classes, apart from those which have more specific overrides provided. By default the root logger in the <filename>jboss-log4j.xml</filename> is set to <literal>INFO</literal>. This effectively means that any <literal>TRACE</literal> or <literal>DEBUG</literal> logger from any logger categories will not be logged in any files or the console appender. This setting is controlled through the <property>jboss.server.log.threshold</property> property. By default this is <literal>INFO</literal>. If you were to change this to <literal>DEBUG</literal>, it would produce much more detailed logging output. In order to change this there are two options:
</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ You can pass the <property>-Djboss.server.log.threshold=DEBUG</property> parameter while starting the server:
+ </para>
+<programlisting>
+./run.sh -Djboss.server.log.threshold=DEBUG
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ You can edit the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/jboss-log4j.xml</filename> file directly in order to set this property:
+ </para>
+<programlisting>
+<root>
+ <!-- Let's comment this out to set our own value
+ <priority value="${jboss.server.log.threshold}"/>-->
+ <priority value="DEBUG"/>
+ <appender-ref ref="CONSOLE"/>
+ <appender-ref ref="FILE"/>
+</root>
+</programlisting>
+ <note>
+ <para>
+ The <filename>JBOSS_DIST/jboss-as/server/<instance-name>/conf/jboss-log4j.xml</filename> is scanned every 60 seconds (by default) to check for any changes. Changing this file does not require a server restart as the changes will be hot deployed within the next 60 seconds following the change.
+ </para>
+ </note>
+ </listitem>
+ </itemizedlist>
<para>
As another example, let’s say you wanted to set the output from the container-managed persistence engine to <literal>DEBUG</literal> level and to redirect it to a separate file, <filename>cmp.log</filename>, in order to analyze the generated SQL commands. You would add the following code to the <filename>conf/jboss-log4j.xml</filename> file:
</para>
@@ -170,6 +315,16 @@
<para>
The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is <filename>cmp.log</filename>. Older files have the date they were written added to their filenames. Please note that the <filename class="directory">log</filename> directory also contains HTTP request logs which are produced by the web container.
</para>
+ <para>
+ By default the <filename>server.log</filename> appender is configured to retain log messages between server restarts. This is controlled by the <property>Append</property> property on the <literal>FILE</literal> appender which corresponds to the <filename>server.log</filename> file. By default this property is set to true; if you want the <filename>server.log</filename> contents to be wiped out on server restarts then you can edit the <filename>JBOSS_DIST/jboss-as/server/<instance-name>conf/jboss-log4j.xml</filename> file to set this property value to false. For example:
+ </para>
+<programlisting>
+<appender name="FILE" class="org.jboss.logging.appender.DailyRollingFileAppender">
+ <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="File" value="${jboss.server.log.dir}/server.log"/>
+ <param name="Append" value="false"/>
+ ...
+</programlisting>
</section>
<section id="Basic_Configuration_Issues-Security_Service">
@@ -264,6 +419,53 @@
</section>
</section>
+ <section id="The_Service_Binding_Manager">
+ <title>The Service Binding Manager</title>
+ <para>
+ JBoss server uses various ports for the services that it provides (for example, port 8080 for HTTP, 1099 for JNDI). The Service Binding Manager (SBM) service provides a centralized location where settings for all services that need to bind to ports can be configured. SBM can be used to configure different sets of port bindings for a server instance. A system property on the SBM controls which named set (for example, ports-default, ports-01) is used by a particular server instance. If you want to run multiple server instances on the same system then you can configure the SBM on each instance to use a different named binding set. You can even use SBM to switch to a different binding set (for example, 8180 port for HTTP instead of the default 8080) for a server instance.
+ </para>
+ <para>
+ In a typical configuration, the <literal>ports-default</literal> set uses the standard ports (for example, JNDI on port 1099), with <literal>ports-01</literal> increasing each port value by 100 (for example, JNDI on 1199), <literal>ports-02</literal> by 200 and so on.
+ </para>
+ <para>
+ SBM is configured through the <filename>$JBOSS_DIST/jboss-as/server/bindingservice.beans/META-INF/bindings-jboss-beans.xml</filename> file. The configuration of the <classname>ServiceBindingManager</classname> involves three primary elements :
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A set of beans containing standard (default) binding configuration data. These are the base values (for example, JNDI on 1099) used to drive <literal>ports-default</literal>, <literal>ports-01</literal> and so on.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A number of beans defining <classname>ServiceBindingSets</classname>, for example, <literal>ports-default</literal>, <literal>ports-01</literal>, <literal>ports-02</literal>. The sets of standard bindings are combined with each of these, along with an offset value (for example, 100 for <literal>ports-01</literal>) that should be applied to the standard port values to create the binding values for that set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <classname>ServiceBindingManager</classname> service bean itself. This has the standard bindings and the <classname>ServiceBindingSets</classname> injected into it. It is also configured with the name of the binding set the particular server instance should use. The name of the binding set to be used is configurable from the command line by using the system property <property>jboss.service.binding.set</property>. The default value is <literal>ports-default</literal>.
+ </para>
+<programlisting>
+<bean name="ServiceBindingManagementObject" class="org.jboss.services.binding.managed.ServiceBindingManagementObject">
+ <constructor>
+ <!-- The name of the set of bindings to use for this server -->
+ <parameter>
+ ${jboss.service.binding.set:ports-default}
+ </parameter>
+ ...
+</programlisting>
+ <para>
+ To switch to a different set of ports than the ones used by default, you can start the server by passing the <property>-Djboss.service.binding.set</property> property to the run command as follows:
+ </para>
+<programlisting>
+./run.sh -Djboss.service.binding.set=ports-01
+</programlisting>
+ <para>
+ This will instruct the server to use the group of ports configured in the <literal>ports-01</literal> binding set.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
<!--<section id="The_JBoss_Server___A_Quick_Tour-The_Web_Container___Tomcat">
<title>The Web Container - Tomcat</title>
Modified: projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Using_Other_Databases.xml
===================================================================
--- projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Using_Other_Databases.xml 2009-08-17 23:32:45 UTC (rev 92465)
+++ projects/docs/enterprise/5.0/Getting_Started_Guide/en-US/Using_Other_Databases.xml 2009-08-18 02:59:07 UTC (rev 92466)
@@ -8,29 +8,23 @@
In the previous chapters, we’ve been using the JBossAS default datasource in our applications. This datasource is configured to use the embedded Hypersonic database instance shipped by default with the distribution. This datasource is bound to the JNDI name <literal>java:/DefaultDS</literal> and its descriptor is named <literal>hsqldb-ds.xml</literal> under the deploy directory
</para>
<para>
- Having a database included with JBossAS is very convenient for running the server and examples out-of-the-box. However, this database is not a production quality database and as such should not be used with enterprise-class deployments. As a consequence of this JBoss Support does not provide any official support for Hypersonic.
+ Having a database included with JBoss Enterprise Application Platform is very convenient for running the server and examples out-of-the-box. However, this database is not a production quality database and as such should not be used with enterprise-class deployments. As a consequence of this JBoss Support does not provide any official support for Hypersonic.
</para>
<para>
- In this chapter we will explain in details how to configure and deploy a datasource to connect JBossAS to the most popular database servers available on the market today.
+ In this chapter we will explain in details how to configure and deploy a datasource to connect the JBoss Enterprise Application Platform to the most popular database servers available on the market today.
</para>
<section id="Using_other_Databases-DataSource_Configuration_Files">
<title>DataSource Configuration Files</title>
<para>
- Datasource configuration file names end with the suffix <literal>-ds.xml</literal> so that they will be recognized correctly by the JCA deployer. The <literal>docs/example/jca</literal> directory contains sample files for a wide selection of databases and it is a good idea to use one of these as a starting point. For a full description of the configuration format, the best place to look is the DTD file <literal>docs/dtd/jboss-ds_1_5.dtd</literal>. Additional documentation on the files and the JBoss JCA implementation can also be found in the JBoss Enterprise Application Platform Administration and Server Configuration Guide available at <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/"/>.
+ Datasource configuration file names end with the suffix <filename>-ds.xml</filename> so that they will be recognized correctly by the JCA deployer. The <filename>docs/example/jca</filename> directory contains sample files for a wide selection of databases and it is a good idea to use one of these as a starting point. For a full description of the configuration format, the best place to look is the DTD file <filename>docs/dtd/jboss-ds_1_5.dtd</filename>. Additional documentation on the files and the JBoss JCA implementation can also be found in the JBoss Enterprise Application Platform Administration and Server Configuration Guide available at <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/"/>.
</para>
-
<para>
- Local transaction datasources are configured using the <literal>local-tx-datasource</literal> element and XA-compliant ones using <literal>xa-tx-datasource</literal>. The example file <literal>generic-ds.xml</literal> shows how to use both types and also some of the other elements that are available for things like connection pool configuration. Examples of both local and XA configurations are available for Oracle, DB2 and Informix.
+ Local transaction datasources are configured using the <literal>local-tx-datasource</literal> element and XA-compliant ones using <literal>xa-tx-datasource</literal>. The example file <filename>generic-ds.xml</filename> shows how to use both types and also some of the other elements that are available for things like connection pool configuration. Examples of both local and XA configurations are available for Oracle, DB2 and Informix.
</para>
-
-
-
<para>
- If you look at the example files <literal> firebird-ds.xml</literal>, <literal> facets-ds.xml</literal> and <literal>sap3-ds.xml</literal>, you’ll notice that they have a completely different format, with the root element being <literal>connection-factories</literal> rather than <literal>datasources</literal>. These use an alternative, more generic JCA configuration syntax used with a pre-packaged JCA resource adapter. The syntax is not specific to datasource configuration and is used, for example, in the <literal>jms-ds.xml</literal> file to configure the JMS resource adapter.
+ If you look at the example files <filename> firebird-ds.xml</filename>, <filename> facets-ds.xml</filename> and <filename>sap3-ds.xml</filename>, you’ll notice that they have a completely different format, with the root element being <literal>connection-factories</literal> rather than <literal>datasources</literal>. These use an alternative, more generic JCA configuration syntax used with a pre-packaged JCA resource adapter. The syntax is not specific to datasource configuration and is used, for example, in the <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deploy/messaging/jms-ds.xml</filename> file to configure the JMS resource adapter.
</para>
- <!-- <para>We would also highly recommend consulting the JCA wiki pages at http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossJCA
- </para> -->
<para>
Next, we’ll work through some step-by-step examples to illustrate what’s involved setting up a datasource for a specific database.
</para>
@@ -39,43 +33,92 @@
<section id="Using_other_Databases-Using_MySQL_as_the_Default_DataSource">
<title>Using MySQL as the Default DataSource</title>
<para>
- The MySQL® database has become the world's most popular open source database thanks to its consistent fast performance, high reliability and ease of use. This database server is used in millions of installations ranging from large corporations to specialized embedded applications across every continent of the world. . In this section, we'll be using the community version of their database server (GA 5.0.45) and the latest JDBC driver (GA 5.1.5) both available at <ulink url="http://www.mysql.com"></ulink>.
+ The MySQL® database has become the world's most popular open source database thanks to its consistent fast performance, high reliability and ease of use. This database server is used in millions of installations ranging from large corporations to specialized embedded applications across every continent of the world. The official JDBC driver is called <literal>Connector/J</literal>. For this example we’ve used MySQL 5.1.31 and <literal>Connector/J</literal> 5.1.8. Both are available at <ulink url="http://www.mysql.com"></ulink>.
</para>
-
-
-
-
-
-
+ <section id="Using_MySQL_as_the_Default_DataSource-Creating_a_Database_and_User">
+ <title>Creating a Database and User</title>
+ <para>
+ We’ll assume that you’ve already installed MySQL and that you have it running and are familiar with the basics. Run the mysql client program from the command line so we can execute some administration commands. You should make sure that you are connected as a user with sufficient privileges (for example, by specifying the <code>-u</code> root option to run as the MySQL root user).
+ </para>
+ <para>
+ First create a database called jboss within MySQL for use by JBoss:
+ </para>
+<programlisting>
+mysql> CREATE DATABASE jboss;
+
+Query OK, 1 row affected (0.05 sec)
+</programlisting>
+ <para>
+ Then check that it has been created:
+ </para>
+<programlisting>
+mysql> SHOW DATABASES;
+
++----------+
+| Database |
++----------+
+| jboss |
++----------+
+1 rows in set (0.00 sec)
+</programlisting>
+ <para>
+ Next, create a user called jboss with password password to access the database:
+ </para>
+<programlisting>
+mysql> GRANT ALL PRIVILEGES ON jboss.* TO jboss at localhost IDENTIFIED BY 'password';
+
+Query OK, 0 rows affected (0.06 sec)
+</programlisting>
+ <para>
+ Again, you can check that everything has gone smoothly:
+ </para>
+<programlisting>
+mysql> select User,Host,Password from mysql.User;
+
++-------+-----------+------------------+
+| User | Host | Password |
++-------+-----------+------------------+
+| root | localhost | |
+| root | % | |
+| | localhost | |
+| | % | |
+| jboss | localhost | 5d2e19393cc5ef67 |
++-------+-----------+------------------+
+5 rows in set (0.02 sec)
+</programlisting>
+ </section>
<section id="Using_MySQL_as_the_Default_DataSource-Installing_the_JDBC_Driver_and_Deploying_the_DataSource">
<title>Installing the JDBC Driver and Deploying the datasource</title>
<para>
- To make the JDBC driver classes available to the JBoss Application Server, copy the archive <literal>mysql-mysql-connector-java-5.1.5-bin.jar</literal> from the Connector/J distribution to the <literal>lib</literal> directory in the <literal>default</literal> server configuration (assuming that is the server configuration you’re running).
+ To make the JDBC driver classes available to the JBoss Enterprise Application Platform, copy the archive <filename>mysql-connector-java-5.1.8-bin.jar</filename> from the <literal>Connector/J</literal> distribution to the <literal>lib</literal> directory in the <literal>default</literal> server configuration (assuming that is the server configuration you’re running).
</para>
<para>
- Then create a text file in the deploy directory called mysql-ds.xml with the following datasource descriptor:
- </para>
-
-<programlisting role="XML"><?xml version="1.0" encoding="UTF-8"?>
+ Then create a file in the deploy directory called <filename>mysql-ds.xml</filename> with the following datasource configuration. Note that the databse user name and password corresponds to the MySQL user that we created in the previous section:
+ </para>
+<programlisting role="XML">
+<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
- <jndi-name>DefaultDS</jndi-name>
- <connection-url>jdbc:mysql://localhost:3306/test</connection-url>
- <driver-class>com.mysql.jdbc.Driver</driver-class>
- <user-name>root</user-name>
- <password>jboss</password>
- <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.MySQLValidConnectionChecker</valid-connection-checker-class-name>
- <metadata>
- <type-mapping>mySQL</type-mapping>
- </metadata>
+ <jndi-name>MySqlDS</jndi-name>
+ <connection-url>jdbc:mysql://localhost:3306/jboss</connection-url>
+ <driver-class>com.mysql.jdbc.Driver</driver-class>
+ <user-name>jboss</user-name>
+ <password>password</password>
</local-tx-datasource>
-</datasources></programlisting>
-
-<para>
-The datasource is pointing at the database called test provided by default with MySQL 5.x.
-Remember to update the connection url attributes as well as the combo username/password to match your environment setup.
-</para>
+</datasources>
+</programlisting>
+ <para>
+ To ensure that you have correctly configured the datasource in <filename>JBOSS_DIST/jboss-as/server/<instance-name>/deploy</filename> folder, start the server and you will notice messages like these in the logs:
+ </para>
+<screen>
+INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=MySqlDS' to JNDI name 'java:MySqlDS'
+</screen>
+ <note>
+ <para>
+ Configuring other datasources is a similar process.
+ </para>
+ </note>
</section>
More information about the jboss-cvs-commits
mailing list