[jboss-cvs] JBossAS SVN: r82120 - projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Dec 8 16:19:25 EST 2008
Author: scott.stark at jboss.org
Date: 2008-12-08 16:19:25 -0500 (Mon, 08 Dec 2008)
New Revision: 82120
Added:
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix2.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Getting_Started.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Alternatives.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Binary_Download.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Source_Download.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Sample_JSF_EJB3_Application.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Server_Configurations.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Test_Your_Installation.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Uninstall_JBoss.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Seam.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/not-used-resolved.xml
Removed:
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/resolved.xml
Modified:
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/About_the_Example_Applications.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix1.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/EJB3_Caveats.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_And_Getting_Started_Guide.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Using_Graphical_Installer.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_RHN.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Preface.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Setting_JBOSS_HOME.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Start_Stop_Server.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml
projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Other_Databases.xml
Log:
JBAS-6280, complete split of resolved.xml into book and sections
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/About_the_Example_Applications.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/About_the_Example_Applications.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/About_the_Example_Applications.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,5 +1,5 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="About_the_Example_Applications">
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix1.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix1.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix1.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,13 +1,61 @@
<?xml version='1.0'?>
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
]>
<appendix id="Book-Revision_History">
- <appendixinfo>
- <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- </appendixinfo>
- <title>Revision History</title>
- <para>
- </para>
+ <title></title>
+ <bibliolist>
+ <biblioentry>
+ <revhistory>
+
+ <revision>
+ <revnumber>5.0.0</revnumber>
+ <date>Jan 08 2007</date>
+ <author>
+ <firstname>S</firstname>
+ <surname>Kittoli</surname>
+
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Updated Content </member>
+
+ </simplelist>
+ </revdescription>
+ </revision>
+
+ <revision>
+ <revnumber>5.0.0</revnumber>
+ <date>Apr 07 2007</date>
+ <author>
+ <firstname>S</firstname>
+ <surname>Kittoli</surname>
+
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Merge Content </member>
+ </simplelist>
+ </revdescription>
+ </revision>
+
+ <revision>
+ <revnumber>5.0.0.GA<remark></remark></revnumber>
+ <date>Dec 08 2008</date>
+ <author>
+ <firstname>S</firstname>
+ <surname>Stark</surname>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Complete the </member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ </revhistory>
+
+ </biblioentry>
+ </bibliolist>
</appendix>
+
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix2.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix2.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Appendix2.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+]>
+<appendix id="appendix2">
+
+ <title>Further Information Sources</title>
+ <para>
+ Developers wanting to get familiar with software development and implementation in JBoss Application Server can read: <emphasis>JBoss: A Developer's Notebook</emphasis>. (O'Reilly, 2005. Norman Richards, Sam Griffith).
+ </para>
+ <para>
+ For more comprehensive JBoss documentation covering advanced JBoss topics, refer to the manuals available online at <ulink url="http://www.jboss.org/jbossas/docs"/>.
+ </para>
+ <para>
+ For general EJB instruction, with thorough JBoss coverage, see <emphasis> Enterprise JavaBeans, 4th Edition</emphasis>. (O'Reilly, 2004. Richard Monson-Haeful, Bill Burke, Sacha Labourey)
+ </para>
+ <para>
+ To learn more about Hibernate, see <emphasis>Java Persistence With Hibernate</emphasis>. (Manning, 2007. Christian Bauer, Gavin King)
+ </para>
+ <para>
+ For complete coverage of the JBoss Seam framework, we recommend <emphasis>JBoss Seam: Simplicity And Power Beyond Java EE</emphasis>. (Prentice Hall, 2007. Michael Yuan, Thomas Heute).
+ </para>
+</appendix>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/EJB3_Caveats.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/EJB3_Caveats.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/EJB3_Caveats.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,5 +1,5 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<chapter id="EJB3_Caveats">
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Getting_Started.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Getting_Started.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Getting_Started.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="Getting_Started">
+ <title>Getting Started</title>
+ <section id="Getting_Started-Pre_Requisites">
+ <title>Pre-Requisites</title>
+ <para>
+ You must have adequate disk space to install JDK and JBoss Application Server while also allowing enough space for your applications. Before installing JBoss Application Server you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java.
+ </para>
+ <section id="Pre_Requisites-Hardware_and_Operating_System_Requirements">
+ <title>Hardware and Operating System Requirements</title>
+
+ <para>For the latest information on supported Operating System / JVM combinations and supported Database platforms, please refer to <ulink url="http://www.jboss.com">http://www.jboss.com</ulink>.
+ </para>
+
+ </section>
+
+ <section id="Pre_Requisites-Configuring_Your_Java_Environment">
+ <title>Configuring Your Java Environment</title>
+ <para>
+ You must have a working installation of <emphasis>JDK 1.5</emphasis> or <emphasis>JDK 1.6</emphasis> before you install JBoss Application Server. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 5.0 on a Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM.
+ <itemizedlist id="Configuring_Your_Java_Environment-Benefits_of_64_bit_JVM_on_64_bit_OS_and_Hardware">
+ <title>Benefits of 64-bit JVM on 64-bit OS and Hardware:</title>
+ <listitem>
+ <para>
+ Wider datapath: The pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Applications that run with more than 1.5GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Linux">
+ <title>Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Linux</title>
+ <listitem>
+ <para>
+ Download the Sun JDK 5.0 or JDK 6 (Java 2 Development Kit) from Sun's website: <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp"/> for JDK 5.0 or <ulink url="http://java.sun.com/javase/downloads/"/> for JDK 6.0. Select the JDK Update <x>" (where x is the latest update number) for download and then select "RPM in self-extracting" file for Linux<footnote><para>Make sure you choose the appropriate file for your platform.</para></footnote>. Read the instructions on Sun's website for installing the JDK.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you do not want to use SysV service scripts you can install the "self-extracting file" for Linux instead of choosing the "RPM in self-extracting" file. In that case you can skip the next step mentioned here. But it is recommended to use the SysV service scripts for production servers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Download and install the appropriate <literal>-compat RPM</literal> from <literal>JPackage</literal> <ulink url="ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/"> here</ulink>. Please ensure you choose a matching version of the <literal>-compat</literal> package to the JDK you installed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create an environment variable that points to the JDK installation directory and call it <literal>JAVA_HOME</literal>. Add <literal>$JAVA_HOME/bin</literal> to the system path to be able to run <literal>java</literal> from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory.
+ <programlisting>#In this example /usr/java/jdk1.6.0_07 is the JDK installation directory.
+ export JAVA_HOME=/usr/java/jdk1.6.0_07
+ export PATH=$PATH:$JAVA_HOME/bin
+ </programlisting>
+ Set this variable for the user account doing the installation and also for the user account that will run the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.5 or JDK1.6 installation as the default source for the <literal>java</literal> and <literal>javac</literal> executables. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system.
+ <itemizedlist>
+ <title>Select alternatives for java, javac and java_sdk_1.<x></title>
+ <listitem>
+ <para>
+ As root, type the following command at the shell prompt and you should see something like this: <programlisting>
+ [root at vsr ~]$ /usr/sbin/alternatives --config java
+ There are 2 programs which provide 'java'.
+ Selection Command
+ -----------------------------------------------
+ 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java
+ *+ 2 /usr/lib/jvm/jre-1.5.0-sun/bin/java
+ Enter to keep the current selection[+], or type selection number:
+ </programlisting>
+ Make sure the Sun version [<literal>jre-1.5.0-sun</literal> in this case] is selected (marked with a '+' in the output), or select it by entering its number as prompted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Repeat the same for javac and java_sdk_1.<x> <programlisting>
+ [root at vsr ~]$ /usr/sbin/alternatives --config javac
+ There are 1 programs which provide 'javac'.
+ Selection Command
+ -----------------------------------------------
+ *+ 1 /usr/lib/jvm/java-1.5.0-sun/bin/javac
+ Enter to keep the current selection[+], or type selection number:
+ </programlisting>
+ <programlisting>
+ [root at vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
+ There are 1 programs which provide 'java_sdk_1.5.0'.
+ Selection Command
+ -----------------------------------------------
+ *+ 1 /usr/lib/jvm/java-1.5.0-sun
+ Enter to keep the current selection[+], or type selection number:
+ </programlisting>
+ You should verify that java, javac and java_sdk_1.<x> all point to the same manufacturer and version.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>
+ You can always override this step by setting the <literal>JAVA_HOME</literal> environment variable as explained in the previous step.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Make sure that the <literal>java</literal> executable is in your path and that you are using an appropriate version. To verify your Java environment, type <literal>java -version</literal> at the shell prompt and you should see something like this: <programlisting>
+ [root at vsr ~]$ java -version
+ java version "1.5.0_14"
+ Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_14-b03)
+ Java HotSpot(TM) Client VM (build 1.5.0_14-b03, mixed mode, sharing)
+ </programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Microsoft_Windows">
+ <title>Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Microsoft Windows</title>
+ <listitem>
+ <para>
+ Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp"/> for JDK 5.0 or <ulink url="http://java.sun.com/javase/downloads/"/> for JDK 6.0. Choose the JDK Update <x>" (where x is the latest update number) for download and then select your Windows Platform options to perform the installation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an environment variable called <literal>JAVA_HOME</literal> that points to the JDK installation directory, for example: <literal>C:\Program Files\Java\jdk1.5.0_14\</literal>. In order to run java from the command line add the <literal>jre\bin</literal> directory to your path, for example: <literal>C:\Program Files\Java\jdk1.5.0_14\jre\bin</literal>. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+
+
+
+
+ </section>
+</chapter>
+
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Alternatives.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Alternatives.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Alternatives.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="Installation_Alternatives">
+ <title>Installation Alternatives</title>
+ <para>
+ You can install the JBoss Application Server in one of these two modes: <itemizedlist>
+ <!--<listitem>
+ <para>
+ <emphasis>Graphical Installer</emphasis>
+ </para>
+ <para>
+ Using the Graphical Installer can simplify the installation and configuration process for non-sophisticated users. In addition to the basic installation, the installer provides you with basic configuration capabilities, allows you to control whether the JMX interfaces are secured and the ability to enter console username/password. The graphical installer is available for <emphasis>subscribed users</emphasis> on <ulink url="https://network.jboss.com"/>.
+ </para>
+ </listitem>-->
+ <listitem>
+ <para>
+ <emphasis>Binary files download</emphasis>
+ </para>
+ <para>
+ In this form of installation, simply unzip the downloaded zip file to the directory of your choice. You can unzip the JBoss Application Server on any operating system that supports the zip format. The zip file is available on <ulink url="http://labs.jboss.com/jbossas/downloads/"/>. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in <xref linkend="Getting_Started-Pre_Requisites"/>. Further details on installation using the Binary files are discussed in <xref linkend="binary_installation"/>
+ </para>
+ <para>
+ JBossAS 5.0.0 can be compiled with both Java5 and Java6. The Java5 compiled binary is our primary/recommended binary distribution. It has undergone rigorous testing and can run under both a Java 5 and a Java 6 runtime. When running
+ under Java 6 you need to manually copy the following libraries from the <filename>JBOSS_HOME/client</filename> directory to the <filename>JBOSS_HOME/lib/endorsed</filename> directory, so that the JAX-WS 2.0 apis supported by JBossWS are used:
+ </para>
+ <screen>* jbossws-native-saaj.jar
+ * jbossws-native-jaxrpc.jar
+ * jbossws-native-jaxws.jar
+ * jbossws-native-jaxws-ext.jar </screen>
+ <para>
+ Another alternative is to download the jdk6 distribution <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2-jdk6.zip?modtime=1221686600&big_mirror=1">(<filename>jboss-5.0.0.CR2-jdk6.zip</filename>)</ulink> in which case no configuration changes are required.
+
+ Please refer to the <ulink url="http://sourceforge.net/project/shownotes.php?release_id=627020&group_id=22866">release notes</ulink> for additional information about running with JDK 6.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Source Files download</emphasis>
+ </para>
+ <para>
+ In this form of installation, download the source files from the web and build the source files locally. On successfully building your source files you can manually copy the built file into a desired folder and start the server. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in <xref linkend="Getting_Started-Pre_Requisites"/>. For more instructions on building your source files, please refer to <xref linkend="source_installation"/>.
+ </para>
+ </listitem>
+ <!--<listitem>
+ <para>
+ <emphasis>RPM download</emphasis>
+ </para>
+ <para>
+ In this form of installation, you can automatically install the platform on a &RHEL; system using the <literal>up2date</literal> command. The RPM installer is available for <emphasis>subscribed users</emphasis> on the Red Hat Network (RHN) on <ulink url="http://rhn.redhat.com"/>.
+ </para>
+ </listitem>-->
+ </itemizedlist>
+ </para>
+ <!--<para>
+ When you install from the installer, you get a smaller install image that is more tuned for your environment. However, the directory structure will be slightly different than when using the rpm/zip archive.
+ </para>-->
+ <para>
+ Three types of server configurations will be included in your installation - <emphasis>minimal</emphasis>, <emphasis>default</emphasis>, and <emphasis>all</emphasis>.
+ </para>
+</chapter>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_And_Getting_Started_Guide.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_And_Getting_Started_Guide.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_And_Getting_Started_Guide.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,7 +1,42 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd"
+[
+<!ENTITY versionNumber "5.0.0.GA">
+<!ENTITY copyrightYear "2008">
+<!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
+<!ELEMENT xi:include (xi:fallback?) >
+<!ATTLIST xi:include
+xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
+href CDATA #REQUIRED
+parse (xml|text) "xml"
+xpointer CDATA #IMPLIED
+encoding CDATA #IMPLIED
+accept CDATA #IMPLIED
+accept-charset CDATA #IMPLIED
+accept-language CDATA #IMPLIED >
+<!ELEMENT xi:fallback ANY >
+<!ATTLIST xi:fallback
+xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude" >
+<!ENTITY % local.preface.class "| xi:include" >
+<!ENTITY % local.part.class "| xi:include" >
+<!ENTITY % local.chapter.class "| xi:include" >
+<!ENTITY % local.divcomponent.mix "| xi:include" >
+<!ENTITY % local.para.char.mix "| xi:include" >
+<!ENTITY % local.info.class "| xi:include" >
+<!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED
+xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'" >
+]>
+
<book>
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <bookinfo>
+ <title>JBoss Application Server</title>
+ <subtitle>Installation And Getting Started Guide</subtitle>
+ <releaseinfo></releaseinfo>
+ <productnumber>&versionNumber;</productnumber>
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </bookinfo>
+
<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Getting_Started.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Installation_Alternatives.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Using_Graphical_Installer.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Using_Graphical_Installer.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_Using_Graphical_Installer.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,7 +1,7 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
<chapter id="Installation_Using_Graphical_Installer">
<title>Installation Using The Graphical Installer</title>
<itemizedlist id="Installation_Using_Graphical_Installer-Launching_the_Graphical_Installer">
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Binary_Download.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Binary_Download.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Binary_Download.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="binary_installation">
+ <title>Installation With Binary Download</title>
+
+ <section id="Binary_Download">
+ <title>Download and Installation</title>
+
+ <para>
+ You can download the Binary zip files from <ulink url="http://labs.jboss.com/jbossas/downloads/">http://labs.jboss.com/jbossas/downloads/</ulink>.
+ </para>
+ <para>
+ There are two binary distributions available:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2.zip?modtime=1221686752&big_mirror=1">jboss-5.0.0.CR2.zip</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2-jdk6.zip?modtime=1221686600&big_mirror=1">jboss-5.0.0.CR2-jdk6.zip</ulink>
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ In this form of installation, simply unzip the downloaded zip file to the directory of your choice on any operating system that supports the zip format.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Unzip <literal>jboss-<release>.zip</literal> to extract the archive contents into the location of your choice. You can do this using the JDK <literal>jar</literal> tool (or any other ZIP extraction tool). In the example below we are assuming you downloaded the zip file to the <filename>/jboss</filename> directory.
+ <programlisting>
+ [usr]$ <literal>cd /jboss</literal>
+ [usr]$ <literal>jar -xvf jboss-<release>.zip</literal></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You should now have a directory called <filename>jboss-<release></filename>. Next you need to set your JBOSS_HOME environment variables. This is discussed in <xref linkend="setting_JBOSS_HOME"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+
+</chapter>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_RHN.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_RHN.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_RHN.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,6 +1,7 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
<chapter id="Installation_With_RHN">
<title>Installation With RHN</title>
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Source_Download.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Source_Download.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Installation_With_Source_Download.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="source_installation">
+ <title>Installation With Source Download</title>
+
+ <section id="Source_Download">
+ <title>Download and Installation</title>
+
+ <para>
+ You can download the zip source file from <ulink url="http://labs.jboss.com/jbossas/downloads/">http://labs.jboss.com/jbossas/downloads/</ulink>.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Uncompress <literal>jboss-<release>-src.tar.gz</literal> to extract the archive contents into the location of your choice. You can do this using the <literal>tar</literal> archiving utility in Linux (or any other compatible extraction tool). In this example we are assuming your source files were copied in the <filename>/jboss</filename> folder.
+
+ <screen>[user at localhost]$ cd /jboss
+ [user at localhost]$ tar -xvf <literal>jboss-<release>-src.tar.gz</literal></screen>
+
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You should now have a directory called <literal>jboss-<release>-src.tar.gz</literal>. The next step is to build your source files. In this example we are using Apache ANT. This is discussed in the following section.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section><title>Installing and configuring ANT</title>
+ <para>
+ <ulink url="http://ant.apache.org/">Apache Ant</ulink> is a Java-based build tool. Instead of using an extended model using shell-based commands, Ant is extended using Java classes that use XML-based configuration files. The configuration files call out a target tree that executes various tasks. Each task is run by an object that implements a particular Task interface.
+ This gives you the ability to perform cross platform builds. Please also note that if needed, Ant provides an <exec> task that allows commands to be executed based on the Operating System it is executing on. For more information on Apache ANT please click <ulink url="http://ant.apache.org/">here</ulink>.
+ </para>
+ <para>
+ You will need to build your JBoss Application Server source files before you can run the application server. Apache Ant is shipped with the JBoss Application Server source files and can be executed from the <filename><source_directory>/tools/bin</filename> directory.
+ </para>
+ <para>
+ The source files can also be built using Apache Maven which is also shipped with the JBoss Application Server source files under <filename><source_directory>/tools/maven</filename> directory. For more information about Apache Maven, please refer to <ulink url="">http://maven.apache.org/</ulink>.
+ </para>
+
+ <para>
+ Like Java, you also need to set the environment variables for Apache ANT and/or Apache Maven. The following example illustrates a desirable configuration for the <filename>.bashrc</filename> file. In the example the file is edited using the gnome text editor (<command>gedit</command>).
+
+ <screen>[user at localhost ~]$ gedit .bashrc
+
+ # Source global definitions
+ if [ -f /etc/bashrc ]; then
+ /etc/bashrc
+ fi
+ ......
+ # User specific aliases and functions
+ # The following are the environment variables for Java , ANT and Maven
+
+ export JAVA_HOME=/usr/java/jdk1.6.0_07/
+ export PATH=$PATH:$JAVA_HOME/bin
+
+ export ANT_HOME=/home/downloads/jboss-<source_directory>/tools/
+ export PATH=$PATH:$ANT_HOME/bin
+
+ export MAVEN_HOME=/home/downloads/jboss-<source_directory>/tools/maven
+ export PATH=$PATH:$MAVEN_HOME/bin
+ </screen>
+
+ </para>
+ <para>
+ To implement the changes you've made to the <filename>.bashrc</filename> file, type the following on a terminal.
+
+ <screen>[user at localhost ~]$ source .bashrc
+ [user at localhost ~]$</screen>
+
+ If any errors are displayed, please check your <filename>.bashrc</filename> file for errors and ensure that all directory paths are correct.
+ </para>
+ </section>
+
+ <section><title>Building with Apache ANT</title>
+ <para>
+ To build the JBoss Application Server source files with Apache ANT, from a terminal change directory to where the unzipped source files are. In the following example we are assuming that the source files were copied and unzipped in the logged in user's <filename>downloads</filename> folder.
+
+ <screen>[user at localhost]$ cd /home/user/downloads/<literal>jboss-<release>-src</literal>/build
+ [user at localhost build]$ ls
+ aspects component-matrix docbook-support iiop jmx mbeans security system-jmx tools
+ bootstrap connector ejb3 j2se jmx-remoting messaging server testsuite varia
+ build console embedded jbossas main pom.xml spring-int thirdparty webservices
+ cluster deployment hibernate-int jbossmq management profileservice system tomcat
+ </screen>
+ From the contents of the <filename>build</filename> directory above, you can see the <filename>build.xml</filename> file which is used by Apache ANT as a configuration file when building your source files.
+ The next step is to perform the build using Apache ANT as illustrated below.
+ <screen>[user at localhost build]$ ant
+
+ compile-classes:
+ [mkdir] Created dir: /jboss/jboss-<release>-src/tomcat/output/classes
+ [javac] Compiling 89 source files to /jboss/jboss-<release>-src/tomcat/output/classes
+ ....
+ ....content truncated
+ .....
+ .....
+ _buildmagic:build-bypass-check:
+ jars:
+ most:
+ main:
+ BUILD SUCCESSFUL
+ Total time: 2 seconds</screen>
+
+ A successful build will have the above message. If your build fails, please check the error log and ensure that your configuration files and environment variables are correctly set. The JBoss Application Server files are built under the <filename>build/output/jboss-<release></filename> directory as indicated below.
+
+ <note><title>Note</title>
+ <para>At this point the JBoss Application Server source files build is a hybrid one (builds in both Ant and Maven) because it declares all JBoss dependencies as maven2 artifacts, however after the dependencies are resolved/imported the legacy ant based build is used to compile and build the distribution. The JBoss Application Server source files will change to a full maven build soon.
+ </para>
+ </note>
+
+ <screen>[user at localhost build]$ ls
+ build.bat build-old.xml build-thirdparty-old.xml eclipse.psf output
+ build-distr.xml build-release.xml build.xml etc pom.xml
+ build.log build.sh docs local.properties VersionRelease.java
+
+ [user at localhost build]$ cd output/jboss-<release>
+ [user at localhost build]$ ls
+ bin client docs lib server
+ </screen>
+
+ The <filename>jboss-<release></filename> directory contains your successful JBoss Application Server files. You can copy this folder to a different location or run the server from this folder after setting the JBOSS_HOME environment variable in your <filename>.bashrc</filename> file. Next you need to set your JBOSS_HOME environment variables. This is discussed in <xref linkend="setting_JBOSS_HOME"/>.
+
+ </para>
+ </section>
+
+
+
+
+</chapter>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Preface.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Preface.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Preface.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,8 +1,6 @@
<?xml version='1.0'?>
-<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-
-
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
<preface id="Book-Preface">
<title>Introduction</title>
<para>
@@ -13,7 +11,22 @@
</para>
<para>
Installing JBoss Application Server is simple and easy. You can have it installed and running in no time. This guide will teach you to install and get started with the JBoss Application Server.</para>
- <xi:include href="Software_Versions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-</preface>
+ <section id="Book-We_Need_Feedback">
+ <title>Help Contribute</title>
+ <para>
+ If you find a typographical error in the <citetitle>Installation Guide and Getting Started Guide</citetitle>, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: <ulink url="http://jira.jboss.com">http://jira.jboss.com</ulink> against the project <citetitle>JBoss Application Server</citetitle> and component <citetitle>Docs/Installation and Getting Started Guide</citetitle>.
+ </para>
+ <para>
+ If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
+ </para>
+ <note><title>Note</title><para>Be sure to give us your name so you can receive full credit.</para></note>
+
+ <note><title>Note</title><para>This content is taken from svn.jboss.org/repos/jbossas/projects/docs/community/5 and has yet to be branched.</para></note>
+
+ <para>To access the content directly and make changes yourself:</para>
+ <screen>
+ svn co https://svn.jboss.org/repos/jbossas/projects/docs/community/5 --username yourusername
+ </screen>
+ </section></preface>
+
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Sample_JSF_EJB3_Application.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Sample_JSF_EJB3_Application.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Sample_JSF_EJB3_Application.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,562 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter id="Sample_JSF_EJB3_Application">
+ <title>Sample JSF-EJB3 Application</title>
+ <para>
+ We use a simple "TODO" application to show how JSF and EJB3 work together in a web application. The "TODO" application works like this: You can create a new 'todo' task item using the "Create" web form. Each 'todo' item has a 'title' and a 'description'. When you submit the form, the application saves your task to a relational database. Using the application, you can view all 'todo' items, edit/delete an existing 'todo' item and update the task in the database.
+ </para>
+ <para>
+ The sample application comprises the following components:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Entity objects - These objects represent the data model; the properties in the object are mapped to column values in relational database tables.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ JSF web pages - The web interface used to capture input data and display result data. The data fields on these web pages are mapped to the data model via the JSF Expression Language (EL).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ EJB3 Session Bean - This is where the functionality is implemented. We make use of a Stateless Session Bean.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <section id="Sample_JSF_EJB3_Application-Data_Model">
+ <title>Data Model</title>
+ <para>
+ Let's take a look at the contents of the Data Model represented by the <literal>Todo</literal> class in the <literal>Todo.java</literal> file. Each instance of the <literal>Todo</literal> class corresponds to a row in the relational database table. The 'Todo' class has three properties: id, title and description. Each of these correspond to a column in the database table.
+ </para>
+ <para>
+ The 'Entity class' to 'Database Table' mapping information is specified using EJB3 Annotations in the 'Todo' class. This eliminates the need for XML configuration and makes it a lot clearer. The <literal>@Entity</literal> annotation defines the <literal>Todo</literal> class as an Entity Bean. The <literal>@Id</literal> and <literal>@GeneratedValue</literal> annotations on the <literal>id</literal> property indicate that the <literal>id</literal> column is the primary key and that the server automatically generates its value for each <literal>Todo</literal> object saved into the database.
+ </para>
+ <para>
+<programlisting>
+ at Entity
+public class Todo implements Serializable {
+
+ private long id;
+ private String title;
+ private String description;
+
+ public Todo () {
+ title ="";
+ description ="";
+ }
+
+ @Id @GeneratedValue
+ public long getId() { return id;}
+ public void setId(long id) { this.id = id; }
+
+ public String getTitle() { return title; }
+ public void setTitle(String title) {this.title = title;}
+
+ public String getDescription() { return description; }
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+}
+</programlisting>
+ </para>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-JSF_Web_Pages">
+ <title>JSF Web Pages</title>
+ <para>
+ In this section we will show you how the web interface is defined using JSF pages. We will also see how the data model is mapped to the web form using JSF EL. Using the #{...} notation to reference Java objects is called <emphasis role="bold">JSF EL</emphasis> (JSF Expression Language). Lets take a look at the pages used in our application:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">index.xhtml</emphasis>: This page displays two options: 1. Create New Todo 2. Show all Todos. When you click on the Submit button the corresponding action is invoked.
+ </para>
+ <para>
+<programlisting>
+<h:form>
+<ul>
+ <li><h:commandLink type="submit" value="Create New Todo" action="create"/></li>
+ <li><h:commandLink type="submit" value="Show All Todos" action="todos"/></li>
+</ul>
+</h:form>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">create.xhtml</emphasis>: When you try to create a new task, this JSF page captures the input data. We use the <literal>todoBean</literal> to back the form input text fields. The #{todoBean.todo.title} symbol refers to the "title" property of the "todo" object in the "TodoBean" class. The #{todoBean.todo.description} symbol refers to the "description" property of the "todo" object in the "TodoBean" class. The #{todoBean.persist} symbol refers to the "persist" method in the "TodoBean" class. This method creates the "Todo" instance with the input data (title and description) and persists the data.
+ </para>
+
+<programlisting role="xml">
+<h:form id="create">
+<table>
+ <tr>
+ <td>Title:</td>
+ <td>
+ <h:inputText id="title" value="#{todoBean.todo.title}" size="15">
+ <f:validateLength minimum="2"/>
+ </h:inputText>
+ </td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>
+ <h:inputTextarea id="description" value="#{todoBean.todo.description}">
+ <f:validateLength minimum="2" maximum="250"/>
+ </h:inputTextarea>
+ </td>
+ </tr>
+</table>
+<h:commandButton type="submit" id="create" value="Create"
+ action="#{todoBean.persist}"/>
+</h:form>
+</programlisting>
+
+<para>
+ <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_create_todo"/> shows the "Create Todo" web page with the input fields mapped to the data model.
+ </para>
+ <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_create_todo">
+ <title>The "Create Todo" web page </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jsfejb3_create_todo.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">todos.xhtml</emphasis>: This page displays the list of all "todos" created. There is also an option to choose a "todo" item for 'edit' or 'delete'.
+ </para>
+ <para>
+ The list of all 'todos' is fetched by #{todoBean.todos} symbol referring to the 'getTodos()' property in the 'TodoBean' class. The JSF <literal>dataTable</literal> iterates through the list and displays each <literal>Todo</literal> object in a row. The 'Edit' option is available across each row. The #{todo.id} symbol represents the "id" property of the "todo" object.
+ </para>
+ <para>
+<programlisting>
+<h:form>
+<h:dataTable value="#{todoBean.todos}" var="todo">
+ <h:column>
+ <f:facet name="header">Title</f:facet>
+ #{todo.title}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ #{todo.description}
+ </h:column>
+ <h:column>
+ <a href="edit.faces?tid=#{todo.id}">Edit</a>
+ </h:column>
+</h:dataTable>
+<center>
+ <h:commandButton action="create"
+ value="Create New Todo" type="submit"/>
+</center>
+</h:form>
+</programlisting>
+ <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_todos"/> shows the "Show All Todos" web page with the data fields mapped to the data model.
+ </para>
+ <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_todos">
+ <title>The "Show All Todos" web page </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jsfejb3_todos.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">edit.xhtml</emphasis>: This page allows you to edit the "todo" item's 'title' and 'description' properties. The #{todoBean.update} and #{todoBean.delete} symbols represent the "update" and "delete" methods in the "TodoBean" class.
+ </para>
+
+<programlisting role="xml">
+<h2>Edit #{todoBean.todo.title}</h2>
+<h:form id="edit">
+<input type="hidden" name="tid" value="#{todoBean.todo.id}"/>
+<table>
+ <tr>
+ <td>Title:</td>
+ <td>
+ <h:inputText id="title" value="#{todoBean.todo.title}" size="15">
+ <f:validateLength minimum="2"/>
+ </h:inputText>
+ </td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>
+ <h:inputTextarea id="description" value="#{todoBean.todo.description}">
+ <f:validateLength minimum="2" maximum="250"/>
+ </h:inputTextarea>
+ </td>
+ </tr>
+</table>
+<h:commandButton type="submit" id="update" value="Update"
+ action="#{todoBean.update}"/>
+<h:commandButton type="submit" id="delete" value="Delete"
+ action="#{todoBean.delete}"/>
+</h:form>
+</programlisting>
+<para>
+ <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_edit_todo"/> shows the "Edit Todo" web page with the mapping to the data model.
+ </para>
+ <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_edit_todo">
+ <title>The "Edit Todo" web page </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jsfejb3_edit_todo.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>
+ We have used XHTML pages in the sample applications because we recommend using Facelets instead of JSP to render JSF view pages.
+ </para>
+ </note>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-EJB3_Session_Beans">
+ <title>EJB3 Session Beans</title>
+ <para>
+ EJB 3.0 is one of the major improvements introduced with Java EE 5.0. It aims at reducing the complexity of older versions of EJB and simplifies Enterprise Java development and deployment. You will notice that to declare a class as a 'Session Bean' you simply have to annotate it. Using annotations eliminates the complexity involved with too many deployment descriptors. Also the only interface an EJB3 Session Bean requires is a business interface that declares all the business methods that must be implemented by the bean.
+ </para>
+ <para>
+ We will explore the two important source files associated with the Bean implementation in our application: <literal>TodoDaoInt.java</literal> and <literal>TodoDao.java</literal>.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">Business interface</emphasis>: <literal>TodoDaoInt.java</literal>
+ </para>
+ <para>We define here the methods that need to be implemented by the bean implementation class. Basically, the business methods that will be used in our application are defined here.
+
+<programlisting role="JAVA">
+public interface TodoDaoInt {
+
+ public void persist (Todo todo);
+ public void delete (Todo todo);
+ public void update (Todo todo);
+
+ public List <Todo> findTodos ();
+ public Todo findTodo (String id);
+}
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">Stateless Session Bean</emphasis>: <literal>TodoDao.java</literal>
+ </para>
+ <para>
+ The <literal>@Stateless</literal> annotation marks the bean as a stateless session bean. In this class, we need to access the Entity bean <literal>Todo</literal> defined earlier. For this we need an <literal>EntityManager</literal>. The <literal>@PersistenceContext</literal> annotation tells the JBoss Server to inject an entity manager during deployment.
+<programlisting>
+ at Stateless
+public class TodoDao implements TodoDaoInt {
+
+ @PersistenceContext
+ private EntityManager em;
+
+ public void persist (Todo todo) {
+ em.persist (todo);
+ }
+
+ public void delete (Todo todo) {
+ Todo t = em.merge (todo);
+ em.remove( t );
+ }
+
+ public void update (Todo todo) {
+ em.merge (todo);
+ }
+
+ public List <Todo> findTodos () {
+ return (List <Todo>) em.createQuery("select t from Todo t")
+ .getResultList();
+ }
+
+ public Todo findTodo (String id) {
+ return (Todo) em.find(Todo.class, Long.parseLong(id));
+ }
+
+}
+</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-Configuration_and_Packaging">
+ <title>Configuration and Packaging</title>
+ <para>
+ We will build the sample application using Ant and explore the configuration and packaging details. Please install Ant if currently not installed on your computer.
+ </para>
+ <section id="Building_The_Application">
+ <title>Building The Application</title>
+ <para>Let's look at building the example application and then explore the configuration files in detail.
+ </para>
+ <para>
+ In <xref linkend="About_the_Example_Applications"/>, we looked at the directory structure of the <literal>jsfejb3</literal> sample application. At the command line, go to the <literal>jsfejb3</literal> directory. There you will see a <literal>build.xml</literal> file. This is our Ant build script for compiling and packaging the archives. To build the application, you need to first of all edit the <literal>build.xml</literal> file and edit the value of <literal>jboss-dist</literal> to reflect the location where the JBoss Application Server is installed. Once you have done this, just type the command <literal>ant</literal> and your output should look like this:
+ </para>
+<screen>[user at localhost jsfejb3]$ ant
+Buildfile: build.xml
+
+compile:
+ [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/classes
+ [javac] Compiling 4 source files to /home/user/Desktop/gettingstarted/jsfejb3/build/classes
+ [javac] Note: /jboss/gettingstarted/jsfejb3/src/TodoDao.java uses unchecked or unsafe operations.
+ [javac] Note: Recompile with -Xlint:unchecked for details.
+
+war:
+ [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/jars
+ [war] Building war: /jboss/gettingstarted/jsfejb3/build/jars/app.war
+
+ejb3jar:
+ [jar] Building jar: /jboss/gettingstarted/jsfejb3/build/jars/app.jar
+
+ear:
+ [ear] Building ear: /jboss/gettingstarted/jsfejb3/build/jars/jsfejb3.ear
+
+main:
+
+BUILD SUCCESSFUL
+Total time: 3 seconds
+
+</screen>
+ <para>
+ If you get the BUILD SUCCESSFUL message, you will find a newly created <literal>build</literal> directory with 2 sub-directories in it: <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">classes</emphasis>: containing the compiled class files.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">jars</emphasis>: containing three archives - <literal>app.jar</literal>, <literal>app.war</literal> and <literal>jsfejb3.ear</literal>. <itemizedlist>
+ <listitem>
+ <para>
+ app.jar : EJB code and descriptors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ app.war : web application which provides the front end to allow users to interact with the business components (the EJBs). The web source (HTML, images etc.) contained in the <literal>jsfejb3/view</literal> directory is added unmodified to this archive. The Ant task also adds the <literal>WEB-INF</literal> directory that contains the files which aren’t meant to be directly accessed by a web browser but are still part of the web application. These include the deployment descriptors (<literal>web.xml</literal>) and extra jars required by the web application.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ jsfejb3.ear : The EAR file is the complete application, containing the EJB modules and the web module. It also contains an additional descriptor, <literal>application.xml</literal>. It is also possible to deploy EJBs and web application modules individually but the EAR provides a convenient single unit.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Configuration_Files">
+ <title>Configuration Files</title>
+ <para>
+ Now that we have built the application, lets take a closer look at some of the important Configuration files. We have built the final archive ready for deployment - <literal>jsfejb3.ear</literal>. The contents of your EAR file should look like this:
+ </para>
+<programlisting>
+jsfejb3.ear
+|+ app.jar // contains the EJB code
+ |+ import.sql
+ |+ Todo.class
+ |+ TodoDao.class
+ |+ TodoDaoInt.class
+ |+ META-INF
+ |+ persistence.xml
+|+ app.war // contains web UI
+ |+ index.html
+ |+ index.xhtml
+ |+ create.xhtml
+ |+ edit.xhtml
+ |+ todos.xhtml
+ |+ TodoBean.class
+ |+ style.css
+ |+ META-INF
+ |+ WEB-INF
+ |+ faces-config.xml
+ |+ navigation.xml
+ |+ web.xml
+|+ META-INF // contains the descriptors
+ |+ application.xml
+ |+ jboss-app.xml
+</programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>application.xml</literal>: This file lists the JAR files in the EAR (in our case <literal>app.jar</literal>) and tells the JBoss server what files to look for and where. The root URL for the application is also specified in this file as 'context-root'.
+<programlisting>
+<application>
+ <display-name>Sample Todo</display-name>
+ <module>
+ <web>
+ <web-uri>app.war</web-uri>
+ <context-root>/jsfejb3</context-root>
+ </web>
+ </module>
+ <module>
+ <ejb>app.jar</ejb>
+ </module>
+</application>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>jboss-app.xml</literal>: Every EAR application should specify a unique string name for the class loader. In our case, we use the application name 'jsfejb3' as the class loader name.
+<programlisting>
+<jboss-app>
+ <loader-repository>
+ jsfejb3:archive=jsfejb3.ear
+ </loader-repository>
+</jboss-app>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>app.jar</literal>: This contains EJB3 Session Bean and Entity Bean classes and the related configuration files. In addition, the <literal>persistence.xml</literal> file configures the back-end data source (in our case the default HSQL database) for the <literal>EntityManager</literal>.
+<programlisting>
+<persistence>
+ <persistence-unit name="helloworld">
+ <provider>org.hibernate.ejb.HibernatePersistence</provider>
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <properties>
+ <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
+ <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
+ </properties>
+ </persistence-unit>
+</persistence>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>app.war</literal>: This contains the Web UI files packaged according to the Web Application aRchive (WAR) specification. It contains all the web pages and the required configuration files. The <literal>web.xml</literal> file is an important file for all JAVA EE web applications. It is the web deployment descriptor file. The <literal>faces-config.xml</literal> file is the configuration file for JSF. The <literal>navigation.xml</literal> file contains the rules for JSF page navigation.
+ </para>
+<programlisting>
+//faces-config.xml
+<faces-config>
+ <application>
+ <view-handler>
+ com.sun.facelets.FaceletViewHandler
+ </view-handler>
+ </application>
+ <managed-bean>
+ <description>Dao</description>
+ <managed-bean-name>todoBean</managed-bean-name>
+ <managed-bean-class>TodoBean</managed-bean-class>
+ <managed-bean-scope>request</managed-bean-scope>
+ </managed-bean>
+</faces-config>
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section id="The_Database">
+ <title>The Database</title>
+ <section id="The_Database-Creating_the_Database_Schema">
+ <title>Creating the Database Schema</title>
+ <para>
+ To pre-populate the database, we have supplied SQL Code (<literal>import.sql</literal>) to run with HSQL in the <literal>examples/jsfejb3/resources</literal> directory. When you build the application using Ant, this is packaged in the app.jar file within the jsfejb3.ear file. When the application is deployed, you should be able to view the pre-populated data.
+ </para>
+ </section>
+ <section id="The_Database-The_HSQL_Database_Manager_Tool">
+ <title>The HSQL Database Manager Tool</title>
+ <para>
+ Just as a quick aside at this point, start up the JMX console application and click on the <literal>service=Hypersonic</literal> link which you’ll find under the section <literal>jboss</literal>. If you can’t find this, make sure the Hypersonic service is enabled in the <literal>hsqldb-ds.xml</literal> file.
+ </para>
+ <para>
+ This will take you to the information for the Hypersonic service MBean. Scroll down to the bottom of the page and click the <literal>invoke</literal> button for the <literal>startDatabaseManager()</literal> operation. This starts up the HSQL Manager, a Java GUI application which you can use to manipulate the database directly.
+ </para>
+ <figure id="The_HSQL_Database_Manager_Tool-The_HSQL_Database_Manger_">
+ <title>The HSQL Database Manger </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/hsql-manager.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-Deploying_the_Application">
+ <title>Deploying the Application</title>
+ <para>
+ Deploying an application in JBoss is simple and easy. You just have to copy the EAR file to the <literal>deploy</literal> directory in the 'server configuration' directory of your choice. Here, we will deploy it to the 'default' configuration, so we copy the EAR file to the <literal>JBOSS_DIST/jboss-as/server/default/deploy</literal> directory.
+ </para>
+ <para>
+ You should see something close to the following output from the server:
+ </para>
+<screen>
+15:32:23,997 INFO [EARDeployer] Init J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
+15:32:24,212 INFO [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
+entity.PersistenceUnitDeployment
+15:32:24,213 INFO [JmxKernelAbstraction] installing MBean: persistence.units:ear=
+jsfejb3.ear,jar=app.jar,unitName=helloworld with dependencies:
+15:32:24,213 INFO [JmxKernelAbstraction] jboss.jca:name=DefaultDS,service=
+DataSourceBinding
+15:32:24,275 INFO [PersistenceUnitDeployment] Starting persistence unit persistence.
+units:ear=jsfejb3.ear,jar=app.jar,unitName=helloworld
+15:32:24,392 INFO [Ejb3Configuration] found EJB3 Entity bean: Todo
+15:32:24,450 WARN [Ejb3Configuration] Persistence provider caller does not implements
+the EJB3 spec correctly. PersistenceUnitInfo.getNewTempClassLoader() is null.
+15:32:24,512 INFO [Configuration] Reading mappings from resource : META-INF/orm.xml
+15:32:24,512 INFO [Ejb3Configuration] [PersistenceUnit: helloworld] no META-INF/orm.xml
+found
+15:32:24,585 INFO [AnnotationBinder] Binding entity from annotated class: Todo
+15:32:24,586 INFO [EntityBinder] Bind entity Todo on table Todo
+.
+.
+.
+.
+15:32:26,311 INFO [SchemaExport] Running hbm2ddl schema export
+15:32:26,312 INFO [SchemaExport] exporting generated schema to database
+15:32:26,314 INFO [SchemaExport] Executing import script: /import.sql
+15:32:26,418 INFO [SchemaExport] schema export complete
+15:32:26,454 INFO [NamingHelper] JNDI InitialContext properties:{java.naming.factory.
+initial=org.jnp.interfaces.NamingContextFactory, java.naming.factory.url.pkgs=org.jboss.
+naming:org.jnp.interfaces}
+15:32:26,484 INFO [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
+stateless.StatelessContainer
+15:32:26,485 INFO [JmxKernelAbstraction] installing MBean: jboss.j2ee:ear=jsfejb3.ear,
+jar=app.jar,name=TodoDao,service=EJB3 with dependencies:
+15:32:26,513 INFO [JmxKernelAbstraction] persistence.units:ear=jsfejb3.ear,
+jar=app.jar,unitName=helloworld
+15:32:26,557 INFO [EJBContainer] STARTED EJB: TodoDao ejbName: TodoDao
+15:32:26,596 INFO [EJB3Deployer] Deployed: file:/jboss/jboss-as-5.0.0<release>
+server/default/tmp/deploy/
+tmp33761jsfejb3.ear-contents/app.jar
+15:32:26,625 INFO [TomcatDeployer] deploy, ctxPath=/jsfejb3, warUrl=.../tmp/deploy/
+tmp33761jsfejb3.ear-contents/app-exp.war/
+15:32:26,914 INFO [EARDeployer] Started J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
+</screen>
+ <para>
+ If there are any errors or exceptions, make a note of the error message. Check that the EAR is complete and inspect the WAR file and the EJB jar files to make sure they contain all the necessary components (classes, descriptors etc.).
+ </para>
+ <para>
+ You can safely redeploy the application if it is already deployed. To undeploy it you just have to remove the archive from the <literal>deploy</literal> directory. There’s no need to restart the server in either case. If everything seems to have gone OK, then point your browser at the application URL.
+ </para>
+ <para>
+ <ulink url="http://localhost:8080/jsfejb3"/>
+ </para>
+ <para>
+ You will be forwarded to the application main page. <xref linkend="Deploying_the_Application-Sample_TODO"/> shows the sample application in action.
+ </para>
+ <figure id="Deploying_the_Application-Sample_TODO">
+ <title>Sample TODO</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/sample_jsfejb3.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+</chapter>
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Server_Configurations.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Server_Configurations.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Server_Configurations.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,1221 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations">
+<title>Server Configurations</title>
+<para>
+ Fundamentally, the JBoss architecture consists of the microcontainer, bootstrap beans loaded into the micrcontainer, a collection of deployers for loading various deployment types, and various mcbean(-jboss-beans.xml) and legacy mbean(jboss-service.xml) deployments.
+ This makes it easy to assemble different configurations and gives you the flexibility to tailor them to meet your requirements.
+</para>
+<para>
+ You don’t have to run a large, monolithic server all the time; you can remove the components you don’t need (which can also reduce the server startup time considerably) and you can also integrate additional services into JBoss by writing your own MBeans. You certainly do not need to do this to be able to run standard Java EE 5 applications though.
+</para>
+<para>
+ You don’t need a detailed understanding of the microcontainer to use JBoss, but it’s worth keeping a picture of this basic architecture in mind as it is central to the way JBoss works.
+</para>
+<para>
+ The JBoss Application Server ships with three different server configurations. Within the <literal><JBoss_Home>/server</literal> directory, you will find five subdirectories:
+ <literal>minimal</literal>, <literal>default</literal>, <literal>standard</literal>, <literal>all</literal> and <literal>web</literal> - one for each server configuration. Each of these configurations provide a different set of services. The <literal>default</literal> configuration is the one used if you don’t specify another one when starting up the server.
+</para>
+<para>
+ <variablelist>
+ <varlistentry>
+ <term>minimal</term>
+ <listitem>
+ <para>
+ has a minimal configuration—the bare minimum services required to start JBoss. It starts the logging service, a JNDI server and a URL deployment scanner to find new deployments. This is what you would use if you want to use JMX/JBoss to start your own services without any other Java EE 5 technologies. This is just the bare server. There is no web container, no EJB or JMS support.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>default</term>
+ <listitem>
+ <para>
+ is a base Java EE 5 server profile containing a default set of services. It has the most frequently used services required to deploy a Java EE application. It does not include the JAXR service, the IIOP service, or any of the clustering services.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>all</term>
+ <listitem>
+ <para>
+ The all configuration starts all the available services. This includes the RMI/IIOP and clustering services, which are not loaded in the default configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>standard</term>
+ <listitem>
+ <para>
+ is the JavaEE 5 certified configuration of services.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>web</term>
+ <listitem>
+ <para>
+ is a lightweight web container oriented profile that previews the JavaEE 6 web profile.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</para>
+<para>
+ If you want to know which services are configured in each of these instances, the primary differences will be in the <filename class="directory"><JBoss_Home>/server/<instance-name>/deployers/</filename> directory and also the services deployments in the <filename class="directory"><JBoss_Home>/server/<instance-name>/deploy</filename> directory. For example, the default profile deployers and deploy directory contents are:
+<programlisting>
+[usr at localhost <JBoss_Home>]$<literal>ls server/default/deployers </literal>
+alias-deployers-jboss-beans.xml jboss-aop-jboss5.deployer
+bsh.deployer jboss-jca.deployer
+clustering-deployer-jboss-beans.xml jbossweb.deployer
+dependency-deployers-jboss-beans.xml jbossws.deployer
+directory-deployer-jboss-beans.xml j sr77-deployers-jboss-beans.xml
+ear-deployer-jboss-beans.xml metadata-deployer-jboss-beans.xml
+ejb-deployer-jboss-beans.xml seam.deployer
+ejb3.deployer security-deployer-jboss-beans.xml
+hibernate-deployer-jboss-beans.xml
+[usr at localhost <JBoss_Home>]$<literal>ls server/default/deploy </literal>
+ROOT.war jsr88-service.xml
+cache-invalidation-service.xml legacy-invokers-service.xml
+ejb2-container-jboss-beans.xml mail-ra.rar
+ejb2-timer-service.xml mail-service.xml
+ejb3-connectors-jboss-beans.xml management
+ejb3-container-jboss-beans.xml messaging
+ejb3-interceptors-aop.xml monitoring-service.xml
+ejb3-timer-service.xml profileservice-jboss-beans.xml
+hdscanner-jboss-beans.xml properties-service.xml
+hsqldb-ds.xml quartz-ra.rar
+http-invoker.sar remoting-jboss-beans.xml
+jboss-local-jdbc.rar schedule-manager-service.xml
+jboss-xa-jdbc.rar scheduler-service.xml
+jbossweb.sar security
+jbossws.sar sqlexception-service.xml
+jca-jboss-beans.xml transaction-jboss-beans.xml
+jms-ra.rar transaction-service.xml
+jmx-console.war uuid-key-generator.sar
+jmx-invoker-service.xml vfs-jboss-beans.xml
+jmx-remoting.sar
+</programlisting>
+ while the web profile deployers and deploy directory contents are:
+<programlisting>
+[usr at localhost <JBoss_Home>]$<literal>ls server/web/deployers </literal>
+alias-deployers-jboss-beans.xml jbossweb.deployer
+ejb3.deployer metadata-deployer-jboss-beans.xml
+jboss-aop-jboss5.deployer security-deployer-jboss-beans.xml
+jboss-jca.deployer
+[usr at localhost <JBoss_Home>]$<literal>ls server/web/deployers </literal>
+ROOT.war jbossweb.sar
+ejb3-container-jboss-beans.xml jca-jboss-beans.xml
+hdscanner-jboss-beans.xml jmx-console.war
+hsqldb-ds.xml jmx-invoker-service.xml
+http-invoker.sar security
+jboss-local-jdbc.rar transaction-jboss-beans.xml
+jboss-xa-jdbc.rar
+</programlisting>
+</para>
+<note>
+ <para>
+ The <emphasis role="bold">default</emphasis> configuration is the one used if you don’t specify another one when starting up the server.
+ </para>
+ <para>
+ To start the server using an alternate configuration refer to <xref linkend="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration"/>.
+ </para>
+</note>
+<section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-Server_Configuration_Directory_Structure">
+ <title>Server Configuration Directory Structure</title>
+ <para>
+ The directory server configuration you’re using, is effectively the server root while JBoss is running. It contains all the code and configuration information for the services provided by the particular server configuration. It’s where the log output goes, and it’s where you deploy your applications. <xref linkend="Server_Configuration_Directory_Structure-Server_Configuration_Directory_Structure"/> shows the directories inside the server configuration directory (<filename class="directory"><JBoss_Home>/server/<instance-name></filename>) and their functions.
+ </para>
+ <para>
+ <table id="Server_Configuration_Directory_Structure-Server_Configuration_Directory_Structure">
+ <title>Server Configuration Directory Structure</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ Directory
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <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.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <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.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <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.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">lib</filename>
+ </entry>
+ <entry>
+ This directory contains JAR files (Java libraries that should not be hot deployed) needed by this server configuration. You can add required library files here for JDBC drivers etc. All JARs in this directory are loaded into the shared classpath at startup. Note that this directory only contains those jars unique to the server configuration. Jars common across the server configurations are now located in <filename class="directory"><JBoss_Home>/common/lib</filename>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">log</filename>
+ </entry>
+ <entry>
+ This is where the log files are written. JBoss uses the Jakarta <literal>log4j</literal> package for logging and you can also use it directly in your own applications from within the server. This may be overridden through the <filename class="directory">conf/</filename><filename>jboss-log4j.xml</filename> configuration file.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">tmp</filename>
+ </entry>
+ <entry>
+ The <filename class="directory">tmp</filename> directory is used for temporary storage by JBoss services. The deployer, for example, expands application archives in this directory.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">work</filename>
+ </entry>
+ <entry>
+ This directory is used by Tomcat for compilation of JSPs.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+</section>
+<section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-The_default_Server_Configuration_File_Set">
+ <title>The "default" Server Configuration File Set</title>
+ <para>
+ The "<literal>default</literal>" server configuration file set is located in the <literal><JBoss_Home>/server/default</literal> directory. The following example illustrates a truncated directory structure of the <literal>jboss-as-<release></literal> server configuration files:
+<screen>[user at localhost <JBoss_Home>]$ tree
+|-- bin
+|-- client
+|-- common
+| |-- lib
+| | |-- antlr.jar
+| | |-- ... many more jars
+|-- docs
+| |-- dtd
+| |-- examples
+| | |-- binding-manager
+| | | `-- sample-bindings.xml
+| | |-- jca
+| | |-- jms
+| | |-- jmx
+| | |-- netboot
+| | | `-- netboot.war
+| | `-- varia
+| | |-- deployment-service
+| | |-- derby-plugin.jar
+| | |-- entity-resolver-manager
+| | | `-- xmlresolver-service.xml
+| | `-- jboss-bindings.xml
+| `-- schema
+|-- lib
+| |-- commons-codec.jar
+| |-- commons-httpclient.jar
+| |-- commons-logging.jar
+| |-- concurrent.jar
+| |-- endorsed
+| | |-- serializer.jar
+| | |-- xalan.jar
+| | `-- xercesImpl.jar
+| |-- getopt.jar
+| |-- jboss-common.jar
+| |-- jboss-jmx.jar
+| |-- jboss-system.jar
+| |-- jboss-xml-binding.jar
+| `-- log4j-boot.jar
+`-- server
+|-- all
+| |-- conf
+| | |-- bootstrap/
+| | | |-- aop.xml
+| | | |-- bindings.xml
+| | | |-- aop.xml
+| | | |-- classloader.xml
+| | | |-- deployers.xml
+| | | |-- jmx.xml
+| | | |-- profile-repository.xml
+| | | |-- profile.xml
+| | | |-- vfs.xml
+| | |-- bootstrap.xml
+| | |-- bootstrap-norepo.xml
+| | |-- jacorb.properties
+| | |-- java.policy
+| | |-- jax-ws-catalog.xml
+| | |-- jboss-log4j.xml
+| | |-- jboss-service.xml
+| | |-- jbossjta-properties.xml
+| | |-- jndi.properties
+| | |-- login-config.xml
+| | |-- props
+| | | |-- jbossws-roles.properties
+| | | |-- jbossws-users.properties
+| | | |-- jmx-console-roles.properties
+| | | `-- jmx-console-users.properties
+| | |-- standardjboss.xml
+| | |-- standardjbosscmp-jdbc.xml
+| | `-- xmdesc
+| |-- deploy
+| |-- deploy-hasingleton
+| | `-- jms
+| |-- deployers
+| `-- lib
+|-- default
+| |-- conf
+| | |-- bootstrap/
+| | | |-- aop.xml
+| | | |-- bindings.xml
+| | | |-- aop.xml
+| | | |-- classloader.xml
+| | | |-- deployers.xml
+| | | |-- jmx.xml
+| | | |-- profile-repository.xml
+| | | |-- profile.xml
+| | | |-- vfs.xml
+| | |-- bootstrap.xml
+| | |-- bootstrap-norepo.xml
+| | |-- jacorb.properties
+| | |-- java.policy
+| | |-- jax-ws-catalog.xml
+| | |-- jboss-log4j.xml
+| | |-- jboss-service.xml
+| | |-- jbossjta-properties.xml
+| | |-- jndi.properties
+| | |-- login-config.xml
+| | |-- props
+| | | |-- jbossws-roles.properties
+| | | |-- jbossws-users.properties
+| | | |-- jmx-console-roles.properties
+| | | `-- jmx-console-users.properties
+| | |-- standardjboss.xml
+| | |-- standardjbosscmp-jdbc.xml
+| | `-- xmdesc
+| | |-- AttributePersistenceService-xmbean.xml
+| | |-- ClientUserTransaction-xmbean.xml
+| | |-- JNDIView-xmbean.xml
+| | |-- Log4jService-xmbean.xml
+| | |-- NamingBean-xmbean.xml
+| | |-- NamingService-xmbean.xml
+| | |-- TransactionManagerService-xmbean.xml
+| | |-- org.jboss.deployment.JARDeployer-xmbean.xml
+| | |-- org.jboss.deployment.MainDeployer-xmbean.xml
+| | `-- org.jboss.deployment.SARDeployer-xmbean.xml
+| |-- data
+| | |-- hypersonic
+| | |-- jboss.identity
+| | |-- tx-object-store
+| | `-- xmbean-attrs
+| |-- deploy
+| |-- lib
+| |-- log
+| | |-- boot.log
+| | |-- server.log
+| | `-- server.log.2008-08-09
+| |-- tmp
+| `-- work
+| `-- jboss.web
+| `-- localhost
+`-- minimal
+|-- conf
+| |-- bootstrap/
+| |-- bootstrap/aop.xml
+| |-- bootstrap/classloader.xml
+| |-- bootstrap/deployers.xml
+| |-- bootstrap/jmx.xml
+| |-- bootstrap/profile.xml
+| |-- bootstrap.xml
+| |-- jboss-log4j.xml
+| |-- jboss-service.xml
+| |-- jndi.properties
+| `-- xmdesc
+| |-- NamingBean-xmbean.xml
+| `-- NamingService-xmbean.xml
+|-- deploy/
+|-- deploy/hdscanner-jboss-beans.xml
+|-- deployers/
+`-- lib
+|-- jboss-minimal.jar
+|-- jnpserver.jar
+`-- log4j.jar</screen>
+
+</para>
+ <section id="The_default_Server_Configuration_File_Set-Contents_of_conf_directory">
+ <title>Contents of "conf" directory</title>
+ <para>
+ The files in the <literal>conf</literal> directory are explained in the following table.
+ </para>
+ <para>
+ <table id="Contents_of_conf_directory-Contents_of_conf_directory">
+ <title>Contents of "conf" directory</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>bootstrap.xml</literal>
+ </entry>
+ <entry>
+ This is the <literal>bootstrap.xml</literal> file that defines which additional microcontainer deployments will be loaded as part of the bootstrap phase.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>bootstrap/*</literal>
+ </entry>
+ <entry>
+ This directory contains the microcontainer bootstrap descriptors that are referenced from the <literal>bootstrap.xml</literal> file.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>jboss-service.xml</literal> legacy core mbeans that have yet to be ported to either bootstrap deployments, or deploy services. This file will go away in the near future.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossjta-properties.xml</literal>
+ </entry>
+ <entry>
+ <literal>jbossjta-properties.xml</literal> specifies the JBossTS transaction manager default properties.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jndi.properties</literal>
+ </entry>
+ <entry>
+ The <literal>jndi.properties</literal> file specifies the JNDI <literal>InitialContext</literal> properties that are used within the JBoss server when an <literal>InitialContext</literal> is created using the no-arg constructor.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>java.policy</literal>
+ </entry>
+ <entry>
+ A placeholder java security policy file that simply grants all permissions.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-log4j.xml</literal>
+ </entry>
+ <entry>
+ This file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>login-config.xml</literal>
+ </entry>
+ <entry>
+ This file contains sample server side authentication configurations that are applicable when using JAAS based security.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>props/*</literal>
+ </entry>
+ <entry>
+ The <literal>props</literal> directory contains the users and roles property files for the <literal>jmx-console</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>standardjboss.xml</literal>
+ </entry>
+ <entry>
+ This file provides the default container configurations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>standardjbosscmp-jdbc.xml</literal>
+ </entry>
+ <entry>
+ This file provides a default configuration file for the JBoss CMP engine.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>xmdesc/*-mbean.xml</literal>
+ </entry>
+ <entry>
+ The <literal>xmdesc</literal> directory contains XMBean descriptors for several services configured in the <literal>jboss-service.xml</literal> file.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section id="The_default_Server_Configuration_File_Set-Contents_of_deployers_directory">
+ <title>Contents of "deployers" directory</title>
+ <para>
+ The files in the <literal>deployers</literal> directory are explained in the following table.
+ </para>
+ <para>
+ <table id="Contents_of_deploy_directory-Contents_of_deployers_directory">
+ <title>Contents of "deploy" directory</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>alias-deployers-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers that know how to handle The know how to handle <alias> in <deployment> as true controller context.
+ Meaning they will only get active/installed when their original is installed.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>bsh.deployer</literal>
+ </entry>
+ <entry>
+ This file configures the bean shell deployer, which deploys bean shell scripts as JBoss mbean services.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>clustering-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Clustering-related deployers which add dependencies on needed clustering services to clustered EJB3, EJB2 beans and to distributable web applications.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>dependency-deployers-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for aliases.txt, jboss-dependency.xml jboss-depedency.xml adds generic dependency on whatever. aliases.txt adds human-readable name for deployments, e.g. vfszip://home/blah/.../jboss-5.0.0.GA/server/default/deploy/some-long-name.ear aliased to ales-app.ear.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>directory-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Adds legacy behavior for directories, handling its children as possible deployments.
+ e.g. .sar's lib directory to treat its .jar files as deployments
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ear-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ JavaEE 5 enterprise application related deployers
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Legacy JavaEE 1.4 ejb jar related deployers
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3.deployer</literal>
+ </entry>
+ <entry>
+ This is a deployer that supports JavaEE 5 ejb3, JPA, and application client deployments, .
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for Hibernate -hibernate.xml descriptors, which are similar to Hibernate's .cfg.xml files.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-aop-jboss5.deployer</literal>
+ </entry>
+ <entry>
+ JBossAspectLibrary and base aspects. Why is this in deployers, dependencies?
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-jca.deployer</literal>
+ </entry>
+ <entry>
+ <literal>jboss-jca.deployer</literal> description
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossweb.deployer</literal>
+ </entry>
+ <entry>
+ The JavaEE 5 servlet, JSF, JSP deployers.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossws.deployer</literal>
+ </entry>
+ <entry>
+ The JavaEE 5 webservices endpoint deployers.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jsr77-deployers-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for creating the JSR77 MBeans from the JavaEE components.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>metadata-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for processing the JavaEE metadata from xml, annotations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>seam.deployer</literal>
+ </entry>
+ <entry>
+ Deployer providing integration support for JBoss Seam applications.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>security-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for configuration the security layers of the JavaEE components.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section id="The_default_Server_Configuration_File_Set-Contents_of_deploy_directory">
+ <title>Contents of "deploy" directory</title>
+ <para>
+ The files in the <literal>deploy</literal> directory are explained in the following table.
+ </para>
+ <para>
+ <table id="Contents_of_deploy_directory-Contents_of_deploy_directory">
+ <title>Contents of "deploy" directory</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>ROOT.war</literal>
+ </entry>
+ <entry>
+ <literal>ROOT.war</literal> establishes the '/' root
+ web application. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>cache-invalidation-service.xml</literal>
+ </entry>
+ <entry> This is a service that allows for custom
+ invalidation of the EJB caches via JMS
+ notifications. It is disabled by default. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb2-container-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb2-container-jboss-beans.xml</literal>
+ UserTransaction integration bean for the EJB2
+ containers. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb2-timer-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb2-timer-service.xml</literal> contains
+ the ejb timer service beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-connectors-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-connectors-jboss-beans.xml</literal>
+ EJB3 remoting transport beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-container-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-container-jboss-beans.xml</literal>
+ UserTransaction integration bean for the EJB3
+ containers. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-interceptors-aop.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-interceptors-aop.xml</literal> defines
+ the EJB3 container aspects. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-timer-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-timer-service.xml</literal> an
+ alternate quartz based timer service </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hdscanner-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>hdscanner-jboss-beans.xml</literal> the
+ deploy directory hot deployment scanning bean
+ </entry>
+ </row>
+ <row>
+ <entry>hsqldb-ds.xml</entry>
+ <entry>configures the Hypersonic embedded database
+ service configuration file. It sets up the embedded
+ database and related connection factories. </entry>
+ </row>
+ <row>
+ <entry>http-invoker.sar</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>jboss-local-jdbc.rar</entry>
+ <entry>is a JCA resource adaptor that implements the JCA
+ <literal>ManagedConnectionFactory</literal>
+ interface for JDBC drivers that support the
+ <literal>DataSource</literal> interface but not
+ JCA. </entry>
+ </row>
+ <row>
+ <entry>jboss-xa-jdbc.rar</entry>
+ <entry>JCA resource adaptors for XA DataSources</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossweb.sar</literal>
+ </entry>
+ <entry>an mbean service supporting TomcatDeployer with
+ web application deployment service
+ management.</entry>
+ </row>
+ <row>
+ <entry><literal>jbossws.sar</literal></entry>
+ <entry>provides JEE web services support. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jca-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>jca-jboss-beans.xml</literal> is the
+ application server implementation of the JCA
+ specification. It provides the connection management
+ facilities for integrating resource adaptors into
+ the JBoss server. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jms-ra.rar</literal>
+ </entry>
+ <entry>
+ <literal>jms-ra.rar</literal> JBoss JMS Resource
+ Adapter </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/connection-factories-service.xml</literal>
+ </entry>
+ <entry>configures the DLQ, ExpiryQueue JMS connection
+ factory</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/destinations-service.xml</literal>
+ </entry>
+ <entry>The message persistence store service</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/destinations-service.xml</literal>
+ </entry>
+ <entry>configures the DLQ, ExpiryQueue JMS destinations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/jms-ds.xml</literal>
+ </entry>
+ <entry>
+ <literal>jms-ds.xml</literal> configures the
+ JMSProviderLoader and JmsXA inflow resource adaptor
+ connection factory binding. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/legacy-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>legacy-service.xml</literal> configures the
+ JMSProviderLoader and JmsXA inflow resource adaptor
+ connection factory binding. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/messaging-jboss-beans.xml</literal>
+ </entry>
+ <entry> The <literal>messaging-jboss-beans.xml</literal>
+ file configures JMS security and management beans.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/messaging-service.xml</literal>
+ </entry>
+ <entry> The <literal>messaging-service.xml</literal>
+ file configures the core JBoss Messaging service.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/remoting-bisocket-service.xml</literal>
+ </entry>
+ <entry> The
+ <literal>remoting-bisocket-service.xml</literal>
+ configures the JMS remoting service layer. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jmx-console.war</literal>
+ </entry>
+ <entry> The <literal>jmx-console.war</literal> directory
+ provides the JMX Console. The JMX Console provides a
+ simple web interface for managing the MBean server.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jmx-invoker-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>jmx-invoker-service.xml</literal> is an
+ MBean service archive that exposes a subset of the
+ JMX <literal>MBeanServer</literal> interface methods
+ as an RMI interface to enable remote access to the
+ JMX core functionality. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jmx-remoting.sar</literal>
+ </entry>
+ <entry>
+ <literal>jmx-remoting.sar</literal> is a
+ javax.management.remote implementation providing
+ access to the JMX server. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>legacy-invokers-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>legacy-invokers-service.xml</literal> the
+ legacy detached jmx invoker remoting services.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jsr-88-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>jsr-88-service.xml</literal> provides the
+ JSR 88 remote deployment service. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>mail-ra.rar</literal>
+ </entry>
+ <entry>
+ <literal>mail-ra.rar</literal> is a resource adaptor
+ that provides a JavaMail connector. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>mail-service.xml</literal>
+ </entry>
+ <entry> The <literal>mail-service.xml</literal> file is
+ an MBean service descriptor that provides JavaMail
+ sessions for use inside the JBoss server. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>monitoring-service.xml</literal>
+ </entry>
+ <entry> The <literal>monitoring-service.xml</literal>
+ file configures alert monitors like the console
+ listener and email listener used by JMX
+ notifications. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>profileservice-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>profileservice-jboss-beans.xml</literal>
+ description </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>properties-service.xml</literal>
+ </entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>
+ <literal>quartz-ra.rar</literal>
+ </entry>
+ <entry>
+ <literal>quartz-ra.rar</literal> is a resource
+ adaptor for inflow of Quartz events </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>remoting-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>remoting-jboss-beans.xml</literal>
+ contains the unified invokers based on JBoss
+ Remoting. </entry>
+ </row>
+ <row>
+ <entry> The <literal>properties-service.xml</literal>
+ file is an MBean service descriptor that allows for
+ customization of the JavaBeans
+ <literal>PropertyEditor</literal>s as well as
+ the definition of system properties. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>scheduler-service.xml</literal>
+ </entry>
+ <entry> The <literal>scheduler-service.xml</literal> and
+ <literal>schedule-manager-service.xml</literal>
+ files are MBean service descriptors that provide a
+ scheduling type of service. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>security/security-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>security-jboss-beans.xml</literal> security
+ domain related beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>security/security-policies-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>security-policies-jboss-beans.xml</literal>
+ security authorization related beans for ejb and web
+ authorization. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>sqlexception-service.xml</literal>
+ </entry>
+ <entry> The <literal>sqlexception-service.xml</literal>
+ file is an MBean service descriptor for the handling
+ of vendor specific <literal>SQLException</literal>s.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>transaction-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>transaction-jboss-beans.xml</literal> JTA
+ transaction manager related beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>transaction-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>transaction-service.xml</literal>
+ ClientUserTransaction proxy service configuration.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>uuid-key-generator.sar</literal>
+ </entry>
+ <entry> The <literal>uuid-key-generator.sar</literal>
+ service provides a UUID-based key generation
+ facility. </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+</section>
+<section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-The_all_Server_Configuration_File_Set">
+ <title>The "all" Server Configuration File Set</title>
+ <para>
+ The "all" server configuration file set is located in the <filename class="directory"><JBoss_Home>/server/all</filename> directory. In addition to the services in the "default" set, the all configuration contains several other services in the <literal>conf/</literal> directory as shown below.
+ </para>
+ <para>
+ <table id="The_all_Server_Configuration_File_Set-Additional_Services_in_conf_directory_for_all_configuration">
+ <title>Additional Services in "conf" directory for "all" configuration</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>cluster-service.xml</literal>
+ </entry>
+ <entry>
+ This service configures clustering communication for most clustered services in JBoss.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>deploy-hasingleton-service.xml</literal>
+ </entry>
+ <entry>
+ This provides the HA singleton service, allowing JBoss to manage services that must be active on only one node of a cluster.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>httpha-invoker.sar</literal>
+ </entry>
+ <entry>
+ This service provides HTTP tunneling support for clustered environments.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>iiop-service.xml</literal>
+ </entry>
+ <entry>
+ This provides IIOP invocation support.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>juddi-service.sar</literal>
+ </entry>
+ <entry>
+ This service provides UDDI lookup services.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>snmp-adaptor.sar</literal>
+ </entry>
+ <entry>
+ This is a JMX to SNMP adaptor. It allows for the mapping of JMX notifications onto SNMP traps.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+</section>
+<section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-EJB3_Services_">
+ <title>EJB3 Services </title>
+ <para>
+ The following table explains the files providing ejb3 services.
+ </para>
+ <para>
+ <table id="EJB3_Services_-EJB3_Services">
+ <title>EJB3 Services</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>ejb3-interceptors-aop.xml</literal>
+ </entry>
+ <entry>
+ This service provides the AOP interceptor stack configurations for EJB3 bean types.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3.deployer</literal>
+ </entry>
+ <entry>
+ This service deploys EJB3 applications into JBoss.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-aop-jdk50.deployer</literal>
+ </entry>
+ <entry>
+ This is a Java 5 version of the AOP deployer. The AOP deployer configures the <literal>AspectManagerService</literal> and deploys JBoss AOP applications.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossws.sar</literal>
+ </entry>
+ <entry>
+ This provides Java EE 5 web services support.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ Finally, in the EJB3 "all" configuration there are two additional services.
+ </para>
+ <para>
+ <table id="EJB3_Services_-Additional_Services_in_EJB3_all_Configuration">
+ <title>Additional Services in EJB3 "all" Configuration</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>ejb3-clustered-sfsbcache-service.xml</literal>
+ </entry>
+ <entry>
+ This provides replication and failover for EJB3 stateful session beans.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-entity-cache-service.xml</literal>
+ </entry>
+ <entry>
+ This provides a clustered cache for EJB3 entity beans.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+</section>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Setting_JBOSS_HOME.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Setting_JBOSS_HOME.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Setting_JBOSS_HOME.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,6 +1,6 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="setting_JBOSS_HOME">
<title>Setting the JBOSS_HOME variable</title>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Start_Stop_Server.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Start_Stop_Server.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Start_Stop_Server.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,8 +1,5 @@
-<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
+<?xml version='1.0' encoding="UTF-8"?>
-
<section id="Starting_and_Stopping_the_Server">
<title>Starting and Stopping the Server</title>
<section id="Starting_and_Stopping_the_Server-Start_the_Server">
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Test_Your_Installation.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Test_Your_Installation.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Test_Your_Installation.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter id="Test_your_Installation">
+ <title>Test your Installation</title>
+ <para>
+ After you have installed the JBoss Application Server, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, open the <filename>JBOSS_DIST/jboss-<release>/bin</filename> directory and execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system.
+ </para>
+ <para>
+ Your output should look similar to the following (accounting for installation directory differences) and contain no error or exception messages:
+ </para>
+ <screen>
+ [samson at dhcp-1-150 bin]$ sh run.sh
+ =========================================================================
+
+ JBoss Bootstrap Environment
+
+ JBOSS_HOME: /home/svn/JBossHead/jboss-head/build/output/jboss-5.0.0.GA
+
+ JAVA: /Library/Java/Home/bin/java
+
+ JAVA_OPTS: -Dprogram.name=run.sh -Xms128m -Xmx512m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
+
+ CLASSPATH: /home/svn/JBossHead/jboss-head/build/output/jboss-5.0.0.GA/bin/run.jar
+
+ =========================================================================
+
+ 21:47:23,874 INFO [ServerImpl] Starting JBoss (Microcontainer)...
+ 21:47:23,875 INFO [ServerImpl] Release ID: JBoss [Morpheus] 5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812011226)
+ .
+ .
+ ...output truncated
+ .
+ .
+ 21:47:46,090 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
+ 21:47:46,112 INFO [ServerImpl] JBoss (Microcontainer) [5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812011226)] Started in 22s:227ms
+ </screen>
+ <!--<note>
+ <para>
+ Note that there is no "Server Started" message shown at the console when the server is started using the <literal>default</literal> profile, which is the default profile used when no other is specified. This message may be observed in the <filename>server.log</filename> file located in the <filename>server/defaut/log</filename> subdirectory.
+ </para>
+ </note>-->
+ <para>
+ Now open <literal>http://localhost:8080</literal> in your web browser. (Make sure you dont have anything else already on your machine using that port).<footnote><para>
+ Note that on some machines, the name localhost may not resolve properly and you may need to use the local loopback address 127.0.0.1 instead.</para></footnote> The contents of your page should look similar to the following: <xref linkend="Test_your_Installation-Test_your_Installation"/>.
+ </para>
+ <para>
+ <figure id="Test_your_Installation-Test_your_Installation">
+ <title>Test your Installation</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/test_install.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </para>
+ <para>
+ You are now ready to use the JBoss Application Server.
+ </para>
+</chapter>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/The_JBoss_Server_A_Quick_Tour.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,26 +1,49 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.docbook.org/xml/4.4/docbookx.dtd"
+[
+<!ENTITY versionNumber "5.0.0.GA">
+<!ENTITY copyrightYear "2008">
+<!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
+<!ELEMENT xi:include (xi:fallback?) >
+<!ATTLIST xi:include
+xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude"
+href CDATA #REQUIRED
+parse (xml|text) "xml"
+xpointer CDATA #IMPLIED
+encoding CDATA #IMPLIED
+accept CDATA #IMPLIED
+accept-charset CDATA #IMPLIED
+accept-language CDATA #IMPLIED >
+<!ELEMENT xi:fallback ANY >
+<!ATTLIST xi:fallback
+xmlns:xi CDATA #FIXED "http://www.w3.org/2001/XInclude" >
+<!ENTITY % local.preface.class "| xi:include" >
+<!ENTITY % local.part.class "| xi:include" >
+<!ENTITY % local.chapter.class "| xi:include" >
+<!ENTITY % local.divcomponent.mix "| xi:include" >
+<!ENTITY % local.para.char.mix "| xi:include" >
+<!ENTITY % local.info.class "| xi:include" >
+<!ENTITY % local.common.attrib "xml:base CDATA #IMPLIED
+xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'" >
]>
<chapter id="The_JBoss_Server___A_Quick_Tour">
<title>The JBoss Server - A Quick Tour</title>
-<section><title>Server Structure</title>
-
+<section id="Server_Structure">
+ <title>Server Structure</title>
<para>
Now that you’ve downloaded JBoss and have run the server for the first time, the next thing you will want to know is how the installation is laid out and what goes where. At first glance there seems to be a lot of stuff in there, and it’s not obvious what you need to look at and what you can safely ignore for the time being. To remedy that, we’ll explore the server directory structure, locations of the key configuration files, log files, deployment and so on. It’s worth familiarizing yourself with the layout at this stage as it will help you understand the JBoss service architecture so that you’ll be able to find your way around when it comes to deploying your own applications.
</para>
-
-
-<!-- Embedded sections -->
+</section>
+ <!-- Embedded sections -->
+
<xi:include href="Server_Configurations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Start_Stop_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<!-- end embedded sections -->
+ <!-- end embedded sections -->
-
-</section>
-
<section id="The_JBoss_Server___A_Quick_Tour-The_JMX_Console">
<title>The JMX Console</title>
<para>
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Uninstall_JBoss.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Uninstall_JBoss.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Uninstall_JBoss.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.docbook.org/xml/4.5/docbookx.dtd">
+<chapter id="Uninstall_JBoss">
+ <title>Uninstall JBoss</title>
+ <para>
+ The JBoss Application Server may be uninstalled by simply deleting the JBoss Application Server's installation directory. You will also need to remove the <emphasis>JBOSS_HOME</emphasis> environment variables discussed in <xref linkend="setting_JBOSS_HOME"/> for your Linux or Windows platform.
+ </para>
+</chapter>
Modified: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Other_Databases.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Other_Databases.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Other_Databases.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,5 +1,5 @@
<?xml version='1.0'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
]>
<chapter id="Using_other_Databases">
Added: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Seam.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Seam.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/Using_Seam.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,395 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<chapter id="Using_Seam">
+ <title>Using Seam</title>
+ <para>
+ JBoss Seam is a framework that provides the glue between the new EJB3 and JSF frameworks that are part of the Java EE 5.0 standard. In fact, the name Seam refers to the seamless manner in which it enables developers to use these two frameworks in an integrated manner. Seam automates many of the common tasks, and makes extensive use of annotations to reduce the amount of xml code that needs to be written. The overall effect is to significantly reduce the total amount of coding that needs to be done.
+ </para>
+
+ <para>
+ If you are new to Seam, you can find more introductory information from the following url and book:
+<itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://docs.jboss.com/seam/2.0.0.GA/reference/en/html_single/">The Seam Reference Guide</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Beginning JBoss Seam</emphasis> by Joseph Faisal Nusairat, Apress 2007.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ <para>
+ We have included two versions of the example application, one coded using EJB3 / JSF without using Seam, and one using Seam, to demonstrate clearly the difference in application development using the Seam framework.
+ </para>
+
+
+
+ <section id="Using_Seam_Data_Model">
+ <title>
+ Data Model
+ </title>
+
+ <para>
+ Let's start off our examination of the Seam implementation in the same way, by examining how the Data Model is implemented. This is done in the <literal>Todo.java</literal> file.
+ </para>
+
+ <programlisting>@Entity
+ at Name("todo")
+public class Todo implements Serializable {
+
+ private long id;
+ private String title;
+ private String description;
+
+ public Todo () {
+ title ="";
+ description ="";
+ }
+
+ @Id @GeneratedValue
+ public long getId() { return id;}
+ public void setId(long id) { this.id = id; }
+
+ @NotNull
+ public String getTitle() { return title; }
+ public void setTitle(String title) {this.title = title;}
+
+ @NotNull
+ @Length(max=250)
+ public String getDescription() { return description; }
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+}</programlisting>
+
+ <para>
+ The <literal>@Entity</literal> annotation defines the class as an EJB3 entity bean, and tells the container to map the <literal>Todo</literal> class to a relational database table. Each property of the class will become a column in the table. Each instance of the class will become a row in this table. Since we have not used the <literal>@Table</literal> annotation, Seam's "configuration by exception" default will name the table after the class.
+ </para>
+
+ <para>
+ <literal>@Entity</literal> and <literal>@Table</literal> are both EJB3 annotations, and are not specific to Seam. It is possible to use Seam completely with POJOs (Plain Old Java Objects) without any EJB3-specific annotations. However, EJB3 brings a lot of advantages to the table, including container managed security, message-driven components, transaction and component level persistence context, and <literal>@PersistenceContext</literal> injection, which we will encounter a little further on.
+ </para>
+
+ <para>
+ The <literal>@Name</literal> annotation is specific to Seam, and defines the string name for Seam to use to register the Entity Bean. This will be the default name for the relational database table. Each component in a Seam application must have a unique name. In the other components in the Seam framework, such as JSF web pages and session beans, you can reference the managed <literal>Todo</literal> bean using this name. If no instance of this class exists when it is referenced from another component, then Seam will instantiate one.
+ </para>
+
+ <para>
+ The <literal>@Id</literal> annotation defines a primary key <literal>id</literal> field for the component. <literal>@GeneratedValue</literal> specifies that the server will automatically generate this value for the component when it is saved to the database.
+ </para>
+
+ <para>
+ Seam provides support for model-based constraints defined using Hibernate Validator, although Hibernate does not have to be the object persister used. The <literal>@NotNull</literal> annotation is a validation constraint that requires this property to have a value before the component can be persisted into the database. Using this annotation allows the validation to be enforced by the JSF code at the view level, without having to specify the exact validation constraint in the JSF code.
+ </para>
+
+ <para>
+ At this point the only apparent difference between the Seam version and the EJB3/JSF version of the app is the inclusion of the validator annotation <literal>@NotNull</literal>, and the <literal>@Name</literal> annotation. However, while the EJB3/JSF version of this application requires a further <literal>TodoBean</literal> class to be manually coded and managed in order to handle the interaction between the <literal>Todo</literal> class and the web interface, when using Seam the Seam framework takes care of this work for us. We'll see how this is done in practice as we examine the implementation of the user interface.
+ </para>
+ </section>
+
+ <section id="Using_Seam_JSF_Web_Pages">
+ <title>
+ JSF Web Pages - index.xhtml and create.xhtml
+ </title>
+
+ <para>
+ The <emphasis role="bold">index.xhtml</emphasis> file used is the same as in the EJB3/JSF example.
+ </para>
+
+ <para>
+ <emphasis role="bold">create.xhtml</emphasis> begins to reveal the difference that coding using the Seam framework makes.
+ </para>
+
+ <programlisting><h:form id="create">
+
+<f:facet name="beforeInvalidField">
+ <h:graphicImage styleClass="errorImg" value="error.png"/>
+</f:facet>
+<f:facet name="afterInvalidField">
+ <s:message styleClass="errorMsg" />
+</f:facet>
+<f:facet name="aroundInvalidField">
+ <s:div styleClass="error"/>
+</f:facet>
+
+<s:validateAll>
+
+<table>
+
+ <tr>
+ <td>Title:</td>
+ <td>
+ <s:decorate>
+ <h:inputText id="title" value="#{todo.title}" size="15"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Description:</td>
+ <td>
+ <s:decorate>
+ <h:inputTextarea id="description" value="#{todo.description}"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+</table>
+
+</s:validateAll>
+
+<h:commandButton type="submit" id="create" value="Create"
+ action="#{todoDao.persist}"/>
+</h:form>
+ </programlisting>
+
+ <para>
+ The first thing that is different here is the Java Server Facelet code at the beginning, which works with the <literal>@NotNull</literal> validation constraint of our <literal>todo</literal> class to enforce and indicate invalid input to the user.
+ </para>
+
+ <para>
+ Also notice here that rather than requiring the use of a <literal>TodoBean</literal> class as we did in the EJB3/JSF example we back the form directly with a <literal>Todo</literal> entity bean. When this page is called, JSF asks Seam to resolve the variable <literal>todo</literal> due to JSF EL references such as <literal>#{todo.title}</literal>. Since there is no value already bound to that variable name, Seam will instantiate an entity bean of the <literal>todo</literal> class and return it to JSF, after storing it in the Seam context. The Seam context replaces the need for an intermediary bean.
+ </para>
+
+ <para>
+ The form input values are validated against the Hibernate Validator constraints specified in the <literal>todo</literal> class. JSF will redisplay the page if the constraints are violated, or it will bind the form input values to the <literal>Todo</literal> entity bean.
+ </para>
+
+ <para>
+ Entity beans shouldn't do database access or transaction management, so we can't use the <literal>Todo</literal> entity bean as a JSF action listener. Instead, creation of a new todo item in the database is accomplished by calling the <literal>persist</literal> method of a <literal>TodoDao</literal> session bean. When JSF requests Seam to resolve the variable <literal>todoDao</literal> through the JSF EL expression <literal>#{todoDao.persist}</literal>, Seam will either instantiate an object if one does not already exist, or else pass the existing stateful <literal>todoDao</literal> object from the Seam context. Seam will intercept the <literal>persist</literal> method call and inject the <literal>todo</literal> entity from the session context.
+ </para>
+
+ <para>
+ Let's have a look at the <literal>TodoDao</literal> class (defined in <literal>TodoDao.java</literal>) to see how this injection capability is implemented.
+ </para>
+ </section>
+
+ <section id="Using_Seam_Session_Bean">
+ <title>
+ Data Access using a Session Bean
+ </title>
+
+ <para>
+ Let's go through a listing of the code for the <literal>TodoDao</literal> class.
+ </para>
+
+ <programlisting>@Stateful
+ at Name("todoDao")
+public class TodoDao implements TodoDaoInt {
+
+ @In (required=false) @Out (required=false)
+ private Todo todo;
+
+ @PersistenceContext (type=EXTENDED)
+ private EntityManager em;
+
+ // Injected from pages.xml
+ Long id;
+
+ public String persist () {
+ em.persist (todo);
+ return "persisted";
+ }
+
+ @DataModel
+ private List <Todo> todos;
+
+ @Factory("todos")
+ public void findTodos () {
+ todos = em.createQuery("select t from Todo t")
+ .getResultList();
+ }
+
+ public void setId (Long id) {
+ this.id = id;
+
+ if (id != null) {
+ todo = (Todo) em.find(Todo.class, id);
+ } else {
+ todo = new Todo ();
+ }
+ }
+
+ public Long getId () {
+ return id;
+ }
+
+ public String delete () {
+ em.remove( todo );
+ return "removed";
+ }
+
+ public String update () {
+ return "updated";
+ }
+
+ @Remove @Destroy
+ public void destroy() {}
+
+}</programlisting>
+
+ <para>
+ First of all notice that this is a stateful session bean. Seam can use both stateful and stateless session beans, the two most common types of EJB3 beans.
+ </para>
+
+ <para>
+ The <literal>@In</literal> and <literal>@Out</literal> annotations define an attribute that is injected by Seam. The attribute is injected to this object or from this object to another via a Seam context variable named <literal>todo</literal>, a reference to the Seam registered name of our <literal>Todo</literal> class defined in <literal>Todo.java</literal>.
+ </para>
+
+ <para>
+ The <literal>@PersistenceContext</literal> annotation injects the EJB3 Entity manager, allowing this object to persist objects to the database. Because this is a stateful session bean and the <literal>PersistenceContext</literal> type is set to <literal>EXTENDED</literal>, the same Entity Manager instance is used until the Remove method of the session bean is called. The database to be used (a <literal>persistence-unit</literal>) is defined in the file <filename>resources/META-INF/persistence.xml</filename>
+ </para>
+
+ <para>
+ Note that this session bean has simultaneous access to context associated with web request (the form values of the <literal>todo</literal> object), and state held in transactional resources (the <literal>EntityManager</literal>). This is a break from traditional J2EE architectures, but Seam does not force you to work this way. You can use more traditional forms of application layering if you wish.
+ </para>
+
+ <para>
+ The <literal>@DataModel</literal> annotation initializes the <literal>todos</literal> property, which will be outjected or "exposed" to the view. The <literal>@Factory</literal> annotated method performs the work of generating the <literal>todos</literal> list, and is called by Seam if it attempts to access the exposed <literal>DataModel</literal> property and finds it to be null. Notice the absence of property access methods for the <literal>todos</literal> property. Seam takes care of this for you automatically.
+ </para>
+
+ <para>
+ Let's take a look at the JSF code that we use for displaying and editing the list of todos, to get an idea of how to use these interfaces in practice.
+ </para>
+
+ </section>
+
+ <section id="Using_Seam_Display_and_Edit">
+ <title>
+ JSF Web Pages - todos.xhtml and edit.xhtml
+ </title>
+
+ <para>
+ Using the <literal>DataModel</literal> exposed property of the Session Bean it becomes trivial to produce a list of todos:
+ </para>
+
+ <programlisting><h:form>
+
+<h:dataTable value="#{todos}" var="todo">
+ <h:column>
+ <f:facet name="header">Title</f:facet>
+ #{todo.title}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ #{todo.description}
+ </h:column>
+ <h:column>
+ <a href="edit.seam?tid=#{todo.id}">Edit</a>
+ </h:column>
+</h:dataTable>
+
+<center>
+ <h:commandButton action="create"
+ value="Create New Todo" type="submit"/>
+</center>
+
+</h:form>
+</programlisting>
+
+ <para>
+ When the JSF variable resolver encounters <literal>{#todos}</literal> and requests <literal>todos</literal>, Seam finds that there is no "todos" component in the current scope, so it calls the @Factory("todos") method to make one. The todos object is then outjected once the factory method is done since it is annotated with the @DataModel annotation. <!--Seam responses by finding the <literal>todos</literal> <literal>DataModel</literal> registered with it, and outjecting that from the bean.-->
+ </para>
+
+ <para>
+ Constructing the view for the edit page is similarly straight forward:
+ </para>
+
+ <programlisting><h:form id="edit">
+
+<f:facet name="beforeInvalidField">
+ <h:graphicImage styleClass="errorImg" value="error.png"/>
+</f:facet>
+<f:facet name="afterInvalidField">
+ <s:message styleClass="errorMsg" />
+</f:facet>
+<f:facet name="aroundInvalidField">
+ <s:div styleClass="error"/>
+</f:facet>
+
+<s:validateAll>
+
+<table>
+
+ <tr>
+ <td>Title:</td>
+ <td>
+ <s:decorate>
+ <h:inputText id="title" value="#{todo.title}" size="15"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Description:</td>
+ <td>
+ <s:decorate>
+ <h:inputTextarea id="description" value="#{todo.description}"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+</table>
+
+</s:validateAll>
+
+<h:commandButton type="submit" id="update" value="Update"
+ action="#{todoDao.update}"/>
+
+<h:commandButton type="submit" id="delete" value="Delete"
+ action="#{todoDao.delete}"/>
+</h:form>
+ </programlisting>
+
+ <para>
+ Here we see the same factors in play. JSF validation code taking advantage of the validation constraints defined in our Entity Bean, and the use of the <literal>todoDao</literal> Session Bean's <literal>update</literal> and <literal>delete</literal> methods to update the database.
+ </para>
+
+ <para>
+ The call from <filename>todos.xhtml</filename>: <literal>edit.seam?tid=#{todo.id}</literal> causes Seam to create a <literal>todoDao</literal> and set it's <literal>id</literal> property to <literal>tid</literal>. Setting its <literal>id</literal> property causes the <literal>todoDao</literal> to retrieve the appropriate record from the database.
+ </para>
+
+ <para>
+ The functionality that allows the edit page to be called with a parameter in this way is implemented through <literal>pages.xml</literal>. Let's have a look at the <literal>pages.xml</literal> file and how it is used by Seam applications.
+ </para>
+ </section>
+
+ <section id="Using_Seam_XML_Files">
+ <title>
+ Xml Files
+ </title>
+
+ <para>
+ Seam drastically reduces the amount of xml coding that needs to be done. One file that is of interest is the <literal>pages.xml</literal>, packaged in the <literal>app.war</literal> file's <literal>WEB-INF</literal> directory. This file is available in the <literal>resources/WEB-INF</literal> directory in the source code bundle. The <literal>pages.xml</literal> file is used to define page descriptions including Seam page parameters (HTTP <literal>GET</literal> parameters), page actions, page navigation rules, error pages etc. <!--This file defines a number of attributes that affect global behaviour of the application.--> Among other things it can be used in a Seam application to define exception handlers and redirections.
+ </para>
+ <para>
+ In the case of our sample application we are using it to define a Seam page parameter. The <literal>pages.xml</literal> in this example contains the following code:
+ </para>
+
+ <programlisting><page view-id="/edit.xhtml">
+ <param name="tid" value="#{todoDao.id}"
+ converterId="javax.faces.Long"/>
+</page></programlisting>
+ <para>
+ This defines a parameter named <literal>tid</literal> for the <literal>edit.xhtml</literal> page. When the <literal>edit.xhtml</literal> page is loaded, the HTTP <literal>GET</literal> request parameter <literal>tid</literal> is converted to a <literal>Long</literal> value and assigned to the <literal>id</literal> property of the <literal>todoDao</literal> object. You can have as many page parameters as required to bind HTTP <literal>GET</literal> request parameters to the back-end components in your application.
+ </para>
+ </section>
+
+ <section id="Further_Information">
+ <title>
+ Further Information
+ </title>
+
+ <para>
+ This completes our walkthrough of the sample Seam application. For further, detailed information on developing applications using the Seam framework, please refer to the <ulink url="http://docs.jboss.com/seam/2.0.0.GA/reference/en/html_single/">The Seam Reference Guide</ulink>.
+ </para>
+ </section>
+</chapter>
Copied: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/not-used-resolved.xml (from rev 82116, projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/resolved.xml)
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/not-used-resolved.xml (rev 0)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/not-used-resolved.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -0,0 +1,4631 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<!ENTITY uArr "⇑">
+<!ENTITY hcirc "ĥ">
+<!ENTITY icirc "î">
+<!ENTITY equals "=">
+<!ENTITY cong "≅">
+<!ENTITY HARDcy "Ъ">
+<!ENTITY icy "и">
+<!ENTITY Ecaron "Ě">
+<!ENTITY clubs "♣">
+<!ENTITY phmmat "ℳ">
+<!ENTITY sqcap "⊓">
+<!ENTITY thorn "þ">
+<!ENTITY Lcedil "Ļ">
+<!ENTITY rarr "→">
+<!ENTITY verbar "|">
+<!ENTITY cire "≗">
+<!ENTITY DZcy "Џ">
+<!ENTITY b.delta "𝛅">
+<!ENTITY Gcirc "Ĝ">
+<!ENTITY ocir "⊚">
+<!ENTITY circ "ˆ">
+<!ENTITY Igr "Ι">
+<!ENTITY udigr "ϋ">
+<!ENTITY prime "′">
+<!ENTITY npr "⊀">
+<!ENTITY b.pi "𝛑">
+<!ENTITY frac58 "⅝">
+<!ENTITY ldquor "„">
+<!ENTITY sqsup "⊐">
+<!ENTITY boxDR "╔">
+<!ENTITY kcedil "ķ">
+<!ENTITY vDash "⊨">
+<!ENTITY Scedil "Ş">
+<!ENTITY perp "⊥">
+<!ENTITY b.Gamma "𝚪">
+<!ENTITY b.kappa "𝛋">
+<!ENTITY Uuml "Ü">
+<!ENTITY mnplus "∓">
+<!ENTITY nearr "↗">
+<!ENTITY nrtri "⋫">
+<!ENTITY cupre "≼">
+<!ENTITY boxV "║">
+<!ENTITY Zdot "Ż">
+<!ENTITY pound "£">
+<!ENTITY lharu "↼">
+<!ENTITY boxdr "┌">
+<!ENTITY ocy "о">
+<!ENTITY xgr "ξ">
+<!ENTITY b.xi "𝛏">
+<!ENTITY larr "←">
+<!ENTITY middot "·">
+<!ENTITY xrArr "⟹">
+<!ENTITY Ncy "Н">
+<!ENTITY acute "´">
+<!ENTITY phis "ϕ">
+<!ENTITY ncedil "ņ">
+<!ENTITY lAarr "⇚">
+<!ENTITY sqsube "⊑">
+<!ENTITY quot '"'>
+<!ENTITY TSHcy "Ћ">
+<!ENTITY b.Gammad "Ϝ">
+<!ENTITY amacr "ā">
+<!ENTITY otimes "⊗">
+<!ENTITY inodot "ı">
+<!ENTITY gsdot "⋗">
+<!ENTITY LJcy "Љ">
+<!ENTITY phiv "φ">
+<!ENTITY odblac "ő">
+<!ENTITY filig "fi">
+<!ENTITY amalg "⨿">
+<!ENTITY sdotb "⊡">
+<!ENTITY boxDL "╗">
+<!ENTITY Theta "Θ">
+<!ENTITY cdot "ċ">
+<!ENTITY ordm "º">
+<!ENTITY atilde "ã">
+<!ENTITY squf "▪">
+<!ENTITY notin "∉">
+<!ENTITY nmid "∤">
+<!ENTITY shchcy "щ">
+<!ENTITY lfloor "⌊">
+<!ENTITY Xi "Ξ">
+<!ENTITY Hstrok "Ħ">
+<!ENTITY period ".">
+<!ENTITY nldr "‥">
+<!ENTITY numsp " ">
+<!ENTITY boxdl "┐">
+<!ENTITY Fcy "Ф">
+<!ENTITY tscy "ц">
+<!ENTITY Iukcy "І">
+<!ENTITY cross "✗">
+<!ENTITY ohgr "ω">
+<!ENTITY nbsp " ">
+<!ENTITY ni "∋">
+<!ENTITY comp "∁">
+<!ENTITY boxH "═">
+<!ENTITY b.Delta "𝚫">
+<!ENTITY Oslash "Ø">
+<!ENTITY marker "▮">
+<!ENTITY ndash "–">
+<!ENTITY ordf "ª">
+<!ENTITY nsce "⪰̸">
+<!ENTITY vrtri "⊳">
+<!ENTITY ubrcy "ў">
+<!ENTITY Ccirc "Ĉ">
+<!ENTITY quest "?">
+<!ENTITY ne "≠">
+<!ENTITY gap "⪆">
+<!ENTITY efDot "≒">
+<!ENTITY rcy "р">
+<!ENTITY bsim "∽">
+<!ENTITY bgr "β">
+<!ENTITY omacr "ō">
+<!ENTITY umacr "ū">
+<!ENTITY lpar "(">
+<!ENTITY uharl "↿">
+<!ENTITY Gcy "Г">
+<!ENTITY ast "*">
+<!ENTITY acy "а">
+<!ENTITY thetas "θ">
+<!ENTITY uring "ů">
+<!ENTITY Zcaron "Ž">
+<!ENTITY horbar "―">
+<!ENTITY star "☆">
+<!ENTITY timesb "⊠">
+<!ENTITY npre "⪯̸">
+<!ENTITY real "ℜ">
+<!ENTITY dlarr "↙">
+<!ENTITY nrArr "⇏">
+<!ENTITY oplus "⊕">
+<!ENTITY Xgr "Ξ">
+<!ENTITY ucy "у">
+<!ENTITY thetav "ϑ">
+<!ENTITY jcirc "ĵ">
+<!ENTITY uharr "↾">
+<!ENTITY mgr "μ">
+<!ENTITY hearts "♥">
+<!ENTITY nvDash "⊭">
+<!ENTITY yicy "ї">
+<!ENTITY dot "˙">
+<!ENTITY alpha "α">
+<!ENTITY wedgeq "≙">
+<!ENTITY bowtie "⋈">
+<!ENTITY boxDr "╓">
+<!ENTITY b.upsi "𝛖">
+<!ENTITY euml "ë">
+<!ENTITY vArr "⇕">
+<!ENTITY lgr "λ">
+<!ENTITY b.rhov "𝛠">
+<!ENTITY ubreve "ŭ">
+<!ENTITY copysr "℗">
+<!ENTITY cap "∩">
+<!ENTITY aogon "ą">
+<!ENTITY racute "ŕ">
+<!ENTITY rthree "⋌">
+<!ENTITY Sgr "Σ">
+<!ENTITY uacute "ú">
+<!ENTITY Tcaron "Ť">
+<!ENTITY dagger "†">
+<!ENTITY oast "⊛">
+<!ENTITY prnE "⪵">
+<!ENTITY thkap "≈">
+<!ENTITY boxdR "╒">
+<!ENTITY dgr "δ">
+<!ENTITY nacute "ń">
+<!ENTITY hardcy "ъ">
+<!ENTITY sqsupe "⊒">
+<!ENTITY TScy "Ц">
+<!ENTITY reg "®">
+<!ENTITY cir "○">
+<!ENTITY lsquor "‚">
+<!ENTITY ycy "ы">
+<!ENTITY Sigma "Σ">
+<!ENTITY Gbreve "Ğ">
+<!ENTITY order "ℴ">
+<!ENTITY nlarr "↚">
+<!ENTITY eng "ŋ">
+<!ENTITY sacute "ś">
+<!ENTITY ensp " ">
+<!ENTITY rarr2 "⇉">
+<!ENTITY coprod "∐">
+<!ENTITY iacgr "ί">
+<!ENTITY b.piv "𝛡">
+<!ENTITY rlhar2 "⇌">
+<!ENTITY boxDl "╖">
+<!ENTITY Pcy "П">
+<!ENTITY Dagger "‡">
+<!ENTITY khcy "х">
+<!ENTITY sigma "σ">
+<!ENTITY nltrie "⋬">
+<!ENTITY gjcy "ѓ">
+<!ENTITY b.alpha "𝛂">
+<!ENTITY plusmn "±">
+<!ENTITY scnap "⪺">
+<!ENTITY vprime "′">
+<!ENTITY iota "ι">
+<!ENTITY Dcaron "Ď">
+<!ENTITY emsp " ">
+<!ENTITY trie "≜">
+<!ENTITY boxdL "╕">
+<!ENTITY cacute "ć">
+<!ENTITY rcedil "ŗ">
+<!ENTITY lhblk "▄">
+<!ENTITY lnsim "⋦">
+<!ENTITY bsime "⋍">
+<!ENTITY Vvdash "⊪">
+<!ENTITY zgr "ζ">
+<!ENTITY Ncaron "Ň">
+<!ENTITY rcaron "ř">
+<!ENTITY radic "√">
+<!ENTITY colone "≔">
+<!ENTITY Ucy "У">
+<!ENTITY lcub "{">
+<!ENTITY mdash "—">
+<!ENTITY ogon "˛">
+<!ENTITY Lgr "Λ">
+<!ENTITY b.chi "𝛘">
+<!ENTITY Barwed "⌆">
+<!ENTITY odot "⊙">
+<!ENTITY softcy "ь">
+<!ENTITY yucy "ю">
+<!ENTITY Ogr "Ο">
+<!ENTITY ecirc "ê">
+<!ENTITY Uacute "Ú">
+<!ENTITY jcy "й">
+<!ENTITY Oacgr "Ό">
+<!ENTITY ntilde "ñ">
+<!ENTITY Uring "Ů">
+<!ENTITY Udigr "Ϋ">
+<!ENTITY squ "□">
+<!ENTITY Uacgr "Ύ">
+<!ENTITY uarr "↑">
+<!ENTITY sim "∼">
+<!ENTITY egr "ε">
+<!ENTITY aleph "ℵ">
+<!ENTITY nharr "↮">
+<!ENTITY kcy "к">
+<!ENTITY Rgr "Ρ">
+<!ENTITY ffilig "ffi">
+<!ENTITY boxvl "┤">
+<!ENTITY Iacgr "Ί">
+<!ENTITY ang90 "∟">
+<!ENTITY nrarr "↛">
+<!ENTITY nges "⩾̸">
+<!ENTITY nsube "⊈">
+<!ENTITY nsup "⊅">
+<!ENTITY egs "⪖">
+<!ENTITY acirc "â">
+<!ENTITY Yuml "Ÿ">
+<!ENTITY ltrif "◂">
+<!ENTITY lagran "ℒ">
+<!ENTITY npar "∦">
+<!ENTITY scsim "≿">
+<!ENTITY boxvr "├">
+<!ENTITY Acirc "Â">
+<!ENTITY Ucirc "Û">
+<!ENTITY zcaron "ž">
+<!ENTITY shy "">
+<!ENTITY ominus "⊖">
+<!ENTITY frac38 "⅜">
+<!ENTITY incare "℅">
+<!ENTITY uhblk "▀">
+<!ENTITY lEg "⪋">
+<!ENTITY gcy "г">
+<!ENTITY b.eta "𝛈">
+<!ENTITY lnap "⪉">
+<!ENTITY Iacute "Í">
+<!ENTITY yacute "ý">
+<!ENTITY dstrok "đ">
+<!ENTITY Imacr "Ī">
+<!ENTITY orarr "↻">
+<!ENTITY Eacgr "Έ">
+<!ENTITY apos "'">
+<!ENTITY b.epsiv "𝛜">
+<!ENTITY gcirc "ĝ">
+<!ENTITY udblac "ű">
+<!ENTITY planck "ℏ">
+<!ENTITY upsi "υ">
+<!ENTITY b.Lambda "𝚲">
+<!ENTITY Bgr "Β">
+<!ENTITY scedil "ş">
+<!ENTITY Rarr "↠">
+<!ENTITY nrtrie "⋭">
+<!ENTITY nsub "⊄">
+<!ENTITY vcy "в">
+<!ENTITY Eacute "É">
+<!ENTITY boxvh "┼">
+<!ENTITY dcy "д">
+<!ENTITY Aring "Å">
+<!ENTITY Igrave "Ì">
+<!ENTITY utilde "ũ">
+<!ENTITY divonx "⋇">
+<!ENTITY lne "⪇">
+<!ENTITY scnE "⪶">
+<!ENTITY ccedil "ç">
+<!ENTITY supne "⊋">
+<!ENTITY empty "∅">
+<!ENTITY b.nu "𝛎">
+<!ENTITY top "⊤">
+<!ENTITY lcy "л">
+<!ENTITY b.gamma "𝛄">
+<!ENTITY aelig "æ">
+<!ENTITY iuml "ï">
+<!ENTITY Lcaron "Ľ">
+<!ENTITY bottom "⊥">
+<!ENTITY rarrhk "↪">
+<!ENTITY DScy "Ѕ">
+<!ENTITY idiagr "ΐ">
+<!ENTITY imacr "ī">
+<!ENTITY ltri "◃">
+<!ENTITY infin "∞">
+<!ENTITY le "≤">
+<!ENTITY sime "≃">
+<!ENTITY kappa "κ">
+<!ENTITY kappav "ϰ">
+<!ENTITY OElig "Œ">
+<!ENTITY urcrop "⌎">
+<!ENTITY darr2 "⇊">
+<!ENTITY lg "≶">
+<!ENTITY spar "∥">
+<!ENTITY Mgr "Μ">
+<!ENTITY rtri "▹">
+<!ENTITY daleth "ℸ">
+<!ENTITY sfrown "⌢">
+<!ENTITY epsiv "ε">
+<!ENTITY Omega "Ω">
+<!ENTITY colon ":">
+<!ENTITY prop "∝">
+<!ENTITY lArr "⇐">
+<!ENTITY Upsi "ϒ">
+<!ENTITY oslash "ø">
+<!ENTITY ap "≈">
+<!ENTITY Sup "⋑">
+<!ENTITY epsis "ϵ">
+<!ENTITY b.omega "𝛚">
+<!ENTITY rpar ")">
+<!ENTITY Abreve "Ă">
+<!ENTITY mldr "…">
+<!ENTITY ltrie "⊴">
+<!ENTITY Psi "Ψ">
+<!ENTITY Agrave "À">
+<!ENTITY Tcedil "Ţ">
+<!ENTITY auml "ä">
+<!ENTITY lcedil "ļ">
+<!ENTITY scirc "ŝ">
+<!ENTITY larrhk "↩">
+<!ENTITY varr "↕">
+<!ENTITY ncong "≇">
+<!ENTITY jnodot "j">
+<!ENTITY subE "⫅">
+<!ENTITY kjcy "ќ">
+<!ENTITY larr2 "⇇">
+<!ENTITY rsh "↱">
+<!ENTITY sdot "⋅">
+<!ENTITY wreath "≀">
+<!ENTITY cuepr "⋞">
+<!ENTITY frown "⌢">
+<!ENTITY Agr "Α">
+<!ENTITY uacgr "ύ">
+<!ENTITY rcub "}">
+<!ENTITY dharl "⇃">
+<!ENTITY bcy "б">
+<!ENTITY Tgr "Τ">
+<!ENTITY diam "⋄">
+<!ENTITY eacute "é">
+<!ENTITY xlArr "⟸">
+<!ENTITY leg "⋚">
+<!ENTITY boxvL "╡">
+<!ENTITY Kcy "К">
+<!ENTITY ncy "н">
+<!ENTITY sgr "σ">
+<!ENTITY beta "β">
+<!ENTITY exist "∃">
+<!ENTITY bprime "‵">
+<!ENTITY boxul "┘">
+<!ENTITY Zcy "З">
+<!ENTITY Iuml "Ï">
+<!ENTITY Scaron "Š">
+<!ENTITY sol "/">
+<!ENTITY boxvR "╞">
+<!ENTITY fcy "ф">
+<!ENTITY Egrave "È">
+<!ENTITY Utilde "Ũ">
+<!ENTITY lthree "⋋">
+<!ENTITY boxur "└">
+<!ENTITY dharr "⇂">
+<!ENTITY uarr2 "⇈">
+<!ENTITY lacute "ĺ">
+<!ENTITY spades "♠">
+<!ENTITY int "∫">
+<!ENTITY rect "▭">
+<!ENTITY compfn "∘">
+<!ENTITY b.sigma "𝛔">
+<!ENTITY Amacr "Ā">
+<!ENTITY prod "∏">
+<!ENTITY rpargt "⦔">
+<!ENTITY b.sigmav "𝛓">
+<!ENTITY excl "!">
+<!ENTITY fnof "ƒ">
+<!ENTITY beth "ℶ">
+<!ENTITY yuml "ÿ">
+<!ENTITY rsquo "’">
+<!ENTITY pr "≺">
+<!ENTITY ccaron "č">
+<!ENTITY hyphen "‐">
+<!ENTITY weierp "℘">
+<!ENTITY smile "⌣">
+<!ENTITY Egr "Ε">
+<!ENTITY eeacgr "ή">
+<!ENTITY nsc "⊁">
+<!ENTITY les "⩽">
+<!ENTITY boxvH "╪">
+<!ENTITY KHcy "Х">
+<!ENTITY bernou "ℬ">
+<!ENTITY lpargt "⦠">
+<!ENTITY tgr "τ">
+<!ENTITY zacute "ź">
+<!ENTITY amp "&">
+<!ENTITY lnE "≨">
+<!ENTITY nlE "≦̸">
+<!ENTITY sbsol "﹨">
+<!ENTITY Pi "Π">
+<!ENTITY b.beta "𝛃">
+<!ENTITY b.mu "𝛍">
+<!ENTITY Ograve "Ò">
+<!ENTITY phone "☎">
+<!ENTITY iff "⇔">
+<!ENTITY gsim "≳">
+<!ENTITY rx "℞">
+<!ENTITY there4 "∴">
+<!ENTITY harrw "↭">
+<!ENTITY udiagr "ΰ">
+<!ENTITY otilde "õ">
+<!ENTITY DotDot " ⃜">
+<!ENTITY lrhar2 "⇋">
+<!ENTITY lE "≦">
+<!ENTITY hstrok "ħ">
+<!ENTITY Racute "Ŕ">
+<!ENTITY rarrw "↝">
+<!ENTITY angmsd "∡">
+<!ENTITY tshcy "ћ">
+<!ENTITY szlig "ß">
+<!ENTITY nequiv "≢">
+<!ENTITY pcy "п">
+<!ENTITY darr "↓">
+<!ENTITY female "♀">
+<!ENTITY curarr "↷">
+<!ENTITY minusb "⊟">
+<!ENTITY aacute "á">
+<!ENTITY Dcy "Д">
+<!ENTITY THORN "Þ">
+<!ENTITY ucirc "û">
+<!ENTITY asymp "≈">
+<!ENTITY bcong "≌">
+<!ENTITY die "¨">
+<!ENTITY ograve "ò">
+<!ENTITY iexcl "¡">
+<!ENTITY frac56 "⅚">
+<!ENTITY rArr "⇒">
+<!ENTITY tprime "‴">
+<!ENTITY osol "⊘">
+<!ENTITY sqsub "⊏">
+<!ENTITY rho "ρ">
+<!ENTITY b.psi "𝛙">
+<!ENTITY aring "å">
+<!ENTITY Edot "Ė">
+<!ENTITY lcaron "ľ">
+<!ENTITY rlarr2 "⇄">
+<!ENTITY EEacgr "Ή">
+<!ENTITY pi "π">
+<!ENTITY sect "§">
+<!ENTITY bepsi "϶">
+<!ENTITY ffllig "ffl">
+<!ENTITY lsh "↰">
+<!ENTITY dscy "ѕ">
+<!ENTITY macr "¯">
+<!ENTITY b.kappav "𝛞">
+<!ENTITY scaron "š">
+<!ENTITY commat "@">
+<!ENTITY dollar "$">
+<!ENTITY angsph "∢">
+<!ENTITY Udblac "Ű">
+<!ENTITY comma ",">
+<!ENTITY copy "©">
+<!ENTITY diams "♦">
+<!ENTITY Dot "¨">
+<!ENTITY sube "⊆">
+<!ENTITY Cap "⋒">
+<!ENTITY nsmid "∤">
+<!ENTITY SOFTcy "Ь">
+<!ENTITY eegr "η">
+<!ENTITY lsim "≲">
+<!ENTITY ssmile "⌣">
+<!ENTITY nlt "≮">
+<!ENTITY boxHU "╩">
+<!ENTITY ZHcy "Ж">
+<!ENTITY abreve "ă">
+<!ENTITY lmidot "ŀ">
+<!ENTITY angst "Å">
+<!ENTITY b.lambda "𝛌">
+<!ENTITY uuml "ü">
+<!ENTITY ENG "Ŋ">
+<!ENTITY IJlig "IJ">
+<!ENTITY brvbar "¦">
+<!ENTITY esdot "≐">
+<!ENTITY boxuL "╛">
+<!ENTITY blk14 "░">
+<!ENTITY YAcy "Я">
+<!ENTITY caron "ˇ">
+<!ENTITY ohacgr "ώ">
+<!ENTITY sup3 "³">
+<!ENTITY flat "♭">
+<!ENTITY minus "−">
+<!ENTITY olarr "↺">
+<!ENTITY dlcorn "⌞">
+<!ENTITY boxuR "╘">
+<!ENTITY iukcy "і">
+<!ENTITY b.tau "𝛕">
+<!ENTITY Otilde "Õ">
+<!ENTITY ldquo "“">
+<!ENTITY lang "〈">
+<!ENTITY Verbar "‖">
+<!ENTITY ges "⩾">
+<!ENTITY prap "⪷">
+<!ENTITY thksim "∼">
+<!ENTITY Vcy "В">
+<!ENTITY yacy "я">
+<!ENTITY drcrop "⌌">
+<!ENTITY omega "ω">
+<!ENTITY Hcirc "Ĥ">
+<!ENTITY tstrok "ŧ">
+<!ENTITY ang "∠">
+<!ENTITY khgr "χ">
+<!ENTITY b.thetas "𝛉">
+<!ENTITY ecaron "ě">
+<!ENTITY Odblac "Ő">
+<!ENTITY fflig "ff">
+<!ENTITY lowast "∗">
+<!ENTITY nvdash "⊬">
+<!ENTITY frac18 "⅛">
+<!ENTITY sup1 "¹">
+<!ENTITY njcy "њ">
+<!ENTITY b.thetav "𝛝">
+<!ENTITY sup2 "²">
+<!ENTITY gimel "ℷ">
+<!ENTITY ldot "⋖">
+<!ENTITY Ccedil "Ç">
+<!ENTITY rdquo "”">
+<!ENTITY rhard "⇁">
+<!ENTITY nsime "≄">
+<!ENTITY boxhu "┴">
+<!ENTITY intcal "⊺">
+<!ENTITY nsupe "⊉">
+<!ENTITY Gt "≫">
+<!ENTITY igr "ι">
+<!ENTITY nabla "∇">
+<!ENTITY urcorn "⌝">
+<!ENTITY nle "≰">
+<!ENTITY Icy "И">
+<!ENTITY DJcy "Ђ">
+<!ENTITY jukcy "є">
+<!ENTITY lceil "⌈">
+<!ENTITY oS "Ⓢ">
+<!ENTITY malt "✠">
+<!ENTITY ccirc "ĉ">
+<!ENTITY ycirc "ŷ">
+<!ENTITY Aacgr "Ά">
+<!ENTITY Ntilde "Ñ">
+<!ENTITY vsupnE "⫌︀">
+<!ENTITY ogr "ο">
+<!ENTITY and "∧">
+<!ENTITY gvnE "≩︀">
+<!ENTITY dashv "⊣">
+<!ENTITY supE "⫆">
+<!ENTITY mu "μ">
+<!ENTITY vsubnE "⫋︀">
+<!ENTITY gE "≧">
+<!ENTITY smid "∣">
+<!ENTITY delta "δ">
+<!ENTITY tcaron "ť">
+<!ENTITY rsqb "]">
+<!ENTITY bull "•">
+<!ENTITY cuwed "⋏">
+<!ENTITY raquo "»">
+<!ENTITY frac45 "⅘">
+<!ENTITY part "∂">
+<!ENTITY Vdash "⊩">
+<!ENTITY boxhd "┬">
+<!ENTITY psi "ψ">
+<!ENTITY b.Omega "𝛀">
+<!ENTITY iquest "¿">
+<!ENTITY sqcup "⊔">
+<!ENTITY YUcy "Ю">
+<!ENTITY psgr "ψ">
+<!ENTITY conint "∮">
+<!ENTITY gel "⋛">
+<!ENTITY Icirc "Î">
+<!ENTITY twixt "≬">
+<!ENTITY boxHD "╦">
+<!ENTITY male "♂">
+<!ENTITY euro "€">
+<!ENTITY epsi "ϵ">
+<!ENTITY Rcaron "Ř">
+<!ENTITY SHCHcy "Щ">
+<!ENTITY ugr "υ">
+<!ENTITY Phi "Φ">
+<!ENTITY b.Xi "𝚵">
+<!ENTITY lt "<">
+<!ENTITY scnsim "⋩">
+<!ENTITY models "⊧">
+<!ENTITY boxHu "╧">
+<!ENTITY Lcy "Л">
+<!ENTITY Sacute "Ś">
+<!ENTITY nwarr "↖">
+<!ENTITY drcorn "⌟">
+<!ENTITY NJcy "Њ">
+<!ENTITY mumap "⊸">
+<!ENTITY rAarr "⇛">
+<!ENTITY nsubE "⫅̸">
+<!ENTITY b.rho "𝛒">
+<!ENTITY oelig "œ">
+<!ENTITY utrif "▴">
+<!ENTITY subne "⊊">
+<!ENTITY para "¶">
+<!ENTITY ocirc "ô">
+<!ENTITY ouml "ö">
+<!ENTITY num "#">
+<!ENTITY boxUL "╝">
+<!ENTITY IEcy "Е">
+<!ENTITY Ocy "О">
+<!ENTITY Ugrave "Ù">
+<!ENTITY eogon "ę">
+<!ENTITY sum "∑">
+<!ENTITY mcy "м">
+<!ENTITY YIcy "Ї">
+<!ENTITY Gamma "Γ">
+<!ENTITY isin "∈">
+<!ENTITY cuesc "⋟">
+<!ENTITY b.Pi "𝚷">
+<!ENTITY Ubreve "Ŭ">
+<!ENTITY starf "★">
+<!ENTITY gne "⪈">
+<!ENTITY gammad "ϝ">
+<!ENTITY napos "ʼn">
+<!ENTITY sup "⊃">
+<!ENTITY dArr "⇓">
+<!ENTITY Larr "↞">
+<!ENTITY nVDash "⊯">
+<!ENTITY boxhU "╨">
+<!ENTITY Ggr "Γ">
+<!ENTITY Idigr "Ϊ">
+<!ENTITY AElig "Æ">
+<!ENTITY Idot "İ">
+<!ENTITY Lacute "Ĺ">
+<!ENTITY sharp "♯">
+<!ENTITY Ubrcy "Ў">
+<!ENTITY lsqb "[">
+<!ENTITY micro "µ">
+<!ENTITY Sub "⋐">
+<!ENTITY agr "α">
+<!ENTITY nap "≉">
+<!ENTITY sfgr "ς">
+<!ENTITY block "█">
+<!ENTITY nspar "∦">
+<!ENTITY supnE "⫌">
+<!ENTITY prsim "≾">
+<!ENTITY shcy "ш">
+<!ENTITY dblac "˝">
+<!ENTITY xhArr "⟺">
+<!ENTITY dtri "▿">
+<!ENTITY barwed "⌅">
+<!ENTITY zcy "з">
+<!ENTITY agrave "à">
+<!ENTITY par "∥">
+<!ENTITY vsupne "⊋︀">
+<!ENTITY Scy "С">
+<!ENTITY zdot "ż">
+<!ENTITY rsquor "’">
+<!ENTITY Delta "Δ">
+<!ENTITY nVdash "⊮">
+<!ENTITY Pgr "Π">
+<!ENTITY gamma "γ">
+<!ENTITY tau "τ">
+<!ENTITY Ecirc "Ê">
+<!ENTITY sung "♪">
+<!ENTITY natur "♮">
+<!ENTITY or "∨">
+<!ENTITY vsubne "⊊︀">
+<!ENTITY Jcy "Й">
+<!ENTITY square "□">
+<!ENTITY b.Psi "𝚿">
+<!ENTITY b.zeta "𝛇">
+<!ENTITY gbreve "ğ">
+<!ENTITY Kcedil "Ķ">
+<!ENTITY ohm "Ω">
+<!ENTITY frac35 "⅗">
+<!ENTITY ssetmn "∖">
+<!ENTITY boxUR "╚">
+<!ENTITY frac34 "¾">
+<!ENTITY target "⌖">
+<!ENTITY cularr "↶">
+<!ENTITY xcirc "◯">
+<!ENTITY boxhD "╥">
+<!ENTITY iecy "е">
+<!ENTITY Euml "Ë">
+<!ENTITY half "½">
+<!ENTITY rang "〉">
+<!ENTITY numero "№">
+<!ENTITY Ugr "Υ">
+<!ENTITY semi ";">
+<!ENTITY times "×">
+<!ENTITY rharu "⇀">
+<!ENTITY iocy "ё">
+<!ENTITY b.gammad "ϝ">
+<!ENTITY lozf "⧫">
+<!ENTITY thinsp " ">
+<!ENTITY plusb "⊞">
+<!ENTITY tilde "˜">
+<!ENTITY Aogon "Ą">
+<!ENTITY Eogon "Ę">
+<!ENTITY blk12 "▒">
+<!ENTITY pre "⪯">
+<!ENTITY boxHd "╤">
+<!ENTITY piv "ϖ">
+<!ENTITY ncaron "ň">
+<!ENTITY wcirc "ŵ">
+<!ENTITY utri "▵">
+<!ENTITY Prime "″">
+<!ENTITY cedil "¸">
+<!ENTITY idigr "ϊ">
+<!ENTITY curren "¤">
+<!ENTITY laquo "«">
+<!ENTITY ulcrop "⌏">
+<!ENTITY ring "˚">
+<!ENTITY oacute "ó">
+<!ENTITY Nacute "Ń">
+<!ENTITY permil "‰">
+<!ENTITY oacgr "ό">
+<!ENTITY frac78 "⅞">
+<!ENTITY blk34 "▓">
+<!ENTITY gnsim "⋧">
+<!ENTITY boxVH "╬">
+<!ENTITY zhcy "ж">
+<!ENTITY b.phiv "𝛟">
+<!ENTITY loz "◊">
+<!ENTITY Ngr "Ν">
+<!ENTITY phgr "φ">
+<!ENTITY b.iota "𝛊">
+<!ENTITY ETH "Ð">
+<!ENTITY trade "™">
+<!ENTITY Cup "⋓">
+<!ENTITY subnE "⫋">
+<!ENTITY PHgr "Φ">
+<!ENTITY xi "ξ">
+<!ENTITY Rcy "Р">
+<!ENTITY ggr "γ">
+<!ENTITY Lmidot "Ŀ">
+<!ENTITY Scirc "Ŝ">
+<!ENTITY rtrif "▸">
+<!ENTITY larrtl "↢">
+<!ENTITY eDot "≑">
+<!ENTITY boxVL "╣">
+<!ENTITY THgr "Θ">
+<!ENTITY Dstrok "Đ">
+<!ENTITY cent "¢">
+<!ENTITY odash "⊝">
+<!ENTITY boxUl "╜">
+<!ENTITY ape "≊">
+<!ENTITY gEl "⪌">
+<!ENTITY nltri "⋪">
+<!ENTITY Aacute "Á">
+<!ENTITY cuvee "⋎">
+<!ENTITY gnE "≩">
+<!ENTITY kgr "κ">
+<!ENTITY iogon "į">
+<!ENTITY rarrtl "↣">
+<!ENTITY b.phi "𝛗">
+<!ENTITY sccue "≽">
+<!ENTITY IOcy "Ё">
+<!ENTITY sext "✶">
+<!ENTITY uplus "⊎">
+<!ENTITY ecolon "≕">
+<!ENTITY nlArr "⇍">
+<!ENTITY scap "⪸">
+<!ENTITY rarrlp "↬">
+<!ENTITY ngE "≧̸">
+<!ENTITY nsim "≁">
+<!ENTITY Acy "А">
+<!ENTITY emacr "ē">
+<!ENTITY Jcirc "Ĵ">
+<!ENTITY ltimes "⋉">
+<!ENTITY Bcy "Б">
+<!ENTITY b.Sigma "𝚺">
+<!ENTITY cup "∪">
+<!ENTITY fork "⋔">
+<!ENTITY frac25 "⅖">
+<!ENTITY setmn "∖">
+<!ENTITY bsol "\">
+<!ENTITY Ycy "Ы">
+<!ENTITY b.Phi "𝚽">
+<!ENTITY Gcedil "Ģ">
+<!ENTITY frac23 "⅔">
+<!ENTITY Iogon "Į">
+<!ENTITY blank "␣">
+<!ENTITY vprop "∝">
+<!ENTITY boxVR "╠">
+<!ENTITY ecy "э">
+<!ENTITY OHacgr "Ώ">
+<!ENTITY yen "¥">
+<!ENTITY hairsp " ">
+<!ENTITY plusdo "∔">
+<!ENTITY lvnE "≨︀">
+<!ENTITY boxUr "╙">
+<!ENTITY breve "˘">
+<!ENTITY rtimes "⋊">
+<!ENTITY gnap "⪊">
+<!ENTITY rtrie "⊵">
+<!ENTITY Mcy "М">
+<!ENTITY chi "χ">
+<!ENTITY tdot " ⃛">
+<!ENTITY PSgr "Ψ">
+<!ENTITY Umacr "Ū">
+<!ENTITY caret "⁁">
+<!ENTITY xutri "△">
+<!ENTITY CHcy "Ч">
+<!ENTITY djcy "ђ">
+<!ENTITY lambda "λ">
+<!ENTITY Tstrok "Ŧ">
+<!ENTITY puncsp " ">
+<!ENTITY Ll "⋘">
+<!ENTITY aacgr "ά">
+<!ENTITY xdtri "▽">
+<!ENTITY GJcy "Ѓ">
+<!ENTITY gdot "ġ">
+<!ENTITY sub "⊂">
+<!ENTITY mid "∣">
+<!ENTITY dzcy "џ">
+<!ENTITY igrave "ì">
+<!ENTITY Emacr "Ē">
+<!ENTITY Rcedil "Ŗ">
+<!ENTITY gt ">">
+<!ENTITY harr "↔">
+<!ENTITY larrlp "↫">
+<!ENTITY thgr "θ">
+<!ENTITY drarr "↘">
+<!ENTITY map "↦">
+<!ENTITY boxVh "╫">
+<!ENTITY ijlig "ij">
+<!ENTITY tcedil "ţ">
+<!ENTITY dlcrop "⌍">
+<!ENTITY prnsim "⋨">
+<!ENTITY ecir "≖">
+<!ENTITY rgr "ρ">
+<!ENTITY deg "°">
+<!ENTITY lap "⪅">
+<!ENTITY KJcy "Ќ">
+<!ENTITY Cdot "Ċ">
+<!ENTITY Uogon "Ų">
+<!ENTITY not "¬">
+<!ENTITY dash "‐">
+<!ENTITY nexist "∄">
+<!ENTITY Lt "≪">
+<!ENTITY b.Upsi "𝚼">
+<!ENTITY Atilde "Ã">
+<!ENTITY edot "ė">
+<!ENTITY Ncedil "Ņ">
+<!ENTITY els "⪕">
+<!ENTITY erDot "≓">
+<!ENTITY boxVl "╢">
+<!ENTITY scy "с">
+<!ENTITY ulcorn "⌜">
+<!ENTITY eacgr "έ">
+<!ENTITY Itilde "Ĩ">
+<!ENTITY Zacute "Ź">
+<!ENTITY xharr "⟷">
+<!ENTITY gl "≷">
+<!ENTITY chcy "ч">
+<!ENTITY Oacute "Ó">
+<!ENTITY itilde "ĩ">
+<!ENTITY Ycirc "Ŷ">
+<!ENTITY nhArr "⇎">
+<!ENTITY Lstrok "Ł">
+<!ENTITY divide "÷">
+<!ENTITY Tcy "Т">
+<!ENTITY Jukcy "Є">
+<!ENTITY Yacute "Ý">
+<!ENTITY boxv "│">
+<!ENTITY hamilt "ℋ">
+<!ENTITY nu "ν">
+<!ENTITY ngt "≯">
+<!ENTITY jsercy "ј">
+<!ENTITY uml "¨">
+<!ENTITY KHgr "Χ">
+<!ENTITY lstrok "ł">
+<!ENTITY nsupE "⫆̸">
+<!ENTITY dtrif "▾">
+<!ENTITY vellip "⋮">
+<!ENTITY rceil "⌉">
+<!ENTITY ell "ℓ">
+<!ENTITY Ecy "Э">
+<!ENTITY Jsercy "Ј">
+<!ENTITY ljcy "љ">
+<!ENTITY Kgr "Κ">
+<!ENTITY ngr "ν">
+<!ENTITY sigmav "ς">
+<!ENTITY Gdot "Ġ">
+<!ENTITY rdquor "”">
+<!ENTITY prnap "⪹">
+<!ENTITY tcy "т">
+<!ENTITY frac12 "½">
+<!ENTITY telrec "⌕">
+<!ENTITY vdash "⊢">
+<!ENTITY Zgr "Ζ">
+<!ENTITY Auml "Ä">
+<!ENTITY Ocirc "Ô">
+<!ENTITY uogon "ų">
+<!ENTITY hArr "⇔">
+<!ENTITY nge "≱">
+<!ENTITY iacute "í">
+<!ENTITY Cacute "Ć">
+<!ENTITY Omacr "Ō">
+<!ENTITY equiv "≡">
+<!ENTITY vltri "⊲">
+<!ENTITY eta "η">
+<!ENTITY SHcy "Ш">
+<!ENTITY lowbar "_">
+<!ENTITY percnt "%">
+<!ENTITY frac16 "⅙">
+<!ENTITY lrarr2 "⇆">
+<!ENTITY nles "⩽̸">
+<!ENTITY bump "≎">
+<!ENTITY veebar "⊻">
+<!ENTITY Wcirc "Ŵ">
+<!ENTITY frac15 "⅕">
+<!ENTITY bumpe "≏">
+<!ENTITY egrave "è">
+<!ENTITY frac14 "¼">
+<!ENTITY supe "⊇">
+<!ENTITY rfloor "⌋">
+<!ENTITY Dgr "Δ">
+<!ENTITY frac13 "⅓">
+<!ENTITY ge "≥">
+<!ENTITY boxVr "╟">
+<!ENTITY pgr "π">
+<!ENTITY kgreen "ĸ">
+<!ENTITY boxh "─">
+<!ENTITY Lambda "Λ">
+<!ENTITY ugrave "ù">
+<!ENTITY emsp13 " ">
+<!ENTITY becaus "∵">
+<!ENTITY sce "⪰">
+<!ENTITY grave "`">
+<!ENTITY zeta "ζ">
+<!ENTITY b.Theta "𝚯">
+<!ENTITY eth "ð">
+<!ENTITY Ouml "Ö">
+<!ENTITY check "✓">
+<!ENTITY hybull "⁃">
+<!ENTITY Gg "⋙">
+<!ENTITY Ccaron "Č">
+<!ENTITY plus "+">
+<!ENTITY fllig "fl">
+<!ENTITY forall "∀">
+<!ENTITY dcaron "ď">
+<!ENTITY gacute "ǵ">
+<!ENTITY sc "≻">
+<!ENTITY OHgr "Ω">
+<!ENTITY emsp14 " ">
+<!ENTITY hellip "…">
+<!ENTITY lhard "↽">
+<!ENTITY sstarf "⋆">
+<!ENTITY samalg "∐">
+<!ENTITY EEgr "Η">
+<!ENTITY rhov "ϱ">
+<!ENTITY b.epsi "𝛆">
+<!ENTITY lsquo "‘">
+]>
+<book>
+ <bookinfo>
+ <title>JBoss Application Server</title>
+ <subtitle>Installation And Getting Started Guide</subtitle>
+ <issuenum>5.0</issuenum>
+ <productnumber>0</productnumber>
+
+ <authorgroup>
+
+ <author>
+ <firstname>JBoss</firstname>
+ <surname>Community</surname>
+
+ </author>
+
+
+</authorgroup>
+</bookinfo>
+ <preface id="Book-Preface">
+ <title>Introduction</title>
+ <para>
+ JBoss Application Server is the open source implementation of the Java EE suite of services. It comprises a set of offerings for enterprise customers who are looking for preconfigured profiles of JBoss Enterprise Middleware components that have been tested and certified together to provide an integrated experience. It's easy-to-use server architecture and high flexibility makes JBoss the ideal choice for users just starting out with J2EE, as well as senior architects looking for a customizable middleware platform.
+ </para>
+ <para>
+ Because it is Java-based, JBoss Application Server is cross-platform, easy to install and use on any operating system that supports Java. The readily available source code is a powerful learning tool to debug the server and understand it. It also gives you the flexibility to create customized versions for your personal or business use.
+ </para>
+ <para>
+ Installing JBoss Application Server is simple and easy. You can have it installed and running in no time. This guide will teach you to install and get started with the JBoss Application Server.</para>
+ <section id="Software_Versions">
+ <title>Software Versions</title>
+ <para>
+ <table>
+ <title>Software Versions</title>
+ <tgroup cols="2">
+ <colspec colwidth="25*"/>
+ <colspec colwidth="75*"/>
+ <thead>
+ <row><entry>Software</entry>
+ <entry>Description</entry></row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><para>JBoss Application Server</para></entry>
+ <entry><para>5.0.0</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+</section>
+ <section id="Book-We_Need_Feedback">
+ <title>Help Contribute</title>
+ <para>
+ If you find a typographical error in the <citetitle>Installation Guide and Getting Started Guide</citetitle>, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: <ulink url="http://jira.jboss.com">http://jira.jboss.com</ulink> against the project <citetitle>JBoss Application Server</citetitle> and component <citetitle>Docs/Installation and Getting Started Guide</citetitle>.
+ </para>
+ <para>
+ If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
+ </para>
+ <note><title>Note</title><para>Be sure to give us your name so you can receive full credit.</para></note>
+
+ <note><title>Note</title><para>This content is taken from svn.jboss.org/repos/jbossas/projects/docs/community/5 and has yet to be branched.</para></note>
+
+ <para>To access the content directly and make changes yourself:</para>
+ <screen>
+ svn co https://svn.jboss.org/repos/jbossas/projects/docs/community/5 --username yourusername
+ </screen>
+</section>
+</preface>
+ <chapter id="Getting_Started">
+ <title>Getting Started</title>
+ <section id="Getting_Started-Pre_Requisites">
+ <title>Pre-Requisites</title>
+ <para>
+ You must have adequate disk space to install JDK and JBoss Application Server while also allowing enough space for your applications. Before installing JBoss Application Server you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java.
+ </para>
+ <section id="Pre_Requisites-Hardware_and_Operating_System_Requirements">
+ <title>Hardware and Operating System Requirements</title>
+
+ <para>For the latest information on supported Operating System / JVM combinations and supported Database platforms, please refer to <ulink url="http://www.jboss.com">http://www.jboss.com</ulink>.
+ </para>
+
+ </section>
+
+ <section id="Pre_Requisites-Configuring_Your_Java_Environment">
+ <title>Configuring Your Java Environment</title>
+ <para>
+ You must have a working installation of <emphasis>JDK 1.5</emphasis> or <emphasis>JDK 1.6</emphasis> before you install JBoss Application Server. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 5.0 on a Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM.
+ <itemizedlist id="Configuring_Your_Java_Environment-Benefits_of_64_bit_JVM_on_64_bit_OS_and_Hardware">
+ <title>Benefits of 64-bit JVM on 64-bit OS and Hardware:</title>
+ <listitem>
+ <para>
+ Wider datapath: The pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Applications that run with more than 1.5GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Linux">
+ <title>Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Linux</title>
+ <listitem>
+ <para>
+ Download the Sun JDK 5.0 or JDK 6 (Java 2 Development Kit) from Sun's website: <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp"/> for JDK 5.0 or <ulink url="http://java.sun.com/javase/downloads/"/> for JDK 6.0. Select the JDK Update <x>" (where x is the latest update number) for download and then select "RPM in self-extracting" file for Linux<footnote><para>Make sure you choose the appropriate file for your platform.</para></footnote>. Read the instructions on Sun's website for installing the JDK.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you do not want to use SysV service scripts you can install the "self-extracting file" for Linux instead of choosing the "RPM in self-extracting" file. In that case you can skip the next step mentioned here. But it is recommended to use the SysV service scripts for production servers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Download and install the appropriate <literal>-compat RPM</literal> from <literal>JPackage</literal> <ulink url="ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/"> here</ulink>. Please ensure you choose a matching version of the <literal>-compat</literal> package to the JDK you installed.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Create an environment variable that points to the JDK installation directory and call it <literal>JAVA_HOME</literal>. Add <literal>$JAVA_HOME/bin</literal> to the system path to be able to run <literal>java</literal> from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory.
+<programlisting>#In this example /usr/java/jdk1.6.0_07 is the JDK installation directory.
+export JAVA_HOME=/usr/java/jdk1.6.0_07
+export PATH=$PATH:$JAVA_HOME/bin
+</programlisting>
+ Set this variable for the user account doing the installation and also for the user account that will run the server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.5 or JDK1.6 installation as the default source for the <literal>java</literal> and <literal>javac</literal> executables. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system.
+ <itemizedlist>
+ <title>Select alternatives for java, javac and java_sdk_1.<x></title>
+ <listitem>
+ <para>
+ As root, type the following command at the shell prompt and you should see something like this: <programlisting>
+[root at vsr ~]$ /usr/sbin/alternatives --config java
+There are 2 programs which provide 'java'.
+Selection Command
+-----------------------------------------------
+ 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java
+*+ 2 /usr/lib/jvm/jre-1.5.0-sun/bin/java
+Enter to keep the current selection[+], or type selection number:
+</programlisting>
+ Make sure the Sun version [<literal>jre-1.5.0-sun</literal> in this case] is selected (marked with a '+' in the output), or select it by entering its number as prompted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Repeat the same for javac and java_sdk_1.<x> <programlisting>
+[root at vsr ~]$ /usr/sbin/alternatives --config javac
+There are 1 programs which provide 'javac'.
+ Selection Command
+-----------------------------------------------
+*+ 1 /usr/lib/jvm/java-1.5.0-sun/bin/javac
+Enter to keep the current selection[+], or type selection number:
+</programlisting>
+<programlisting>
+[root at vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
+There are 1 programs which provide 'java_sdk_1.5.0'.
+ Selection Command
+-----------------------------------------------
+*+ 1 /usr/lib/jvm/java-1.5.0-sun
+Enter to keep the current selection[+], or type selection number:
+</programlisting>
+ You should verify that java, javac and java_sdk_1.<x> all point to the same manufacturer and version.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>
+ You can always override this step by setting the <literal>JAVA_HOME</literal> environment variable as explained in the previous step.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Make sure that the <literal>java</literal> executable is in your path and that you are using an appropriate version. To verify your Java environment, type <literal>java -version</literal> at the shell prompt and you should see something like this: <programlisting>
+[root at vsr ~]$ java -version
+java version "1.5.0_14"
+Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_14-b03)
+Java HotSpot(TM) Client VM (build 1.5.0_14-b03, mixed mode, sharing)
+</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Microsoft_Windows">
+ <title>Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Microsoft Windows</title>
+ <listitem>
+ <para>
+ Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp"/> for JDK 5.0 or <ulink url="http://java.sun.com/javase/downloads/"/> for JDK 6.0. Choose the JDK Update <x>" (where x is the latest update number) for download and then select your Windows Platform options to perform the installation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an environment variable called <literal>JAVA_HOME</literal> that points to the JDK installation directory, for example: <literal>C:\Program Files\Java\jdk1.5.0_14\</literal>. In order to run java from the command line add the <literal>jre\bin</literal> directory to your path, for example: <literal>C:\Program Files\Java\jdk1.5.0_14\jre\bin</literal>. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+
+
+
+
+ </section>
+</chapter>
+ <chapter id="Installation_Alternatives">
+ <title>Installation Alternatives</title>
+ <para>
+ You can install the JBoss Application Server in one of these two modes: <itemizedlist>
+ <!--<listitem>
+ <para>
+ <emphasis>Graphical Installer</emphasis>
+ </para>
+ <para>
+ Using the Graphical Installer can simplify the installation and configuration process for non-sophisticated users. In addition to the basic installation, the installer provides you with basic configuration capabilities, allows you to control whether the JMX interfaces are secured and the ability to enter console username/password. The graphical installer is available for <emphasis>subscribed users</emphasis> on <ulink url="https://network.jboss.com"/>.
+ </para>
+ </listitem>-->
+ <listitem>
+ <para>
+ <emphasis>Binary files download</emphasis>
+ </para>
+ <para>
+ In this form of installation, simply unzip the downloaded zip file to the directory of your choice. You can unzip the JBoss Application Server on any operating system that supports the zip format. The zip file is available on <ulink url="http://labs.jboss.com/jbossas/downloads/"/>. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in <xref linkend="Getting_Started-Pre_Requisites"/>. Further details on installation using the Binary files are discussed in <xref linkend="binary_installation"/>
+ </para>
+ <para>
+ JBossAS 5.0.0 can be compiled with both Java5 and Java6. The Java5 compiled binary is our primary/recommended binary distribution. It has undergone rigorous testing and can run under both a Java 5 and a Java 6 runtime. When running
+ under Java 6 you need to manually copy the following libraries from the <filename>JBOSS_HOME/client</filename> directory to the <filename>JBOSS_HOME/lib/endorsed</filename> directory, so that the JAX-WS 2.0 apis supported by JBossWS are used:
+ </para>
+<screen>* jbossws-native-saaj.jar
+* jbossws-native-jaxrpc.jar
+* jbossws-native-jaxws.jar
+* jbossws-native-jaxws-ext.jar </screen>
+ <para>
+ Another alternative is to download the jdk6 distribution <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2-jdk6.zip?modtime=1221686600&big_mirror=1">(<filename>jboss-5.0.0.CR2-jdk6.zip</filename>)</ulink> in which case no configuration changes are required.
+
+ Please refer to the <ulink url="http://sourceforge.net/project/shownotes.php?release_id=627020&group_id=22866">release notes</ulink> for additional information about running with JDK 6.
+ </para>
+
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>Source Files download</emphasis>
+ </para>
+ <para>
+ In this form of installation, download the source files from the web and build the source files locally. On successfully building your source files you can manually copy the built file into a desired folder and start the server. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in <xref linkend="Getting_Started-Pre_Requisites"/>. For more instructions on building your source files, please refer to <xref linkend="source_installation"/>.
+ </para>
+ </listitem>
+ <!--<listitem>
+ <para>
+ <emphasis>RPM download</emphasis>
+ </para>
+ <para>
+ In this form of installation, you can automatically install the platform on a &RHEL; system using the <literal>up2date</literal> command. The RPM installer is available for <emphasis>subscribed users</emphasis> on the Red Hat Network (RHN) on <ulink url="http://rhn.redhat.com"/>.
+ </para>
+ </listitem>-->
+ </itemizedlist>
+ </para>
+ <!--<para>
+ When you install from the installer, you get a smaller install image that is more tuned for your environment. However, the directory structure will be slightly different than when using the rpm/zip archive.
+ </para>-->
+ <para>
+ Three types of server configurations will be included in your installation - <emphasis>minimal</emphasis>, <emphasis>default</emphasis>, and <emphasis>all</emphasis>.
+ </para>
+</chapter>
+ <chapter id="binary_installation">
+ <title>Installation With Binary Download</title>
+
+ <section id="Binary_Download">
+ <title>Download and Installation</title>
+
+ <para>
+ You can download the Binary zip files from <ulink url="http://labs.jboss.com/jbossas/downloads/">http://labs.jboss.com/jbossas/downloads/</ulink>.
+ </para>
+ <para>
+ There are two binary distributions available:
+ </para>
+<orderedlist>
+ <listitem>
+ <para>
+ <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2.zip?modtime=1221686752&big_mirror=1">jboss-5.0.0.CR2.zip</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2-jdk6.zip?modtime=1221686600&big_mirror=1">jboss-5.0.0.CR2-jdk6.zip</ulink>
+ </para>
+ </listitem>
+</orderedlist>
+
+ <para>
+ In this form of installation, simply unzip the downloaded zip file to the directory of your choice on any operating system that supports the zip format.
+ <itemizedlist>
+ <listitem>
+ <para>
+ Unzip <literal>jboss-<release>.zip</literal> to extract the archive contents into the location of your choice. You can do this using the JDK <literal>jar</literal> tool (or any other ZIP extraction tool). In the example below we are assuming you downloaded the zip file to the <filename>/jboss</filename> directory.
+<programlisting>
+[usr]$ <literal>cd /jboss</literal>
+[usr]$ <literal>jar -xvf jboss-<release>.zip</literal></programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You should now have a directory called <filename>jboss-<release></filename>. Next you need to set your JBOSS_HOME environment variables. This is discussed in <xref linkend="setting_JBOSS_HOME"/>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+
+</chapter>
+ <chapter id="source_installation">
+ <title>Installation With Source Download</title>
+
+ <section id="Source_Download">
+ <title>Download and Installation</title>
+
+ <para>
+ You can download the zip source file from <ulink url="http://labs.jboss.com/jbossas/downloads/">http://labs.jboss.com/jbossas/downloads/</ulink>.
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Uncompress <literal>jboss-<release>-src.tar.gz</literal> to extract the archive contents into the location of your choice. You can do this using the <literal>tar</literal> archiving utility in Linux (or any other compatible extraction tool). In this example we are assuming your source files were copied in the <filename>/jboss</filename> folder.
+
+<screen>[user at localhost]$ cd /jboss
+[user at localhost]$ tar -xvf <literal>jboss-<release>-src.tar.gz</literal></screen>
+
+</para>
+ </listitem>
+ <listitem>
+ <para>
+ You should now have a directory called <literal>jboss-<release>-src.tar.gz</literal>. The next step is to build your source files. In this example we are using Apache ANT. This is discussed in the following section.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section><title>Installing and configuring ANT</title>
+ <para>
+ <ulink url="http://ant.apache.org/">Apache Ant</ulink> is a Java-based build tool. Instead of using an extended model using shell-based commands, Ant is extended using Java classes that use XML-based configuration files. The configuration files call out a target tree that executes various tasks. Each task is run by an object that implements a particular Task interface.
+ This gives you the ability to perform cross platform builds. Please also note that if needed, Ant provides an <exec> task that allows commands to be executed based on the Operating System it is executing on. For more information on Apache ANT please click <ulink url="http://ant.apache.org/">here</ulink>.
+ </para>
+ <para>
+ You will need to build your JBoss Application Server source files before you can run the application server. Apache Ant is shipped with the JBoss Application Server source files and can be executed from the <filename><source_directory>/tools/bin</filename> directory.
+ </para>
+ <para>
+ The source files can also be built using Apache Maven which is also shipped with the JBoss Application Server source files under <filename><source_directory>/tools/maven</filename> directory. For more information about Apache Maven, please refer to <ulink url="">http://maven.apache.org/</ulink>.
+ </para>
+
+ <para>
+ Like Java, you also need to set the environment variables for Apache ANT and/or Apache Maven. The following example illustrates a desirable configuration for the <filename>.bashrc</filename> file. In the example the file is edited using the gnome text editor (<command>gedit</command>).
+
+<screen>[user at localhost ~]$ gedit .bashrc
+
+# Source global definitions
+if [ -f /etc/bashrc ]; then
+/etc/bashrc
+fi
+......
+# User specific aliases and functions
+# The following are the environment variables for Java , ANT and Maven
+
+export JAVA_HOME=/usr/java/jdk1.6.0_07/
+export PATH=$PATH:$JAVA_HOME/bin
+
+export ANT_HOME=/home/downloads/jboss-<source_directory>/tools/
+export PATH=$PATH:$ANT_HOME/bin
+
+export MAVEN_HOME=/home/downloads/jboss-<source_directory>/tools/maven
+export PATH=$PATH:$MAVEN_HOME/bin
+</screen>
+
+ </para>
+ <para>
+ To implement the changes you've made to the <filename>.bashrc</filename> file, type the following on a terminal.
+
+<screen>[user at localhost ~]$ source .bashrc
+[user at localhost ~]$</screen>
+
+ If any errors are displayed, please check your <filename>.bashrc</filename> file for errors and ensure that all directory paths are correct.
+ </para>
+ </section>
+
+<section><title>Building with Apache ANT</title>
+ <para>
+ To build the JBoss Application Server source files with Apache ANT, from a terminal change directory to where the unzipped source files are. In the following example we are assuming that the source files were copied and unzipped in the logged in user's <filename>downloads</filename> folder.
+
+<screen>[user at localhost]$ cd /home/user/downloads/<literal>jboss-<release>-src</literal>/build
+[user at localhost build]$ ls
+aspects component-matrix docbook-support iiop jmx mbeans security system-jmx tools
+bootstrap connector ejb3 j2se jmx-remoting messaging server testsuite varia
+build console embedded jbossas main pom.xml spring-int thirdparty webservices
+cluster deployment hibernate-int jbossmq management profileservice system tomcat
+</screen>
+ From the contents of the <filename>build</filename> directory above, you can see the <filename>build.xml</filename> file which is used by Apache ANT as a configuration file when building your source files.
+ The next step is to perform the build using Apache ANT as illustrated below.
+<screen>[user at localhost build]$ ant
+
+compile-classes:
+[mkdir] Created dir: /jboss/jboss-<release>-src/tomcat/output/classes
+[javac] Compiling 89 source files to /jboss/jboss-<release>-src/tomcat/output/classes
+....
+....content truncated
+.....
+.....
+_buildmagic:build-bypass-check:
+jars:
+most:
+main:
+BUILD SUCCESSFUL
+Total time: 2 seconds</screen>
+
+A successful build will have the above message. If your build fails, please check the error log and ensure that your configuration files and environment variables are correctly set. The JBoss Application Server files are built under the <filename>build/output/jboss-<release></filename> directory as indicated below.
+
+<note><title>Note</title>
+ <para>At this point the JBoss Application Server source files build is a hybrid one (builds in both Ant and Maven) because it declares all JBoss dependencies as maven2 artifacts, however after the dependencies are resolved/imported the legacy ant based build is used to compile and build the distribution. The JBoss Application Server source files will change to a full maven build soon.
+ </para>
+</note>
+
+<screen>[user at localhost build]$ ls
+build.bat build-old.xml build-thirdparty-old.xml eclipse.psf output
+build-distr.xml build-release.xml build.xml etc pom.xml
+build.log build.sh docs local.properties VersionRelease.java
+
+[user at localhost build]$ cd output/jboss-<release>
+[user at localhost build]$ ls
+bin client docs lib server
+</screen>
+
+ The <filename>jboss-<release></filename> directory contains your successful JBoss Application Server files. You can copy this folder to a different location or run the server from this folder after setting the JBOSS_HOME environment variable in your <filename>.bashrc</filename> file. Next you need to set your JBOSS_HOME environment variables. This is discussed in <xref linkend="setting_JBOSS_HOME"/>.
+
+ </para>
+ </section>
+
+
+
+
+</chapter>
+ <chapter id="setting_JBOSS_HOME">
+ <title>Setting the JBOSS_HOME variable</title>
+
+<section id="setting_JBOSS_HOME_linux"><title>Setting the <command>JBOSS_HOME</command> variable in Linux.</title>
+
+ <para>
+ Before you can run the JBoss Application Server, you need to ensure that you've configured the JBOSS_HOME environment variable in your <filename>.bashrc</filename> file as follows. In this example the Application Server folder has beeen copied to the <filename>/usr/jboss/jboss-<release></filename> folder.
+ The following is a <filename>.bashrc</filename> file used in this installation. Please ensure that your <filename>.bashrc</filename> file has a similar configuration.
+
+<screen>[user at localhost ~]$ gedit .bashrc
+
+# Source global definitions
+if [ -f /etc/bashrc ]; then
+/etc/bashrc
+fi
+......
+# User specific aliases and functions
+# The following are the environment variables for Java, ANT and JBoss
+
+export JAVA_HOME=/usr/java/jdk1.6.0_07
+export PATH=$PATH:$JAVA_HOME/bin
+
+export ANT_HOME=/usr/ant/apache-ant-1.6.0
+export PATH=$PATH:$ANT_HOME/bin
+
+export JBOSS_HOME=/usr/jboss/jboss-<release>
+export PATH=$PATH:$JBOSS_HOME/bin
+</screen>
+
+ To implement your <filename>.bashrc</filename> file changes run the following command.
+
+<screen>[user at localhost ~]$ source .bashrc
+[user at localhost ~]$</screen>
+
+ If no errors are displayed on your terminal, you are now ready to run your JBoss Application Server.
+ </para>
+
+ </section>
+
+<section id="setting_JBOSS_HOME_windows"> <title>Setting the <command>JBOSS_HOME</command> variable in Windows.</title>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Create an environment variable called <literal>JBOSS_HOME</literal> that points to the JBoss Application Server installation directory, for example: <literal>C:\Program Files\JBoss\jboss-<release>\</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ In order to run JBoss Application Server from the command line, add the <literal>jboss-<release>\bin</literal> directory to your path, for example: <literal>C:\Program Files\JBoss\jboss-<release>\bin</literal>. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
+ </para>
+ </listitem>
+ </itemizedlist>
+ You are now ready to start the JBoss Application Server.
+ </para>
+
+</section>
+
+</chapter>
+
+ <chapter id="Uninstall_JBoss">
+ <title>Uninstall JBoss</title>
+ <para>
+ The JBoss Application Server may be uninstalled by simply deleting the JBoss Application Server's installation directory. You will also need to remove the <emphasis>JBOSS_HOME</emphasis> environment variables discussed in <xref linkend="setting_JBOSS_HOME"/> for your Linux or Windows platform.
+ </para>
+</chapter>
+ <chapter id="Test_your_Installation">
+ <title>Test your Installation</title>
+ <para>
+ After you have installed the JBoss Application Server, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, open the <filename>JBOSS_DIST/jboss-<release>/bin</filename> directory and execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system.
+ </para>
+ <para>
+ Your output should look similar to the following (accounting for installation directory differences) and contain no error or exception messages:
+ </para>
+<screen>
+[samson at dhcp-1-150 bin]$ sh run.sh
+=========================================================================
+
+JBoss Bootstrap Environment
+
+JBOSS_HOME: /home/svn/JBossHead/jboss-head/build/output/jboss-5.0.0.GA
+
+JAVA: /Library/Java/Home/bin/java
+
+JAVA_OPTS: -Dprogram.name=run.sh -Xms128m -Xmx512m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
+
+CLASSPATH: /home/svn/JBossHead/jboss-head/build/output/jboss-5.0.0.GA/bin/run.jar
+
+=========================================================================
+
+21:47:23,874 INFO [ServerImpl] Starting JBoss (Microcontainer)...
+21:47:23,875 INFO [ServerImpl] Release ID: JBoss [Morpheus] 5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812011226)
+.
+.
+...output truncated
+.
+.
+21:47:46,090 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
+21:47:46,112 INFO [ServerImpl] JBoss (Microcontainer) [5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812011226)] Started in 22s:227ms
+</screen>
+ <!--<note>
+ <para>
+ Note that there is no "Server Started" message shown at the console when the server is started using the <literal>default</literal> profile, which is the default profile used when no other is specified. This message may be observed in the <filename>server.log</filename> file located in the <filename>server/defaut/log</filename> subdirectory.
+ </para>
+ </note>-->
+ <para>
+ Now open <literal>http://localhost:8080</literal> in your web browser. (Make sure you dont have anything else already on your machine using that port).<footnote><para>
+ Note that on some machines, the name localhost may not resolve properly and you may need to use the local loopback address 127.0.0.1 instead.</para></footnote> The contents of your page should look similar to the following: <xref linkend="Test_your_Installation-Test_your_Installation"/>.
+ </para>
+ <para>
+ <figure id="Test_your_Installation-Test_your_Installation">
+ <title>Test your Installation</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/test_install.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </para>
+ <para>
+ You are now ready to use the JBoss Application Server.
+ </para>
+</chapter>
+ <chapter id="The_JBoss_Server___A_Quick_Tour">
+ <title>The JBoss Server - A Quick Tour</title>
+
+<section><title>Server Structure</title>
+
+ <para>
+ Now that you’ve downloaded JBoss and have run the server for the first time, the next thing you will want to know is how the installation is laid out and what goes where. At first glance there seems to be a lot of stuff in there, and it’s not obvious what you need to look at and what you can safely ignore for the time being. To remedy that, we’ll explore the server directory structure, locations of the key configuration files, log files, deployment and so on. It’s worth familiarizing yourself with the layout at this stage as it will help you understand the JBoss service architecture so that you’ll be able to find your way around when it comes to deploying your own applications.
+ </para>
+
+
+<!-- Embedded sections -->
+
+ <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations">
+ <title>Server Configurations</title>
+ <para>
+ Fundamentally, the JBoss architecture consists of the microcontainer, bootstrap beans loaded into the micrcontainer, a collection of deployers for loading various deployment types, and various mcbean(-jboss-beans.xml) and legacy mbean(jboss-service.xml) deployments.
+ This makes it easy to assemble different configurations and gives you the flexibility to tailor them to meet your requirements.
+ </para>
+ <para>
+ You don’t have to run a large, monolithic server all the time; you can remove the components you don’t need (which can also reduce the server startup time considerably) and you can also integrate additional services into JBoss by writing your own MBeans. You certainly do not need to do this to be able to run standard Java EE 5 applications though.
+ </para>
+ <para>
+ You don’t need a detailed understanding of the microcontainer to use JBoss, but it’s worth keeping a picture of this basic architecture in mind as it is central to the way JBoss works.
+ </para>
+ <para>
+ The JBoss Application Server ships with three different server configurations. Within the <literal><JBoss_Home>/server</literal> directory, you will find five subdirectories:
+ <literal>minimal</literal>, <literal>default</literal>, <literal>standard</literal>, <literal>all</literal> and <literal>web</literal> - one for each server configuration. Each of these configurations provide a different set of services. The <literal>default</literal> configuration is the one used if you don’t specify another one when starting up the server.
+ </para>
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term>minimal</term>
+ <listitem>
+ <para>
+ has a minimal configuration—the bare minimum services required to start JBoss. It starts the logging service, a JNDI server and a URL deployment scanner to find new deployments. This is what you would use if you want to use JMX/JBoss to start your own services without any other Java EE 5 technologies. This is just the bare server. There is no web container, no EJB or JMS support.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>default</term>
+ <listitem>
+ <para>
+ is a base Java EE 5 server profile containing a default set of services. It has the most frequently used services required to deploy a Java EE application. It does not include the JAXR service, the IIOP service, or any of the clustering services.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>all</term>
+ <listitem>
+ <para>
+ The all configuration starts all the available services. This includes the RMI/IIOP and clustering services, which are not loaded in the default configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>standard</term>
+ <listitem>
+ <para>
+ is the JavaEE 5 certified configuration of services.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>web</term>
+ <listitem>
+ <para>
+ is a lightweight web container oriented profile that previews the JavaEE 6 web profile.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ If you want to know which services are configured in each of these instances, the primary differences will be in the <filename class="directory"><JBoss_Home>/server/<instance-name>/deployers/</filename> directory and also the services deployments in the <filename class="directory"><JBoss_Home>/server/<instance-name>/deploy</filename> directory. For example, the default profile deployers and deploy directory contents are:
+<programlisting>
+[usr at localhost <JBoss_Home>]$<literal>ls server/default/deployers </literal>
+alias-deployers-jboss-beans.xml jboss-aop-jboss5.deployer
+bsh.deployer jboss-jca.deployer
+clustering-deployer-jboss-beans.xml jbossweb.deployer
+dependency-deployers-jboss-beans.xml jbossws.deployer
+directory-deployer-jboss-beans.xml j sr77-deployers-jboss-beans.xml
+ear-deployer-jboss-beans.xml metadata-deployer-jboss-beans.xml
+ejb-deployer-jboss-beans.xml seam.deployer
+ejb3.deployer security-deployer-jboss-beans.xml
+hibernate-deployer-jboss-beans.xml
+[usr at localhost <JBoss_Home>]$<literal>ls server/default/deploy </literal>
+ROOT.war jsr88-service.xml
+cache-invalidation-service.xml legacy-invokers-service.xml
+ejb2-container-jboss-beans.xml mail-ra.rar
+ejb2-timer-service.xml mail-service.xml
+ejb3-connectors-jboss-beans.xml management
+ejb3-container-jboss-beans.xml messaging
+ejb3-interceptors-aop.xml monitoring-service.xml
+ejb3-timer-service.xml profileservice-jboss-beans.xml
+hdscanner-jboss-beans.xml properties-service.xml
+hsqldb-ds.xml quartz-ra.rar
+http-invoker.sar remoting-jboss-beans.xml
+jboss-local-jdbc.rar schedule-manager-service.xml
+jboss-xa-jdbc.rar scheduler-service.xml
+jbossweb.sar security
+jbossws.sar sqlexception-service.xml
+jca-jboss-beans.xml transaction-jboss-beans.xml
+jms-ra.rar transaction-service.xml
+jmx-console.war uuid-key-generator.sar
+jmx-invoker-service.xml vfs-jboss-beans.xml
+jmx-remoting.sar
+</programlisting>
+ while the web profile deployers and deploy directory contents are:
+<programlisting>
+[usr at localhost <JBoss_Home>]$<literal>ls server/web/deployers </literal>
+alias-deployers-jboss-beans.xml jbossweb.deployer
+ejb3.deployer metadata-deployer-jboss-beans.xml
+jboss-aop-jboss5.deployer security-deployer-jboss-beans.xml
+jboss-jca.deployer
+[usr at localhost <JBoss_Home>]$<literal>ls server/web/deployers </literal>
+ROOT.war jbossweb.sar
+ejb3-container-jboss-beans.xml jca-jboss-beans.xml
+hdscanner-jboss-beans.xml jmx-console.war
+hsqldb-ds.xml jmx-invoker-service.xml
+http-invoker.sar security
+jboss-local-jdbc.rar transaction-jboss-beans.xml
+jboss-xa-jdbc.rar
+</programlisting>
+ </para>
+ <note>
+ <para>
+ The <emphasis role="bold">default</emphasis> configuration is the one used if you don’t specify another one when starting up the server.
+ </para>
+ <para>
+ To start the server using an alternate configuration refer to <xref linkend="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration"/>.
+ </para>
+ </note>
+ <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-Server_Configuration_Directory_Structure">
+ <title>Server Configuration Directory Structure</title>
+ <para>
+ The directory server configuration you’re using, is effectively the server root while JBoss is running. It contains all the code and configuration information for the services provided by the particular server configuration. It’s where the log output goes, and it’s where you deploy your applications. <xref linkend="Server_Configuration_Directory_Structure-Server_Configuration_Directory_Structure"/> shows the directories inside the server configuration directory (<filename class="directory"><JBoss_Home>/server/<instance-name></filename>) and their functions.
+ </para>
+ <para>
+ <table id="Server_Configuration_Directory_Structure-Server_Configuration_Directory_Structure">
+ <title>Server Configuration Directory Structure</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="1*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ Directory
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <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.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <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.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <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.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">lib</filename>
+ </entry>
+ <entry>
+ This directory contains JAR files (Java libraries that should not be hot deployed) needed by this server configuration. You can add required library files here for JDBC drivers etc. All JARs in this directory are loaded into the shared classpath at startup. Note that this directory only contains those jars unique to the server configuration. Jars common across the server configurations are now located in <filename class="directory"><JBoss_Home>/common/lib</filename>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">log</filename>
+ </entry>
+ <entry>
+ This is where the log files are written. JBoss uses the Jakarta <literal>log4j</literal> package for logging and you can also use it directly in your own applications from within the server. This may be overridden through the <filename class="directory">conf/</filename><filename>jboss-log4j.xml</filename> configuration file.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">tmp</filename>
+ </entry>
+ <entry>
+ The <filename class="directory">tmp</filename> directory is used for temporary storage by JBoss services. The deployer, for example, expands application archives in this directory.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <filename class="directory">work</filename>
+ </entry>
+ <entry>
+ This directory is used by Tomcat for compilation of JSPs.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+ <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-The_default_Server_Configuration_File_Set">
+ <title>The "default" Server Configuration File Set</title>
+ <para>
+ The "<literal>default</literal>" server configuration file set is located in the <literal><JBoss_Home>/server/default</literal> directory. The following example illustrates a truncated directory structure of the <literal>jboss-as-<release></literal> server configuration files:
+<screen>[user at localhost <JBoss_Home>]$ tree
+|-- bin
+|-- client
+|-- common
+| |-- lib
+| | |-- antlr.jar
+| | |-- ... many more jars
+|-- docs
+| |-- dtd
+| |-- examples
+| | |-- binding-manager
+| | | `-- sample-bindings.xml
+| | |-- jca
+| | |-- jms
+| | |-- jmx
+| | |-- netboot
+| | | `-- netboot.war
+| | `-- varia
+| | |-- deployment-service
+| | |-- derby-plugin.jar
+| | |-- entity-resolver-manager
+| | | `-- xmlresolver-service.xml
+| | `-- jboss-bindings.xml
+| `-- schema
+|-- lib
+| |-- commons-codec.jar
+| |-- commons-httpclient.jar
+| |-- commons-logging.jar
+| |-- concurrent.jar
+| |-- endorsed
+| | |-- serializer.jar
+| | |-- xalan.jar
+| | `-- xercesImpl.jar
+| |-- getopt.jar
+| |-- jboss-common.jar
+| |-- jboss-jmx.jar
+| |-- jboss-system.jar
+| |-- jboss-xml-binding.jar
+| `-- log4j-boot.jar
+`-- server
+|-- all
+| |-- conf
+| | |-- bootstrap/
+| | | |-- aop.xml
+| | | |-- bindings.xml
+| | | |-- aop.xml
+| | | |-- classloader.xml
+| | | |-- deployers.xml
+| | | |-- jmx.xml
+| | | |-- profile-repository.xml
+| | | |-- profile.xml
+| | | |-- vfs.xml
+| | |-- bootstrap.xml
+| | |-- bootstrap-norepo.xml
+| | |-- jacorb.properties
+| | |-- java.policy
+| | |-- jax-ws-catalog.xml
+| | |-- jboss-log4j.xml
+| | |-- jboss-service.xml
+| | |-- jbossjta-properties.xml
+| | |-- jndi.properties
+| | |-- login-config.xml
+| | |-- props
+| | | |-- jbossws-roles.properties
+| | | |-- jbossws-users.properties
+| | | |-- jmx-console-roles.properties
+| | | `-- jmx-console-users.properties
+| | |-- standardjboss.xml
+| | |-- standardjbosscmp-jdbc.xml
+| | `-- xmdesc
+| |-- deploy
+| |-- deploy-hasingleton
+| | `-- jms
+| |-- deployers
+| `-- lib
+|-- default
+| |-- conf
+| | |-- bootstrap/
+| | | |-- aop.xml
+| | | |-- bindings.xml
+| | | |-- aop.xml
+| | | |-- classloader.xml
+| | | |-- deployers.xml
+| | | |-- jmx.xml
+| | | |-- profile-repository.xml
+| | | |-- profile.xml
+| | | |-- vfs.xml
+| | |-- bootstrap.xml
+| | |-- bootstrap-norepo.xml
+| | |-- jacorb.properties
+| | |-- java.policy
+| | |-- jax-ws-catalog.xml
+| | |-- jboss-log4j.xml
+| | |-- jboss-service.xml
+| | |-- jbossjta-properties.xml
+| | |-- jndi.properties
+| | |-- login-config.xml
+| | |-- props
+| | | |-- jbossws-roles.properties
+| | | |-- jbossws-users.properties
+| | | |-- jmx-console-roles.properties
+| | | `-- jmx-console-users.properties
+| | |-- standardjboss.xml
+| | |-- standardjbosscmp-jdbc.xml
+| | `-- xmdesc
+| | |-- AttributePersistenceService-xmbean.xml
+| | |-- ClientUserTransaction-xmbean.xml
+| | |-- JNDIView-xmbean.xml
+| | |-- Log4jService-xmbean.xml
+| | |-- NamingBean-xmbean.xml
+| | |-- NamingService-xmbean.xml
+| | |-- TransactionManagerService-xmbean.xml
+| | |-- org.jboss.deployment.JARDeployer-xmbean.xml
+| | |-- org.jboss.deployment.MainDeployer-xmbean.xml
+| | `-- org.jboss.deployment.SARDeployer-xmbean.xml
+| |-- data
+| | |-- hypersonic
+| | |-- jboss.identity
+| | |-- tx-object-store
+| | `-- xmbean-attrs
+| |-- deploy
+| |-- lib
+| |-- log
+| | |-- boot.log
+| | |-- server.log
+| | `-- server.log.2008-08-09
+| |-- tmp
+| `-- work
+| `-- jboss.web
+| `-- localhost
+`-- minimal
+|-- conf
+| |-- bootstrap/
+| |-- bootstrap/aop.xml
+| |-- bootstrap/classloader.xml
+| |-- bootstrap/deployers.xml
+| |-- bootstrap/jmx.xml
+| |-- bootstrap/profile.xml
+| |-- bootstrap.xml
+| |-- jboss-log4j.xml
+| |-- jboss-service.xml
+| |-- jndi.properties
+| `-- xmdesc
+| |-- NamingBean-xmbean.xml
+| `-- NamingService-xmbean.xml
+|-- deploy/
+|-- deploy/hdscanner-jboss-beans.xml
+|-- deployers/
+`-- lib
+|-- jboss-minimal.jar
+|-- jnpserver.jar
+`-- log4j.jar</screen>
+
+</para>
+ <section id="The_default_Server_Configuration_File_Set-Contents_of_conf_directory">
+ <title>Contents of "conf" directory</title>
+ <para>
+ The files in the <literal>conf</literal> directory are explained in the following table.
+ </para>
+ <para>
+ <table id="Contents_of_conf_directory-Contents_of_conf_directory">
+ <title>Contents of "conf" directory</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>bootstrap.xml</literal>
+ </entry>
+ <entry>
+ This is the <literal>bootstrap.xml</literal> file that defines which additional microcontainer deployments will be loaded as part of the bootstrap phase.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>bootstrap/*</literal>
+ </entry>
+ <entry>
+ This directory contains the microcontainer bootstrap descriptors that are referenced from the <literal>bootstrap.xml</literal> file.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>jboss-service.xml</literal> legacy core mbeans that have yet to be ported to either bootstrap deployments, or deploy services. This file will go away in the near future.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossjta-properties.xml</literal>
+ </entry>
+ <entry>
+ <literal>jbossjta-properties.xml</literal> specifies the JBossTS transaction manager default properties.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jndi.properties</literal>
+ </entry>
+ <entry>
+ The <literal>jndi.properties</literal> file specifies the JNDI <literal>InitialContext</literal> properties that are used within the JBoss server when an <literal>InitialContext</literal> is created using the no-arg constructor.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>java.policy</literal>
+ </entry>
+ <entry>
+ A placeholder java security policy file that simply grants all permissions.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-log4j.xml</literal>
+ </entry>
+ <entry>
+ This file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>login-config.xml</literal>
+ </entry>
+ <entry>
+ This file contains sample server side authentication configurations that are applicable when using JAAS based security.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>props/*</literal>
+ </entry>
+ <entry>
+ The <literal>props</literal> directory contains the users and roles property files for the <literal>jmx-console</literal>.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>standardjboss.xml</literal>
+ </entry>
+ <entry>
+ This file provides the default container configurations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>standardjbosscmp-jdbc.xml</literal>
+ </entry>
+ <entry>
+ This file provides a default configuration file for the JBoss CMP engine.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>xmdesc/*-mbean.xml</literal>
+ </entry>
+ <entry>
+ The <literal>xmdesc</literal> directory contains XMBean descriptors for several services configured in the <literal>jboss-service.xml</literal> file.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section id="The_default_Server_Configuration_File_Set-Contents_of_deployers_directory">
+ <title>Contents of "deployers" directory</title>
+ <para>
+ The files in the <literal>deployers</literal> directory are explained in the following table.
+ </para>
+ <para>
+ <table id="Contents_of_deploy_directory-Contents_of_deployers_directory">
+ <title>Contents of "deploy" directory</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>alias-deployers-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers that know how to handle The know how to handle <alias> in <deployment> as true controller context.
+ Meaning they will only get active/installed when their original is installed.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>bsh.deployer</literal>
+ </entry>
+ <entry>
+ This file configures the bean shell deployer, which deploys bean shell scripts as JBoss mbean services.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>clustering-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Clustering-related deployers which add dependencies on needed clustering services to clustered EJB3, EJB2 beans and to distributable web applications.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>dependency-deployers-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for aliases.txt, jboss-dependency.xml jboss-depedency.xml adds generic dependency on whatever. aliases.txt adds human-readable name for deployments, e.g. vfszip://home/blah/.../jboss-5.0.0.GA/server/default/deploy/some-long-name.ear aliased to ales-app.ear.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>directory-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Adds legacy behavior for directories, handling its children as possible deployments.
+ e.g. .sar's lib directory to treat its .jar files as deployments
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ear-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ JavaEE 5 enterprise application related deployers
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Legacy JavaEE 1.4 ejb jar related deployers
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3.deployer</literal>
+ </entry>
+ <entry>
+ This is a deployer that supports JavaEE 5 ejb3, JPA, and application client deployments, .
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hibernate-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for Hibernate -hibernate.xml descriptors, which are similar to Hibernate's .cfg.xml files.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-aop-jboss5.deployer</literal>
+ </entry>
+ <entry>
+ JBossAspectLibrary and base aspects. Why is this in deployers, dependencies?
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-jca.deployer</literal>
+ </entry>
+ <entry>
+ <literal>jboss-jca.deployer</literal> description
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossweb.deployer</literal>
+ </entry>
+ <entry>
+ The JavaEE 5 servlet, JSF, JSP deployers.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossws.deployer</literal>
+ </entry>
+ <entry>
+ The JavaEE 5 webservices endpoint deployers.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jsr77-deployers-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for creating the JSR77 MBeans from the JavaEE components.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>metadata-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for processing the JavaEE metadata from xml, annotations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>seam.deployer</literal>
+ </entry>
+ <entry>
+ Deployer providing integration support for JBoss Seam applications.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>security-deployer-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ Deployers for configuration the security layers of the JavaEE components.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section id="The_default_Server_Configuration_File_Set-Contents_of_deploy_directory">
+ <title>Contents of "deploy" directory</title>
+ <para>
+ The files in the <literal>deploy</literal> directory are explained in the following table.
+ </para>
+ <para>
+ <table id="Contents_of_deploy_directory-Contents_of_deploy_directory">
+ <title>Contents of "deploy" directory</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>ROOT.war</literal>
+ </entry>
+ <entry>
+ <literal>ROOT.war</literal> establishes the '/' root
+ web application. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>cache-invalidation-service.xml</literal>
+ </entry>
+ <entry> This is a service that allows for custom
+ invalidation of the EJB caches via JMS
+ notifications. It is disabled by default. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb2-container-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb2-container-jboss-beans.xml</literal>
+ UserTransaction integration bean for the EJB2
+ containers. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb2-timer-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb2-timer-service.xml</literal> contains
+ the ejb timer service beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-connectors-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-connectors-jboss-beans.xml</literal>
+ EJB3 remoting transport beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-container-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-container-jboss-beans.xml</literal>
+ UserTransaction integration bean for the EJB3
+ containers. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-interceptors-aop.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-interceptors-aop.xml</literal> defines
+ the EJB3 container aspects. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-timer-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>ejb3-timer-service.xml</literal> an
+ alternate quartz based timer service </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>hdscanner-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>hdscanner-jboss-beans.xml</literal> the
+ deploy directory hot deployment scanning bean
+ </entry>
+ </row>
+ <row>
+ <entry>hsqldb-ds.xml</entry>
+ <entry>configures the Hypersonic embedded database
+ service configuration file. It sets up the embedded
+ database and related connection factories. </entry>
+ </row>
+ <row>
+ <entry>http-invoker.sar</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>jboss-local-jdbc.rar</entry>
+ <entry>is a JCA resource adaptor that implements the JCA
+ <literal>ManagedConnectionFactory</literal>
+ interface for JDBC drivers that support the
+ <literal>DataSource</literal> interface but not
+ JCA. </entry>
+ </row>
+ <row>
+ <entry>jboss-xa-jdbc.rar</entry>
+ <entry>JCA resource adaptors for XA DataSources</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossweb.sar</literal>
+ </entry>
+ <entry>an mbean service supporting TomcatDeployer with
+ web application deployment service
+ management.</entry>
+ </row>
+ <row>
+ <entry><literal>jbossws.sar</literal></entry>
+ <entry>provides JEE web services support. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jca-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>jca-jboss-beans.xml</literal> is the
+ application server implementation of the JCA
+ specification. It provides the connection management
+ facilities for integrating resource adaptors into
+ the JBoss server. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jms-ra.rar</literal>
+ </entry>
+ <entry>
+ <literal>jms-ra.rar</literal> JBoss JMS Resource
+ Adapter </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/connection-factories-service.xml</literal>
+ </entry>
+ <entry>configures the DLQ, ExpiryQueue JMS connection
+ factory</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/destinations-service.xml</literal>
+ </entry>
+ <entry>The message persistence store service</entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/destinations-service.xml</literal>
+ </entry>
+ <entry>configures the DLQ, ExpiryQueue JMS destinations.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/jms-ds.xml</literal>
+ </entry>
+ <entry>
+ <literal>jms-ds.xml</literal> configures the
+ JMSProviderLoader and JmsXA inflow resource adaptor
+ connection factory binding. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/legacy-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>legacy-service.xml</literal> configures the
+ JMSProviderLoader and JmsXA inflow resource adaptor
+ connection factory binding. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/messaging-jboss-beans.xml</literal>
+ </entry>
+ <entry> The <literal>messaging-jboss-beans.xml</literal>
+ file configures JMS security and management beans.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/messaging-service.xml</literal>
+ </entry>
+ <entry> The <literal>messaging-service.xml</literal>
+ file configures the core JBoss Messaging service.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>messaging/remoting-bisocket-service.xml</literal>
+ </entry>
+ <entry> The
+ <literal>remoting-bisocket-service.xml</literal>
+ configures the JMS remoting service layer. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jmx-console.war</literal>
+ </entry>
+ <entry> The <literal>jmx-console.war</literal> directory
+ provides the JMX Console. The JMX Console provides a
+ simple web interface for managing the MBean server.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jmx-invoker-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>jmx-invoker-service.xml</literal> is an
+ MBean service archive that exposes a subset of the
+ JMX <literal>MBeanServer</literal> interface methods
+ as an RMI interface to enable remote access to the
+ JMX core functionality. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jmx-remoting.sar</literal>
+ </entry>
+ <entry>
+ <literal>jmx-remoting.sar</literal> is a
+ javax.management.remote implementation providing
+ access to the JMX server. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>legacy-invokers-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>legacy-invokers-service.xml</literal> the
+ legacy detached jmx invoker remoting services.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jsr-88-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>jsr-88-service.xml</literal> provides the
+ JSR 88 remote deployment service. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>mail-ra.rar</literal>
+ </entry>
+ <entry>
+ <literal>mail-ra.rar</literal> is a resource adaptor
+ that provides a JavaMail connector. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>mail-service.xml</literal>
+ </entry>
+ <entry> The <literal>mail-service.xml</literal> file is
+ an MBean service descriptor that provides JavaMail
+ sessions for use inside the JBoss server. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>monitoring-service.xml</literal>
+ </entry>
+ <entry> The <literal>monitoring-service.xml</literal>
+ file configures alert monitors like the console
+ listener and email listener used by JMX
+ notifications. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>profileservice-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>profileservice-jboss-beans.xml</literal>
+ description </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>properties-service.xml</literal>
+ </entry>
+ <entry></entry>
+ </row>
+ <row>
+ <entry>
+ <literal>quartz-ra.rar</literal>
+ </entry>
+ <entry>
+ <literal>quartz-ra.rar</literal> is a resource
+ adaptor for inflow of Quartz events </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>remoting-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>remoting-jboss-beans.xml</literal>
+ contains the unified invokers based on JBoss
+ Remoting. </entry>
+ </row>
+ <row>
+ <entry> The <literal>properties-service.xml</literal>
+ file is an MBean service descriptor that allows for
+ customization of the JavaBeans
+ <literal>PropertyEditor</literal>s as well as
+ the definition of system properties. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>scheduler-service.xml</literal>
+ </entry>
+ <entry> The <literal>scheduler-service.xml</literal> and
+ <literal>schedule-manager-service.xml</literal>
+ files are MBean service descriptors that provide a
+ scheduling type of service. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>security/security-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>security-jboss-beans.xml</literal> security
+ domain related beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>security/security-policies-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>security-policies-jboss-beans.xml</literal>
+ security authorization related beans for ejb and web
+ authorization. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>sqlexception-service.xml</literal>
+ </entry>
+ <entry> The <literal>sqlexception-service.xml</literal>
+ file is an MBean service descriptor for the handling
+ of vendor specific <literal>SQLException</literal>s.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>transaction-jboss-beans.xml</literal>
+ </entry>
+ <entry>
+ <literal>transaction-jboss-beans.xml</literal> JTA
+ transaction manager related beans. </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>transaction-service.xml</literal>
+ </entry>
+ <entry>
+ <literal>transaction-service.xml</literal>
+ ClientUserTransaction proxy service configuration.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>uuid-key-generator.sar</literal>
+ </entry>
+ <entry> The <literal>uuid-key-generator.sar</literal>
+ service provides a UUID-based key generation
+ facility. </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ </section>
+ <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-The_all_Server_Configuration_File_Set">
+ <title>The "all" Server Configuration File Set</title>
+ <para>
+ The "all" server configuration file set is located in the <filename class="directory"><JBoss_Home>/server/all</filename> directory. In addition to the services in the "default" set, the all configuration contains several other services in the <literal>conf/</literal> directory as shown below.
+ </para>
+ <para>
+ <table id="The_all_Server_Configuration_File_Set-Additional_Services_in_conf_directory_for_all_configuration">
+ <title>Additional Services in "conf" directory for "all" configuration</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>cluster-service.xml</literal>
+ </entry>
+ <entry>
+ This service configures clustering communication for most clustered services in JBoss.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>deploy-hasingleton-service.xml</literal>
+ </entry>
+ <entry>
+ This provides the HA singleton service, allowing JBoss to manage services that must be active on only one node of a cluster.
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>httpha-invoker.sar</literal>
+ </entry>
+ <entry>
+ This service provides HTTP tunneling support for clustered environments.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>iiop-service.xml</literal>
+ </entry>
+ <entry>
+ This provides IIOP invocation support.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>juddi-service.sar</literal>
+ </entry>
+ <entry>
+ This service provides UDDI lookup services.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>snmp-adaptor.sar</literal>
+ </entry>
+ <entry>
+ This is a JMX to SNMP adaptor. It allows for the mapping of JMX notifications onto SNMP traps.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+ <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-EJB3_Services_">
+ <title>EJB3 Services </title>
+ <para>
+ The following table explains the files providing ejb3 services.
+ </para>
+ <para>
+ <table id="EJB3_Services_-EJB3_Services">
+ <title>EJB3 Services</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>ejb3-interceptors-aop.xml</literal>
+ </entry>
+ <entry>
+ This service provides the AOP interceptor stack configurations for EJB3 bean types.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3.deployer</literal>
+ </entry>
+ <entry>
+ This service deploys EJB3 applications into JBoss.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jboss-aop-jdk50.deployer</literal>
+ </entry>
+ <entry>
+ This is a Java 5 version of the AOP deployer. The AOP deployer configures the <literal>AspectManagerService</literal> and deploys JBoss AOP applications.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>jbossws.sar</literal>
+ </entry>
+ <entry>
+ This provides Java EE 5 web services support.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ Finally, in the EJB3 "all" configuration there are two additional services.
+ </para>
+ <para>
+ <table id="EJB3_Services_-Additional_Services_in_EJB3_all_Configuration">
+ <title>Additional Services in EJB3 "all" Configuration</title>
+ <tgroup cols="2">
+ <colspec colname="c1" colnum="1" colwidth="4*"/>
+ <colspec colname="c2" colnum="2" colwidth="4*"/>
+ <thead>
+ <row>
+ <entry>
+ File
+ </entry>
+ <entry>
+ Description
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>ejb3-clustered-sfsbcache-service.xml</literal>
+ </entry>
+ <entry>
+ This provides replication and failover for EJB3 stateful session beans.
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>ejb3-entity-cache-service.xml</literal>
+ </entry>
+ <entry>
+ This provides a clustered cache for EJB3 entity beans.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+ <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-Adding_Your_Own_Configuration">
+ <title>Adding Your Own Configuration</title>
+ <para>
+ You can add your own configurations too. The best way to do this is to copy an existing one that is closest to your needs and modify the contents. For example, if you weren’t interested in using messaging, you could copy the <literal>production</literal> directory, renaming it as <literal>myconfig</literal>, remove the <literal>jms</literal> subdirectory and then start JBoss with the new configuration.
+ </para>
+<programlisting>
+./run.sh -c <emphasis role="bold">myconfig</emphasis>
+</programlisting>
+ </section>
+</section>
+ <section id="Starting_and_Stopping_the_Server">
+ <title>Starting and Stopping the Server</title>
+ <section id="Starting_and_Stopping_the_Server-Start_the_Server">
+ <title>Start the Server</title>
+ <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>
+</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>.
+</para>
+
+<para>
+ On starting your server, your screen output should look like the following (accounting for installation directory differences) and contain no error or exception messages:
+</para>
+
+<programlisting>[user at mypc bin]$ ./run.sh
+=========================================================================
+
+ JBoss Bootstrap Environment
+
+ JBOSS_HOME: /home/user/jboss-as-version/jboss-as
+
+ JAVA: java
+
+ JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1503m -Xmx1503m -Dsun.rmi.dgc.client.
+gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true
+
+ CLASSPATH: /home/user/jboss-as-version/jboss-as/bin/run.jar
+
+=========================================================================
+
+</programlisting>
+
+<para>More options for the JBoss AS <literal>run</literal> script are discussed in <xref linkend="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration"/> below.</para>
+ <note>
+ <para>
+ Note that there is no "Server Started" 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 may be observed in the <filename>server.log</filename> file located in the <filename class="directory">server/production/log</filename> subdirectory.
+ </para>
+ </note>
+ </section>
+
+ <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:
+ </para>
+<programlisting>[bin]$ ./run.sh -c minimal
+...
+...
+...
+15:05:40,301 INFO [Server] JBoss (MX MicroKernel) [5.0.0 (build: SVNTag=JBoss_5_0_0 date=200801092200)] Started in 5s:75ms
+</programlisting>
+ </section>
+
+ <section id="Starting_and_Stopping_the_Server-Using_run.sh">
+ <title>Using run.sh</title>
+ <para>
+ The <literal>run</literal> script supports the following options:
+ </para>
+<programlisting>
+usage: run.sh [options]
+-h, --help Show help message
+-V, --version Show version information
+-- Stop processing options
+-D<name>[=<value>] Set a system property
+-d, --bootdir=<dir> Set the boot patch directory; Must be absolute or url
+-p, --patchdir=<dir> Set the patch directory; Must be absolute or url
+-n, --netboot=<url> Boot from net with the given url as base
+-c, --configuration=<name> Set the server configuration name
+-B, --bootlib=<filename> Add an extra library to the front bootclasspath
+-L, --library=<filename> Add an extra library to the loaders classpath
+-C, --classpath=<url> Add an extra url to the loaders classpath
+-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)
+-u, --udp=<ip> UDP multicast address
+-l, --log=<log4j|jdk> Specify the logger plugin type
+</programlisting>
+
+ </section>
+
+ <section id="Starting_and_Stopping_the_Server-Stopping_the_Server">
+ <title>Stopping the Server</title>
+ <para>
+ To shutdown the server, you simply issue a Ctrl-C sequence in the console in which JBoss was started. Alternatively, you can use the <literal>shutdown.sh</literal> command.
+ </para>
+<programlisting>[bin]$ ./shutdown.sh -S</programlisting>
+ <para>
+ The <literal>shutdown</literal> script supports the following options:
+ </para>
+<programlisting>A JMX client to shutdown (exit or halt) a remote JBoss server.
+
+usage: shutdown [options] <operation>
+
+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
+-u, --user=<name> Specify the username for authentication
+-p, --password=<name> Specify the password for authentication
+
+operations:
+-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>
+ <para>
+ Using the shutdown command requires a server configuration that contains the <literal>jmx-invoker-service.xml</literal> service. Hence you cannot use the shutdown command with the <literal>minimal</literal> configuration.
+ </para>
+ </section>
+
+ <section id="Starting_and_Stopping_the_Server-Running_as_a_Service_under_Microsoft_Windows">
+ <title> Running as a Service under Microsoft Windows </title>
+ <para>
+ You can configure the server to run as a service under Microsoft Windows, and configure it to start automatically if desired.
+ </para>
+ <para>
+ Download the <literal>JavaService</literal> package from <ulink url="http://forge.objectweb.org/projects/javaservice/">http://forge.objectweb.org/projects/javaservice/</ulink>.
+ </para>
+ <para>
+ Unzip the package and use the <literal>JBossInstall.bat</literal> file to install the JBoss service. You must set the <literal>JAVA_HOME</literal> and <literal>JBOSS_HOME</literal> environment variables to point to the <literal>jdk</literal> and <literal>jboss-as</literal> directories before running <literal>JBossInstall.bat</literal>. Run <literal>JBossInstall.bat</literal> with the following syntax:
+ </para>
+<screen>JBossInstall.bat <replaceable><depends></replaceable> [-auto | -manual]</screen>
+ <para>
+ Where <replaceable><depends></replaceable> is the name of any service that the JBoss AS server depends on, such as the <literal>mysql</literal> database service.
+ </para>
+ <para>
+ Once the service is installed the server can be started by using the command <literal>net start JBoss</literal>, and stopped with the command <literal>net stop JBoss</literal>.
+ </para>
+ <para>
+ Please refer to the documentation included in the <literal>JavaService</literal> package for further information.
+ </para>
+ </section>
+</section>
+<!-- end embedded sections -->
+
+
+</section>
+
+ <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"/>. You should see something similar to <xref linkend="The_JMX_Console-View_of_the_JMX_Management_Console_Web_Application"/>.
+ </para>
+ <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>
+ For example, find the <literal>service=JNDIView</literal> link and click on it. This particular MBean provides a service to allow you to view the structure of the JNDI namespaces within the server. Now find the operation called <literal>list</literal> near the bottom of the MBean view page and click the <literal>invoke</literal> button. The operation returns a view of the current names bound into the JNDI tree, which is very useful when you start deploying your own applications and want to know why you can’t resolve a particular EJB name.
+ </para>
+ <figure id="The_JMX_Console-View_of_the_JMX_Management_Console_Web_Application">
+ <title>View of the JMX Management Console Web Application</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jmx-console.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Look at some of the other MBeans and their listed operations; try changing some of the configuration attributes and see what happens. With a very few exceptions, none of the changes made through the console are persistent. The original configuration will be reloaded when you restart JBoss, so you can experiment freely without doing any permanent damage.
+ </para>
+ <note>
+ <para>
+ If you installed JBoss using the graphical installer, the JMX Console will prompt you for a username and password before you can access it. If you installed using other modes, you can still configure JMX Security manually. We will show you how to secure your console in <xref linkend="Basic_Configuration_Issues-Security_Service"/>.
+ </para>
+ </note>
+ </section>
+ <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.
+ </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>
+ </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>
+ This is hot-deployment in action.
+ </para>
+ </section>
+ <section id="The_JBoss_Server___A_Quick_Tour-Basic_Configuration_Issues">
+ <title>Basic Configuration Issues</title>
+ <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/production</filename>, for example).
+ </para>
+ <section id="Basic_Configuration_Issues-Core_Services">
+ <title>Core Services</title>
+ <para>
+ The core services specified in the <filename>conf/jboss-service.xml</filename> file are started first when the server starts up. If you have a look at this file in an editor you will see MBeans for various services including logging, security, JNDI, JNDIView etc. Try commenting out the entry for the <literal>JNDIView</literal> service.
+ </para>
+ <para>
+ Note that because the mbeans definition had nested comments, we had to comment out the mbean in two sections, leaving the original comment as it was.
+ </para>
+<programlisting>
+<!-- Section 1 commented out
+<mbean code="org.jboss.naming.JNDIView"
+ name="jboss:service=JNDIView"
+ xmbean-dd="resource:xmdesc/JNDIView-xmbean.xml">
+-->
+ <!-- The HANamingService service name -->
+<!-- Section two commented out
+ <attribute name="HANamingService">jboss:service=HAJNDI</attribute></mbean>
+-->
+
+</programlisting>
+ <para>
+ If you then restart JBoss, you will see that the <literal>JNDIView</literal> service no longer appears in the JMX Management Console (JMX Console) listing. In practice, you should rarely, if ever, need to modify this file, though there is nothing to stop you adding extra MBean entries in here if you want to. The alternative is to use a separate file in the <filename class="directory">deploy</filename> directory, which allows your service to be hot deployable.
+ </para>
+ </section>
+
+ <section id="Basic_Configuration_Issues-Logging_Service">
+ <title>Logging Service</title>
+ <para>
+ In JBoss <literal>log4j</literal> is used for logging. If you are not familiar with the <literal>log4j</literal> package and would like to use it in your applications, you can read more about it at the Jakarta web site (<ulink url="http://jakarta.apache.org/log4j/"/>).
+ </para>
+ <para>
+ 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 5 basic log levels used: <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.
+ </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.
+ </para>
+<programlisting><!-- Limit JBoss categories to INFO -->
+<category name="org.jboss">
+ <priority value="<emphasis role="bold">INFO</emphasis>"/>
+</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.
+ </para>
+ <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>
+<programlisting><appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender">
+ <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
+ <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/>
+ <param name="Append" value="false"/>
+ <param name="MaxFileSize" value="500KB"/>
+ <param name="MaxBackupIndex" value="1"/>
+
+ <layout class="org.apache.log4j.PatternLayout">
+ <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
+ </layout>
+</appender>
+
+<category name="org.jboss.ejb.plugins.cmp">
+ <priority value="DEBUG" />
+ <appender-ref ref="CMP"/>
+</category>
+</programlisting>
+ <para>
+ This creates a new file appender and specifies that it should be used by the logger (or category) for the package <literal>org.jboss.ejb.plugins.cmp</literal>.
+ </para>
+ <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>
+ </section>
+
+ <section id="Basic_Configuration_Issues-Security_Service">
+ <title>Security Service</title>
+ <para>
+ The security domain information is stored in the file <filename>conf/login-config.xml</filename> as a list of named security domains, each of which specifies a number of JAAS <footnote><para>
+ The Java Authentication and Authorization Service. JBoss uses JAAS to provide pluggable authentication modules. You can use the ones that are provided or write your own if you have more specific requirements.
+ </para>
+ </footnote> login modules which are used for authentication purposes in that domain. When you want to use security in an application, you specify the name of the domain you want to use in the application’s JBoss-specific deployment descriptors, <filename>jboss.xml</filename> (used in defining jboss specific configurations for an application) and/or <filename>jboss-web.xml</filename> (used in defining jboss for a Web application. We'll quickly look at how to do this to secure the JMX Console application which ships with JBoss.
+ </para>
+ <para>
+ Almost every aspect of the JBoss server can be controlled through the JMX Console, so it is important to make sure that, at the very least, the application is password protected. Otherwise, any remote user could completely control your server. To protect it, we will add a security domain to cover the application.
+ <!--<footnote><para>
+ If you installed JBoss using the Graphical Installer and set the JMX Security up, then you will not have to uncomment the sections, because they are already uncommented. Additionally, the admin password will be set up to whatever you had specified.
+ </para>
+ </footnote>-->
+
+ This can be done in the <filename>jboss-web.xml</filename> file for the JMX Console, which can be found in <filename class="directory">deploy/jmx-console.war/WEB-INF/</filename> directory. Uncomment the <literal>security-domain</literal> in that file, as shown below.
+ </para>
+ <para>
+<programlisting><jboss-web>
+ <security-domain>java:/jaas/jmx-console</security-domain>
+</jboss-web>
+</programlisting>
+ </para>
+ <para>
+ This links the security domain to the web application, but it doesn't tell the web application what security policy to enforce, what URLs are we trying to protect, and who is allowed to access them. To configure this, go to the <filename>web.xml</filename> file in the same directory and uncomment the <literal>security-constraint</literal> that is already there. This security constraint will require a valid user name and password for a user in the <literal>JBossAdmin</literal> group.
+ </para>
+<programlisting><!--
+ A security constraint that restricts access to the HTML JMX console
+ to users with the role JBossAdmin. Edit the roles to what you want and
+ uncomment the WEB-INF/jboss-web.xml/security-domain element to enable
+ secured access to the HTML JMX console.
+-->
+<security-constraint>
+ <web-resource-collection>
+ <web-resource-name>HtmlAdaptor</web-resource-name>
+ <description>
+ An example security config that only allows users with the
+ role JBossAdmin to access the HTML JMX console web application
+ </description>
+ <url-pattern>/*</url-pattern>
+ <http-method>GET</http-method>
+ <http-method>POST</http-method>
+ </web-resource-collection>
+ <auth-constraint>
+ <role-name>JBossAdmin</role-name>
+ </auth-constraint>
+</security-constraint>
+</programlisting>
+ <para>
+ That's great, but where do the user names and passwords come from? They come from the <literal>jmx-console</literal> security domain we linked the application to. We have provided the configuration for this in the <filename>conf/login-config.xml</filename>.
+ </para>
+ <para>
+<programlisting><application-policy name="jmx-console">
+ <authentication>
+ <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
+ flag="required">
+ <module-option name="usersProperties">
+ props/jmx-console-users.properties
+ </module-option>
+ <module-option name="rolesProperties">
+ props/jmx-console-roles.properties
+ </module-option>
+ </login-module>
+ </authentication>
+</application-policy>
+</programlisting>
+ </para>
+ <para>
+ This configuration uses a simple file based security policy. The configuration files are found in the <filename class="directory">conf/props</filename> directory of your server configuration. The usernames and passwords are stored in the <literal>conf/props/jmx-console-users.properties</literal> file and take the form "<literal>username=password</literal>". To assign a user to the <literal>JBossAdmin</literal> group add "<literal>username=JBossAdmin</literal>" to the <literal>jmx-console-roles.properties</literal> file (additional roles on that username can be added comma separated). The existing file creates an <literal>admin</literal> user with the password <literal>admin</literal>. For security, please either remove the user or change the password to a stronger one.
+ </para>
+ <para>
+ JBoss will re-deploy the JMX Console whenever you update its <filename>web.xml</filename>. You can check the server console to verify that JBoss has seen your changes. If you have configured everything correctly and re-deployed the application, the next time you try to access the JMX Console, it will ask you for a name and password. <footnote><para>
+ Since the username and password are session variables in the web browser you may need to restart your browser to use the login dialog window.
+ </para>
+ </footnote>
+ </para>
+ <para>
+ The JMX Console isn't the only web based management interface to JBoss. There is also the Web Console. Although it's a Java applet, the corresponding web application can be secured in the same way as the JMX Console. The Web Console is in the file <filename>deploy/management/console-mgr.sar/web-console.war.</filename>. The only difference is that the Web Console is provided as a simple WAR file instead of using the exploded directory structure that the JMX Console did. The only real difference between the two is that editing the files inside the WAR file is a bit more cumbersome.
+ </para>
+ </section>
+
+ <section id="Basic_Configuration_Issues-Additional_Services">
+ <title>Additional Services</title>
+ <para>
+ The non-core, hot-deployable services are added to the <filename class="directory">deploy</filename> directory. They can be either XML descriptor files, <filename>*-service.xml</filename>, or JBoss Service Archive (SAR) files. SARs contain both the XML descriptor and additional resources the service requires (e.g. classes, library JAR files or other archives), all packaged up into a single archive.
+ </para>
+ <para>
+ Detailed information on all these services can be found in the <emphasis>JBoss Application Server: Configuration Guide</emphasis>, which also provides comprehensive information on server internals and the implementation of services such as JTA and the J2EE Connector Architecture (JCA).
+ </para>
+ </section>
+
+ </section>
+
+ <!--<section id="The_JBoss_Server___A_Quick_Tour-The_Web_Container___Tomcat">
+ <title>The Web Container - Tomcat</title>
+ <para>
+ JBoss Application Server comes with Tomcat as the default web container.
+ </para>
+ <para>
+ </para>
+ </section>-->
+</chapter>
+ <chapter id="EJB3_Caveats">
+ <title>
+ EJB3 Caveats in JBoss Application Server 5.0.0
+ </title>
+
+ <para>
+ There are a number of implementation features that you should be aware of when developing applications for JBoss Application Server 5.0.0.
+ </para>
+
+ <section>
+ <title>
+ Unimplemented features
+ </title>
+
+ <para>
+ The Release Notes for JBoss Application Server contain information on EJB3 features that are not yet implemented, or partially implemented. The Release Notes include links to issues in JIRA for information on workarounds and further details.
+ </para>
+ </section>
+
+
+ <section id="EJB3_Support">
+ <title>
+ Referencing EJB3 Session Beans from non-EJB3 Beans
+ </title>
+
+ <para>
+ JBoss Application Server 5 fully supports the entire Java 5 Enterprise Edition specification. JBoss Application Server 4.2.2 implemented EJB3 functionality by way of an EJB MBean container running as a plugin in the JBoss Application Server. This had certain implications for application development.
+ </para>
+
+ <para>
+ The EJB3 plugin injects references to an EntityManager and @EJB references from one EJB object to another. However this support is limited to the EJB3 MBean and the JAR files it manages. Any JAR files which are loaded from a WAR (such as Servlets, JSF backing beans, and so forth) do not undergo this processing. The Java 5 Enterprise Edition standard specifies that a Servlet can reference a Session Bean through an @EJB annotated reference, this was not implemented in JBoss Application Server 4.2.2.
+ </para>
+<!--
+ <para>
+ In order to access an EJB3 Session Bean from a Servlet or JSF Backing Bean you will need to do one of two things:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <formalpara>
+ <title>
+ Without Seam - JNDI Lookup
+ </title>
+
+ <para>
+ Without utilizing the Seam framework that is part of JBoss Application Server you will need to use an explicit JNDI lookup to access the EJB3 Session Bean. You can see an example of this being done in the <filename>TodoBean.java</filename> file in the <literal>jsfejb3</literal> example application, described in <xref linkend="Sample_JSF_EJB3_Application"/>.
+ </para>
+ </formalpara>
+
+<programlisting>private TodoDaoInt getDao () {
+ try {
+ InitialContext ctx = new InitialContext();
+ return (TodoDaoInt) ctx.lookup("jsfejb3/TodoDao/local");
+ } catch (Exception e) {
+ e.printStackTrace();
+ throw new RuntimeException("couldn't lookup Dao", e);
+ }
+ }</programlisting>
+
+ <para>
+ <literal>ctx.lookup("jsfejb3/TodoDao/local");</literal> is the method used to reference the EJB3 Session Bean. The form is: <replaceable>AppName</replaceable>/<replaceable>SessionBeanName</replaceable>/local.
+ </para>
+ </listitem>
+
+ <listitem>
+ <formalpara>
+ <title>
+ With Seam - Leave it to the Seam Framework
+ </title>
+
+ <para>
+ When you are using the Seam Framework you don't need to worry about this. Because the Seam framework manages the interaction of Beans anyway, it already automates this type of interaction.
+ </para>
+ </formalpara>
+
+ <para>
+ Refer to <xref linkend="Using_Seam"/> for a more detailed explanation of achieving this using the Seam framework.
+ </para>
+ </listitem>
+ </orderedlist> -->
+ </section>
+</chapter>
+ <chapter id="About_the_Example_Applications">
+ <title>About the Example Applications</title>
+ <para>
+ In this guide, we make use of a simple web application to show the use of JSF-EJB3 components. We then illustrate how to use Seam to integrate the JSF and EJB3 components. The example applications (source code) come with this guide and you can find them located in the <filename class="directory">JBOSS_DIST/doc/examples</filename> directory. You can also download the sample applications from <ulink url="http://www.redhat.com/docs/manuals/jboss"/>. We use two examples in this book:
+ <itemizedlist>
+ <listitem>
+ <para>A simple "TODO" application to create, view and edit tasks - implemented using JSF and EJB3;
+ </para>
+ </listitem>
+ <listitem>
+ <para>The same application using the SEAM framework.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If you installed the documentation on your hard drive, then the first example can be found in the <filename class="directory">JBOSS_DIST/doc/examples/jsfejb3</filename> directory (if you download the examples the path is: <filename class="directory">gettingstarted/jsfejb3</filename>). We will see how to build this example using the <filename>build.xml</filename> file present here and also how to deploy the application. We will also cover in detail the workings of the .java, .xml and .properties files.
+ </para>
+ <para>
+ The second example used in this guide can be found in the <filename class="directory">JBOSS_DIST/doc/examples/seamejb3</filename> directory. Using a simple "TODO" application we will illustrate how Seam ties together the database, the web interface and the EJB3 business logic in a web application. We will use the <filename>build.xml</filename> file present here to compile and build our Seam application.
+ </para>
+ <para>
+ Within the <filename class="directory">JBOSS_DIST/doc/examples/<seamejb3|jsfejb3></filename> directory, you will find the following sub-directories: <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">src</emphasis>: contains the Java source code files.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">view</emphasis>: contains the web pages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">resources</emphasis>: contains all the configuration files used.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <section id="About_the_Example_Applications-Install_Ant">
+ <title>Install Ant</title>
+ <para>
+ To compile and package the examples, you must have Apache Ant 1.6+ installed in your machine. You can download it from <ulink url="http://ant.apache.org"/> and have it installed in few steps: <itemizedlist>
+ <listitem>
+ <para>
+ Unzip the downloaded file to the directory of your choice.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Create an environment variable called <literal>ANT_HOME</literal> pointing to the Ant installation directory. You can do this by adding the following line to your <filename>.bashrc</filename> file (substituting with the actual location of the ant directory on your system): <programlisting>
+export ANT_HOME=/home/user/apache-ant-1.7.0
+</programlisting>
+ </para>
+
+ <para>
+ On Windows you do this by opening the Control Panel from the Start Menu, switching it to classic view if necessary, then opening System/Advanced/Environment Variables. Create a new variable, call it <literal>ANT_HOME</literal> and set it to be the ant directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add <literal>$ANT_HOME/bin</literal> to the system path to be able to run <literal>ant</literal> from the command line. You can do this by adding the following line to your <filename>.bashrc</filename> file: <programlisting>
+export PATH=$PATH:$ANT_HOME/bin
+</programlisting>
+ </para>
+ <para>
+ On Windows you do this by opening the Control Panel from the Start Menu, switching it to classic view if necessary, then editing the <literal>PATH</literal> environment variable found in System/Advanced/Environment Variables/System Variables/Path. Add a semicolon and the path to the ant <filename class="directory">bin</filename> directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Verify your Ant installation. To do this type <literal> ant -version</literal> at the command prompt. Your output should look something like this: <programlisting>
+Apache Ant version 1.7.0 compiled on December 13 2006
+</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</chapter>
+ <chapter id="Sample_JSF_EJB3_Application">
+ <title>Sample JSF-EJB3 Application</title>
+ <para>
+ We use a simple "TODO" application to show how JSF and EJB3 work together in a web application. The "TODO" application works like this: You can create a new 'todo' task item using the "Create" web form. Each 'todo' item has a 'title' and a 'description'. When you submit the form, the application saves your task to a relational database. Using the application, you can view all 'todo' items, edit/delete an existing 'todo' item and update the task in the database.
+ </para>
+ <para>
+ The sample application comprises the following components:
+ <itemizedlist>
+ <listitem>
+ <para>
+ Entity objects - These objects represent the data model; the properties in the object are mapped to column values in relational database tables.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ JSF web pages - The web interface used to capture input data and display result data. The data fields on these web pages are mapped to the data model via the JSF Expression Language (EL).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ EJB3 Session Bean - This is where the functionality is implemented. We make use of a Stateless Session Bean.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <section id="Sample_JSF_EJB3_Application-Data_Model">
+ <title>Data Model</title>
+ <para>
+ Let's take a look at the contents of the Data Model represented by the <literal>Todo</literal> class in the <literal>Todo.java</literal> file. Each instance of the <literal>Todo</literal> class corresponds to a row in the relational database table. The 'Todo' class has three properties: id, title and description. Each of these correspond to a column in the database table.
+ </para>
+ <para>
+ The 'Entity class' to 'Database Table' mapping information is specified using EJB3 Annotations in the 'Todo' class. This eliminates the need for XML configuration and makes it a lot clearer. The <literal>@Entity</literal> annotation defines the <literal>Todo</literal> class as an Entity Bean. The <literal>@Id</literal> and <literal>@GeneratedValue</literal> annotations on the <literal>id</literal> property indicate that the <literal>id</literal> column is the primary key and that the server automatically generates its value for each <literal>Todo</literal> object saved into the database.
+ </para>
+ <para>
+<programlisting>
+ at Entity
+public class Todo implements Serializable {
+
+ private long id;
+ private String title;
+ private String description;
+
+ public Todo () {
+ title ="";
+ description ="";
+ }
+
+ @Id @GeneratedValue
+ public long getId() { return id;}
+ public void setId(long id) { this.id = id; }
+
+ public String getTitle() { return title; }
+ public void setTitle(String title) {this.title = title;}
+
+ public String getDescription() { return description; }
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+}
+</programlisting>
+ </para>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-JSF_Web_Pages">
+ <title>JSF Web Pages</title>
+ <para>
+ In this section we will show you how the web interface is defined using JSF pages. We will also see how the data model is mapped to the web form using JSF EL. Using the #{...} notation to reference Java objects is called <emphasis role="bold">JSF EL</emphasis> (JSF Expression Language). Lets take a look at the pages used in our application:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">index.xhtml</emphasis>: This page displays two options: 1. Create New Todo 2. Show all Todos. When you click on the Submit button the corresponding action is invoked.
+ </para>
+ <para>
+<programlisting>
+<h:form>
+<ul>
+ <li><h:commandLink type="submit" value="Create New Todo" action="create"/></li>
+ <li><h:commandLink type="submit" value="Show All Todos" action="todos"/></li>
+</ul>
+</h:form>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">create.xhtml</emphasis>: When you try to create a new task, this JSF page captures the input data. We use the <literal>todoBean</literal> to back the form input text fields. The #{todoBean.todo.title} symbol refers to the "title" property of the "todo" object in the "TodoBean" class. The #{todoBean.todo.description} symbol refers to the "description" property of the "todo" object in the "TodoBean" class. The #{todoBean.persist} symbol refers to the "persist" method in the "TodoBean" class. This method creates the "Todo" instance with the input data (title and description) and persists the data.
+ </para>
+
+<programlisting role="xml">
+<h:form id="create">
+<table>
+ <tr>
+ <td>Title:</td>
+ <td>
+ <h:inputText id="title" value="#{todoBean.todo.title}" size="15">
+ <f:validateLength minimum="2"/>
+ </h:inputText>
+ </td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>
+ <h:inputTextarea id="description" value="#{todoBean.todo.description}">
+ <f:validateLength minimum="2" maximum="250"/>
+ </h:inputTextarea>
+ </td>
+ </tr>
+</table>
+<h:commandButton type="submit" id="create" value="Create"
+ action="#{todoBean.persist}"/>
+</h:form>
+</programlisting>
+
+<para>
+ <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_create_todo"/> shows the "Create Todo" web page with the input fields mapped to the data model.
+ </para>
+ <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_create_todo">
+ <title>The "Create Todo" web page </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jsfejb3_create_todo.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">todos.xhtml</emphasis>: This page displays the list of all "todos" created. There is also an option to choose a "todo" item for 'edit' or 'delete'.
+ </para>
+ <para>
+ The list of all 'todos' is fetched by #{todoBean.todos} symbol referring to the 'getTodos()' property in the 'TodoBean' class. The JSF <literal>dataTable</literal> iterates through the list and displays each <literal>Todo</literal> object in a row. The 'Edit' option is available across each row. The #{todo.id} symbol represents the "id" property of the "todo" object.
+ </para>
+ <para>
+<programlisting>
+<h:form>
+<h:dataTable value="#{todoBean.todos}" var="todo">
+ <h:column>
+ <f:facet name="header">Title</f:facet>
+ #{todo.title}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ #{todo.description}
+ </h:column>
+ <h:column>
+ <a href="edit.faces?tid=#{todo.id}">Edit</a>
+ </h:column>
+</h:dataTable>
+<center>
+ <h:commandButton action="create"
+ value="Create New Todo" type="submit"/>
+</center>
+</h:form>
+</programlisting>
+ <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_todos"/> shows the "Show All Todos" web page with the data fields mapped to the data model.
+ </para>
+ <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_todos">
+ <title>The "Show All Todos" web page </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jsfejb3_todos.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">edit.xhtml</emphasis>: This page allows you to edit the "todo" item's 'title' and 'description' properties. The #{todoBean.update} and #{todoBean.delete} symbols represent the "update" and "delete" methods in the "TodoBean" class.
+ </para>
+
+<programlisting role="xml">
+<h2>Edit #{todoBean.todo.title}</h2>
+<h:form id="edit">
+<input type="hidden" name="tid" value="#{todoBean.todo.id}"/>
+<table>
+ <tr>
+ <td>Title:</td>
+ <td>
+ <h:inputText id="title" value="#{todoBean.todo.title}" size="15">
+ <f:validateLength minimum="2"/>
+ </h:inputText>
+ </td>
+ </tr>
+ <tr>
+ <td>Description:</td>
+ <td>
+ <h:inputTextarea id="description" value="#{todoBean.todo.description}">
+ <f:validateLength minimum="2" maximum="250"/>
+ </h:inputTextarea>
+ </td>
+ </tr>
+</table>
+<h:commandButton type="submit" id="update" value="Update"
+ action="#{todoBean.update}"/>
+<h:commandButton type="submit" id="delete" value="Delete"
+ action="#{todoBean.delete}"/>
+</h:form>
+</programlisting>
+<para>
+ <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_edit_todo"/> shows the "Edit Todo" web page with the mapping to the data model.
+ </para>
+ <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_edit_todo">
+ <title>The "Edit Todo" web page </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/jsfejb3_edit_todo.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <note>
+ <para>
+ We have used XHTML pages in the sample applications because we recommend using Facelets instead of JSP to render JSF view pages.
+ </para>
+ </note>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-EJB3_Session_Beans">
+ <title>EJB3 Session Beans</title>
+ <para>
+ EJB 3.0 is one of the major improvements introduced with Java EE 5.0. It aims at reducing the complexity of older versions of EJB and simplifies Enterprise Java development and deployment. You will notice that to declare a class as a 'Session Bean' you simply have to annotate it. Using annotations eliminates the complexity involved with too many deployment descriptors. Also the only interface an EJB3 Session Bean requires is a business interface that declares all the business methods that must be implemented by the bean.
+ </para>
+ <para>
+ We will explore the two important source files associated with the Bean implementation in our application: <literal>TodoDaoInt.java</literal> and <literal>TodoDao.java</literal>.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">Business interface</emphasis>: <literal>TodoDaoInt.java</literal>
+ </para>
+ <para>We define here the methods that need to be implemented by the bean implementation class. Basically, the business methods that will be used in our application are defined here.
+
+<programlisting role="JAVA">
+public interface TodoDaoInt {
+
+ public void persist (Todo todo);
+ public void delete (Todo todo);
+ public void update (Todo todo);
+
+ public List <Todo> findTodos ();
+ public Todo findTodo (String id);
+}
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">Stateless Session Bean</emphasis>: <literal>TodoDao.java</literal>
+ </para>
+ <para>
+ The <literal>@Stateless</literal> annotation marks the bean as a stateless session bean. In this class, we need to access the Entity bean <literal>Todo</literal> defined earlier. For this we need an <literal>EntityManager</literal>. The <literal>@PersistenceContext</literal> annotation tells the JBoss Server to inject an entity manager during deployment.
+<programlisting>
+ at Stateless
+public class TodoDao implements TodoDaoInt {
+
+ @PersistenceContext
+ private EntityManager em;
+
+ public void persist (Todo todo) {
+ em.persist (todo);
+ }
+
+ public void delete (Todo todo) {
+ Todo t = em.merge (todo);
+ em.remove( t );
+ }
+
+ public void update (Todo todo) {
+ em.merge (todo);
+ }
+
+ public List <Todo> findTodos () {
+ return (List <Todo>) em.createQuery("select t from Todo t")
+ .getResultList();
+ }
+
+ public Todo findTodo (String id) {
+ return (Todo) em.find(Todo.class, Long.parseLong(id));
+ }
+
+}
+</programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-Configuration_and_Packaging">
+ <title>Configuration and Packaging</title>
+ <para>
+ We will build the sample application using Ant and explore the configuration and packaging details. Please install Ant if currently not installed on your computer.
+ </para>
+ <section id="Building_The_Application">
+ <title>Building The Application</title>
+ <para>Let's look at building the example application and then explore the configuration files in detail.
+ </para>
+ <para>
+ In <xref linkend="About_the_Example_Applications"/>, we looked at the directory structure of the <literal>jsfejb3</literal> sample application. At the command line, go to the <literal>jsfejb3</literal> directory. There you will see a <literal>build.xml</literal> file. This is our Ant build script for compiling and packaging the archives. To build the application, you need to first of all edit the <literal>build.xml</literal> file and edit the value of <literal>jboss-dist</literal> to reflect the location where the JBoss Application Server is installed. Once you have done this, just type the command <literal>ant</literal> and your output should look like this:
+ </para>
+<screen>[user at localhost jsfejb3]$ ant
+Buildfile: build.xml
+
+compile:
+ [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/classes
+ [javac] Compiling 4 source files to /home/user/Desktop/gettingstarted/jsfejb3/build/classes
+ [javac] Note: /jboss/gettingstarted/jsfejb3/src/TodoDao.java uses unchecked or unsafe operations.
+ [javac] Note: Recompile with -Xlint:unchecked for details.
+
+war:
+ [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/jars
+ [war] Building war: /jboss/gettingstarted/jsfejb3/build/jars/app.war
+
+ejb3jar:
+ [jar] Building jar: /jboss/gettingstarted/jsfejb3/build/jars/app.jar
+
+ear:
+ [ear] Building ear: /jboss/gettingstarted/jsfejb3/build/jars/jsfejb3.ear
+
+main:
+
+BUILD SUCCESSFUL
+Total time: 3 seconds
+
+</screen>
+ <para>
+ If you get the BUILD SUCCESSFUL message, you will find a newly created <literal>build</literal> directory with 2 sub-directories in it: <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis role="bold">classes</emphasis>: containing the compiled class files.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis role="bold">jars</emphasis>: containing three archives - <literal>app.jar</literal>, <literal>app.war</literal> and <literal>jsfejb3.ear</literal>. <itemizedlist>
+ <listitem>
+ <para>
+ app.jar : EJB code and descriptors.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ app.war : web application which provides the front end to allow users to interact with the business components (the EJBs). The web source (HTML, images etc.) contained in the <literal>jsfejb3/view</literal> directory is added unmodified to this archive. The Ant task also adds the <literal>WEB-INF</literal> directory that contains the files which aren’t meant to be directly accessed by a web browser but are still part of the web application. These include the deployment descriptors (<literal>web.xml</literal>) and extra jars required by the web application.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ jsfejb3.ear : The EAR file is the complete application, containing the EJB modules and the web module. It also contains an additional descriptor, <literal>application.xml</literal>. It is also possible to deploy EJBs and web application modules individually but the EAR provides a convenient single unit.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="Configuration_Files">
+ <title>Configuration Files</title>
+ <para>
+ Now that we have built the application, lets take a closer look at some of the important Configuration files. We have built the final archive ready for deployment - <literal>jsfejb3.ear</literal>. The contents of your EAR file should look like this:
+ </para>
+<programlisting>
+jsfejb3.ear
+|+ app.jar // contains the EJB code
+ |+ import.sql
+ |+ Todo.class
+ |+ TodoDao.class
+ |+ TodoDaoInt.class
+ |+ META-INF
+ |+ persistence.xml
+|+ app.war // contains web UI
+ |+ index.html
+ |+ index.xhtml
+ |+ create.xhtml
+ |+ edit.xhtml
+ |+ todos.xhtml
+ |+ TodoBean.class
+ |+ style.css
+ |+ META-INF
+ |+ WEB-INF
+ |+ faces-config.xml
+ |+ navigation.xml
+ |+ web.xml
+|+ META-INF // contains the descriptors
+ |+ application.xml
+ |+ jboss-app.xml
+</programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>application.xml</literal>: This file lists the JAR files in the EAR (in our case <literal>app.jar</literal>) and tells the JBoss server what files to look for and where. The root URL for the application is also specified in this file as 'context-root'.
+<programlisting>
+<application>
+ <display-name>Sample Todo</display-name>
+ <module>
+ <web>
+ <web-uri>app.war</web-uri>
+ <context-root>/jsfejb3</context-root>
+ </web>
+ </module>
+ <module>
+ <ejb>app.jar</ejb>
+ </module>
+</application>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>jboss-app.xml</literal>: Every EAR application should specify a unique string name for the class loader. In our case, we use the application name 'jsfejb3' as the class loader name.
+<programlisting>
+<jboss-app>
+ <loader-repository>
+ jsfejb3:archive=jsfejb3.ear
+ </loader-repository>
+</jboss-app>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>app.jar</literal>: This contains EJB3 Session Bean and Entity Bean classes and the related configuration files. In addition, the <literal>persistence.xml</literal> file configures the back-end data source (in our case the default HSQL database) for the <literal>EntityManager</literal>.
+<programlisting>
+<persistence>
+ <persistence-unit name="helloworld">
+ <provider>org.hibernate.ejb.HibernatePersistence</provider>
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <properties>
+ <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
+ <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
+ </properties>
+ </persistence-unit>
+</persistence>
+</programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>app.war</literal>: This contains the Web UI files packaged according to the Web Application aRchive (WAR) specification. It contains all the web pages and the required configuration files. The <literal>web.xml</literal> file is an important file for all JAVA EE web applications. It is the web deployment descriptor file. The <literal>faces-config.xml</literal> file is the configuration file for JSF. The <literal>navigation.xml</literal> file contains the rules for JSF page navigation.
+ </para>
+<programlisting>
+//faces-config.xml
+<faces-config>
+ <application>
+ <view-handler>
+ com.sun.facelets.FaceletViewHandler
+ </view-handler>
+ </application>
+ <managed-bean>
+ <description>Dao</description>
+ <managed-bean-name>todoBean</managed-bean-name>
+ <managed-bean-class>TodoBean</managed-bean-class>
+ <managed-bean-scope>request</managed-bean-scope>
+ </managed-bean>
+</faces-config>
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
+ <section id="The_Database">
+ <title>The Database</title>
+ <section id="The_Database-Creating_the_Database_Schema">
+ <title>Creating the Database Schema</title>
+ <para>
+ To pre-populate the database, we have supplied SQL Code (<literal>import.sql</literal>) to run with HSQL in the <literal>examples/jsfejb3/resources</literal> directory. When you build the application using Ant, this is packaged in the app.jar file within the jsfejb3.ear file. When the application is deployed, you should be able to view the pre-populated data.
+ </para>
+ </section>
+ <section id="The_Database-The_HSQL_Database_Manager_Tool">
+ <title>The HSQL Database Manager Tool</title>
+ <para>
+ Just as a quick aside at this point, start up the JMX console application and click on the <literal>service=Hypersonic</literal> link which you’ll find under the section <literal>jboss</literal>. If you can’t find this, make sure the Hypersonic service is enabled in the <literal>hsqldb-ds.xml</literal> file.
+ </para>
+ <para>
+ This will take you to the information for the Hypersonic service MBean. Scroll down to the bottom of the page and click the <literal>invoke</literal> button for the <literal>startDatabaseManager()</literal> operation. This starts up the HSQL Manager, a Java GUI application which you can use to manipulate the database directly.
+ </para>
+ <figure id="The_HSQL_Database_Manager_Tool-The_HSQL_Database_Manger_">
+ <title>The HSQL Database Manger </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/hsql-manager.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+ <section id="Sample_JSF_EJB3_Application-Deploying_the_Application">
+ <title>Deploying the Application</title>
+ <para>
+ Deploying an application in JBoss is simple and easy. You just have to copy the EAR file to the <literal>deploy</literal> directory in the 'server configuration' directory of your choice. Here, we will deploy it to the 'default' configuration, so we copy the EAR file to the <literal>JBOSS_DIST/jboss-as/server/default/deploy</literal> directory.
+ </para>
+ <para>
+ You should see something close to the following output from the server:
+ </para>
+<screen>
+15:32:23,997 INFO [EARDeployer] Init J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
+15:32:24,212 INFO [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
+entity.PersistenceUnitDeployment
+15:32:24,213 INFO [JmxKernelAbstraction] installing MBean: persistence.units:ear=
+jsfejb3.ear,jar=app.jar,unitName=helloworld with dependencies:
+15:32:24,213 INFO [JmxKernelAbstraction] jboss.jca:name=DefaultDS,service=
+DataSourceBinding
+15:32:24,275 INFO [PersistenceUnitDeployment] Starting persistence unit persistence.
+units:ear=jsfejb3.ear,jar=app.jar,unitName=helloworld
+15:32:24,392 INFO [Ejb3Configuration] found EJB3 Entity bean: Todo
+15:32:24,450 WARN [Ejb3Configuration] Persistence provider caller does not implements
+the EJB3 spec correctly. PersistenceUnitInfo.getNewTempClassLoader() is null.
+15:32:24,512 INFO [Configuration] Reading mappings from resource : META-INF/orm.xml
+15:32:24,512 INFO [Ejb3Configuration] [PersistenceUnit: helloworld] no META-INF/orm.xml
+found
+15:32:24,585 INFO [AnnotationBinder] Binding entity from annotated class: Todo
+15:32:24,586 INFO [EntityBinder] Bind entity Todo on table Todo
+.
+.
+.
+.
+15:32:26,311 INFO [SchemaExport] Running hbm2ddl schema export
+15:32:26,312 INFO [SchemaExport] exporting generated schema to database
+15:32:26,314 INFO [SchemaExport] Executing import script: /import.sql
+15:32:26,418 INFO [SchemaExport] schema export complete
+15:32:26,454 INFO [NamingHelper] JNDI InitialContext properties:{java.naming.factory.
+initial=org.jnp.interfaces.NamingContextFactory, java.naming.factory.url.pkgs=org.jboss.
+naming:org.jnp.interfaces}
+15:32:26,484 INFO [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
+stateless.StatelessContainer
+15:32:26,485 INFO [JmxKernelAbstraction] installing MBean: jboss.j2ee:ear=jsfejb3.ear,
+jar=app.jar,name=TodoDao,service=EJB3 with dependencies:
+15:32:26,513 INFO [JmxKernelAbstraction] persistence.units:ear=jsfejb3.ear,
+jar=app.jar,unitName=helloworld
+15:32:26,557 INFO [EJBContainer] STARTED EJB: TodoDao ejbName: TodoDao
+15:32:26,596 INFO [EJB3Deployer] Deployed: file:/jboss/jboss-as-5.0.0<release>
+server/default/tmp/deploy/
+tmp33761jsfejb3.ear-contents/app.jar
+15:32:26,625 INFO [TomcatDeployer] deploy, ctxPath=/jsfejb3, warUrl=.../tmp/deploy/
+tmp33761jsfejb3.ear-contents/app-exp.war/
+15:32:26,914 INFO [EARDeployer] Started J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
+</screen>
+ <para>
+ If there are any errors or exceptions, make a note of the error message. Check that the EAR is complete and inspect the WAR file and the EJB jar files to make sure they contain all the necessary components (classes, descriptors etc.).
+ </para>
+ <para>
+ You can safely redeploy the application if it is already deployed. To undeploy it you just have to remove the archive from the <literal>deploy</literal> directory. There’s no need to restart the server in either case. If everything seems to have gone OK, then point your browser at the application URL.
+ </para>
+ <para>
+ <ulink url="http://localhost:8080/jsfejb3"/>
+ </para>
+ <para>
+ You will be forwarded to the application main page. <xref linkend="Deploying_the_Application-Sample_TODO"/> shows the sample application in action.
+ </para>
+ <figure id="Deploying_the_Application-Sample_TODO">
+ <title>Sample TODO</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/sample_jsfejb3.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+</chapter>
+ <chapter id="Using_Seam">
+ <title>Using Seam</title>
+ <para>
+ JBoss Seam is a framework that provides the glue between the new EJB3 and JSF frameworks that are part of the Java EE 5.0 standard. In fact, the name Seam refers to the seamless manner in which it enables developers to use these two frameworks in an integrated manner. Seam automates many of the common tasks, and makes extensive use of annotations to reduce the amount of xml code that needs to be written. The overall effect is to significantly reduce the total amount of coding that needs to be done.
+ </para>
+
+ <para>
+ If you are new to Seam, you can find more introductory information from the following url and book:
+<itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://docs.jboss.com/seam/2.0.0.GA/reference/en/html_single/">The Seam Reference Guide</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Beginning JBoss Seam</emphasis> by Joseph Faisal Nusairat, Apress 2007.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ <para>
+ We have included two versions of the example application, one coded using EJB3 / JSF without using Seam, and one using Seam, to demonstrate clearly the difference in application development using the Seam framework.
+ </para>
+
+
+
+ <section id="Using_Seam_Data_Model">
+ <title>
+ Data Model
+ </title>
+
+ <para>
+ Let's start off our examination of the Seam implementation in the same way, by examining how the Data Model is implemented. This is done in the <literal>Todo.java</literal> file.
+ </para>
+
+ <programlisting>@Entity
+ at Name("todo")
+public class Todo implements Serializable {
+
+ private long id;
+ private String title;
+ private String description;
+
+ public Todo () {
+ title ="";
+ description ="";
+ }
+
+ @Id @GeneratedValue
+ public long getId() { return id;}
+ public void setId(long id) { this.id = id; }
+
+ @NotNull
+ public String getTitle() { return title; }
+ public void setTitle(String title) {this.title = title;}
+
+ @NotNull
+ @Length(max=250)
+ public String getDescription() { return description; }
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+}</programlisting>
+
+ <para>
+ The <literal>@Entity</literal> annotation defines the class as an EJB3 entity bean, and tells the container to map the <literal>Todo</literal> class to a relational database table. Each property of the class will become a column in the table. Each instance of the class will become a row in this table. Since we have not used the <literal>@Table</literal> annotation, Seam's "configuration by exception" default will name the table after the class.
+ </para>
+
+ <para>
+ <literal>@Entity</literal> and <literal>@Table</literal> are both EJB3 annotations, and are not specific to Seam. It is possible to use Seam completely with POJOs (Plain Old Java Objects) without any EJB3-specific annotations. However, EJB3 brings a lot of advantages to the table, including container managed security, message-driven components, transaction and component level persistence context, and <literal>@PersistenceContext</literal> injection, which we will encounter a little further on.
+ </para>
+
+ <para>
+ The <literal>@Name</literal> annotation is specific to Seam, and defines the string name for Seam to use to register the Entity Bean. This will be the default name for the relational database table. Each component in a Seam application must have a unique name. In the other components in the Seam framework, such as JSF web pages and session beans, you can reference the managed <literal>Todo</literal> bean using this name. If no instance of this class exists when it is referenced from another component, then Seam will instantiate one.
+ </para>
+
+ <para>
+ The <literal>@Id</literal> annotation defines a primary key <literal>id</literal> field for the component. <literal>@GeneratedValue</literal> specifies that the server will automatically generate this value for the component when it is saved to the database.
+ </para>
+
+ <para>
+ Seam provides support for model-based constraints defined using Hibernate Validator, although Hibernate does not have to be the object persister used. The <literal>@NotNull</literal> annotation is a validation constraint that requires this property to have a value before the component can be persisted into the database. Using this annotation allows the validation to be enforced by the JSF code at the view level, without having to specify the exact validation constraint in the JSF code.
+ </para>
+
+ <para>
+ At this point the only apparent difference between the Seam version and the EJB3/JSF version of the app is the inclusion of the validator annotation <literal>@NotNull</literal>, and the <literal>@Name</literal> annotation. However, while the EJB3/JSF version of this application requires a further <literal>TodoBean</literal> class to be manually coded and managed in order to handle the interaction between the <literal>Todo</literal> class and the web interface, when using Seam the Seam framework takes care of this work for us. We'll see how this is done in practice as we examine the implementation of the user interface.
+ </para>
+ </section>
+
+ <section id="Using_Seam_JSF_Web_Pages">
+ <title>
+ JSF Web Pages - index.xhtml and create.xhtml
+ </title>
+
+ <para>
+ The <emphasis role="bold">index.xhtml</emphasis> file used is the same as in the EJB3/JSF example.
+ </para>
+
+ <para>
+ <emphasis role="bold">create.xhtml</emphasis> begins to reveal the difference that coding using the Seam framework makes.
+ </para>
+
+ <programlisting><h:form id="create">
+
+<f:facet name="beforeInvalidField">
+ <h:graphicImage styleClass="errorImg" value="error.png"/>
+</f:facet>
+<f:facet name="afterInvalidField">
+ <s:message styleClass="errorMsg" />
+</f:facet>
+<f:facet name="aroundInvalidField">
+ <s:div styleClass="error"/>
+</f:facet>
+
+<s:validateAll>
+
+<table>
+
+ <tr>
+ <td>Title:</td>
+ <td>
+ <s:decorate>
+ <h:inputText id="title" value="#{todo.title}" size="15"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Description:</td>
+ <td>
+ <s:decorate>
+ <h:inputTextarea id="description" value="#{todo.description}"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+</table>
+
+</s:validateAll>
+
+<h:commandButton type="submit" id="create" value="Create"
+ action="#{todoDao.persist}"/>
+</h:form>
+ </programlisting>
+
+ <para>
+ The first thing that is different here is the Java Server Facelet code at the beginning, which works with the <literal>@NotNull</literal> validation constraint of our <literal>todo</literal> class to enforce and indicate invalid input to the user.
+ </para>
+
+ <para>
+ Also notice here that rather than requiring the use of a <literal>TodoBean</literal> class as we did in the EJB3/JSF example we back the form directly with a <literal>Todo</literal> entity bean. When this page is called, JSF asks Seam to resolve the variable <literal>todo</literal> due to JSF EL references such as <literal>#{todo.title}</literal>. Since there is no value already bound to that variable name, Seam will instantiate an entity bean of the <literal>todo</literal> class and return it to JSF, after storing it in the Seam context. The Seam context replaces the need for an intermediary bean.
+ </para>
+
+ <para>
+ The form input values are validated against the Hibernate Validator constraints specified in the <literal>todo</literal> class. JSF will redisplay the page if the constraints are violated, or it will bind the form input values to the <literal>Todo</literal> entity bean.
+ </para>
+
+ <para>
+ Entity beans shouldn't do database access or transaction management, so we can't use the <literal>Todo</literal> entity bean as a JSF action listener. Instead, creation of a new todo item in the database is accomplished by calling the <literal>persist</literal> method of a <literal>TodoDao</literal> session bean. When JSF requests Seam to resolve the variable <literal>todoDao</literal> through the JSF EL expression <literal>#{todoDao.persist}</literal>, Seam will either instantiate an object if one does not already exist, or else pass the existing stateful <literal>todoDao</literal> object from the Seam context. Seam will intercept the <literal>persist</literal> method call and inject the <literal>todo</literal> entity from the session context.
+ </para>
+
+ <para>
+ Let's have a look at the <literal>TodoDao</literal> class (defined in <literal>TodoDao.java</literal>) to see how this injection capability is implemented.
+ </para>
+ </section>
+
+ <section id="Using_Seam_Session_Bean">
+ <title>
+ Data Access using a Session Bean
+ </title>
+
+ <para>
+ Let's go through a listing of the code for the <literal>TodoDao</literal> class.
+ </para>
+
+ <programlisting>@Stateful
+ at Name("todoDao")
+public class TodoDao implements TodoDaoInt {
+
+ @In (required=false) @Out (required=false)
+ private Todo todo;
+
+ @PersistenceContext (type=EXTENDED)
+ private EntityManager em;
+
+ // Injected from pages.xml
+ Long id;
+
+ public String persist () {
+ em.persist (todo);
+ return "persisted";
+ }
+
+ @DataModel
+ private List <Todo> todos;
+
+ @Factory("todos")
+ public void findTodos () {
+ todos = em.createQuery("select t from Todo t")
+ .getResultList();
+ }
+
+ public void setId (Long id) {
+ this.id = id;
+
+ if (id != null) {
+ todo = (Todo) em.find(Todo.class, id);
+ } else {
+ todo = new Todo ();
+ }
+ }
+
+ public Long getId () {
+ return id;
+ }
+
+ public String delete () {
+ em.remove( todo );
+ return "removed";
+ }
+
+ public String update () {
+ return "updated";
+ }
+
+ @Remove @Destroy
+ public void destroy() {}
+
+}</programlisting>
+
+ <para>
+ First of all notice that this is a stateful session bean. Seam can use both stateful and stateless session beans, the two most common types of EJB3 beans.
+ </para>
+
+ <para>
+ The <literal>@In</literal> and <literal>@Out</literal> annotations define an attribute that is injected by Seam. The attribute is injected to this object or from this object to another via a Seam context variable named <literal>todo</literal>, a reference to the Seam registered name of our <literal>Todo</literal> class defined in <literal>Todo.java</literal>.
+ </para>
+
+ <para>
+ The <literal>@PersistenceContext</literal> annotation injects the EJB3 Entity manager, allowing this object to persist objects to the database. Because this is a stateful session bean and the <literal>PersistenceContext</literal> type is set to <literal>EXTENDED</literal>, the same Entity Manager instance is used until the Remove method of the session bean is called. The database to be used (a <literal>persistence-unit</literal>) is defined in the file <filename>resources/META-INF/persistence.xml</filename>
+ </para>
+
+ <para>
+ Note that this session bean has simultaneous access to context associated with web request (the form values of the <literal>todo</literal> object), and state held in transactional resources (the <literal>EntityManager</literal>). This is a break from traditional J2EE architectures, but Seam does not force you to work this way. You can use more traditional forms of application layering if you wish.
+ </para>
+
+ <para>
+ The <literal>@DataModel</literal> annotation initializes the <literal>todos</literal> property, which will be outjected or "exposed" to the view. The <literal>@Factory</literal> annotated method performs the work of generating the <literal>todos</literal> list, and is called by Seam if it attempts to access the exposed <literal>DataModel</literal> property and finds it to be null. Notice the absence of property access methods for the <literal>todos</literal> property. Seam takes care of this for you automatically.
+ </para>
+
+ <para>
+ Let's take a look at the JSF code that we use for displaying and editing the list of todos, to get an idea of how to use these interfaces in practice.
+ </para>
+
+ </section>
+
+ <section id="Using_Seam_Display_and_Edit">
+ <title>
+ JSF Web Pages - todos.xhtml and edit.xhtml
+ </title>
+
+ <para>
+ Using the <literal>DataModel</literal> exposed property of the Session Bean it becomes trivial to produce a list of todos:
+ </para>
+
+ <programlisting><h:form>
+
+<h:dataTable value="#{todos}" var="todo">
+ <h:column>
+ <f:facet name="header">Title</f:facet>
+ #{todo.title}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ #{todo.description}
+ </h:column>
+ <h:column>
+ <a href="edit.seam?tid=#{todo.id}">Edit</a>
+ </h:column>
+</h:dataTable>
+
+<center>
+ <h:commandButton action="create"
+ value="Create New Todo" type="submit"/>
+</center>
+
+</h:form>
+</programlisting>
+
+ <para>
+ When the JSF variable resolver encounters <literal>{#todos}</literal> and requests <literal>todos</literal>, Seam finds that there is no "todos" component in the current scope, so it calls the @Factory("todos") method to make one. The todos object is then outjected once the factory method is done since it is annotated with the @DataModel annotation. <!--Seam responses by finding the <literal>todos</literal> <literal>DataModel</literal> registered with it, and outjecting that from the bean.-->
+ </para>
+
+ <para>
+ Constructing the view for the edit page is similarly straight forward:
+ </para>
+
+ <programlisting><h:form id="edit">
+
+<f:facet name="beforeInvalidField">
+ <h:graphicImage styleClass="errorImg" value="error.png"/>
+</f:facet>
+<f:facet name="afterInvalidField">
+ <s:message styleClass="errorMsg" />
+</f:facet>
+<f:facet name="aroundInvalidField">
+ <s:div styleClass="error"/>
+</f:facet>
+
+<s:validateAll>
+
+<table>
+
+ <tr>
+ <td>Title:</td>
+ <td>
+ <s:decorate>
+ <h:inputText id="title" value="#{todo.title}" size="15"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+ <tr>
+ <td>Description:</td>
+ <td>
+ <s:decorate>
+ <h:inputTextarea id="description" value="#{todo.description}"/>
+ </s:decorate>
+ </td>
+ </tr>
+
+</table>
+
+</s:validateAll>
+
+<h:commandButton type="submit" id="update" value="Update"
+ action="#{todoDao.update}"/>
+
+<h:commandButton type="submit" id="delete" value="Delete"
+ action="#{todoDao.delete}"/>
+</h:form>
+ </programlisting>
+
+ <para>
+ Here we see the same factors in play. JSF validation code taking advantage of the validation constraints defined in our Entity Bean, and the use of the <literal>todoDao</literal> Session Bean's <literal>update</literal> and <literal>delete</literal> methods to update the database.
+ </para>
+
+ <para>
+ The call from <filename>todos.xhtml</filename>: <literal>edit.seam?tid=#{todo.id}</literal> causes Seam to create a <literal>todoDao</literal> and set it's <literal>id</literal> property to <literal>tid</literal>. Setting its <literal>id</literal> property causes the <literal>todoDao</literal> to retrieve the appropriate record from the database.
+ </para>
+
+ <para>
+ The functionality that allows the edit page to be called with a parameter in this way is implemented through <literal>pages.xml</literal>. Let's have a look at the <literal>pages.xml</literal> file and how it is used by Seam applications.
+ </para>
+ </section>
+
+ <section id="Using_Seam_XML_Files">
+ <title>
+ Xml Files
+ </title>
+
+ <para>
+ Seam drastically reduces the amount of xml coding that needs to be done. One file that is of interest is the <literal>pages.xml</literal>, packaged in the <literal>app.war</literal> file's <literal>WEB-INF</literal> directory. This file is available in the <literal>resources/WEB-INF</literal> directory in the source code bundle. The <literal>pages.xml</literal> file is used to define page descriptions including Seam page parameters (HTTP <literal>GET</literal> parameters), page actions, page navigation rules, error pages etc. <!--This file defines a number of attributes that affect global behaviour of the application.--> Among other things it can be used in a Seam application to define exception handlers and redirections.
+ </para>
+ <para>
+ In the case of our sample application we are using it to define a Seam page parameter. The <literal>pages.xml</literal> in this example contains the following code:
+ </para>
+
+ <programlisting><page view-id="/edit.xhtml">
+ <param name="tid" value="#{todoDao.id}"
+ converterId="javax.faces.Long"/>
+</page></programlisting>
+ <para>
+ This defines a parameter named <literal>tid</literal> for the <literal>edit.xhtml</literal> page. When the <literal>edit.xhtml</literal> page is loaded, the HTTP <literal>GET</literal> request parameter <literal>tid</literal> is converted to a <literal>Long</literal> value and assigned to the <literal>id</literal> property of the <literal>todoDao</literal> object. You can have as many page parameters as required to bind HTTP <literal>GET</literal> request parameters to the back-end components in your application.
+ </para>
+ </section>
+
+ <section id="Further_Information">
+ <title>
+ Further Information
+ </title>
+
+ <para>
+ This completes our walkthrough of the sample Seam application. For further, detailed information on developing applications using the Seam framework, please refer to the <ulink url="http://docs.jboss.com/seam/2.0.0.GA/reference/en/html_single/">The Seam Reference Guide</ulink>.
+ </para>
+ </section>
+</chapter>
+ <chapter id="Using_other_Databases">
+ <title>Using other Databases</title>
+ <para>
+ 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.
+ </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.
+ </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 Application Server Guide available at <ulink url="http://labs.jboss.com/projects/docs/"/>.
+ </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.
+ </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.
+ </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>
+ </section>
+
+ <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"/>.
+ </para>
+
+
+
+
+
+
+ <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).
+ </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"?>
+<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>
+ </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>
+ </section>
+
+
+
+ <section id="Using_MySQL_as_the_Default_DataSource-Testing_the_MySQL_DataSource">
+ <title>Testing the MySQL DataSource</title>
+ <para>
+ Using the test client described in <xref linkend="creating_a_jdbc_client"/>, you may now verify the proper installation of your datasource.
+ </para>
+
+ </section>
+
+ </section>
+
+ <section id="Configuring_a_datasource_for_Oracle_DB">
+ <title>Configuring a datasource for Oracle DB</title>
+ <para>
+ Oracle is one of the main players in the commercial database field and most readers will probably have come across it at some point. You can download it freely for non-commercial purposes from <ulink url="http://www.oracle.com/technology/products/database/xe/index.html"/>
+ </para>
+ <para>
+ In this section, we'll connect the server to Oracle Database 10g Express Edition using the latest JDBC driver (11g) available at <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html"/>
+ </para>
+
+
+
+ <section id="Setting_up_an_XADataSource_with_Oracle_9i-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 JBoss Application Server, copy the archive ojdbc5.jar to the lib directory in the default server configuration (assuming that is the server configuration you’re running).
+ </para>
+ <para>
+ Then create a text file in the <filename>deploy</filename> directory called <filename>oracle-ds.xml</filename> with the following datasource descriptor :
+ </para>
+
+<programlisting role="XML"><?xml version="1.0" encoding="UTF-8"?>
+<datasources>
+ <local-tx-datasource>
+ <jndi-name>DefaultDS</jndi-name>
+ <connection-url>jdbc:oracle:thin:@localhost:1521:xe</connection-url>
+ <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
+ <user-name>SYSTEM</user-name>
+ <password>jboss</password>
+ <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker</valid-connection-checker-class-name>
+ <metadata>
+ <type-mapping>Oracle9i</type-mapping>
+ </metadata>
+ </local-tx-datasource>
+</datasources></programlisting>
+
+ <para>
+ The datasource is pointing at the database/SID called “xe” provided by default with Oracle XE.
+ </para>
+ <para>
+ Of course, you need to update the connection url attributes as well as the username/password combination to match your environment setup.
+ </para>
+
+ </section>
+
+
+
+
+
+
+
+
+
+
+
+ <section id="Setting_up_an_XADataSource_with_Oracle_9i-Testing_the_Oracle_DataSource">
+ <title>Testing the Oracle DataSource</title>
+ <para>
+ Before you can verify the datasource configuration, Oracle XE should be reconfigured to avoid port conflict with JBossAS as by default they both start a web server on port 8080.
+ </para>
+ <para>Open up an Oracle SQLcommand line and execute the following commands:
+ </para>
+<screen>
+<command>SQL> connect;
+Enter user-name: SYSTEM
+Enter password:</command>
+Connected.
+SQL> <command>begin
+2 dbms_xdb.sethttpport('8090');
+3 end;
+4 /</command>
+PL/SQL procedure successfully completed.
+SQL> <command>select dbms_xdb.gethttpport from dual;</command>
+GETHTTPPORT
+-----------
+8090
+</screen>
+
+<para>
+ The web server started by Oracle XE to provide http-based administration tools is now running on port 8090.
+ Start the JBossAS server instance as you would normally do. You are now ready to use the test client described in Chapter 6.5 to verify the proper installation of your datasource.
+</para>
+
+ </section>
+ </section>
+
+
+ <section><title>Configuring a datasource for Microsoft SQL Server 200x</title>
+ <para>In this section, we'll connect the server to MS SQL Server 2000 using the latest JDBC driver (v1.2) available at <ulink url="http://msdn2.microsoft.com/en-us/data/aa937724.aspx"/>.
+ </para>
+
+ <section><title>Installing the JDBC Driver and Deploying the DataSource</title>
+ <para>
+ To make the JDBC driver classes available to JBoss Application Server, copy the archive <filename>sqljdbc.jar</filename> from the <filename>sqljdbc_1.2</filename> distribution to the <filename>lib</filename> directory in the default server configuration (assuming that is the server configuration you’re running).
+ </para>
+ <para>
+ Then create a text file in the <literal>deploy</literal> directory called <literal>mssql-ds.xml</literal> with the following datasource descriptor :
+<programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<datasources>
+ <local-tx-datasource>
+ <jndi-name>DefaultDS</jndi-name>
+ <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=pubs</connection-url>
+ <driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>
+ <user-name>sa</user-name>
+ <password>jboss</password>
+ <check-valid-connection-sql>SELECT 1 FROM sysobjects</check-valid-connection-sql>
+ <metadata>
+ <type-mapping>MS SQLSERVER2000</type-mapping>
+ </metadata>
+ </local-tx-datasource>
+</datasources> ]]>
+</programlisting>
+
+The datasource is pointing at a database “pubs” provided by default with MS SQL Server 2000.
+</para>
+<para>
+Remember to update the connection url attributes as well as the username/password combination to match your environment setup.
+
+</para>
+
+<section id="testing_the_datasource"><title>Testing the datasource</title>
+ <para>Using the test client described in <xref linkend="creating_a_jdbc_client"/>, you may now verify the proper installation of your datasource.
+ </para>
+</section>
+ </section>
+</section>
+
+
+<section id="configuring_jbossmessaging_persistence_manager"><title>Configuring JBoss Messaging Persistence Manager</title>
+ <para>
+ The persistence manager of JBoss Messaging uses the default datasource to create tables to store messages, transaction data and other indexes. Configuration of "persistence" is grouped in <filename>xxx-persistence-service.xml</filename> files. JBoss Application Server ships with a default <filename>hsqldb-persistence-service.xml</filename> file, which configures the Messaging server to use the Hypersonic database instance that ships by default with the JBoss Application Server.
+ </para>
+ <para>
+ You can view the <filename>hsqldb-persistence-service.xml</filename> file in configurations based on the <emphasis>all</emphasis> or <emphasis>default</emphasis> configurations:
+
+ <screen><JBoss_Home>/server/all/deploy/messaging/hsqldb-persistence-service.xml and
+ <JBoss_Home>/server/default/deploy/messaging/hsqldb-persistence-service.xml</screen>
+
+ </para>
+
+
+ <warning><title>Warning</title>
+ <para>Please note that the Hypersonic database is not recommended for production environments due to its limited support for transaction isolation and its low reliability under high load</para>
+ </warning>
+
+ <para>
+ More information on configuring JBoss Messaging can be found in the <ulink url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Server_Configuration_Guide/beta500/html-single/index.html#d0e3471">JBoss AS Configuration Guide</ulink>.
+
+ </para>
+
+
+</section>
+
+
+<section id="creating_a_jdbc_client"><title>Creating a JDBC client</title>
+ <para>
+ When testing a newly configured datasource we suggest using some very basic JDBC client code embedded in a JSP page.
+ First of all, you should create an exploded WAR archive under the deploy directory which is simply a folder named "<literal>jdbcclient.war</literal>".
+In this folder, create a text document named client.jsp and paste the code below:
+<programlisting><![CDATA[
+<%@page contentType="text/html"
+ import="java.util.*,javax.naming.*,javax.sql.DataSource,java.sql.*"
+ %>
+ <%
+
+ DataSource ds = null;
+ Connection con = null;
+ PreparedStatement pr = null;
+ InitialContext ic;
+ try {
+ ic = new InitialContext();
+ ds = (DataSource)ic.lookup( "java:/DefaultDS" );
+ con = ds.getConnection();
+ pr = con.prepareStatement("SELECT USERID, PASSWD FROM JMS_USERS");
+ ResultSet rs = pr.executeQuery();
+ while (rs.next()) {
+ out.println("<br> " +rs.getString("USERID") + " | " +rs.getString("PASSWD"));
+ }
+ rs.close();
+ pr.close();
+ }catch(Exception e){
+ out.println("Exception thrown " +e);
+ }finally{
+ if(con != null){
+ con.close();
+ }
+}]]> %> </programlisting>
+
+Open up a web browser and hit the url: <ulink url="http://localhost:8080/jdbcclient/client.jsp"/>.
+A list of users and password should show up as a result of the jdbc query:
+<screen>
+dynsub | dynsub
+guest | guest
+j2ee | j2ee
+john | needle
+nobody | nobody
+</screen>
+
+ </para>
+</section>
+
+</chapter>
+ <appendix id="Book-Revision_History">
+ <appendixinfo>
+ <revhistory>
+
+<revision>
+ <revnumber>5.0.0</revnumber>
+ <date>Jan 08 2007</date>
+ <author>
+ <firstname>S</firstname>
+ <surname>Kittoli</surname>
+
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Updated Content </member>
+
+ </simplelist>
+ </revdescription>
+ </revision>
+
+ <revision>
+ <revnumber>5.0.0</revnumber>
+ <date>Apr 07 2007</date>
+ <author>
+ <firstname>S</firstname>
+ <surname>Kittoli</surname>
+
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Merge Content </member>
+ </simplelist>
+ </revdescription>
+ </revision>
+</revhistory>
+ </appendixinfo>
+ <title>Revision History</title>
+ <para>
+ </para>
+</appendix>
+ <appendix id="appendix2">
+
+ <title>Further Information Sources</title>
+ <para>
+ Developers wanting to get familiar with software development and implementation in JBoss Application Server can read: <emphasis>JBoss: A Developer's Notebook</emphasis>. (O'Reilly, 2005. Norman Richards, Sam Griffith).
+ </para>
+ <para>
+ For more comprehensive JBoss documentation covering advanced JBoss topics, refer to the manuals available online at <ulink url="http://www.jboss.org/jbossas/docs"/>.
+ </para>
+ <para>
+ For general EJB instruction, with thorough JBoss coverage, see <emphasis> Enterprise JavaBeans, 4th Edition</emphasis>. (O'Reilly, 2004. Richard Monson-Haeful, Bill Burke, Sacha Labourey)
+ </para>
+ <para>
+ To learn more about Hibernate, see <emphasis>Java Persistence With Hibernate</emphasis>. (Manning, 2007. Christian Bauer, Gavin King)
+ </para>
+ <para>
+ For complete coverage of the JBoss Seam framework, we recommend <emphasis>JBoss Seam: Simplicity And Power Beyond Java EE</emphasis>. (Prentice Hall, 2007. Michael Yuan, Thomas Heute).
+ </para>
+</appendix>
+
+</book>
Deleted: projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/resolved.xml
===================================================================
--- projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/resolved.xml 2008-12-08 18:23:23 UTC (rev 82119)
+++ projects/docs/community/5/Installation_And_Getting_Started_Guide/en-US/resolved.xml 2008-12-08 21:19:25 UTC (rev 82120)
@@ -1,4631 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY uArr "⇑">
-<!ENTITY hcirc "ĥ">
-<!ENTITY icirc "î">
-<!ENTITY equals "=">
-<!ENTITY cong "≅">
-<!ENTITY HARDcy "Ъ">
-<!ENTITY icy "и">
-<!ENTITY Ecaron "Ě">
-<!ENTITY clubs "♣">
-<!ENTITY phmmat "ℳ">
-<!ENTITY sqcap "⊓">
-<!ENTITY thorn "þ">
-<!ENTITY Lcedil "Ļ">
-<!ENTITY rarr "→">
-<!ENTITY verbar "|">
-<!ENTITY cire "≗">
-<!ENTITY DZcy "Џ">
-<!ENTITY b.delta "𝛅">
-<!ENTITY Gcirc "Ĝ">
-<!ENTITY ocir "⊚">
-<!ENTITY circ "ˆ">
-<!ENTITY Igr "Ι">
-<!ENTITY udigr "ϋ">
-<!ENTITY prime "′">
-<!ENTITY npr "⊀">
-<!ENTITY b.pi "𝛑">
-<!ENTITY frac58 "⅝">
-<!ENTITY ldquor "„">
-<!ENTITY sqsup "⊐">
-<!ENTITY boxDR "╔">
-<!ENTITY kcedil "ķ">
-<!ENTITY vDash "⊨">
-<!ENTITY Scedil "Ş">
-<!ENTITY perp "⊥">
-<!ENTITY b.Gamma "𝚪">
-<!ENTITY b.kappa "𝛋">
-<!ENTITY Uuml "Ü">
-<!ENTITY mnplus "∓">
-<!ENTITY nearr "↗">
-<!ENTITY nrtri "⋫">
-<!ENTITY cupre "≼">
-<!ENTITY boxV "║">
-<!ENTITY Zdot "Ż">
-<!ENTITY pound "£">
-<!ENTITY lharu "↼">
-<!ENTITY boxdr "┌">
-<!ENTITY ocy "о">
-<!ENTITY xgr "ξ">
-<!ENTITY b.xi "𝛏">
-<!ENTITY larr "←">
-<!ENTITY middot "·">
-<!ENTITY xrArr "⟹">
-<!ENTITY Ncy "Н">
-<!ENTITY acute "´">
-<!ENTITY phis "ϕ">
-<!ENTITY ncedil "ņ">
-<!ENTITY lAarr "⇚">
-<!ENTITY sqsube "⊑">
-<!ENTITY quot '"'>
-<!ENTITY TSHcy "Ћ">
-<!ENTITY b.Gammad "Ϝ">
-<!ENTITY amacr "ā">
-<!ENTITY otimes "⊗">
-<!ENTITY inodot "ı">
-<!ENTITY gsdot "⋗">
-<!ENTITY LJcy "Љ">
-<!ENTITY phiv "φ">
-<!ENTITY odblac "ő">
-<!ENTITY filig "fi">
-<!ENTITY amalg "⨿">
-<!ENTITY sdotb "⊡">
-<!ENTITY boxDL "╗">
-<!ENTITY Theta "Θ">
-<!ENTITY cdot "ċ">
-<!ENTITY ordm "º">
-<!ENTITY atilde "ã">
-<!ENTITY squf "▪">
-<!ENTITY notin "∉">
-<!ENTITY nmid "∤">
-<!ENTITY shchcy "щ">
-<!ENTITY lfloor "⌊">
-<!ENTITY Xi "Ξ">
-<!ENTITY Hstrok "Ħ">
-<!ENTITY period ".">
-<!ENTITY nldr "‥">
-<!ENTITY numsp " ">
-<!ENTITY boxdl "┐">
-<!ENTITY Fcy "Ф">
-<!ENTITY tscy "ц">
-<!ENTITY Iukcy "І">
-<!ENTITY cross "✗">
-<!ENTITY ohgr "ω">
-<!ENTITY nbsp " ">
-<!ENTITY ni "∋">
-<!ENTITY comp "∁">
-<!ENTITY boxH "═">
-<!ENTITY b.Delta "𝚫">
-<!ENTITY Oslash "Ø">
-<!ENTITY marker "▮">
-<!ENTITY ndash "–">
-<!ENTITY ordf "ª">
-<!ENTITY nsce "⪰̸">
-<!ENTITY vrtri "⊳">
-<!ENTITY ubrcy "ў">
-<!ENTITY Ccirc "Ĉ">
-<!ENTITY quest "?">
-<!ENTITY ne "≠">
-<!ENTITY gap "⪆">
-<!ENTITY efDot "≒">
-<!ENTITY rcy "р">
-<!ENTITY bsim "∽">
-<!ENTITY bgr "β">
-<!ENTITY omacr "ō">
-<!ENTITY umacr "ū">
-<!ENTITY lpar "(">
-<!ENTITY uharl "↿">
-<!ENTITY Gcy "Г">
-<!ENTITY ast "*">
-<!ENTITY acy "а">
-<!ENTITY thetas "θ">
-<!ENTITY uring "ů">
-<!ENTITY Zcaron "Ž">
-<!ENTITY horbar "―">
-<!ENTITY star "☆">
-<!ENTITY timesb "⊠">
-<!ENTITY npre "⪯̸">
-<!ENTITY real "ℜ">
-<!ENTITY dlarr "↙">
-<!ENTITY nrArr "⇏">
-<!ENTITY oplus "⊕">
-<!ENTITY Xgr "Ξ">
-<!ENTITY ucy "у">
-<!ENTITY thetav "ϑ">
-<!ENTITY jcirc "ĵ">
-<!ENTITY uharr "↾">
-<!ENTITY mgr "μ">
-<!ENTITY hearts "♥">
-<!ENTITY nvDash "⊭">
-<!ENTITY yicy "ї">
-<!ENTITY dot "˙">
-<!ENTITY alpha "α">
-<!ENTITY wedgeq "≙">
-<!ENTITY bowtie "⋈">
-<!ENTITY boxDr "╓">
-<!ENTITY b.upsi "𝛖">
-<!ENTITY euml "ë">
-<!ENTITY vArr "⇕">
-<!ENTITY lgr "λ">
-<!ENTITY b.rhov "𝛠">
-<!ENTITY ubreve "ŭ">
-<!ENTITY copysr "℗">
-<!ENTITY cap "∩">
-<!ENTITY aogon "ą">
-<!ENTITY racute "ŕ">
-<!ENTITY rthree "⋌">
-<!ENTITY Sgr "Σ">
-<!ENTITY uacute "ú">
-<!ENTITY Tcaron "Ť">
-<!ENTITY dagger "†">
-<!ENTITY oast "⊛">
-<!ENTITY prnE "⪵">
-<!ENTITY thkap "≈">
-<!ENTITY boxdR "╒">
-<!ENTITY dgr "δ">
-<!ENTITY nacute "ń">
-<!ENTITY hardcy "ъ">
-<!ENTITY sqsupe "⊒">
-<!ENTITY TScy "Ц">
-<!ENTITY reg "®">
-<!ENTITY cir "○">
-<!ENTITY lsquor "‚">
-<!ENTITY ycy "ы">
-<!ENTITY Sigma "Σ">
-<!ENTITY Gbreve "Ğ">
-<!ENTITY order "ℴ">
-<!ENTITY nlarr "↚">
-<!ENTITY eng "ŋ">
-<!ENTITY sacute "ś">
-<!ENTITY ensp " ">
-<!ENTITY rarr2 "⇉">
-<!ENTITY coprod "∐">
-<!ENTITY iacgr "ί">
-<!ENTITY b.piv "𝛡">
-<!ENTITY rlhar2 "⇌">
-<!ENTITY boxDl "╖">
-<!ENTITY Pcy "П">
-<!ENTITY Dagger "‡">
-<!ENTITY khcy "х">
-<!ENTITY sigma "σ">
-<!ENTITY nltrie "⋬">
-<!ENTITY gjcy "ѓ">
-<!ENTITY b.alpha "𝛂">
-<!ENTITY plusmn "±">
-<!ENTITY scnap "⪺">
-<!ENTITY vprime "′">
-<!ENTITY iota "ι">
-<!ENTITY Dcaron "Ď">
-<!ENTITY emsp " ">
-<!ENTITY trie "≜">
-<!ENTITY boxdL "╕">
-<!ENTITY cacute "ć">
-<!ENTITY rcedil "ŗ">
-<!ENTITY lhblk "▄">
-<!ENTITY lnsim "⋦">
-<!ENTITY bsime "⋍">
-<!ENTITY Vvdash "⊪">
-<!ENTITY zgr "ζ">
-<!ENTITY Ncaron "Ň">
-<!ENTITY rcaron "ř">
-<!ENTITY radic "√">
-<!ENTITY colone "≔">
-<!ENTITY Ucy "У">
-<!ENTITY lcub "{">
-<!ENTITY mdash "—">
-<!ENTITY ogon "˛">
-<!ENTITY Lgr "Λ">
-<!ENTITY b.chi "𝛘">
-<!ENTITY Barwed "⌆">
-<!ENTITY odot "⊙">
-<!ENTITY softcy "ь">
-<!ENTITY yucy "ю">
-<!ENTITY Ogr "Ο">
-<!ENTITY ecirc "ê">
-<!ENTITY Uacute "Ú">
-<!ENTITY jcy "й">
-<!ENTITY Oacgr "Ό">
-<!ENTITY ntilde "ñ">
-<!ENTITY Uring "Ů">
-<!ENTITY Udigr "Ϋ">
-<!ENTITY squ "□">
-<!ENTITY Uacgr "Ύ">
-<!ENTITY uarr "↑">
-<!ENTITY sim "∼">
-<!ENTITY egr "ε">
-<!ENTITY aleph "ℵ">
-<!ENTITY nharr "↮">
-<!ENTITY kcy "к">
-<!ENTITY Rgr "Ρ">
-<!ENTITY ffilig "ffi">
-<!ENTITY boxvl "┤">
-<!ENTITY Iacgr "Ί">
-<!ENTITY ang90 "∟">
-<!ENTITY nrarr "↛">
-<!ENTITY nges "⩾̸">
-<!ENTITY nsube "⊈">
-<!ENTITY nsup "⊅">
-<!ENTITY egs "⪖">
-<!ENTITY acirc "â">
-<!ENTITY Yuml "Ÿ">
-<!ENTITY ltrif "◂">
-<!ENTITY lagran "ℒ">
-<!ENTITY npar "∦">
-<!ENTITY scsim "≿">
-<!ENTITY boxvr "├">
-<!ENTITY Acirc "Â">
-<!ENTITY Ucirc "Û">
-<!ENTITY zcaron "ž">
-<!ENTITY shy "">
-<!ENTITY ominus "⊖">
-<!ENTITY frac38 "⅜">
-<!ENTITY incare "℅">
-<!ENTITY uhblk "▀">
-<!ENTITY lEg "⪋">
-<!ENTITY gcy "г">
-<!ENTITY b.eta "𝛈">
-<!ENTITY lnap "⪉">
-<!ENTITY Iacute "Í">
-<!ENTITY yacute "ý">
-<!ENTITY dstrok "đ">
-<!ENTITY Imacr "Ī">
-<!ENTITY orarr "↻">
-<!ENTITY Eacgr "Έ">
-<!ENTITY apos "'">
-<!ENTITY b.epsiv "𝛜">
-<!ENTITY gcirc "ĝ">
-<!ENTITY udblac "ű">
-<!ENTITY planck "ℏ">
-<!ENTITY upsi "υ">
-<!ENTITY b.Lambda "𝚲">
-<!ENTITY Bgr "Β">
-<!ENTITY scedil "ş">
-<!ENTITY Rarr "↠">
-<!ENTITY nrtrie "⋭">
-<!ENTITY nsub "⊄">
-<!ENTITY vcy "в">
-<!ENTITY Eacute "É">
-<!ENTITY boxvh "┼">
-<!ENTITY dcy "д">
-<!ENTITY Aring "Å">
-<!ENTITY Igrave "Ì">
-<!ENTITY utilde "ũ">
-<!ENTITY divonx "⋇">
-<!ENTITY lne "⪇">
-<!ENTITY scnE "⪶">
-<!ENTITY ccedil "ç">
-<!ENTITY supne "⊋">
-<!ENTITY empty "∅">
-<!ENTITY b.nu "𝛎">
-<!ENTITY top "⊤">
-<!ENTITY lcy "л">
-<!ENTITY b.gamma "𝛄">
-<!ENTITY aelig "æ">
-<!ENTITY iuml "ï">
-<!ENTITY Lcaron "Ľ">
-<!ENTITY bottom "⊥">
-<!ENTITY rarrhk "↪">
-<!ENTITY DScy "Ѕ">
-<!ENTITY idiagr "ΐ">
-<!ENTITY imacr "ī">
-<!ENTITY ltri "◃">
-<!ENTITY infin "∞">
-<!ENTITY le "≤">
-<!ENTITY sime "≃">
-<!ENTITY kappa "κ">
-<!ENTITY kappav "ϰ">
-<!ENTITY OElig "Œ">
-<!ENTITY urcrop "⌎">
-<!ENTITY darr2 "⇊">
-<!ENTITY lg "≶">
-<!ENTITY spar "∥">
-<!ENTITY Mgr "Μ">
-<!ENTITY rtri "▹">
-<!ENTITY daleth "ℸ">
-<!ENTITY sfrown "⌢">
-<!ENTITY epsiv "ε">
-<!ENTITY Omega "Ω">
-<!ENTITY colon ":">
-<!ENTITY prop "∝">
-<!ENTITY lArr "⇐">
-<!ENTITY Upsi "ϒ">
-<!ENTITY oslash "ø">
-<!ENTITY ap "≈">
-<!ENTITY Sup "⋑">
-<!ENTITY epsis "ϵ">
-<!ENTITY b.omega "𝛚">
-<!ENTITY rpar ")">
-<!ENTITY Abreve "Ă">
-<!ENTITY mldr "…">
-<!ENTITY ltrie "⊴">
-<!ENTITY Psi "Ψ">
-<!ENTITY Agrave "À">
-<!ENTITY Tcedil "Ţ">
-<!ENTITY auml "ä">
-<!ENTITY lcedil "ļ">
-<!ENTITY scirc "ŝ">
-<!ENTITY larrhk "↩">
-<!ENTITY varr "↕">
-<!ENTITY ncong "≇">
-<!ENTITY jnodot "j">
-<!ENTITY subE "⫅">
-<!ENTITY kjcy "ќ">
-<!ENTITY larr2 "⇇">
-<!ENTITY rsh "↱">
-<!ENTITY sdot "⋅">
-<!ENTITY wreath "≀">
-<!ENTITY cuepr "⋞">
-<!ENTITY frown "⌢">
-<!ENTITY Agr "Α">
-<!ENTITY uacgr "ύ">
-<!ENTITY rcub "}">
-<!ENTITY dharl "⇃">
-<!ENTITY bcy "б">
-<!ENTITY Tgr "Τ">
-<!ENTITY diam "⋄">
-<!ENTITY eacute "é">
-<!ENTITY xlArr "⟸">
-<!ENTITY leg "⋚">
-<!ENTITY boxvL "╡">
-<!ENTITY Kcy "К">
-<!ENTITY ncy "н">
-<!ENTITY sgr "σ">
-<!ENTITY beta "β">
-<!ENTITY exist "∃">
-<!ENTITY bprime "‵">
-<!ENTITY boxul "┘">
-<!ENTITY Zcy "З">
-<!ENTITY Iuml "Ï">
-<!ENTITY Scaron "Š">
-<!ENTITY sol "/">
-<!ENTITY boxvR "╞">
-<!ENTITY fcy "ф">
-<!ENTITY Egrave "È">
-<!ENTITY Utilde "Ũ">
-<!ENTITY lthree "⋋">
-<!ENTITY boxur "└">
-<!ENTITY dharr "⇂">
-<!ENTITY uarr2 "⇈">
-<!ENTITY lacute "ĺ">
-<!ENTITY spades "♠">
-<!ENTITY int "∫">
-<!ENTITY rect "▭">
-<!ENTITY compfn "∘">
-<!ENTITY b.sigma "𝛔">
-<!ENTITY Amacr "Ā">
-<!ENTITY prod "∏">
-<!ENTITY rpargt "⦔">
-<!ENTITY b.sigmav "𝛓">
-<!ENTITY excl "!">
-<!ENTITY fnof "ƒ">
-<!ENTITY beth "ℶ">
-<!ENTITY yuml "ÿ">
-<!ENTITY rsquo "’">
-<!ENTITY pr "≺">
-<!ENTITY ccaron "č">
-<!ENTITY hyphen "‐">
-<!ENTITY weierp "℘">
-<!ENTITY smile "⌣">
-<!ENTITY Egr "Ε">
-<!ENTITY eeacgr "ή">
-<!ENTITY nsc "⊁">
-<!ENTITY les "⩽">
-<!ENTITY boxvH "╪">
-<!ENTITY KHcy "Х">
-<!ENTITY bernou "ℬ">
-<!ENTITY lpargt "⦠">
-<!ENTITY tgr "τ">
-<!ENTITY zacute "ź">
-<!ENTITY amp "&">
-<!ENTITY lnE "≨">
-<!ENTITY nlE "≦̸">
-<!ENTITY sbsol "﹨">
-<!ENTITY Pi "Π">
-<!ENTITY b.beta "𝛃">
-<!ENTITY b.mu "𝛍">
-<!ENTITY Ograve "Ò">
-<!ENTITY phone "☎">
-<!ENTITY iff "⇔">
-<!ENTITY gsim "≳">
-<!ENTITY rx "℞">
-<!ENTITY there4 "∴">
-<!ENTITY harrw "↭">
-<!ENTITY udiagr "ΰ">
-<!ENTITY otilde "õ">
-<!ENTITY DotDot " ⃜">
-<!ENTITY lrhar2 "⇋">
-<!ENTITY lE "≦">
-<!ENTITY hstrok "ħ">
-<!ENTITY Racute "Ŕ">
-<!ENTITY rarrw "↝">
-<!ENTITY angmsd "∡">
-<!ENTITY tshcy "ћ">
-<!ENTITY szlig "ß">
-<!ENTITY nequiv "≢">
-<!ENTITY pcy "п">
-<!ENTITY darr "↓">
-<!ENTITY female "♀">
-<!ENTITY curarr "↷">
-<!ENTITY minusb "⊟">
-<!ENTITY aacute "á">
-<!ENTITY Dcy "Д">
-<!ENTITY THORN "Þ">
-<!ENTITY ucirc "û">
-<!ENTITY asymp "≈">
-<!ENTITY bcong "≌">
-<!ENTITY die "¨">
-<!ENTITY ograve "ò">
-<!ENTITY iexcl "¡">
-<!ENTITY frac56 "⅚">
-<!ENTITY rArr "⇒">
-<!ENTITY tprime "‴">
-<!ENTITY osol "⊘">
-<!ENTITY sqsub "⊏">
-<!ENTITY rho "ρ">
-<!ENTITY b.psi "𝛙">
-<!ENTITY aring "å">
-<!ENTITY Edot "Ė">
-<!ENTITY lcaron "ľ">
-<!ENTITY rlarr2 "⇄">
-<!ENTITY EEacgr "Ή">
-<!ENTITY pi "π">
-<!ENTITY sect "§">
-<!ENTITY bepsi "϶">
-<!ENTITY ffllig "ffl">
-<!ENTITY lsh "↰">
-<!ENTITY dscy "ѕ">
-<!ENTITY macr "¯">
-<!ENTITY b.kappav "𝛞">
-<!ENTITY scaron "š">
-<!ENTITY commat "@">
-<!ENTITY dollar "$">
-<!ENTITY angsph "∢">
-<!ENTITY Udblac "Ű">
-<!ENTITY comma ",">
-<!ENTITY copy "©">
-<!ENTITY diams "♦">
-<!ENTITY Dot "¨">
-<!ENTITY sube "⊆">
-<!ENTITY Cap "⋒">
-<!ENTITY nsmid "∤">
-<!ENTITY SOFTcy "Ь">
-<!ENTITY eegr "η">
-<!ENTITY lsim "≲">
-<!ENTITY ssmile "⌣">
-<!ENTITY nlt "≮">
-<!ENTITY boxHU "╩">
-<!ENTITY ZHcy "Ж">
-<!ENTITY abreve "ă">
-<!ENTITY lmidot "ŀ">
-<!ENTITY angst "Å">
-<!ENTITY b.lambda "𝛌">
-<!ENTITY uuml "ü">
-<!ENTITY ENG "Ŋ">
-<!ENTITY IJlig "IJ">
-<!ENTITY brvbar "¦">
-<!ENTITY esdot "≐">
-<!ENTITY boxuL "╛">
-<!ENTITY blk14 "░">
-<!ENTITY YAcy "Я">
-<!ENTITY caron "ˇ">
-<!ENTITY ohacgr "ώ">
-<!ENTITY sup3 "³">
-<!ENTITY flat "♭">
-<!ENTITY minus "−">
-<!ENTITY olarr "↺">
-<!ENTITY dlcorn "⌞">
-<!ENTITY boxuR "╘">
-<!ENTITY iukcy "і">
-<!ENTITY b.tau "𝛕">
-<!ENTITY Otilde "Õ">
-<!ENTITY ldquo "“">
-<!ENTITY lang "〈">
-<!ENTITY Verbar "‖">
-<!ENTITY ges "⩾">
-<!ENTITY prap "⪷">
-<!ENTITY thksim "∼">
-<!ENTITY Vcy "В">
-<!ENTITY yacy "я">
-<!ENTITY drcrop "⌌">
-<!ENTITY omega "ω">
-<!ENTITY Hcirc "Ĥ">
-<!ENTITY tstrok "ŧ">
-<!ENTITY ang "∠">
-<!ENTITY khgr "χ">
-<!ENTITY b.thetas "𝛉">
-<!ENTITY ecaron "ě">
-<!ENTITY Odblac "Ő">
-<!ENTITY fflig "ff">
-<!ENTITY lowast "∗">
-<!ENTITY nvdash "⊬">
-<!ENTITY frac18 "⅛">
-<!ENTITY sup1 "¹">
-<!ENTITY njcy "њ">
-<!ENTITY b.thetav "𝛝">
-<!ENTITY sup2 "²">
-<!ENTITY gimel "ℷ">
-<!ENTITY ldot "⋖">
-<!ENTITY Ccedil "Ç">
-<!ENTITY rdquo "”">
-<!ENTITY rhard "⇁">
-<!ENTITY nsime "≄">
-<!ENTITY boxhu "┴">
-<!ENTITY intcal "⊺">
-<!ENTITY nsupe "⊉">
-<!ENTITY Gt "≫">
-<!ENTITY igr "ι">
-<!ENTITY nabla "∇">
-<!ENTITY urcorn "⌝">
-<!ENTITY nle "≰">
-<!ENTITY Icy "И">
-<!ENTITY DJcy "Ђ">
-<!ENTITY jukcy "є">
-<!ENTITY lceil "⌈">
-<!ENTITY oS "Ⓢ">
-<!ENTITY malt "✠">
-<!ENTITY ccirc "ĉ">
-<!ENTITY ycirc "ŷ">
-<!ENTITY Aacgr "Ά">
-<!ENTITY Ntilde "Ñ">
-<!ENTITY vsupnE "⫌︀">
-<!ENTITY ogr "ο">
-<!ENTITY and "∧">
-<!ENTITY gvnE "≩︀">
-<!ENTITY dashv "⊣">
-<!ENTITY supE "⫆">
-<!ENTITY mu "μ">
-<!ENTITY vsubnE "⫋︀">
-<!ENTITY gE "≧">
-<!ENTITY smid "∣">
-<!ENTITY delta "δ">
-<!ENTITY tcaron "ť">
-<!ENTITY rsqb "]">
-<!ENTITY bull "•">
-<!ENTITY cuwed "⋏">
-<!ENTITY raquo "»">
-<!ENTITY frac45 "⅘">
-<!ENTITY part "∂">
-<!ENTITY Vdash "⊩">
-<!ENTITY boxhd "┬">
-<!ENTITY psi "ψ">
-<!ENTITY b.Omega "𝛀">
-<!ENTITY iquest "¿">
-<!ENTITY sqcup "⊔">
-<!ENTITY YUcy "Ю">
-<!ENTITY psgr "ψ">
-<!ENTITY conint "∮">
-<!ENTITY gel "⋛">
-<!ENTITY Icirc "Î">
-<!ENTITY twixt "≬">
-<!ENTITY boxHD "╦">
-<!ENTITY male "♂">
-<!ENTITY euro "€">
-<!ENTITY epsi "ϵ">
-<!ENTITY Rcaron "Ř">
-<!ENTITY SHCHcy "Щ">
-<!ENTITY ugr "υ">
-<!ENTITY Phi "Φ">
-<!ENTITY b.Xi "𝚵">
-<!ENTITY lt "<">
-<!ENTITY scnsim "⋩">
-<!ENTITY models "⊧">
-<!ENTITY boxHu "╧">
-<!ENTITY Lcy "Л">
-<!ENTITY Sacute "Ś">
-<!ENTITY nwarr "↖">
-<!ENTITY drcorn "⌟">
-<!ENTITY NJcy "Њ">
-<!ENTITY mumap "⊸">
-<!ENTITY rAarr "⇛">
-<!ENTITY nsubE "⫅̸">
-<!ENTITY b.rho "𝛒">
-<!ENTITY oelig "œ">
-<!ENTITY utrif "▴">
-<!ENTITY subne "⊊">
-<!ENTITY para "¶">
-<!ENTITY ocirc "ô">
-<!ENTITY ouml "ö">
-<!ENTITY num "#">
-<!ENTITY boxUL "╝">
-<!ENTITY IEcy "Е">
-<!ENTITY Ocy "О">
-<!ENTITY Ugrave "Ù">
-<!ENTITY eogon "ę">
-<!ENTITY sum "∑">
-<!ENTITY mcy "м">
-<!ENTITY YIcy "Ї">
-<!ENTITY Gamma "Γ">
-<!ENTITY isin "∈">
-<!ENTITY cuesc "⋟">
-<!ENTITY b.Pi "𝚷">
-<!ENTITY Ubreve "Ŭ">
-<!ENTITY starf "★">
-<!ENTITY gne "⪈">
-<!ENTITY gammad "ϝ">
-<!ENTITY napos "ʼn">
-<!ENTITY sup "⊃">
-<!ENTITY dArr "⇓">
-<!ENTITY Larr "↞">
-<!ENTITY nVDash "⊯">
-<!ENTITY boxhU "╨">
-<!ENTITY Ggr "Γ">
-<!ENTITY Idigr "Ϊ">
-<!ENTITY AElig "Æ">
-<!ENTITY Idot "İ">
-<!ENTITY Lacute "Ĺ">
-<!ENTITY sharp "♯">
-<!ENTITY Ubrcy "Ў">
-<!ENTITY lsqb "[">
-<!ENTITY micro "µ">
-<!ENTITY Sub "⋐">
-<!ENTITY agr "α">
-<!ENTITY nap "≉">
-<!ENTITY sfgr "ς">
-<!ENTITY block "█">
-<!ENTITY nspar "∦">
-<!ENTITY supnE "⫌">
-<!ENTITY prsim "≾">
-<!ENTITY shcy "ш">
-<!ENTITY dblac "˝">
-<!ENTITY xhArr "⟺">
-<!ENTITY dtri "▿">
-<!ENTITY barwed "⌅">
-<!ENTITY zcy "з">
-<!ENTITY agrave "à">
-<!ENTITY par "∥">
-<!ENTITY vsupne "⊋︀">
-<!ENTITY Scy "С">
-<!ENTITY zdot "ż">
-<!ENTITY rsquor "’">
-<!ENTITY Delta "Δ">
-<!ENTITY nVdash "⊮">
-<!ENTITY Pgr "Π">
-<!ENTITY gamma "γ">
-<!ENTITY tau "τ">
-<!ENTITY Ecirc "Ê">
-<!ENTITY sung "♪">
-<!ENTITY natur "♮">
-<!ENTITY or "∨">
-<!ENTITY vsubne "⊊︀">
-<!ENTITY Jcy "Й">
-<!ENTITY square "□">
-<!ENTITY b.Psi "𝚿">
-<!ENTITY b.zeta "𝛇">
-<!ENTITY gbreve "ğ">
-<!ENTITY Kcedil "Ķ">
-<!ENTITY ohm "Ω">
-<!ENTITY frac35 "⅗">
-<!ENTITY ssetmn "∖">
-<!ENTITY boxUR "╚">
-<!ENTITY frac34 "¾">
-<!ENTITY target "⌖">
-<!ENTITY cularr "↶">
-<!ENTITY xcirc "◯">
-<!ENTITY boxhD "╥">
-<!ENTITY iecy "е">
-<!ENTITY Euml "Ë">
-<!ENTITY half "½">
-<!ENTITY rang "〉">
-<!ENTITY numero "№">
-<!ENTITY Ugr "Υ">
-<!ENTITY semi ";">
-<!ENTITY times "×">
-<!ENTITY rharu "⇀">
-<!ENTITY iocy "ё">
-<!ENTITY b.gammad "ϝ">
-<!ENTITY lozf "⧫">
-<!ENTITY thinsp " ">
-<!ENTITY plusb "⊞">
-<!ENTITY tilde "˜">
-<!ENTITY Aogon "Ą">
-<!ENTITY Eogon "Ę">
-<!ENTITY blk12 "▒">
-<!ENTITY pre "⪯">
-<!ENTITY boxHd "╤">
-<!ENTITY piv "ϖ">
-<!ENTITY ncaron "ň">
-<!ENTITY wcirc "ŵ">
-<!ENTITY utri "▵">
-<!ENTITY Prime "″">
-<!ENTITY cedil "¸">
-<!ENTITY idigr "ϊ">
-<!ENTITY curren "¤">
-<!ENTITY laquo "«">
-<!ENTITY ulcrop "⌏">
-<!ENTITY ring "˚">
-<!ENTITY oacute "ó">
-<!ENTITY Nacute "Ń">
-<!ENTITY permil "‰">
-<!ENTITY oacgr "ό">
-<!ENTITY frac78 "⅞">
-<!ENTITY blk34 "▓">
-<!ENTITY gnsim "⋧">
-<!ENTITY boxVH "╬">
-<!ENTITY zhcy "ж">
-<!ENTITY b.phiv "𝛟">
-<!ENTITY loz "◊">
-<!ENTITY Ngr "Ν">
-<!ENTITY phgr "φ">
-<!ENTITY b.iota "𝛊">
-<!ENTITY ETH "Ð">
-<!ENTITY trade "™">
-<!ENTITY Cup "⋓">
-<!ENTITY subnE "⫋">
-<!ENTITY PHgr "Φ">
-<!ENTITY xi "ξ">
-<!ENTITY Rcy "Р">
-<!ENTITY ggr "γ">
-<!ENTITY Lmidot "Ŀ">
-<!ENTITY Scirc "Ŝ">
-<!ENTITY rtrif "▸">
-<!ENTITY larrtl "↢">
-<!ENTITY eDot "≑">
-<!ENTITY boxVL "╣">
-<!ENTITY THgr "Θ">
-<!ENTITY Dstrok "Đ">
-<!ENTITY cent "¢">
-<!ENTITY odash "⊝">
-<!ENTITY boxUl "╜">
-<!ENTITY ape "≊">
-<!ENTITY gEl "⪌">
-<!ENTITY nltri "⋪">
-<!ENTITY Aacute "Á">
-<!ENTITY cuvee "⋎">
-<!ENTITY gnE "≩">
-<!ENTITY kgr "κ">
-<!ENTITY iogon "į">
-<!ENTITY rarrtl "↣">
-<!ENTITY b.phi "𝛗">
-<!ENTITY sccue "≽">
-<!ENTITY IOcy "Ё">
-<!ENTITY sext "✶">
-<!ENTITY uplus "⊎">
-<!ENTITY ecolon "≕">
-<!ENTITY nlArr "⇍">
-<!ENTITY scap "⪸">
-<!ENTITY rarrlp "↬">
-<!ENTITY ngE "≧̸">
-<!ENTITY nsim "≁">
-<!ENTITY Acy "А">
-<!ENTITY emacr "ē">
-<!ENTITY Jcirc "Ĵ">
-<!ENTITY ltimes "⋉">
-<!ENTITY Bcy "Б">
-<!ENTITY b.Sigma "𝚺">
-<!ENTITY cup "∪">
-<!ENTITY fork "⋔">
-<!ENTITY frac25 "⅖">
-<!ENTITY setmn "∖">
-<!ENTITY bsol "\">
-<!ENTITY Ycy "Ы">
-<!ENTITY b.Phi "𝚽">
-<!ENTITY Gcedil "Ģ">
-<!ENTITY frac23 "⅔">
-<!ENTITY Iogon "Į">
-<!ENTITY blank "␣">
-<!ENTITY vprop "∝">
-<!ENTITY boxVR "╠">
-<!ENTITY ecy "э">
-<!ENTITY OHacgr "Ώ">
-<!ENTITY yen "¥">
-<!ENTITY hairsp " ">
-<!ENTITY plusdo "∔">
-<!ENTITY lvnE "≨︀">
-<!ENTITY boxUr "╙">
-<!ENTITY breve "˘">
-<!ENTITY rtimes "⋊">
-<!ENTITY gnap "⪊">
-<!ENTITY rtrie "⊵">
-<!ENTITY Mcy "М">
-<!ENTITY chi "χ">
-<!ENTITY tdot " ⃛">
-<!ENTITY PSgr "Ψ">
-<!ENTITY Umacr "Ū">
-<!ENTITY caret "⁁">
-<!ENTITY xutri "△">
-<!ENTITY CHcy "Ч">
-<!ENTITY djcy "ђ">
-<!ENTITY lambda "λ">
-<!ENTITY Tstrok "Ŧ">
-<!ENTITY puncsp " ">
-<!ENTITY Ll "⋘">
-<!ENTITY aacgr "ά">
-<!ENTITY xdtri "▽">
-<!ENTITY GJcy "Ѓ">
-<!ENTITY gdot "ġ">
-<!ENTITY sub "⊂">
-<!ENTITY mid "∣">
-<!ENTITY dzcy "џ">
-<!ENTITY igrave "ì">
-<!ENTITY Emacr "Ē">
-<!ENTITY Rcedil "Ŗ">
-<!ENTITY gt ">">
-<!ENTITY harr "↔">
-<!ENTITY larrlp "↫">
-<!ENTITY thgr "θ">
-<!ENTITY drarr "↘">
-<!ENTITY map "↦">
-<!ENTITY boxVh "╫">
-<!ENTITY ijlig "ij">
-<!ENTITY tcedil "ţ">
-<!ENTITY dlcrop "⌍">
-<!ENTITY prnsim "⋨">
-<!ENTITY ecir "≖">
-<!ENTITY rgr "ρ">
-<!ENTITY deg "°">
-<!ENTITY lap "⪅">
-<!ENTITY KJcy "Ќ">
-<!ENTITY Cdot "Ċ">
-<!ENTITY Uogon "Ų">
-<!ENTITY not "¬">
-<!ENTITY dash "‐">
-<!ENTITY nexist "∄">
-<!ENTITY Lt "≪">
-<!ENTITY b.Upsi "𝚼">
-<!ENTITY Atilde "Ã">
-<!ENTITY edot "ė">
-<!ENTITY Ncedil "Ņ">
-<!ENTITY els "⪕">
-<!ENTITY erDot "≓">
-<!ENTITY boxVl "╢">
-<!ENTITY scy "с">
-<!ENTITY ulcorn "⌜">
-<!ENTITY eacgr "έ">
-<!ENTITY Itilde "Ĩ">
-<!ENTITY Zacute "Ź">
-<!ENTITY xharr "⟷">
-<!ENTITY gl "≷">
-<!ENTITY chcy "ч">
-<!ENTITY Oacute "Ó">
-<!ENTITY itilde "ĩ">
-<!ENTITY Ycirc "Ŷ">
-<!ENTITY nhArr "⇎">
-<!ENTITY Lstrok "Ł">
-<!ENTITY divide "÷">
-<!ENTITY Tcy "Т">
-<!ENTITY Jukcy "Є">
-<!ENTITY Yacute "Ý">
-<!ENTITY boxv "│">
-<!ENTITY hamilt "ℋ">
-<!ENTITY nu "ν">
-<!ENTITY ngt "≯">
-<!ENTITY jsercy "ј">
-<!ENTITY uml "¨">
-<!ENTITY KHgr "Χ">
-<!ENTITY lstrok "ł">
-<!ENTITY nsupE "⫆̸">
-<!ENTITY dtrif "▾">
-<!ENTITY vellip "⋮">
-<!ENTITY rceil "⌉">
-<!ENTITY ell "ℓ">
-<!ENTITY Ecy "Э">
-<!ENTITY Jsercy "Ј">
-<!ENTITY ljcy "љ">
-<!ENTITY Kgr "Κ">
-<!ENTITY ngr "ν">
-<!ENTITY sigmav "ς">
-<!ENTITY Gdot "Ġ">
-<!ENTITY rdquor "”">
-<!ENTITY prnap "⪹">
-<!ENTITY tcy "т">
-<!ENTITY frac12 "½">
-<!ENTITY telrec "⌕">
-<!ENTITY vdash "⊢">
-<!ENTITY Zgr "Ζ">
-<!ENTITY Auml "Ä">
-<!ENTITY Ocirc "Ô">
-<!ENTITY uogon "ų">
-<!ENTITY hArr "⇔">
-<!ENTITY nge "≱">
-<!ENTITY iacute "í">
-<!ENTITY Cacute "Ć">
-<!ENTITY Omacr "Ō">
-<!ENTITY equiv "≡">
-<!ENTITY vltri "⊲">
-<!ENTITY eta "η">
-<!ENTITY SHcy "Ш">
-<!ENTITY lowbar "_">
-<!ENTITY percnt "%">
-<!ENTITY frac16 "⅙">
-<!ENTITY lrarr2 "⇆">
-<!ENTITY nles "⩽̸">
-<!ENTITY bump "≎">
-<!ENTITY veebar "⊻">
-<!ENTITY Wcirc "Ŵ">
-<!ENTITY frac15 "⅕">
-<!ENTITY bumpe "≏">
-<!ENTITY egrave "è">
-<!ENTITY frac14 "¼">
-<!ENTITY supe "⊇">
-<!ENTITY rfloor "⌋">
-<!ENTITY Dgr "Δ">
-<!ENTITY frac13 "⅓">
-<!ENTITY ge "≥">
-<!ENTITY boxVr "╟">
-<!ENTITY pgr "π">
-<!ENTITY kgreen "ĸ">
-<!ENTITY boxh "─">
-<!ENTITY Lambda "Λ">
-<!ENTITY ugrave "ù">
-<!ENTITY emsp13 " ">
-<!ENTITY becaus "∵">
-<!ENTITY sce "⪰">
-<!ENTITY grave "`">
-<!ENTITY zeta "ζ">
-<!ENTITY b.Theta "𝚯">
-<!ENTITY eth "ð">
-<!ENTITY Ouml "Ö">
-<!ENTITY check "✓">
-<!ENTITY hybull "⁃">
-<!ENTITY Gg "⋙">
-<!ENTITY Ccaron "Č">
-<!ENTITY plus "+">
-<!ENTITY fllig "fl">
-<!ENTITY forall "∀">
-<!ENTITY dcaron "ď">
-<!ENTITY gacute "ǵ">
-<!ENTITY sc "≻">
-<!ENTITY OHgr "Ω">
-<!ENTITY emsp14 " ">
-<!ENTITY hellip "…">
-<!ENTITY lhard "↽">
-<!ENTITY sstarf "⋆">
-<!ENTITY samalg "∐">
-<!ENTITY EEgr "Η">
-<!ENTITY rhov "ϱ">
-<!ENTITY b.epsi "𝛆">
-<!ENTITY lsquo "‘">
-]>
-<book>
- <bookinfo>
- <title>JBoss Application Server</title>
- <subtitle>Installation And Getting Started Guide</subtitle>
- <issuenum>5.0</issuenum>
- <productnumber>0</productnumber>
-
- <authorgroup>
-
- <author>
- <firstname>JBoss</firstname>
- <surname>Community</surname>
-
- </author>
-
-
-</authorgroup>
-</bookinfo>
- <preface id="Book-Preface">
- <title>Introduction</title>
- <para>
- JBoss Application Server is the open source implementation of the Java EE suite of services. It comprises a set of offerings for enterprise customers who are looking for preconfigured profiles of JBoss Enterprise Middleware components that have been tested and certified together to provide an integrated experience. It's easy-to-use server architecture and high flexibility makes JBoss the ideal choice for users just starting out with J2EE, as well as senior architects looking for a customizable middleware platform.
- </para>
- <para>
- Because it is Java-based, JBoss Application Server is cross-platform, easy to install and use on any operating system that supports Java. The readily available source code is a powerful learning tool to debug the server and understand it. It also gives you the flexibility to create customized versions for your personal or business use.
- </para>
- <para>
- Installing JBoss Application Server is simple and easy. You can have it installed and running in no time. This guide will teach you to install and get started with the JBoss Application Server.</para>
- <section id="Software_Versions">
- <title>Software Versions</title>
- <para>
- <table>
- <title>Software Versions</title>
- <tgroup cols="2">
- <colspec colwidth="25*"/>
- <colspec colwidth="75*"/>
- <thead>
- <row><entry>Software</entry>
- <entry>Description</entry></row>
- </thead>
- <tbody>
- <row>
- <entry><para>JBoss Application Server</para></entry>
- <entry><para>5.0.0</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
-</section>
- <section id="Book-We_Need_Feedback">
- <title>Help Contribute</title>
- <para>
- If you find a typographical error in the <citetitle>Installation Guide and Getting Started Guide</citetitle>, or if you have thought of a way to make this manual better, we would love to hear from you! Please submit a report in JIRA: <ulink url="http://jira.jboss.com">http://jira.jboss.com</ulink> against the project <citetitle>JBoss Application Server</citetitle> and component <citetitle>Docs/Installation and Getting Started Guide</citetitle>.
- </para>
- <para>
- If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
- </para>
- <note><title>Note</title><para>Be sure to give us your name so you can receive full credit.</para></note>
-
- <note><title>Note</title><para>This content is taken from svn.jboss.org/repos/jbossas/projects/docs/community/5 and has yet to be branched.</para></note>
-
- <para>To access the content directly and make changes yourself:</para>
- <screen>
- svn co https://svn.jboss.org/repos/jbossas/projects/docs/community/5 --username yourusername
- </screen>
-</section>
-</preface>
- <chapter id="Getting_Started">
- <title>Getting Started</title>
- <section id="Getting_Started-Pre_Requisites">
- <title>Pre-Requisites</title>
- <para>
- You must have adequate disk space to install JDK and JBoss Application Server while also allowing enough space for your applications. Before installing JBoss Application Server you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java.
- </para>
- <section id="Pre_Requisites-Hardware_and_Operating_System_Requirements">
- <title>Hardware and Operating System Requirements</title>
-
- <para>For the latest information on supported Operating System / JVM combinations and supported Database platforms, please refer to <ulink url="http://www.jboss.com">http://www.jboss.com</ulink>.
- </para>
-
- </section>
-
- <section id="Pre_Requisites-Configuring_Your_Java_Environment">
- <title>Configuring Your Java Environment</title>
- <para>
- You must have a working installation of <emphasis>JDK 1.5</emphasis> or <emphasis>JDK 1.6</emphasis> before you install JBoss Application Server. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 5.0 on a Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM.
- <itemizedlist id="Configuring_Your_Java_Environment-Benefits_of_64_bit_JVM_on_64_bit_OS_and_Hardware">
- <title>Benefits of 64-bit JVM on 64-bit OS and Hardware:</title>
- <listitem>
- <para>
- Wider datapath: The pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications.
- </para>
- </listitem>
- <listitem>
- <para>
- 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection.
- </para>
- </listitem>
- <listitem>
- <para>
- Applications that run with more than 1.5GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.
- </para>
- </listitem>
- <listitem>
- <para>
- Applications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Linux">
- <title>Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Linux</title>
- <listitem>
- <para>
- Download the Sun JDK 5.0 or JDK 6 (Java 2 Development Kit) from Sun's website: <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp"/> for JDK 5.0 or <ulink url="http://java.sun.com/javase/downloads/"/> for JDK 6.0. Select the JDK Update <x>" (where x is the latest update number) for download and then select "RPM in self-extracting" file for Linux<footnote><para>Make sure you choose the appropriate file for your platform.</para></footnote>. Read the instructions on Sun's website for installing the JDK.
- </para>
- </listitem>
- <listitem>
- <para>
- If you do not want to use SysV service scripts you can install the "self-extracting file" for Linux instead of choosing the "RPM in self-extracting" file. In that case you can skip the next step mentioned here. But it is recommended to use the SysV service scripts for production servers.
- </para>
- </listitem>
- <listitem>
- <para>
- Download and install the appropriate <literal>-compat RPM</literal> from <literal>JPackage</literal> <ulink url="ftp://jpackage.hmdc.harvard.edu/JPackage/1.7/generic/RPMS.non-free/"> here</ulink>. Please ensure you choose a matching version of the <literal>-compat</literal> package to the JDK you installed.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Create an environment variable that points to the JDK installation directory and call it <literal>JAVA_HOME</literal>. Add <literal>$JAVA_HOME/bin</literal> to the system path to be able to run <literal>java</literal> from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory.
-<programlisting>#In this example /usr/java/jdk1.6.0_07 is the JDK installation directory.
-export JAVA_HOME=/usr/java/jdk1.6.0_07
-export PATH=$PATH:$JAVA_HOME/bin
-</programlisting>
- Set this variable for the user account doing the installation and also for the user account that will run the server.
- </para>
- </listitem>
- <listitem>
- <para>
- If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.5 or JDK1.6 installation as the default source for the <literal>java</literal> and <literal>javac</literal> executables. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system.
- <itemizedlist>
- <title>Select alternatives for java, javac and java_sdk_1.<x></title>
- <listitem>
- <para>
- As root, type the following command at the shell prompt and you should see something like this: <programlisting>
-[root at vsr ~]$ /usr/sbin/alternatives --config java
-There are 2 programs which provide 'java'.
-Selection Command
------------------------------------------------
- 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java
-*+ 2 /usr/lib/jvm/jre-1.5.0-sun/bin/java
-Enter to keep the current selection[+], or type selection number:
-</programlisting>
- Make sure the Sun version [<literal>jre-1.5.0-sun</literal> in this case] is selected (marked with a '+' in the output), or select it by entering its number as prompted.
- </para>
- </listitem>
- <listitem>
- <para>
- Repeat the same for javac and java_sdk_1.<x> <programlisting>
-[root at vsr ~]$ /usr/sbin/alternatives --config javac
-There are 1 programs which provide 'javac'.
- Selection Command
------------------------------------------------
-*+ 1 /usr/lib/jvm/java-1.5.0-sun/bin/javac
-Enter to keep the current selection[+], or type selection number:
-</programlisting>
-<programlisting>
-[root at vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.5.0
-There are 1 programs which provide 'java_sdk_1.5.0'.
- Selection Command
------------------------------------------------
-*+ 1 /usr/lib/jvm/java-1.5.0-sun
-Enter to keep the current selection[+], or type selection number:
-</programlisting>
- You should verify that java, javac and java_sdk_1.<x> all point to the same manufacturer and version.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <note>
- <para>
- You can always override this step by setting the <literal>JAVA_HOME</literal> environment variable as explained in the previous step.
- </para>
- </note>
- </listitem>
- <listitem>
- <para>
- Make sure that the <literal>java</literal> executable is in your path and that you are using an appropriate version. To verify your Java environment, type <literal>java -version</literal> at the shell prompt and you should see something like this: <programlisting>
-[root at vsr ~]$ java -version
-java version "1.5.0_14"
-Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_14-b03)
-Java HotSpot(TM) Client VM (build 1.5.0_14-b03, mixed mode, sharing)
-</programlisting>
- </para>
- </listitem>
- </itemizedlist>
- <itemizedlist id="Configuring_Your_Java_Environment-Installing_and_Configuring_32_bit_Sun_JDK_5.0_on_Microsoft_Windows">
- <title>Installing and Configuring 32-bit Sun JDK 5.0 or JDK 6.0 on Microsoft Windows</title>
- <listitem>
- <para>
- Download the Sun JDK 5.0 (Java 2 Development Kit) from Sun's website: <ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp"/> for JDK 5.0 or <ulink url="http://java.sun.com/javase/downloads/"/> for JDK 6.0. Choose the JDK Update <x>" (where x is the latest update number) for download and then select your Windows Platform options to perform the installation.
- </para>
- </listitem>
- <listitem>
- <para>
- Create an environment variable called <literal>JAVA_HOME</literal> that points to the JDK installation directory, for example: <literal>C:\Program Files\Java\jdk1.5.0_14\</literal>. In order to run java from the command line add the <literal>jre\bin</literal> directory to your path, for example: <literal>C:\Program Files\Java\jdk1.5.0_14\jre\bin</literal>. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
-
-
-
-
- </section>
-</chapter>
- <chapter id="Installation_Alternatives">
- <title>Installation Alternatives</title>
- <para>
- You can install the JBoss Application Server in one of these two modes: <itemizedlist>
- <!--<listitem>
- <para>
- <emphasis>Graphical Installer</emphasis>
- </para>
- <para>
- Using the Graphical Installer can simplify the installation and configuration process for non-sophisticated users. In addition to the basic installation, the installer provides you with basic configuration capabilities, allows you to control whether the JMX interfaces are secured and the ability to enter console username/password. The graphical installer is available for <emphasis>subscribed users</emphasis> on <ulink url="https://network.jboss.com"/>.
- </para>
- </listitem>-->
- <listitem>
- <para>
- <emphasis>Binary files download</emphasis>
- </para>
- <para>
- In this form of installation, simply unzip the downloaded zip file to the directory of your choice. You can unzip the JBoss Application Server on any operating system that supports the zip format. The zip file is available on <ulink url="http://labs.jboss.com/jbossas/downloads/"/>. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in <xref linkend="Getting_Started-Pre_Requisites"/>. Further details on installation using the Binary files are discussed in <xref linkend="binary_installation"/>
- </para>
- <para>
- JBossAS 5.0.0 can be compiled with both Java5 and Java6. The Java5 compiled binary is our primary/recommended binary distribution. It has undergone rigorous testing and can run under both a Java 5 and a Java 6 runtime. When running
- under Java 6 you need to manually copy the following libraries from the <filename>JBOSS_HOME/client</filename> directory to the <filename>JBOSS_HOME/lib/endorsed</filename> directory, so that the JAX-WS 2.0 apis supported by JBossWS are used:
- </para>
-<screen>* jbossws-native-saaj.jar
-* jbossws-native-jaxrpc.jar
-* jbossws-native-jaxws.jar
-* jbossws-native-jaxws-ext.jar </screen>
- <para>
- Another alternative is to download the jdk6 distribution <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2-jdk6.zip?modtime=1221686600&big_mirror=1">(<filename>jboss-5.0.0.CR2-jdk6.zip</filename>)</ulink> in which case no configuration changes are required.
-
- Please refer to the <ulink url="http://sourceforge.net/project/shownotes.php?release_id=627020&group_id=22866">release notes</ulink> for additional information about running with JDK 6.
- </para>
-
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Source Files download</emphasis>
- </para>
- <para>
- In this form of installation, download the source files from the web and build the source files locally. On successfully building your source files you can manually copy the built file into a desired folder and start the server. Please ensure you have met the pre-requisites required before proceeding with your installation. Pre-requisites are discussed in <xref linkend="Getting_Started-Pre_Requisites"/>. For more instructions on building your source files, please refer to <xref linkend="source_installation"/>.
- </para>
- </listitem>
- <!--<listitem>
- <para>
- <emphasis>RPM download</emphasis>
- </para>
- <para>
- In this form of installation, you can automatically install the platform on a &RHEL; system using the <literal>up2date</literal> command. The RPM installer is available for <emphasis>subscribed users</emphasis> on the Red Hat Network (RHN) on <ulink url="http://rhn.redhat.com"/>.
- </para>
- </listitem>-->
- </itemizedlist>
- </para>
- <!--<para>
- When you install from the installer, you get a smaller install image that is more tuned for your environment. However, the directory structure will be slightly different than when using the rpm/zip archive.
- </para>-->
- <para>
- Three types of server configurations will be included in your installation - <emphasis>minimal</emphasis>, <emphasis>default</emphasis>, and <emphasis>all</emphasis>.
- </para>
-</chapter>
- <chapter id="binary_installation">
- <title>Installation With Binary Download</title>
-
- <section id="Binary_Download">
- <title>Download and Installation</title>
-
- <para>
- You can download the Binary zip files from <ulink url="http://labs.jboss.com/jbossas/downloads/">http://labs.jboss.com/jbossas/downloads/</ulink>.
- </para>
- <para>
- There are two binary distributions available:
- </para>
-<orderedlist>
- <listitem>
- <para>
- <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2.zip?modtime=1221686752&big_mirror=1">jboss-5.0.0.CR2.zip</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://downloads.sourceforge.net/jboss/jboss-5.0.0.CR2-jdk6.zip?modtime=1221686600&big_mirror=1">jboss-5.0.0.CR2-jdk6.zip</ulink>
- </para>
- </listitem>
-</orderedlist>
-
- <para>
- In this form of installation, simply unzip the downloaded zip file to the directory of your choice on any operating system that supports the zip format.
- <itemizedlist>
- <listitem>
- <para>
- Unzip <literal>jboss-<release>.zip</literal> to extract the archive contents into the location of your choice. You can do this using the JDK <literal>jar</literal> tool (or any other ZIP extraction tool). In the example below we are assuming you downloaded the zip file to the <filename>/jboss</filename> directory.
-<programlisting>
-[usr]$ <literal>cd /jboss</literal>
-[usr]$ <literal>jar -xvf jboss-<release>.zip</literal></programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- You should now have a directory called <filename>jboss-<release></filename>. Next you need to set your JBOSS_HOME environment variables. This is discussed in <xref linkend="setting_JBOSS_HOME"/>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
-
-</chapter>
- <chapter id="source_installation">
- <title>Installation With Source Download</title>
-
- <section id="Source_Download">
- <title>Download and Installation</title>
-
- <para>
- You can download the zip source file from <ulink url="http://labs.jboss.com/jbossas/downloads/">http://labs.jboss.com/jbossas/downloads/</ulink>.
-
- <itemizedlist>
- <listitem>
- <para>
- Uncompress <literal>jboss-<release>-src.tar.gz</literal> to extract the archive contents into the location of your choice. You can do this using the <literal>tar</literal> archiving utility in Linux (or any other compatible extraction tool). In this example we are assuming your source files were copied in the <filename>/jboss</filename> folder.
-
-<screen>[user at localhost]$ cd /jboss
-[user at localhost]$ tar -xvf <literal>jboss-<release>-src.tar.gz</literal></screen>
-
-</para>
- </listitem>
- <listitem>
- <para>
- You should now have a directory called <literal>jboss-<release>-src.tar.gz</literal>. The next step is to build your source files. In this example we are using Apache ANT. This is discussed in the following section.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section><title>Installing and configuring ANT</title>
- <para>
- <ulink url="http://ant.apache.org/">Apache Ant</ulink> is a Java-based build tool. Instead of using an extended model using shell-based commands, Ant is extended using Java classes that use XML-based configuration files. The configuration files call out a target tree that executes various tasks. Each task is run by an object that implements a particular Task interface.
- This gives you the ability to perform cross platform builds. Please also note that if needed, Ant provides an <exec> task that allows commands to be executed based on the Operating System it is executing on. For more information on Apache ANT please click <ulink url="http://ant.apache.org/">here</ulink>.
- </para>
- <para>
- You will need to build your JBoss Application Server source files before you can run the application server. Apache Ant is shipped with the JBoss Application Server source files and can be executed from the <filename><source_directory>/tools/bin</filename> directory.
- </para>
- <para>
- The source files can also be built using Apache Maven which is also shipped with the JBoss Application Server source files under <filename><source_directory>/tools/maven</filename> directory. For more information about Apache Maven, please refer to <ulink url="">http://maven.apache.org/</ulink>.
- </para>
-
- <para>
- Like Java, you also need to set the environment variables for Apache ANT and/or Apache Maven. The following example illustrates a desirable configuration for the <filename>.bashrc</filename> file. In the example the file is edited using the gnome text editor (<command>gedit</command>).
-
-<screen>[user at localhost ~]$ gedit .bashrc
-
-# Source global definitions
-if [ -f /etc/bashrc ]; then
-/etc/bashrc
-fi
-......
-# User specific aliases and functions
-# The following are the environment variables for Java , ANT and Maven
-
-export JAVA_HOME=/usr/java/jdk1.6.0_07/
-export PATH=$PATH:$JAVA_HOME/bin
-
-export ANT_HOME=/home/downloads/jboss-<source_directory>/tools/
-export PATH=$PATH:$ANT_HOME/bin
-
-export MAVEN_HOME=/home/downloads/jboss-<source_directory>/tools/maven
-export PATH=$PATH:$MAVEN_HOME/bin
-</screen>
-
- </para>
- <para>
- To implement the changes you've made to the <filename>.bashrc</filename> file, type the following on a terminal.
-
-<screen>[user at localhost ~]$ source .bashrc
-[user at localhost ~]$</screen>
-
- If any errors are displayed, please check your <filename>.bashrc</filename> file for errors and ensure that all directory paths are correct.
- </para>
- </section>
-
-<section><title>Building with Apache ANT</title>
- <para>
- To build the JBoss Application Server source files with Apache ANT, from a terminal change directory to where the unzipped source files are. In the following example we are assuming that the source files were copied and unzipped in the logged in user's <filename>downloads</filename> folder.
-
-<screen>[user at localhost]$ cd /home/user/downloads/<literal>jboss-<release>-src</literal>/build
-[user at localhost build]$ ls
-aspects component-matrix docbook-support iiop jmx mbeans security system-jmx tools
-bootstrap connector ejb3 j2se jmx-remoting messaging server testsuite varia
-build console embedded jbossas main pom.xml spring-int thirdparty webservices
-cluster deployment hibernate-int jbossmq management profileservice system tomcat
-</screen>
- From the contents of the <filename>build</filename> directory above, you can see the <filename>build.xml</filename> file which is used by Apache ANT as a configuration file when building your source files.
- The next step is to perform the build using Apache ANT as illustrated below.
-<screen>[user at localhost build]$ ant
-
-compile-classes:
-[mkdir] Created dir: /jboss/jboss-<release>-src/tomcat/output/classes
-[javac] Compiling 89 source files to /jboss/jboss-<release>-src/tomcat/output/classes
-....
-....content truncated
-.....
-.....
-_buildmagic:build-bypass-check:
-jars:
-most:
-main:
-BUILD SUCCESSFUL
-Total time: 2 seconds</screen>
-
-A successful build will have the above message. If your build fails, please check the error log and ensure that your configuration files and environment variables are correctly set. The JBoss Application Server files are built under the <filename>build/output/jboss-<release></filename> directory as indicated below.
-
-<note><title>Note</title>
- <para>At this point the JBoss Application Server source files build is a hybrid one (builds in both Ant and Maven) because it declares all JBoss dependencies as maven2 artifacts, however after the dependencies are resolved/imported the legacy ant based build is used to compile and build the distribution. The JBoss Application Server source files will change to a full maven build soon.
- </para>
-</note>
-
-<screen>[user at localhost build]$ ls
-build.bat build-old.xml build-thirdparty-old.xml eclipse.psf output
-build-distr.xml build-release.xml build.xml etc pom.xml
-build.log build.sh docs local.properties VersionRelease.java
-
-[user at localhost build]$ cd output/jboss-<release>
-[user at localhost build]$ ls
-bin client docs lib server
-</screen>
-
- The <filename>jboss-<release></filename> directory contains your successful JBoss Application Server files. You can copy this folder to a different location or run the server from this folder after setting the JBOSS_HOME environment variable in your <filename>.bashrc</filename> file. Next you need to set your JBOSS_HOME environment variables. This is discussed in <xref linkend="setting_JBOSS_HOME"/>.
-
- </para>
- </section>
-
-
-
-
-</chapter>
- <chapter id="setting_JBOSS_HOME">
- <title>Setting the JBOSS_HOME variable</title>
-
-<section id="setting_JBOSS_HOME_linux"><title>Setting the <command>JBOSS_HOME</command> variable in Linux.</title>
-
- <para>
- Before you can run the JBoss Application Server, you need to ensure that you've configured the JBOSS_HOME environment variable in your <filename>.bashrc</filename> file as follows. In this example the Application Server folder has beeen copied to the <filename>/usr/jboss/jboss-<release></filename> folder.
- The following is a <filename>.bashrc</filename> file used in this installation. Please ensure that your <filename>.bashrc</filename> file has a similar configuration.
-
-<screen>[user at localhost ~]$ gedit .bashrc
-
-# Source global definitions
-if [ -f /etc/bashrc ]; then
-/etc/bashrc
-fi
-......
-# User specific aliases and functions
-# The following are the environment variables for Java, ANT and JBoss
-
-export JAVA_HOME=/usr/java/jdk1.6.0_07
-export PATH=$PATH:$JAVA_HOME/bin
-
-export ANT_HOME=/usr/ant/apache-ant-1.6.0
-export PATH=$PATH:$ANT_HOME/bin
-
-export JBOSS_HOME=/usr/jboss/jboss-<release>
-export PATH=$PATH:$JBOSS_HOME/bin
-</screen>
-
- To implement your <filename>.bashrc</filename> file changes run the following command.
-
-<screen>[user at localhost ~]$ source .bashrc
-[user at localhost ~]$</screen>
-
- If no errors are displayed on your terminal, you are now ready to run your JBoss Application Server.
- </para>
-
- </section>
-
-<section id="setting_JBOSS_HOME_windows"> <title>Setting the <command>JBOSS_HOME</command> variable in Windows.</title>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- Create an environment variable called <literal>JBOSS_HOME</literal> that points to the JBoss Application Server installation directory, for example: <literal>C:\Program Files\JBoss\jboss-<release>\</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- In order to run JBoss Application Server from the command line, add the <literal>jboss-<release>\bin</literal> directory to your path, for example: <literal>C:\Program Files\JBoss\jboss-<release>\bin</literal>. To do this, open the Control Panel from the Start Menu, switch to Classic View if necessary, open the System Control Panel applet, select the Advanced Tab, and click on the Environment Variables button.
- </para>
- </listitem>
- </itemizedlist>
- You are now ready to start the JBoss Application Server.
- </para>
-
-</section>
-
-</chapter>
-
- <chapter id="Uninstall_JBoss">
- <title>Uninstall JBoss</title>
- <para>
- The JBoss Application Server may be uninstalled by simply deleting the JBoss Application Server's installation directory. You will also need to remove the <emphasis>JBOSS_HOME</emphasis> environment variables discussed in <xref linkend="setting_JBOSS_HOME"/> for your Linux or Windows platform.
- </para>
-</chapter>
- <chapter id="Test_your_Installation">
- <title>Test your Installation</title>
- <para>
- After you have installed the JBoss Application Server, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. To test your installation, open the <filename>JBOSS_DIST/jboss-<release>/bin</filename> directory and execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system.
- </para>
- <para>
- Your output should look similar to the following (accounting for installation directory differences) and contain no error or exception messages:
- </para>
-<screen>
-[samson at dhcp-1-150 bin]$ sh run.sh
-=========================================================================
-
-JBoss Bootstrap Environment
-
-JBOSS_HOME: /home/svn/JBossHead/jboss-head/build/output/jboss-5.0.0.GA
-
-JAVA: /Library/Java/Home/bin/java
-
-JAVA_OPTS: -Dprogram.name=run.sh -Xms128m -Xmx512m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
-
-CLASSPATH: /home/svn/JBossHead/jboss-head/build/output/jboss-5.0.0.GA/bin/run.jar
-
-=========================================================================
-
-21:47:23,874 INFO [ServerImpl] Starting JBoss (Microcontainer)...
-21:47:23,875 INFO [ServerImpl] Release ID: JBoss [Morpheus] 5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812011226)
-.
-.
-...output truncated
-.
-.
-21:47:46,090 INFO [AjpProtocol] Starting Coyote AJP/1.3 on ajp-127.0.0.1-8009
-21:47:46,112 INFO [ServerImpl] JBoss (Microcontainer) [5.0.0.GA (build: SVNTag=JBoss_5_0_0_GA date=200812011226)] Started in 22s:227ms
-</screen>
- <!--<note>
- <para>
- Note that there is no "Server Started" message shown at the console when the server is started using the <literal>default</literal> profile, which is the default profile used when no other is specified. This message may be observed in the <filename>server.log</filename> file located in the <filename>server/defaut/log</filename> subdirectory.
- </para>
- </note>-->
- <para>
- Now open <literal>http://localhost:8080</literal> in your web browser. (Make sure you dont have anything else already on your machine using that port).<footnote><para>
- Note that on some machines, the name localhost may not resolve properly and you may need to use the local loopback address 127.0.0.1 instead.</para></footnote> The contents of your page should look similar to the following: <xref linkend="Test_your_Installation-Test_your_Installation"/>.
- </para>
- <para>
- <figure id="Test_your_Installation-Test_your_Installation">
- <title>Test your Installation</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/test_install.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </para>
- <para>
- You are now ready to use the JBoss Application Server.
- </para>
-</chapter>
- <chapter id="The_JBoss_Server___A_Quick_Tour">
- <title>The JBoss Server - A Quick Tour</title>
-
-<section><title>Server Structure</title>
-
- <para>
- Now that you’ve downloaded JBoss and have run the server for the first time, the next thing you will want to know is how the installation is laid out and what goes where. At first glance there seems to be a lot of stuff in there, and it’s not obvious what you need to look at and what you can safely ignore for the time being. To remedy that, we’ll explore the server directory structure, locations of the key configuration files, log files, deployment and so on. It’s worth familiarizing yourself with the layout at this stage as it will help you understand the JBoss service architecture so that you’ll be able to find your way around when it comes to deploying your own applications.
- </para>
-
-
-<!-- Embedded sections -->
-
- <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations">
- <title>Server Configurations</title>
- <para>
- Fundamentally, the JBoss architecture consists of the microcontainer, bootstrap beans loaded into the micrcontainer, a collection of deployers for loading various deployment types, and various mcbean(-jboss-beans.xml) and legacy mbean(jboss-service.xml) deployments.
- This makes it easy to assemble different configurations and gives you the flexibility to tailor them to meet your requirements.
- </para>
- <para>
- You don’t have to run a large, monolithic server all the time; you can remove the components you don’t need (which can also reduce the server startup time considerably) and you can also integrate additional services into JBoss by writing your own MBeans. You certainly do not need to do this to be able to run standard Java EE 5 applications though.
- </para>
- <para>
- You don’t need a detailed understanding of the microcontainer to use JBoss, but it’s worth keeping a picture of this basic architecture in mind as it is central to the way JBoss works.
- </para>
- <para>
- The JBoss Application Server ships with three different server configurations. Within the <literal><JBoss_Home>/server</literal> directory, you will find five subdirectories:
- <literal>minimal</literal>, <literal>default</literal>, <literal>standard</literal>, <literal>all</literal> and <literal>web</literal> - one for each server configuration. Each of these configurations provide a different set of services. The <literal>default</literal> configuration is the one used if you don’t specify another one when starting up the server.
- </para>
- <para>
- <variablelist>
- <varlistentry>
- <term>minimal</term>
- <listitem>
- <para>
- has a minimal configuration—the bare minimum services required to start JBoss. It starts the logging service, a JNDI server and a URL deployment scanner to find new deployments. This is what you would use if you want to use JMX/JBoss to start your own services without any other Java EE 5 technologies. This is just the bare server. There is no web container, no EJB or JMS support.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>default</term>
- <listitem>
- <para>
- is a base Java EE 5 server profile containing a default set of services. It has the most frequently used services required to deploy a Java EE application. It does not include the JAXR service, the IIOP service, or any of the clustering services.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>all</term>
- <listitem>
- <para>
- The all configuration starts all the available services. This includes the RMI/IIOP and clustering services, which are not loaded in the default configuration.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>standard</term>
- <listitem>
- <para>
- is the JavaEE 5 certified configuration of services.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>web</term>
- <listitem>
- <para>
- is a lightweight web container oriented profile that previews the JavaEE 6 web profile.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>
- If you want to know which services are configured in each of these instances, the primary differences will be in the <filename class="directory"><JBoss_Home>/server/<instance-name>/deployers/</filename> directory and also the services deployments in the <filename class="directory"><JBoss_Home>/server/<instance-name>/deploy</filename> directory. For example, the default profile deployers and deploy directory contents are:
-<programlisting>
-[usr at localhost <JBoss_Home>]$<literal>ls server/default/deployers </literal>
-alias-deployers-jboss-beans.xml jboss-aop-jboss5.deployer
-bsh.deployer jboss-jca.deployer
-clustering-deployer-jboss-beans.xml jbossweb.deployer
-dependency-deployers-jboss-beans.xml jbossws.deployer
-directory-deployer-jboss-beans.xml j sr77-deployers-jboss-beans.xml
-ear-deployer-jboss-beans.xml metadata-deployer-jboss-beans.xml
-ejb-deployer-jboss-beans.xml seam.deployer
-ejb3.deployer security-deployer-jboss-beans.xml
-hibernate-deployer-jboss-beans.xml
-[usr at localhost <JBoss_Home>]$<literal>ls server/default/deploy </literal>
-ROOT.war jsr88-service.xml
-cache-invalidation-service.xml legacy-invokers-service.xml
-ejb2-container-jboss-beans.xml mail-ra.rar
-ejb2-timer-service.xml mail-service.xml
-ejb3-connectors-jboss-beans.xml management
-ejb3-container-jboss-beans.xml messaging
-ejb3-interceptors-aop.xml monitoring-service.xml
-ejb3-timer-service.xml profileservice-jboss-beans.xml
-hdscanner-jboss-beans.xml properties-service.xml
-hsqldb-ds.xml quartz-ra.rar
-http-invoker.sar remoting-jboss-beans.xml
-jboss-local-jdbc.rar schedule-manager-service.xml
-jboss-xa-jdbc.rar scheduler-service.xml
-jbossweb.sar security
-jbossws.sar sqlexception-service.xml
-jca-jboss-beans.xml transaction-jboss-beans.xml
-jms-ra.rar transaction-service.xml
-jmx-console.war uuid-key-generator.sar
-jmx-invoker-service.xml vfs-jboss-beans.xml
-jmx-remoting.sar
-</programlisting>
- while the web profile deployers and deploy directory contents are:
-<programlisting>
-[usr at localhost <JBoss_Home>]$<literal>ls server/web/deployers </literal>
-alias-deployers-jboss-beans.xml jbossweb.deployer
-ejb3.deployer metadata-deployer-jboss-beans.xml
-jboss-aop-jboss5.deployer security-deployer-jboss-beans.xml
-jboss-jca.deployer
-[usr at localhost <JBoss_Home>]$<literal>ls server/web/deployers </literal>
-ROOT.war jbossweb.sar
-ejb3-container-jboss-beans.xml jca-jboss-beans.xml
-hdscanner-jboss-beans.xml jmx-console.war
-hsqldb-ds.xml jmx-invoker-service.xml
-http-invoker.sar security
-jboss-local-jdbc.rar transaction-jboss-beans.xml
-jboss-xa-jdbc.rar
-</programlisting>
- </para>
- <note>
- <para>
- The <emphasis role="bold">default</emphasis> configuration is the one used if you don’t specify another one when starting up the server.
- </para>
- <para>
- To start the server using an alternate configuration refer to <xref linkend="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration"/>.
- </para>
- </note>
- <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-Server_Configuration_Directory_Structure">
- <title>Server Configuration Directory Structure</title>
- <para>
- The directory server configuration you’re using, is effectively the server root while JBoss is running. It contains all the code and configuration information for the services provided by the particular server configuration. It’s where the log output goes, and it’s where you deploy your applications. <xref linkend="Server_Configuration_Directory_Structure-Server_Configuration_Directory_Structure"/> shows the directories inside the server configuration directory (<filename class="directory"><JBoss_Home>/server/<instance-name></filename>) and their functions.
- </para>
- <para>
- <table id="Server_Configuration_Directory_Structure-Server_Configuration_Directory_Structure">
- <title>Server Configuration Directory Structure</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="1*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- Directory
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <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.
- </entry>
- </row>
- <row>
- <entry>
- <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.
- </entry>
- </row>
- <row>
- <entry>
- <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.
- </entry>
- </row>
- <row>
- <entry>
- <filename class="directory">lib</filename>
- </entry>
- <entry>
- This directory contains JAR files (Java libraries that should not be hot deployed) needed by this server configuration. You can add required library files here for JDBC drivers etc. All JARs in this directory are loaded into the shared classpath at startup. Note that this directory only contains those jars unique to the server configuration. Jars common across the server configurations are now located in <filename class="directory"><JBoss_Home>/common/lib</filename>.
- </entry>
- </row>
- <row>
- <entry>
- <filename class="directory">log</filename>
- </entry>
- <entry>
- This is where the log files are written. JBoss uses the Jakarta <literal>log4j</literal> package for logging and you can also use it directly in your own applications from within the server. This may be overridden through the <filename class="directory">conf/</filename><filename>jboss-log4j.xml</filename> configuration file.
- </entry>
- </row>
- <row>
- <entry>
- <filename class="directory">tmp</filename>
- </entry>
- <entry>
- The <filename class="directory">tmp</filename> directory is used for temporary storage by JBoss services. The deployer, for example, expands application archives in this directory.
- </entry>
- </row>
- <row>
- <entry>
- <filename class="directory">work</filename>
- </entry>
- <entry>
- This directory is used by Tomcat for compilation of JSPs.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
- <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-The_default_Server_Configuration_File_Set">
- <title>The "default" Server Configuration File Set</title>
- <para>
- The "<literal>default</literal>" server configuration file set is located in the <literal><JBoss_Home>/server/default</literal> directory. The following example illustrates a truncated directory structure of the <literal>jboss-as-<release></literal> server configuration files:
-<screen>[user at localhost <JBoss_Home>]$ tree
-|-- bin
-|-- client
-|-- common
-| |-- lib
-| | |-- antlr.jar
-| | |-- ... many more jars
-|-- docs
-| |-- dtd
-| |-- examples
-| | |-- binding-manager
-| | | `-- sample-bindings.xml
-| | |-- jca
-| | |-- jms
-| | |-- jmx
-| | |-- netboot
-| | | `-- netboot.war
-| | `-- varia
-| | |-- deployment-service
-| | |-- derby-plugin.jar
-| | |-- entity-resolver-manager
-| | | `-- xmlresolver-service.xml
-| | `-- jboss-bindings.xml
-| `-- schema
-|-- lib
-| |-- commons-codec.jar
-| |-- commons-httpclient.jar
-| |-- commons-logging.jar
-| |-- concurrent.jar
-| |-- endorsed
-| | |-- serializer.jar
-| | |-- xalan.jar
-| | `-- xercesImpl.jar
-| |-- getopt.jar
-| |-- jboss-common.jar
-| |-- jboss-jmx.jar
-| |-- jboss-system.jar
-| |-- jboss-xml-binding.jar
-| `-- log4j-boot.jar
-`-- server
-|-- all
-| |-- conf
-| | |-- bootstrap/
-| | | |-- aop.xml
-| | | |-- bindings.xml
-| | | |-- aop.xml
-| | | |-- classloader.xml
-| | | |-- deployers.xml
-| | | |-- jmx.xml
-| | | |-- profile-repository.xml
-| | | |-- profile.xml
-| | | |-- vfs.xml
-| | |-- bootstrap.xml
-| | |-- bootstrap-norepo.xml
-| | |-- jacorb.properties
-| | |-- java.policy
-| | |-- jax-ws-catalog.xml
-| | |-- jboss-log4j.xml
-| | |-- jboss-service.xml
-| | |-- jbossjta-properties.xml
-| | |-- jndi.properties
-| | |-- login-config.xml
-| | |-- props
-| | | |-- jbossws-roles.properties
-| | | |-- jbossws-users.properties
-| | | |-- jmx-console-roles.properties
-| | | `-- jmx-console-users.properties
-| | |-- standardjboss.xml
-| | |-- standardjbosscmp-jdbc.xml
-| | `-- xmdesc
-| |-- deploy
-| |-- deploy-hasingleton
-| | `-- jms
-| |-- deployers
-| `-- lib
-|-- default
-| |-- conf
-| | |-- bootstrap/
-| | | |-- aop.xml
-| | | |-- bindings.xml
-| | | |-- aop.xml
-| | | |-- classloader.xml
-| | | |-- deployers.xml
-| | | |-- jmx.xml
-| | | |-- profile-repository.xml
-| | | |-- profile.xml
-| | | |-- vfs.xml
-| | |-- bootstrap.xml
-| | |-- bootstrap-norepo.xml
-| | |-- jacorb.properties
-| | |-- java.policy
-| | |-- jax-ws-catalog.xml
-| | |-- jboss-log4j.xml
-| | |-- jboss-service.xml
-| | |-- jbossjta-properties.xml
-| | |-- jndi.properties
-| | |-- login-config.xml
-| | |-- props
-| | | |-- jbossws-roles.properties
-| | | |-- jbossws-users.properties
-| | | |-- jmx-console-roles.properties
-| | | `-- jmx-console-users.properties
-| | |-- standardjboss.xml
-| | |-- standardjbosscmp-jdbc.xml
-| | `-- xmdesc
-| | |-- AttributePersistenceService-xmbean.xml
-| | |-- ClientUserTransaction-xmbean.xml
-| | |-- JNDIView-xmbean.xml
-| | |-- Log4jService-xmbean.xml
-| | |-- NamingBean-xmbean.xml
-| | |-- NamingService-xmbean.xml
-| | |-- TransactionManagerService-xmbean.xml
-| | |-- org.jboss.deployment.JARDeployer-xmbean.xml
-| | |-- org.jboss.deployment.MainDeployer-xmbean.xml
-| | `-- org.jboss.deployment.SARDeployer-xmbean.xml
-| |-- data
-| | |-- hypersonic
-| | |-- jboss.identity
-| | |-- tx-object-store
-| | `-- xmbean-attrs
-| |-- deploy
-| |-- lib
-| |-- log
-| | |-- boot.log
-| | |-- server.log
-| | `-- server.log.2008-08-09
-| |-- tmp
-| `-- work
-| `-- jboss.web
-| `-- localhost
-`-- minimal
-|-- conf
-| |-- bootstrap/
-| |-- bootstrap/aop.xml
-| |-- bootstrap/classloader.xml
-| |-- bootstrap/deployers.xml
-| |-- bootstrap/jmx.xml
-| |-- bootstrap/profile.xml
-| |-- bootstrap.xml
-| |-- jboss-log4j.xml
-| |-- jboss-service.xml
-| |-- jndi.properties
-| `-- xmdesc
-| |-- NamingBean-xmbean.xml
-| `-- NamingService-xmbean.xml
-|-- deploy/
-|-- deploy/hdscanner-jboss-beans.xml
-|-- deployers/
-`-- lib
-|-- jboss-minimal.jar
-|-- jnpserver.jar
-`-- log4j.jar</screen>
-
-</para>
- <section id="The_default_Server_Configuration_File_Set-Contents_of_conf_directory">
- <title>Contents of "conf" directory</title>
- <para>
- The files in the <literal>conf</literal> directory are explained in the following table.
- </para>
- <para>
- <table id="Contents_of_conf_directory-Contents_of_conf_directory">
- <title>Contents of "conf" directory</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="4*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- File
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>bootstrap.xml</literal>
- </entry>
- <entry>
- This is the <literal>bootstrap.xml</literal> file that defines which additional microcontainer deployments will be loaded as part of the bootstrap phase.
- </entry>
- </row>
- <row>
- <entry>
- <literal>bootstrap/*</literal>
- </entry>
- <entry>
- This directory contains the microcontainer bootstrap descriptors that are referenced from the <literal>bootstrap.xml</literal> file.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jboss-service.xml</literal>
- </entry>
- <entry>
- <literal>jboss-service.xml</literal> legacy core mbeans that have yet to be ported to either bootstrap deployments, or deploy services. This file will go away in the near future.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jbossjta-properties.xml</literal>
- </entry>
- <entry>
- <literal>jbossjta-properties.xml</literal> specifies the JBossTS transaction manager default properties.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jndi.properties</literal>
- </entry>
- <entry>
- The <literal>jndi.properties</literal> file specifies the JNDI <literal>InitialContext</literal> properties that are used within the JBoss server when an <literal>InitialContext</literal> is created using the no-arg constructor.
- </entry>
- </row>
- <row>
- <entry>
- <literal>java.policy</literal>
- </entry>
- <entry>
- A placeholder java security policy file that simply grants all permissions.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jboss-log4j.xml</literal>
- </entry>
- <entry>
- This file configures the Apache log4j framework category priorities and appenders used by the JBoss server code.
- </entry>
- </row>
- <row>
- <entry>
- <literal>login-config.xml</literal>
- </entry>
- <entry>
- This file contains sample server side authentication configurations that are applicable when using JAAS based security.
- </entry>
- </row>
- <row>
- <entry>
- <literal>props/*</literal>
- </entry>
- <entry>
- The <literal>props</literal> directory contains the users and roles property files for the <literal>jmx-console</literal>.
- </entry>
- </row>
- <row>
- <entry>
- <literal>standardjboss.xml</literal>
- </entry>
- <entry>
- This file provides the default container configurations.
- </entry>
- </row>
- <row>
- <entry>
- <literal>standardjbosscmp-jdbc.xml</literal>
- </entry>
- <entry>
- This file provides a default configuration file for the JBoss CMP engine.
- </entry>
- </row>
- <row>
- <entry>
- <literal>xmdesc/*-mbean.xml</literal>
- </entry>
- <entry>
- The <literal>xmdesc</literal> directory contains XMBean descriptors for several services configured in the <literal>jboss-service.xml</literal> file.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
-
- <section id="The_default_Server_Configuration_File_Set-Contents_of_deployers_directory">
- <title>Contents of "deployers" directory</title>
- <para>
- The files in the <literal>deployers</literal> directory are explained in the following table.
- </para>
- <para>
- <table id="Contents_of_deploy_directory-Contents_of_deployers_directory">
- <title>Contents of "deploy" directory</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="4*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- File
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>alias-deployers-jboss-beans.xml</literal>
- </entry>
- <entry>
- Deployers that know how to handle The know how to handle <alias> in <deployment> as true controller context.
- Meaning they will only get active/installed when their original is installed.
- </entry>
- </row>
- <row>
- <entry>
- <literal>bsh.deployer</literal>
- </entry>
- <entry>
- This file configures the bean shell deployer, which deploys bean shell scripts as JBoss mbean services.
- </entry>
- </row>
- <row>
- <entry>
- <literal>clustering-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- Clustering-related deployers which add dependencies on needed clustering services to clustered EJB3, EJB2 beans and to distributable web applications.
- </entry>
- </row>
- <row>
- <entry>
- <literal>dependency-deployers-jboss-beans.xml</literal>
- </entry>
- <entry>
- Deployers for aliases.txt, jboss-dependency.xml jboss-depedency.xml adds generic dependency on whatever. aliases.txt adds human-readable name for deployments, e.g. vfszip://home/blah/.../jboss-5.0.0.GA/server/default/deploy/some-long-name.ear aliased to ales-app.ear.
- </entry>
- </row>
- <row>
- <entry>
- <literal>directory-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- Adds legacy behavior for directories, handling its children as possible deployments.
- e.g. .sar's lib directory to treat its .jar files as deployments
- </entry>
- </row>
- <row>
- <entry>
- <literal>ear-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- JavaEE 5 enterprise application related deployers
- </entry>
- </row>
- <row>
- <entry>
- <literal>ejb-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- Legacy JavaEE 1.4 ejb jar related deployers
- </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3.deployer</literal>
- </entry>
- <entry>
- This is a deployer that supports JavaEE 5 ejb3, JPA, and application client deployments, .
- </entry>
- </row>
- <row>
- <entry>
- <literal>hibernate-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- Deployers for Hibernate -hibernate.xml descriptors, which are similar to Hibernate's .cfg.xml files.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jboss-aop-jboss5.deployer</literal>
- </entry>
- <entry>
- JBossAspectLibrary and base aspects. Why is this in deployers, dependencies?
- </entry>
- </row>
- <row>
- <entry>
- <literal>jboss-jca.deployer</literal>
- </entry>
- <entry>
- <literal>jboss-jca.deployer</literal> description
- </entry>
- </row>
- <row>
- <entry>
- <literal>jbossweb.deployer</literal>
- </entry>
- <entry>
- The JavaEE 5 servlet, JSF, JSP deployers.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jbossws.deployer</literal>
- </entry>
- <entry>
- The JavaEE 5 webservices endpoint deployers.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jsr77-deployers-jboss-beans.xml</literal>
- </entry>
- <entry>
- Deployers for creating the JSR77 MBeans from the JavaEE components.
- </entry>
- </row>
- <row>
- <entry>
- <literal>metadata-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- Deployers for processing the JavaEE metadata from xml, annotations.
- </entry>
- </row>
- <row>
- <entry>
- <literal>seam.deployer</literal>
- </entry>
- <entry>
- Deployer providing integration support for JBoss Seam applications.
- </entry>
- </row>
- <row>
- <entry>
- <literal>security-deployer-jboss-beans.xml</literal>
- </entry>
- <entry>
- Deployers for configuration the security layers of the JavaEE components.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
-
- <section id="The_default_Server_Configuration_File_Set-Contents_of_deploy_directory">
- <title>Contents of "deploy" directory</title>
- <para>
- The files in the <literal>deploy</literal> directory are explained in the following table.
- </para>
- <para>
- <table id="Contents_of_deploy_directory-Contents_of_deploy_directory">
- <title>Contents of "deploy" directory</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="4*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- File
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>ROOT.war</literal>
- </entry>
- <entry>
- <literal>ROOT.war</literal> establishes the '/' root
- web application. </entry>
- </row>
- <row>
- <entry>
- <literal>cache-invalidation-service.xml</literal>
- </entry>
- <entry> This is a service that allows for custom
- invalidation of the EJB caches via JMS
- notifications. It is disabled by default. </entry>
- </row>
- <row>
- <entry>
- <literal>ejb2-container-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>ejb2-container-jboss-beans.xml</literal>
- UserTransaction integration bean for the EJB2
- containers. </entry>
- </row>
- <row>
- <entry>
- <literal>ejb2-timer-service.xml</literal>
- </entry>
- <entry>
- <literal>ejb2-timer-service.xml</literal> contains
- the ejb timer service beans. </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3-connectors-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>ejb3-connectors-jboss-beans.xml</literal>
- EJB3 remoting transport beans. </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3-container-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>ejb3-container-jboss-beans.xml</literal>
- UserTransaction integration bean for the EJB3
- containers. </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3-interceptors-aop.xml</literal>
- </entry>
- <entry>
- <literal>ejb3-interceptors-aop.xml</literal> defines
- the EJB3 container aspects. </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3-timer-service.xml</literal>
- </entry>
- <entry>
- <literal>ejb3-timer-service.xml</literal> an
- alternate quartz based timer service </entry>
- </row>
- <row>
- <entry>
- <literal>hdscanner-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>hdscanner-jboss-beans.xml</literal> the
- deploy directory hot deployment scanning bean
- </entry>
- </row>
- <row>
- <entry>hsqldb-ds.xml</entry>
- <entry>configures the Hypersonic embedded database
- service configuration file. It sets up the embedded
- database and related connection factories. </entry>
- </row>
- <row>
- <entry>http-invoker.sar</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>jboss-local-jdbc.rar</entry>
- <entry>is a JCA resource adaptor that implements the JCA
- <literal>ManagedConnectionFactory</literal>
- interface for JDBC drivers that support the
- <literal>DataSource</literal> interface but not
- JCA. </entry>
- </row>
- <row>
- <entry>jboss-xa-jdbc.rar</entry>
- <entry>JCA resource adaptors for XA DataSources</entry>
- </row>
- <row>
- <entry>
- <literal>jbossweb.sar</literal>
- </entry>
- <entry>an mbean service supporting TomcatDeployer with
- web application deployment service
- management.</entry>
- </row>
- <row>
- <entry><literal>jbossws.sar</literal></entry>
- <entry>provides JEE web services support. </entry>
- </row>
- <row>
- <entry>
- <literal>jca-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>jca-jboss-beans.xml</literal> is the
- application server implementation of the JCA
- specification. It provides the connection management
- facilities for integrating resource adaptors into
- the JBoss server. </entry>
- </row>
- <row>
- <entry>
- <literal>jms-ra.rar</literal>
- </entry>
- <entry>
- <literal>jms-ra.rar</literal> JBoss JMS Resource
- Adapter </entry>
- </row>
- <row>
- <entry>
- <literal>messaging/connection-factories-service.xml</literal>
- </entry>
- <entry>configures the DLQ, ExpiryQueue JMS connection
- factory</entry>
- </row>
- <row>
- <entry>
- <literal>messaging/destinations-service.xml</literal>
- </entry>
- <entry>The message persistence store service</entry>
- </row>
- <row>
- <entry>
- <literal>messaging/destinations-service.xml</literal>
- </entry>
- <entry>configures the DLQ, ExpiryQueue JMS destinations.
- </entry>
- </row>
- <row>
- <entry>
- <literal>messaging/jms-ds.xml</literal>
- </entry>
- <entry>
- <literal>jms-ds.xml</literal> configures the
- JMSProviderLoader and JmsXA inflow resource adaptor
- connection factory binding. </entry>
- </row>
- <row>
- <entry>
- <literal>messaging/legacy-service.xml</literal>
- </entry>
- <entry>
- <literal>legacy-service.xml</literal> configures the
- JMSProviderLoader and JmsXA inflow resource adaptor
- connection factory binding. </entry>
- </row>
- <row>
- <entry>
- <literal>messaging/messaging-jboss-beans.xml</literal>
- </entry>
- <entry> The <literal>messaging-jboss-beans.xml</literal>
- file configures JMS security and management beans.
- </entry>
- </row>
- <row>
- <entry>
- <literal>messaging/messaging-service.xml</literal>
- </entry>
- <entry> The <literal>messaging-service.xml</literal>
- file configures the core JBoss Messaging service.
- </entry>
- </row>
- <row>
- <entry>
- <literal>messaging/remoting-bisocket-service.xml</literal>
- </entry>
- <entry> The
- <literal>remoting-bisocket-service.xml</literal>
- configures the JMS remoting service layer. </entry>
- </row>
- <row>
- <entry>
- <literal>jmx-console.war</literal>
- </entry>
- <entry> The <literal>jmx-console.war</literal> directory
- provides the JMX Console. The JMX Console provides a
- simple web interface for managing the MBean server.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jmx-invoker-service.xml</literal>
- </entry>
- <entry>
- <literal>jmx-invoker-service.xml</literal> is an
- MBean service archive that exposes a subset of the
- JMX <literal>MBeanServer</literal> interface methods
- as an RMI interface to enable remote access to the
- JMX core functionality. </entry>
- </row>
- <row>
- <entry>
- <literal>jmx-remoting.sar</literal>
- </entry>
- <entry>
- <literal>jmx-remoting.sar</literal> is a
- javax.management.remote implementation providing
- access to the JMX server. </entry>
- </row>
- <row>
- <entry>
- <literal>legacy-invokers-service.xml</literal>
- </entry>
- <entry>
- <literal>legacy-invokers-service.xml</literal> the
- legacy detached jmx invoker remoting services.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jsr-88-service.xml</literal>
- </entry>
- <entry>
- <literal>jsr-88-service.xml</literal> provides the
- JSR 88 remote deployment service. </entry>
- </row>
- <row>
- <entry>
- <literal>mail-ra.rar</literal>
- </entry>
- <entry>
- <literal>mail-ra.rar</literal> is a resource adaptor
- that provides a JavaMail connector. </entry>
- </row>
- <row>
- <entry>
- <literal>mail-service.xml</literal>
- </entry>
- <entry> The <literal>mail-service.xml</literal> file is
- an MBean service descriptor that provides JavaMail
- sessions for use inside the JBoss server. </entry>
- </row>
- <row>
- <entry>
- <literal>monitoring-service.xml</literal>
- </entry>
- <entry> The <literal>monitoring-service.xml</literal>
- file configures alert monitors like the console
- listener and email listener used by JMX
- notifications. </entry>
- </row>
- <row>
- <entry>
- <literal>profileservice-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>profileservice-jboss-beans.xml</literal>
- description </entry>
- </row>
- <row>
- <entry>
- <literal>properties-service.xml</literal>
- </entry>
- <entry></entry>
- </row>
- <row>
- <entry>
- <literal>quartz-ra.rar</literal>
- </entry>
- <entry>
- <literal>quartz-ra.rar</literal> is a resource
- adaptor for inflow of Quartz events </entry>
- </row>
- <row>
- <entry>
- <literal>remoting-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>remoting-jboss-beans.xml</literal>
- contains the unified invokers based on JBoss
- Remoting. </entry>
- </row>
- <row>
- <entry> The <literal>properties-service.xml</literal>
- file is an MBean service descriptor that allows for
- customization of the JavaBeans
- <literal>PropertyEditor</literal>s as well as
- the definition of system properties. </entry>
- </row>
- <row>
- <entry>
- <literal>scheduler-service.xml</literal>
- </entry>
- <entry> The <literal>scheduler-service.xml</literal> and
- <literal>schedule-manager-service.xml</literal>
- files are MBean service descriptors that provide a
- scheduling type of service. </entry>
- </row>
- <row>
- <entry>
- <literal>security/security-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>security-jboss-beans.xml</literal> security
- domain related beans. </entry>
- </row>
- <row>
- <entry>
- <literal>security/security-policies-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>security-policies-jboss-beans.xml</literal>
- security authorization related beans for ejb and web
- authorization. </entry>
- </row>
- <row>
- <entry>
- <literal>sqlexception-service.xml</literal>
- </entry>
- <entry> The <literal>sqlexception-service.xml</literal>
- file is an MBean service descriptor for the handling
- of vendor specific <literal>SQLException</literal>s.
- </entry>
- </row>
- <row>
- <entry>
- <literal>transaction-jboss-beans.xml</literal>
- </entry>
- <entry>
- <literal>transaction-jboss-beans.xml</literal> JTA
- transaction manager related beans. </entry>
- </row>
- <row>
- <entry>
- <literal>transaction-service.xml</literal>
- </entry>
- <entry>
- <literal>transaction-service.xml</literal>
- ClientUserTransaction proxy service configuration.
- </entry>
- </row>
- <row>
- <entry>
- <literal>uuid-key-generator.sar</literal>
- </entry>
- <entry> The <literal>uuid-key-generator.sar</literal>
- service provides a UUID-based key generation
- facility. </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
-
- </section>
- <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-The_all_Server_Configuration_File_Set">
- <title>The "all" Server Configuration File Set</title>
- <para>
- The "all" server configuration file set is located in the <filename class="directory"><JBoss_Home>/server/all</filename> directory. In addition to the services in the "default" set, the all configuration contains several other services in the <literal>conf/</literal> directory as shown below.
- </para>
- <para>
- <table id="The_all_Server_Configuration_File_Set-Additional_Services_in_conf_directory_for_all_configuration">
- <title>Additional Services in "conf" directory for "all" configuration</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="4*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- File
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>cluster-service.xml</literal>
- </entry>
- <entry>
- This service configures clustering communication for most clustered services in JBoss.
- </entry>
- </row>
- <row>
- <entry>
- <literal>deploy-hasingleton-service.xml</literal>
- </entry>
- <entry>
- This provides the HA singleton service, allowing JBoss to manage services that must be active on only one node of a cluster.
- </entry>
- </row>
-
- <row>
- <entry>
- <literal>httpha-invoker.sar</literal>
- </entry>
- <entry>
- This service provides HTTP tunneling support for clustered environments.
- </entry>
- </row>
- <row>
- <entry>
- <literal>iiop-service.xml</literal>
- </entry>
- <entry>
- This provides IIOP invocation support.
- </entry>
- </row>
- <row>
- <entry>
- <literal>juddi-service.sar</literal>
- </entry>
- <entry>
- This service provides UDDI lookup services.
- </entry>
- </row>
- <row>
- <entry>
- <literal>snmp-adaptor.sar</literal>
- </entry>
- <entry>
- This is a JMX to SNMP adaptor. It allows for the mapping of JMX notifications onto SNMP traps.
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
- <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-EJB3_Services_">
- <title>EJB3 Services </title>
- <para>
- The following table explains the files providing ejb3 services.
- </para>
- <para>
- <table id="EJB3_Services_-EJB3_Services">
- <title>EJB3 Services</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="4*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- File
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>ejb3-interceptors-aop.xml</literal>
- </entry>
- <entry>
- This service provides the AOP interceptor stack configurations for EJB3 bean types.
- </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3.deployer</literal>
- </entry>
- <entry>
- This service deploys EJB3 applications into JBoss.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jboss-aop-jdk50.deployer</literal>
- </entry>
- <entry>
- This is a Java 5 version of the AOP deployer. The AOP deployer configures the <literal>AspectManagerService</literal> and deploys JBoss AOP applications.
- </entry>
- </row>
- <row>
- <entry>
- <literal>jbossws.sar</literal>
- </entry>
- <entry>
- This provides Java EE 5 web services support.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- <para>
- Finally, in the EJB3 "all" configuration there are two additional services.
- </para>
- <para>
- <table id="EJB3_Services_-Additional_Services_in_EJB3_all_Configuration">
- <title>Additional Services in EJB3 "all" Configuration</title>
- <tgroup cols="2">
- <colspec colname="c1" colnum="1" colwidth="4*"/>
- <colspec colname="c2" colnum="2" colwidth="4*"/>
- <thead>
- <row>
- <entry>
- File
- </entry>
- <entry>
- Description
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>ejb3-clustered-sfsbcache-service.xml</literal>
- </entry>
- <entry>
- This provides replication and failover for EJB3 stateful session beans.
- </entry>
- </row>
- <row>
- <entry>
- <literal>ejb3-entity-cache-service.xml</literal>
- </entry>
- <entry>
- This provides a clustered cache for EJB3 entity beans.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </para>
- </section>
- <section id="The_JBoss_Server___A_Quick_Tour-Server_Configurations-Adding_Your_Own_Configuration">
- <title>Adding Your Own Configuration</title>
- <para>
- You can add your own configurations too. The best way to do this is to copy an existing one that is closest to your needs and modify the contents. For example, if you weren’t interested in using messaging, you could copy the <literal>production</literal> directory, renaming it as <literal>myconfig</literal>, remove the <literal>jms</literal> subdirectory and then start JBoss with the new configuration.
- </para>
-<programlisting>
-./run.sh -c <emphasis role="bold">myconfig</emphasis>
-</programlisting>
- </section>
-</section>
- <section id="Starting_and_Stopping_the_Server">
- <title>Starting and Stopping the Server</title>
- <section id="Starting_and_Stopping_the_Server-Start_the_Server">
- <title>Start the Server</title>
- <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>
-</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>.
-</para>
-
-<para>
- On starting your server, your screen output should look like the following (accounting for installation directory differences) and contain no error or exception messages:
-</para>
-
-<programlisting>[user at mypc bin]$ ./run.sh
-=========================================================================
-
- JBoss Bootstrap Environment
-
- JBOSS_HOME: /home/user/jboss-as-version/jboss-as
-
- JAVA: java
-
- JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1503m -Xmx1503m -Dsun.rmi.dgc.client.
-gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 -Djava.net.preferIPv4Stack=true
-
- CLASSPATH: /home/user/jboss-as-version/jboss-as/bin/run.jar
-
-=========================================================================
-
-</programlisting>
-
-<para>More options for the JBoss AS <literal>run</literal> script are discussed in <xref linkend="Starting_and_Stopping_the_Server-Start_the_Server_With_Alternate_Configuration"/> below.</para>
- <note>
- <para>
- Note that there is no "Server Started" 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 may be observed in the <filename>server.log</filename> file located in the <filename class="directory">server/production/log</filename> subdirectory.
- </para>
- </note>
- </section>
-
- <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:
- </para>
-<programlisting>[bin]$ ./run.sh -c minimal
-...
-...
-...
-15:05:40,301 INFO [Server] JBoss (MX MicroKernel) [5.0.0 (build: SVNTag=JBoss_5_0_0 date=200801092200)] Started in 5s:75ms
-</programlisting>
- </section>
-
- <section id="Starting_and_Stopping_the_Server-Using_run.sh">
- <title>Using run.sh</title>
- <para>
- The <literal>run</literal> script supports the following options:
- </para>
-<programlisting>
-usage: run.sh [options]
--h, --help Show help message
--V, --version Show version information
--- Stop processing options
--D<name>[=<value>] Set a system property
--d, --bootdir=<dir> Set the boot patch directory; Must be absolute or url
--p, --patchdir=<dir> Set the patch directory; Must be absolute or url
--n, --netboot=<url> Boot from net with the given url as base
--c, --configuration=<name> Set the server configuration name
--B, --bootlib=<filename> Add an extra library to the front bootclasspath
--L, --library=<filename> Add an extra library to the loaders classpath
--C, --classpath=<url> Add an extra url to the loaders classpath
--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)
--u, --udp=<ip> UDP multicast address
--l, --log=<log4j|jdk> Specify the logger plugin type
-</programlisting>
-
- </section>
-
- <section id="Starting_and_Stopping_the_Server-Stopping_the_Server">
- <title>Stopping the Server</title>
- <para>
- To shutdown the server, you simply issue a Ctrl-C sequence in the console in which JBoss was started. Alternatively, you can use the <literal>shutdown.sh</literal> command.
- </para>
-<programlisting>[bin]$ ./shutdown.sh -S</programlisting>
- <para>
- The <literal>shutdown</literal> script supports the following options:
- </para>
-<programlisting>A JMX client to shutdown (exit or halt) a remote JBoss server.
-
-usage: shutdown [options] <operation>
-
-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
--u, --user=<name> Specify the username for authentication
--p, --password=<name> Specify the password for authentication
-
-operations:
--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>
- <para>
- Using the shutdown command requires a server configuration that contains the <literal>jmx-invoker-service.xml</literal> service. Hence you cannot use the shutdown command with the <literal>minimal</literal> configuration.
- </para>
- </section>
-
- <section id="Starting_and_Stopping_the_Server-Running_as_a_Service_under_Microsoft_Windows">
- <title> Running as a Service under Microsoft Windows </title>
- <para>
- You can configure the server to run as a service under Microsoft Windows, and configure it to start automatically if desired.
- </para>
- <para>
- Download the <literal>JavaService</literal> package from <ulink url="http://forge.objectweb.org/projects/javaservice/">http://forge.objectweb.org/projects/javaservice/</ulink>.
- </para>
- <para>
- Unzip the package and use the <literal>JBossInstall.bat</literal> file to install the JBoss service. You must set the <literal>JAVA_HOME</literal> and <literal>JBOSS_HOME</literal> environment variables to point to the <literal>jdk</literal> and <literal>jboss-as</literal> directories before running <literal>JBossInstall.bat</literal>. Run <literal>JBossInstall.bat</literal> with the following syntax:
- </para>
-<screen>JBossInstall.bat <replaceable><depends></replaceable> [-auto | -manual]</screen>
- <para>
- Where <replaceable><depends></replaceable> is the name of any service that the JBoss AS server depends on, such as the <literal>mysql</literal> database service.
- </para>
- <para>
- Once the service is installed the server can be started by using the command <literal>net start JBoss</literal>, and stopped with the command <literal>net stop JBoss</literal>.
- </para>
- <para>
- Please refer to the documentation included in the <literal>JavaService</literal> package for further information.
- </para>
- </section>
-</section>
-<!-- end embedded sections -->
-
-
-</section>
-
- <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"/>. You should see something similar to <xref linkend="The_JMX_Console-View_of_the_JMX_Management_Console_Web_Application"/>.
- </para>
- <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>
- For example, find the <literal>service=JNDIView</literal> link and click on it. This particular MBean provides a service to allow you to view the structure of the JNDI namespaces within the server. Now find the operation called <literal>list</literal> near the bottom of the MBean view page and click the <literal>invoke</literal> button. The operation returns a view of the current names bound into the JNDI tree, which is very useful when you start deploying your own applications and want to know why you can’t resolve a particular EJB name.
- </para>
- <figure id="The_JMX_Console-View_of_the_JMX_Management_Console_Web_Application">
- <title>View of the JMX Management Console Web Application</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jmx-console.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>
- Look at some of the other MBeans and their listed operations; try changing some of the configuration attributes and see what happens. With a very few exceptions, none of the changes made through the console are persistent. The original configuration will be reloaded when you restart JBoss, so you can experiment freely without doing any permanent damage.
- </para>
- <note>
- <para>
- If you installed JBoss using the graphical installer, the JMX Console will prompt you for a username and password before you can access it. If you installed using other modes, you can still configure JMX Security manually. We will show you how to secure your console in <xref linkend="Basic_Configuration_Issues-Security_Service"/>.
- </para>
- </note>
- </section>
- <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.
- </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>
- </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>
- This is hot-deployment in action.
- </para>
- </section>
- <section id="The_JBoss_Server___A_Quick_Tour-Basic_Configuration_Issues">
- <title>Basic Configuration Issues</title>
- <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/production</filename>, for example).
- </para>
- <section id="Basic_Configuration_Issues-Core_Services">
- <title>Core Services</title>
- <para>
- The core services specified in the <filename>conf/jboss-service.xml</filename> file are started first when the server starts up. If you have a look at this file in an editor you will see MBeans for various services including logging, security, JNDI, JNDIView etc. Try commenting out the entry for the <literal>JNDIView</literal> service.
- </para>
- <para>
- Note that because the mbeans definition had nested comments, we had to comment out the mbean in two sections, leaving the original comment as it was.
- </para>
-<programlisting>
-<!-- Section 1 commented out
-<mbean code="org.jboss.naming.JNDIView"
- name="jboss:service=JNDIView"
- xmbean-dd="resource:xmdesc/JNDIView-xmbean.xml">
--->
- <!-- The HANamingService service name -->
-<!-- Section two commented out
- <attribute name="HANamingService">jboss:service=HAJNDI</attribute></mbean>
--->
-
-</programlisting>
- <para>
- If you then restart JBoss, you will see that the <literal>JNDIView</literal> service no longer appears in the JMX Management Console (JMX Console) listing. In practice, you should rarely, if ever, need to modify this file, though there is nothing to stop you adding extra MBean entries in here if you want to. The alternative is to use a separate file in the <filename class="directory">deploy</filename> directory, which allows your service to be hot deployable.
- </para>
- </section>
-
- <section id="Basic_Configuration_Issues-Logging_Service">
- <title>Logging Service</title>
- <para>
- In JBoss <literal>log4j</literal> is used for logging. If you are not familiar with the <literal>log4j</literal> package and would like to use it in your applications, you can read more about it at the Jakarta web site (<ulink url="http://jakarta.apache.org/log4j/"/>).
- </para>
- <para>
- 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 5 basic log levels used: <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.
- </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.
- </para>
-<programlisting><!-- Limit JBoss categories to INFO -->
-<category name="org.jboss">
- <priority value="<emphasis role="bold">INFO</emphasis>"/>
-</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.
- </para>
- <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>
-<programlisting><appender name="CMP" class="org.jboss.logging.appender.RollingFileAppender">
- <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
- <param name="File" value="${jboss.server.home.dir}/log/cmp.log"/>
- <param name="Append" value="false"/>
- <param name="MaxFileSize" value="500KB"/>
- <param name="MaxBackupIndex" value="1"/>
-
- <layout class="org.apache.log4j.PatternLayout">
- <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
- </layout>
-</appender>
-
-<category name="org.jboss.ejb.plugins.cmp">
- <priority value="DEBUG" />
- <appender-ref ref="CMP"/>
-</category>
-</programlisting>
- <para>
- This creates a new file appender and specifies that it should be used by the logger (or category) for the package <literal>org.jboss.ejb.plugins.cmp</literal>.
- </para>
- <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>
- </section>
-
- <section id="Basic_Configuration_Issues-Security_Service">
- <title>Security Service</title>
- <para>
- The security domain information is stored in the file <filename>conf/login-config.xml</filename> as a list of named security domains, each of which specifies a number of JAAS <footnote><para>
- The Java Authentication and Authorization Service. JBoss uses JAAS to provide pluggable authentication modules. You can use the ones that are provided or write your own if you have more specific requirements.
- </para>
- </footnote> login modules which are used for authentication purposes in that domain. When you want to use security in an application, you specify the name of the domain you want to use in the application’s JBoss-specific deployment descriptors, <filename>jboss.xml</filename> (used in defining jboss specific configurations for an application) and/or <filename>jboss-web.xml</filename> (used in defining jboss for a Web application. We'll quickly look at how to do this to secure the JMX Console application which ships with JBoss.
- </para>
- <para>
- Almost every aspect of the JBoss server can be controlled through the JMX Console, so it is important to make sure that, at the very least, the application is password protected. Otherwise, any remote user could completely control your server. To protect it, we will add a security domain to cover the application.
- <!--<footnote><para>
- If you installed JBoss using the Graphical Installer and set the JMX Security up, then you will not have to uncomment the sections, because they are already uncommented. Additionally, the admin password will be set up to whatever you had specified.
- </para>
- </footnote>-->
-
- This can be done in the <filename>jboss-web.xml</filename> file for the JMX Console, which can be found in <filename class="directory">deploy/jmx-console.war/WEB-INF/</filename> directory. Uncomment the <literal>security-domain</literal> in that file, as shown below.
- </para>
- <para>
-<programlisting><jboss-web>
- <security-domain>java:/jaas/jmx-console</security-domain>
-</jboss-web>
-</programlisting>
- </para>
- <para>
- This links the security domain to the web application, but it doesn't tell the web application what security policy to enforce, what URLs are we trying to protect, and who is allowed to access them. To configure this, go to the <filename>web.xml</filename> file in the same directory and uncomment the <literal>security-constraint</literal> that is already there. This security constraint will require a valid user name and password for a user in the <literal>JBossAdmin</literal> group.
- </para>
-<programlisting><!--
- A security constraint that restricts access to the HTML JMX console
- to users with the role JBossAdmin. Edit the roles to what you want and
- uncomment the WEB-INF/jboss-web.xml/security-domain element to enable
- secured access to the HTML JMX console.
--->
-<security-constraint>
- <web-resource-collection>
- <web-resource-name>HtmlAdaptor</web-resource-name>
- <description>
- An example security config that only allows users with the
- role JBossAdmin to access the HTML JMX console web application
- </description>
- <url-pattern>/*</url-pattern>
- <http-method>GET</http-method>
- <http-method>POST</http-method>
- </web-resource-collection>
- <auth-constraint>
- <role-name>JBossAdmin</role-name>
- </auth-constraint>
-</security-constraint>
-</programlisting>
- <para>
- That's great, but where do the user names and passwords come from? They come from the <literal>jmx-console</literal> security domain we linked the application to. We have provided the configuration for this in the <filename>conf/login-config.xml</filename>.
- </para>
- <para>
-<programlisting><application-policy name="jmx-console">
- <authentication>
- <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
- flag="required">
- <module-option name="usersProperties">
- props/jmx-console-users.properties
- </module-option>
- <module-option name="rolesProperties">
- props/jmx-console-roles.properties
- </module-option>
- </login-module>
- </authentication>
-</application-policy>
-</programlisting>
- </para>
- <para>
- This configuration uses a simple file based security policy. The configuration files are found in the <filename class="directory">conf/props</filename> directory of your server configuration. The usernames and passwords are stored in the <literal>conf/props/jmx-console-users.properties</literal> file and take the form "<literal>username=password</literal>". To assign a user to the <literal>JBossAdmin</literal> group add "<literal>username=JBossAdmin</literal>" to the <literal>jmx-console-roles.properties</literal> file (additional roles on that username can be added comma separated). The existing file creates an <literal>admin</literal> user with the password <literal>admin</literal>. For security, please either remove the user or change the password to a stronger one.
- </para>
- <para>
- JBoss will re-deploy the JMX Console whenever you update its <filename>web.xml</filename>. You can check the server console to verify that JBoss has seen your changes. If you have configured everything correctly and re-deployed the application, the next time you try to access the JMX Console, it will ask you for a name and password. <footnote><para>
- Since the username and password are session variables in the web browser you may need to restart your browser to use the login dialog window.
- </para>
- </footnote>
- </para>
- <para>
- The JMX Console isn't the only web based management interface to JBoss. There is also the Web Console. Although it's a Java applet, the corresponding web application can be secured in the same way as the JMX Console. The Web Console is in the file <filename>deploy/management/console-mgr.sar/web-console.war.</filename>. The only difference is that the Web Console is provided as a simple WAR file instead of using the exploded directory structure that the JMX Console did. The only real difference between the two is that editing the files inside the WAR file is a bit more cumbersome.
- </para>
- </section>
-
- <section id="Basic_Configuration_Issues-Additional_Services">
- <title>Additional Services</title>
- <para>
- The non-core, hot-deployable services are added to the <filename class="directory">deploy</filename> directory. They can be either XML descriptor files, <filename>*-service.xml</filename>, or JBoss Service Archive (SAR) files. SARs contain both the XML descriptor and additional resources the service requires (e.g. classes, library JAR files or other archives), all packaged up into a single archive.
- </para>
- <para>
- Detailed information on all these services can be found in the <emphasis>JBoss Application Server: Configuration Guide</emphasis>, which also provides comprehensive information on server internals and the implementation of services such as JTA and the J2EE Connector Architecture (JCA).
- </para>
- </section>
-
- </section>
-
- <!--<section id="The_JBoss_Server___A_Quick_Tour-The_Web_Container___Tomcat">
- <title>The Web Container - Tomcat</title>
- <para>
- JBoss Application Server comes with Tomcat as the default web container.
- </para>
- <para>
- </para>
- </section>-->
-</chapter>
- <chapter id="EJB3_Caveats">
- <title>
- EJB3 Caveats in JBoss Application Server 5.0.0
- </title>
-
- <para>
- There are a number of implementation features that you should be aware of when developing applications for JBoss Application Server 5.0.0.
- </para>
-
- <section>
- <title>
- Unimplemented features
- </title>
-
- <para>
- The Release Notes for JBoss Application Server contain information on EJB3 features that are not yet implemented, or partially implemented. The Release Notes include links to issues in JIRA for information on workarounds and further details.
- </para>
- </section>
-
-
- <section id="EJB3_Support">
- <title>
- Referencing EJB3 Session Beans from non-EJB3 Beans
- </title>
-
- <para>
- JBoss Application Server 5 fully supports the entire Java 5 Enterprise Edition specification. JBoss Application Server 4.2.2 implemented EJB3 functionality by way of an EJB MBean container running as a plugin in the JBoss Application Server. This had certain implications for application development.
- </para>
-
- <para>
- The EJB3 plugin injects references to an EntityManager and @EJB references from one EJB object to another. However this support is limited to the EJB3 MBean and the JAR files it manages. Any JAR files which are loaded from a WAR (such as Servlets, JSF backing beans, and so forth) do not undergo this processing. The Java 5 Enterprise Edition standard specifies that a Servlet can reference a Session Bean through an @EJB annotated reference, this was not implemented in JBoss Application Server 4.2.2.
- </para>
-<!--
- <para>
- In order to access an EJB3 Session Bean from a Servlet or JSF Backing Bean you will need to do one of two things:
- </para>
-
- <orderedlist>
- <listitem>
- <formalpara>
- <title>
- Without Seam - JNDI Lookup
- </title>
-
- <para>
- Without utilizing the Seam framework that is part of JBoss Application Server you will need to use an explicit JNDI lookup to access the EJB3 Session Bean. You can see an example of this being done in the <filename>TodoBean.java</filename> file in the <literal>jsfejb3</literal> example application, described in <xref linkend="Sample_JSF_EJB3_Application"/>.
- </para>
- </formalpara>
-
-<programlisting>private TodoDaoInt getDao () {
- try {
- InitialContext ctx = new InitialContext();
- return (TodoDaoInt) ctx.lookup("jsfejb3/TodoDao/local");
- } catch (Exception e) {
- e.printStackTrace();
- throw new RuntimeException("couldn't lookup Dao", e);
- }
- }</programlisting>
-
- <para>
- <literal>ctx.lookup("jsfejb3/TodoDao/local");</literal> is the method used to reference the EJB3 Session Bean. The form is: <replaceable>AppName</replaceable>/<replaceable>SessionBeanName</replaceable>/local.
- </para>
- </listitem>
-
- <listitem>
- <formalpara>
- <title>
- With Seam - Leave it to the Seam Framework
- </title>
-
- <para>
- When you are using the Seam Framework you don't need to worry about this. Because the Seam framework manages the interaction of Beans anyway, it already automates this type of interaction.
- </para>
- </formalpara>
-
- <para>
- Refer to <xref linkend="Using_Seam"/> for a more detailed explanation of achieving this using the Seam framework.
- </para>
- </listitem>
- </orderedlist> -->
- </section>
-</chapter>
- <chapter id="About_the_Example_Applications">
- <title>About the Example Applications</title>
- <para>
- In this guide, we make use of a simple web application to show the use of JSF-EJB3 components. We then illustrate how to use Seam to integrate the JSF and EJB3 components. The example applications (source code) come with this guide and you can find them located in the <filename class="directory">JBOSS_DIST/doc/examples</filename> directory. You can also download the sample applications from <ulink url="http://www.redhat.com/docs/manuals/jboss"/>. We use two examples in this book:
- <itemizedlist>
- <listitem>
- <para>A simple "TODO" application to create, view and edit tasks - implemented using JSF and EJB3;
- </para>
- </listitem>
- <listitem>
- <para>The same application using the SEAM framework.</para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- If you installed the documentation on your hard drive, then the first example can be found in the <filename class="directory">JBOSS_DIST/doc/examples/jsfejb3</filename> directory (if you download the examples the path is: <filename class="directory">gettingstarted/jsfejb3</filename>). We will see how to build this example using the <filename>build.xml</filename> file present here and also how to deploy the application. We will also cover in detail the workings of the .java, .xml and .properties files.
- </para>
- <para>
- The second example used in this guide can be found in the <filename class="directory">JBOSS_DIST/doc/examples/seamejb3</filename> directory. Using a simple "TODO" application we will illustrate how Seam ties together the database, the web interface and the EJB3 business logic in a web application. We will use the <filename>build.xml</filename> file present here to compile and build our Seam application.
- </para>
- <para>
- Within the <filename class="directory">JBOSS_DIST/doc/examples/<seamejb3|jsfejb3></filename> directory, you will find the following sub-directories: <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">src</emphasis>: contains the Java source code files.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">view</emphasis>: contains the web pages.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">resources</emphasis>: contains all the configuration files used.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <section id="About_the_Example_Applications-Install_Ant">
- <title>Install Ant</title>
- <para>
- To compile and package the examples, you must have Apache Ant 1.6+ installed in your machine. You can download it from <ulink url="http://ant.apache.org"/> and have it installed in few steps: <itemizedlist>
- <listitem>
- <para>
- Unzip the downloaded file to the directory of your choice.
- </para>
- </listitem>
- <listitem>
- <para>
- Create an environment variable called <literal>ANT_HOME</literal> pointing to the Ant installation directory. You can do this by adding the following line to your <filename>.bashrc</filename> file (substituting with the actual location of the ant directory on your system): <programlisting>
-export ANT_HOME=/home/user/apache-ant-1.7.0
-</programlisting>
- </para>
-
- <para>
- On Windows you do this by opening the Control Panel from the Start Menu, switching it to classic view if necessary, then opening System/Advanced/Environment Variables. Create a new variable, call it <literal>ANT_HOME</literal> and set it to be the ant directory.
- </para>
- </listitem>
- <listitem>
- <para>
- Add <literal>$ANT_HOME/bin</literal> to the system path to be able to run <literal>ant</literal> from the command line. You can do this by adding the following line to your <filename>.bashrc</filename> file: <programlisting>
-export PATH=$PATH:$ANT_HOME/bin
-</programlisting>
- </para>
- <para>
- On Windows you do this by opening the Control Panel from the Start Menu, switching it to classic view if necessary, then editing the <literal>PATH</literal> environment variable found in System/Advanced/Environment Variables/System Variables/Path. Add a semicolon and the path to the ant <filename class="directory">bin</filename> directory.
- </para>
- </listitem>
- <listitem>
- <para>
- Verify your Ant installation. To do this type <literal> ant -version</literal> at the command prompt. Your output should look something like this: <programlisting>
-Apache Ant version 1.7.0 compiled on December 13 2006
-</programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
-</chapter>
- <chapter id="Sample_JSF_EJB3_Application">
- <title>Sample JSF-EJB3 Application</title>
- <para>
- We use a simple "TODO" application to show how JSF and EJB3 work together in a web application. The "TODO" application works like this: You can create a new 'todo' task item using the "Create" web form. Each 'todo' item has a 'title' and a 'description'. When you submit the form, the application saves your task to a relational database. Using the application, you can view all 'todo' items, edit/delete an existing 'todo' item and update the task in the database.
- </para>
- <para>
- The sample application comprises the following components:
- <itemizedlist>
- <listitem>
- <para>
- Entity objects - These objects represent the data model; the properties in the object are mapped to column values in relational database tables.
- </para>
- </listitem>
- <listitem>
- <para>
- JSF web pages - The web interface used to capture input data and display result data. The data fields on these web pages are mapped to the data model via the JSF Expression Language (EL).
- </para>
- </listitem>
- <listitem>
- <para>
- EJB3 Session Bean - This is where the functionality is implemented. We make use of a Stateless Session Bean.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <section id="Sample_JSF_EJB3_Application-Data_Model">
- <title>Data Model</title>
- <para>
- Let's take a look at the contents of the Data Model represented by the <literal>Todo</literal> class in the <literal>Todo.java</literal> file. Each instance of the <literal>Todo</literal> class corresponds to a row in the relational database table. The 'Todo' class has three properties: id, title and description. Each of these correspond to a column in the database table.
- </para>
- <para>
- The 'Entity class' to 'Database Table' mapping information is specified using EJB3 Annotations in the 'Todo' class. This eliminates the need for XML configuration and makes it a lot clearer. The <literal>@Entity</literal> annotation defines the <literal>Todo</literal> class as an Entity Bean. The <literal>@Id</literal> and <literal>@GeneratedValue</literal> annotations on the <literal>id</literal> property indicate that the <literal>id</literal> column is the primary key and that the server automatically generates its value for each <literal>Todo</literal> object saved into the database.
- </para>
- <para>
-<programlisting>
- at Entity
-public class Todo implements Serializable {
-
- private long id;
- private String title;
- private String description;
-
- public Todo () {
- title ="";
- description ="";
- }
-
- @Id @GeneratedValue
- public long getId() { return id;}
- public void setId(long id) { this.id = id; }
-
- public String getTitle() { return title; }
- public void setTitle(String title) {this.title = title;}
-
- public String getDescription() { return description; }
- public void setDescription(String description) {
- this.description = description;
- }
-
-}
-</programlisting>
- </para>
- </section>
- <section id="Sample_JSF_EJB3_Application-JSF_Web_Pages">
- <title>JSF Web Pages</title>
- <para>
- In this section we will show you how the web interface is defined using JSF pages. We will also see how the data model is mapped to the web form using JSF EL. Using the #{...} notation to reference Java objects is called <emphasis role="bold">JSF EL</emphasis> (JSF Expression Language). Lets take a look at the pages used in our application:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">index.xhtml</emphasis>: This page displays two options: 1. Create New Todo 2. Show all Todos. When you click on the Submit button the corresponding action is invoked.
- </para>
- <para>
-<programlisting>
-<h:form>
-<ul>
- <li><h:commandLink type="submit" value="Create New Todo" action="create"/></li>
- <li><h:commandLink type="submit" value="Show All Todos" action="todos"/></li>
-</ul>
-</h:form>
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">create.xhtml</emphasis>: When you try to create a new task, this JSF page captures the input data. We use the <literal>todoBean</literal> to back the form input text fields. The #{todoBean.todo.title} symbol refers to the "title" property of the "todo" object in the "TodoBean" class. The #{todoBean.todo.description} symbol refers to the "description" property of the "todo" object in the "TodoBean" class. The #{todoBean.persist} symbol refers to the "persist" method in the "TodoBean" class. This method creates the "Todo" instance with the input data (title and description) and persists the data.
- </para>
-
-<programlisting role="xml">
-<h:form id="create">
-<table>
- <tr>
- <td>Title:</td>
- <td>
- <h:inputText id="title" value="#{todoBean.todo.title}" size="15">
- <f:validateLength minimum="2"/>
- </h:inputText>
- </td>
- </tr>
- <tr>
- <td>Description:</td>
- <td>
- <h:inputTextarea id="description" value="#{todoBean.todo.description}">
- <f:validateLength minimum="2" maximum="250"/>
- </h:inputTextarea>
- </td>
- </tr>
-</table>
-<h:commandButton type="submit" id="create" value="Create"
- action="#{todoBean.persist}"/>
-</h:form>
-</programlisting>
-
-<para>
- <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_create_todo"/> shows the "Create Todo" web page with the input fields mapped to the data model.
- </para>
- <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_create_todo">
- <title>The "Create Todo" web page </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jsfejb3_create_todo.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">todos.xhtml</emphasis>: This page displays the list of all "todos" created. There is also an option to choose a "todo" item for 'edit' or 'delete'.
- </para>
- <para>
- The list of all 'todos' is fetched by #{todoBean.todos} symbol referring to the 'getTodos()' property in the 'TodoBean' class. The JSF <literal>dataTable</literal> iterates through the list and displays each <literal>Todo</literal> object in a row. The 'Edit' option is available across each row. The #{todo.id} symbol represents the "id" property of the "todo" object.
- </para>
- <para>
-<programlisting>
-<h:form>
-<h:dataTable value="#{todoBean.todos}" var="todo">
- <h:column>
- <f:facet name="header">Title</f:facet>
- #{todo.title}
- </h:column>
- <h:column>
- <f:facet name="header">Description</f:facet>
- #{todo.description}
- </h:column>
- <h:column>
- <a href="edit.faces?tid=#{todo.id}">Edit</a>
- </h:column>
-</h:dataTable>
-<center>
- <h:commandButton action="create"
- value="Create New Todo" type="submit"/>
-</center>
-</h:form>
-</programlisting>
- <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_todos"/> shows the "Show All Todos" web page with the data fields mapped to the data model.
- </para>
- <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_todos">
- <title>The "Show All Todos" web page </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jsfejb3_todos.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">edit.xhtml</emphasis>: This page allows you to edit the "todo" item's 'title' and 'description' properties. The #{todoBean.update} and #{todoBean.delete} symbols represent the "update" and "delete" methods in the "TodoBean" class.
- </para>
-
-<programlisting role="xml">
-<h2>Edit #{todoBean.todo.title}</h2>
-<h:form id="edit">
-<input type="hidden" name="tid" value="#{todoBean.todo.id}"/>
-<table>
- <tr>
- <td>Title:</td>
- <td>
- <h:inputText id="title" value="#{todoBean.todo.title}" size="15">
- <f:validateLength minimum="2"/>
- </h:inputText>
- </td>
- </tr>
- <tr>
- <td>Description:</td>
- <td>
- <h:inputTextarea id="description" value="#{todoBean.todo.description}">
- <f:validateLength minimum="2" maximum="250"/>
- </h:inputTextarea>
- </td>
- </tr>
-</table>
-<h:commandButton type="submit" id="update" value="Update"
- action="#{todoBean.update}"/>
-<h:commandButton type="submit" id="delete" value="Delete"
- action="#{todoBean.delete}"/>
-</h:form>
-</programlisting>
-<para>
- <xref linkend="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_edit_todo"/> shows the "Edit Todo" web page with the mapping to the data model.
- </para>
- <figure id="Sample_JSF_EJB3_Application-JSF_Web_Pages-jsfejb3_edit_todo">
- <title>The "Edit Todo" web page </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jsfejb3_edit_todo.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </listitem>
- </itemizedlist>
- </para>
- <note>
- <para>
- We have used XHTML pages in the sample applications because we recommend using Facelets instead of JSP to render JSF view pages.
- </para>
- </note>
- </section>
- <section id="Sample_JSF_EJB3_Application-EJB3_Session_Beans">
- <title>EJB3 Session Beans</title>
- <para>
- EJB 3.0 is one of the major improvements introduced with Java EE 5.0. It aims at reducing the complexity of older versions of EJB and simplifies Enterprise Java development and deployment. You will notice that to declare a class as a 'Session Bean' you simply have to annotate it. Using annotations eliminates the complexity involved with too many deployment descriptors. Also the only interface an EJB3 Session Bean requires is a business interface that declares all the business methods that must be implemented by the bean.
- </para>
- <para>
- We will explore the two important source files associated with the Bean implementation in our application: <literal>TodoDaoInt.java</literal> and <literal>TodoDao.java</literal>.
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">Business interface</emphasis>: <literal>TodoDaoInt.java</literal>
- </para>
- <para>We define here the methods that need to be implemented by the bean implementation class. Basically, the business methods that will be used in our application are defined here.
-
-<programlisting role="JAVA">
-public interface TodoDaoInt {
-
- public void persist (Todo todo);
- public void delete (Todo todo);
- public void update (Todo todo);
-
- public List <Todo> findTodos ();
- public Todo findTodo (String id);
-}
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">Stateless Session Bean</emphasis>: <literal>TodoDao.java</literal>
- </para>
- <para>
- The <literal>@Stateless</literal> annotation marks the bean as a stateless session bean. In this class, we need to access the Entity bean <literal>Todo</literal> defined earlier. For this we need an <literal>EntityManager</literal>. The <literal>@PersistenceContext</literal> annotation tells the JBoss Server to inject an entity manager during deployment.
-<programlisting>
- at Stateless
-public class TodoDao implements TodoDaoInt {
-
- @PersistenceContext
- private EntityManager em;
-
- public void persist (Todo todo) {
- em.persist (todo);
- }
-
- public void delete (Todo todo) {
- Todo t = em.merge (todo);
- em.remove( t );
- }
-
- public void update (Todo todo) {
- em.merge (todo);
- }
-
- public List <Todo> findTodos () {
- return (List <Todo>) em.createQuery("select t from Todo t")
- .getResultList();
- }
-
- public Todo findTodo (String id) {
- return (Todo) em.find(Todo.class, Long.parseLong(id));
- }
-
-}
-</programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="Sample_JSF_EJB3_Application-Configuration_and_Packaging">
- <title>Configuration and Packaging</title>
- <para>
- We will build the sample application using Ant and explore the configuration and packaging details. Please install Ant if currently not installed on your computer.
- </para>
- <section id="Building_The_Application">
- <title>Building The Application</title>
- <para>Let's look at building the example application and then explore the configuration files in detail.
- </para>
- <para>
- In <xref linkend="About_the_Example_Applications"/>, we looked at the directory structure of the <literal>jsfejb3</literal> sample application. At the command line, go to the <literal>jsfejb3</literal> directory. There you will see a <literal>build.xml</literal> file. This is our Ant build script for compiling and packaging the archives. To build the application, you need to first of all edit the <literal>build.xml</literal> file and edit the value of <literal>jboss-dist</literal> to reflect the location where the JBoss Application Server is installed. Once you have done this, just type the command <literal>ant</literal> and your output should look like this:
- </para>
-<screen>[user at localhost jsfejb3]$ ant
-Buildfile: build.xml
-
-compile:
- [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/classes
- [javac] Compiling 4 source files to /home/user/Desktop/gettingstarted/jsfejb3/build/classes
- [javac] Note: /jboss/gettingstarted/jsfejb3/src/TodoDao.java uses unchecked or unsafe operations.
- [javac] Note: Recompile with -Xlint:unchecked for details.
-
-war:
- [mkdir] Created dir: /jboss/gettingstarted/jsfejb3/build/jars
- [war] Building war: /jboss/gettingstarted/jsfejb3/build/jars/app.war
-
-ejb3jar:
- [jar] Building jar: /jboss/gettingstarted/jsfejb3/build/jars/app.jar
-
-ear:
- [ear] Building ear: /jboss/gettingstarted/jsfejb3/build/jars/jsfejb3.ear
-
-main:
-
-BUILD SUCCESSFUL
-Total time: 3 seconds
-
-</screen>
- <para>
- If you get the BUILD SUCCESSFUL message, you will find a newly created <literal>build</literal> directory with 2 sub-directories in it: <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">classes</emphasis>: containing the compiled class files.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">jars</emphasis>: containing three archives - <literal>app.jar</literal>, <literal>app.war</literal> and <literal>jsfejb3.ear</literal>. <itemizedlist>
- <listitem>
- <para>
- app.jar : EJB code and descriptors.
- </para>
- </listitem>
- <listitem>
- <para>
- app.war : web application which provides the front end to allow users to interact with the business components (the EJBs). The web source (HTML, images etc.) contained in the <literal>jsfejb3/view</literal> directory is added unmodified to this archive. The Ant task also adds the <literal>WEB-INF</literal> directory that contains the files which aren’t meant to be directly accessed by a web browser but are still part of the web application. These include the deployment descriptors (<literal>web.xml</literal>) and extra jars required by the web application.
- </para>
- </listitem>
- <listitem>
- <para>
- jsfejb3.ear : The EAR file is the complete application, containing the EJB modules and the web module. It also contains an additional descriptor, <literal>application.xml</literal>. It is also possible to deploy EJBs and web application modules individually but the EAR provides a convenient single unit.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section id="Configuration_Files">
- <title>Configuration Files</title>
- <para>
- Now that we have built the application, lets take a closer look at some of the important Configuration files. We have built the final archive ready for deployment - <literal>jsfejb3.ear</literal>. The contents of your EAR file should look like this:
- </para>
-<programlisting>
-jsfejb3.ear
-|+ app.jar // contains the EJB code
- |+ import.sql
- |+ Todo.class
- |+ TodoDao.class
- |+ TodoDaoInt.class
- |+ META-INF
- |+ persistence.xml
-|+ app.war // contains web UI
- |+ index.html
- |+ index.xhtml
- |+ create.xhtml
- |+ edit.xhtml
- |+ todos.xhtml
- |+ TodoBean.class
- |+ style.css
- |+ META-INF
- |+ WEB-INF
- |+ faces-config.xml
- |+ navigation.xml
- |+ web.xml
-|+ META-INF // contains the descriptors
- |+ application.xml
- |+ jboss-app.xml
-</programlisting>
- <itemizedlist>
- <listitem>
- <para>
- <literal>application.xml</literal>: This file lists the JAR files in the EAR (in our case <literal>app.jar</literal>) and tells the JBoss server what files to look for and where. The root URL for the application is also specified in this file as 'context-root'.
-<programlisting>
-<application>
- <display-name>Sample Todo</display-name>
- <module>
- <web>
- <web-uri>app.war</web-uri>
- <context-root>/jsfejb3</context-root>
- </web>
- </module>
- <module>
- <ejb>app.jar</ejb>
- </module>
-</application>
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>jboss-app.xml</literal>: Every EAR application should specify a unique string name for the class loader. In our case, we use the application name 'jsfejb3' as the class loader name.
-<programlisting>
-<jboss-app>
- <loader-repository>
- jsfejb3:archive=jsfejb3.ear
- </loader-repository>
-</jboss-app>
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>app.jar</literal>: This contains EJB3 Session Bean and Entity Bean classes and the related configuration files. In addition, the <literal>persistence.xml</literal> file configures the back-end data source (in our case the default HSQL database) for the <literal>EntityManager</literal>.
-<programlisting>
-<persistence>
- <persistence-unit name="helloworld">
- <provider>org.hibernate.ejb.HibernatePersistence</provider>
- <jta-data-source>java:/DefaultDS</jta-data-source>
- <properties>
- <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
- <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
- </properties>
- </persistence-unit>
-</persistence>
-</programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>app.war</literal>: This contains the Web UI files packaged according to the Web Application aRchive (WAR) specification. It contains all the web pages and the required configuration files. The <literal>web.xml</literal> file is an important file for all JAVA EE web applications. It is the web deployment descriptor file. The <literal>faces-config.xml</literal> file is the configuration file for JSF. The <literal>navigation.xml</literal> file contains the rules for JSF page navigation.
- </para>
-<programlisting>
-//faces-config.xml
-<faces-config>
- <application>
- <view-handler>
- com.sun.facelets.FaceletViewHandler
- </view-handler>
- </application>
- <managed-bean>
- <description>Dao</description>
- <managed-bean-name>todoBean</managed-bean-name>
- <managed-bean-class>TodoBean</managed-bean-class>
- <managed-bean-scope>request</managed-bean-scope>
- </managed-bean>
-</faces-config>
-</programlisting>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section id="The_Database">
- <title>The Database</title>
- <section id="The_Database-Creating_the_Database_Schema">
- <title>Creating the Database Schema</title>
- <para>
- To pre-populate the database, we have supplied SQL Code (<literal>import.sql</literal>) to run with HSQL in the <literal>examples/jsfejb3/resources</literal> directory. When you build the application using Ant, this is packaged in the app.jar file within the jsfejb3.ear file. When the application is deployed, you should be able to view the pre-populated data.
- </para>
- </section>
- <section id="The_Database-The_HSQL_Database_Manager_Tool">
- <title>The HSQL Database Manager Tool</title>
- <para>
- Just as a quick aside at this point, start up the JMX console application and click on the <literal>service=Hypersonic</literal> link which you’ll find under the section <literal>jboss</literal>. If you can’t find this, make sure the Hypersonic service is enabled in the <literal>hsqldb-ds.xml</literal> file.
- </para>
- <para>
- This will take you to the information for the Hypersonic service MBean. Scroll down to the bottom of the page and click the <literal>invoke</literal> button for the <literal>startDatabaseManager()</literal> operation. This starts up the HSQL Manager, a Java GUI application which you can use to manipulate the database directly.
- </para>
- <figure id="The_HSQL_Database_Manager_Tool-The_HSQL_Database_Manger_">
- <title>The HSQL Database Manger </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/hsql-manager.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- </section>
- <section id="Sample_JSF_EJB3_Application-Deploying_the_Application">
- <title>Deploying the Application</title>
- <para>
- Deploying an application in JBoss is simple and easy. You just have to copy the EAR file to the <literal>deploy</literal> directory in the 'server configuration' directory of your choice. Here, we will deploy it to the 'default' configuration, so we copy the EAR file to the <literal>JBOSS_DIST/jboss-as/server/default/deploy</literal> directory.
- </para>
- <para>
- You should see something close to the following output from the server:
- </para>
-<screen>
-15:32:23,997 INFO [EARDeployer] Init J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
-15:32:24,212 INFO [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
-entity.PersistenceUnitDeployment
-15:32:24,213 INFO [JmxKernelAbstraction] installing MBean: persistence.units:ear=
-jsfejb3.ear,jar=app.jar,unitName=helloworld with dependencies:
-15:32:24,213 INFO [JmxKernelAbstraction] jboss.jca:name=DefaultDS,service=
-DataSourceBinding
-15:32:24,275 INFO [PersistenceUnitDeployment] Starting persistence unit persistence.
-units:ear=jsfejb3.ear,jar=app.jar,unitName=helloworld
-15:32:24,392 INFO [Ejb3Configuration] found EJB3 Entity bean: Todo
-15:32:24,450 WARN [Ejb3Configuration] Persistence provider caller does not implements
-the EJB3 spec correctly. PersistenceUnitInfo.getNewTempClassLoader() is null.
-15:32:24,512 INFO [Configuration] Reading mappings from resource : META-INF/orm.xml
-15:32:24,512 INFO [Ejb3Configuration] [PersistenceUnit: helloworld] no META-INF/orm.xml
-found
-15:32:24,585 INFO [AnnotationBinder] Binding entity from annotated class: Todo
-15:32:24,586 INFO [EntityBinder] Bind entity Todo on table Todo
-.
-.
-.
-.
-15:32:26,311 INFO [SchemaExport] Running hbm2ddl schema export
-15:32:26,312 INFO [SchemaExport] exporting generated schema to database
-15:32:26,314 INFO [SchemaExport] Executing import script: /import.sql
-15:32:26,418 INFO [SchemaExport] schema export complete
-15:32:26,454 INFO [NamingHelper] JNDI InitialContext properties:{java.naming.factory.
-initial=org.jnp.interfaces.NamingContextFactory, java.naming.factory.url.pkgs=org.jboss.
-naming:org.jnp.interfaces}
-15:32:26,484 INFO [JmxKernelAbstraction] creating wrapper delegate for: org.jboss.ejb3.
-stateless.StatelessContainer
-15:32:26,485 INFO [JmxKernelAbstraction] installing MBean: jboss.j2ee:ear=jsfejb3.ear,
-jar=app.jar,name=TodoDao,service=EJB3 with dependencies:
-15:32:26,513 INFO [JmxKernelAbstraction] persistence.units:ear=jsfejb3.ear,
-jar=app.jar,unitName=helloworld
-15:32:26,557 INFO [EJBContainer] STARTED EJB: TodoDao ejbName: TodoDao
-15:32:26,596 INFO [EJB3Deployer] Deployed: file:/jboss/jboss-as-5.0.0<release>
-server/default/tmp/deploy/
-tmp33761jsfejb3.ear-contents/app.jar
-15:32:26,625 INFO [TomcatDeployer] deploy, ctxPath=/jsfejb3, warUrl=.../tmp/deploy/
-tmp33761jsfejb3.ear-contents/app-exp.war/
-15:32:26,914 INFO [EARDeployer] Started J2EE application: file:/jboss/jboss-as-5.0.0<release>/server/default/deploy/jsfejb3.ear
-</screen>
- <para>
- If there are any errors or exceptions, make a note of the error message. Check that the EAR is complete and inspect the WAR file and the EJB jar files to make sure they contain all the necessary components (classes, descriptors etc.).
- </para>
- <para>
- You can safely redeploy the application if it is already deployed. To undeploy it you just have to remove the archive from the <literal>deploy</literal> directory. There’s no need to restart the server in either case. If everything seems to have gone OK, then point your browser at the application URL.
- </para>
- <para>
- <ulink url="http://localhost:8080/jsfejb3"/>
- </para>
- <para>
- You will be forwarded to the application main page. <xref linkend="Deploying_the_Application-Sample_TODO"/> shows the sample application in action.
- </para>
- <figure id="Deploying_the_Application-Sample_TODO">
- <title>Sample TODO</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/sample_jsfejb3.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
-</chapter>
- <chapter id="Using_Seam">
- <title>Using Seam</title>
- <para>
- JBoss Seam is a framework that provides the glue between the new EJB3 and JSF frameworks that are part of the Java EE 5.0 standard. In fact, the name Seam refers to the seamless manner in which it enables developers to use these two frameworks in an integrated manner. Seam automates many of the common tasks, and makes extensive use of annotations to reduce the amount of xml code that needs to be written. The overall effect is to significantly reduce the total amount of coding that needs to be done.
- </para>
-
- <para>
- If you are new to Seam, you can find more introductory information from the following url and book:
-<itemizedlist>
- <listitem>
- <para>
- <ulink url="http://docs.jboss.com/seam/2.0.0.GA/reference/en/html_single/">The Seam Reference Guide</ulink>.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Beginning JBoss Seam</emphasis> by Joseph Faisal Nusairat, Apress 2007.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
-
- <para>
- We have included two versions of the example application, one coded using EJB3 / JSF without using Seam, and one using Seam, to demonstrate clearly the difference in application development using the Seam framework.
- </para>
-
-
-
- <section id="Using_Seam_Data_Model">
- <title>
- Data Model
- </title>
-
- <para>
- Let's start off our examination of the Seam implementation in the same way, by examining how the Data Model is implemented. This is done in the <literal>Todo.java</literal> file.
- </para>
-
- <programlisting>@Entity
- at Name("todo")
-public class Todo implements Serializable {
-
- private long id;
- private String title;
- private String description;
-
- public Todo () {
- title ="";
- description ="";
- }
-
- @Id @GeneratedValue
- public long getId() { return id;}
- public void setId(long id) { this.id = id; }
-
- @NotNull
- public String getTitle() { return title; }
- public void setTitle(String title) {this.title = title;}
-
- @NotNull
- @Length(max=250)
- public String getDescription() { return description; }
- public void setDescription(String description) {
- this.description = description;
- }
-
-}</programlisting>
-
- <para>
- The <literal>@Entity</literal> annotation defines the class as an EJB3 entity bean, and tells the container to map the <literal>Todo</literal> class to a relational database table. Each property of the class will become a column in the table. Each instance of the class will become a row in this table. Since we have not used the <literal>@Table</literal> annotation, Seam's "configuration by exception" default will name the table after the class.
- </para>
-
- <para>
- <literal>@Entity</literal> and <literal>@Table</literal> are both EJB3 annotations, and are not specific to Seam. It is possible to use Seam completely with POJOs (Plain Old Java Objects) without any EJB3-specific annotations. However, EJB3 brings a lot of advantages to the table, including container managed security, message-driven components, transaction and component level persistence context, and <literal>@PersistenceContext</literal> injection, which we will encounter a little further on.
- </para>
-
- <para>
- The <literal>@Name</literal> annotation is specific to Seam, and defines the string name for Seam to use to register the Entity Bean. This will be the default name for the relational database table. Each component in a Seam application must have a unique name. In the other components in the Seam framework, such as JSF web pages and session beans, you can reference the managed <literal>Todo</literal> bean using this name. If no instance of this class exists when it is referenced from another component, then Seam will instantiate one.
- </para>
-
- <para>
- The <literal>@Id</literal> annotation defines a primary key <literal>id</literal> field for the component. <literal>@GeneratedValue</literal> specifies that the server will automatically generate this value for the component when it is saved to the database.
- </para>
-
- <para>
- Seam provides support for model-based constraints defined using Hibernate Validator, although Hibernate does not have to be the object persister used. The <literal>@NotNull</literal> annotation is a validation constraint that requires this property to have a value before the component can be persisted into the database. Using this annotation allows the validation to be enforced by the JSF code at the view level, without having to specify the exact validation constraint in the JSF code.
- </para>
-
- <para>
- At this point the only apparent difference between the Seam version and the EJB3/JSF version of the app is the inclusion of the validator annotation <literal>@NotNull</literal>, and the <literal>@Name</literal> annotation. However, while the EJB3/JSF version of this application requires a further <literal>TodoBean</literal> class to be manually coded and managed in order to handle the interaction between the <literal>Todo</literal> class and the web interface, when using Seam the Seam framework takes care of this work for us. We'll see how this is done in practice as we examine the implementation of the user interface.
- </para>
- </section>
-
- <section id="Using_Seam_JSF_Web_Pages">
- <title>
- JSF Web Pages - index.xhtml and create.xhtml
- </title>
-
- <para>
- The <emphasis role="bold">index.xhtml</emphasis> file used is the same as in the EJB3/JSF example.
- </para>
-
- <para>
- <emphasis role="bold">create.xhtml</emphasis> begins to reveal the difference that coding using the Seam framework makes.
- </para>
-
- <programlisting><h:form id="create">
-
-<f:facet name="beforeInvalidField">
- <h:graphicImage styleClass="errorImg" value="error.png"/>
-</f:facet>
-<f:facet name="afterInvalidField">
- <s:message styleClass="errorMsg" />
-</f:facet>
-<f:facet name="aroundInvalidField">
- <s:div styleClass="error"/>
-</f:facet>
-
-<s:validateAll>
-
-<table>
-
- <tr>
- <td>Title:</td>
- <td>
- <s:decorate>
- <h:inputText id="title" value="#{todo.title}" size="15"/>
- </s:decorate>
- </td>
- </tr>
-
- <tr>
- <td>Description:</td>
- <td>
- <s:decorate>
- <h:inputTextarea id="description" value="#{todo.description}"/>
- </s:decorate>
- </td>
- </tr>
-
-</table>
-
-</s:validateAll>
-
-<h:commandButton type="submit" id="create" value="Create"
- action="#{todoDao.persist}"/>
-</h:form>
- </programlisting>
-
- <para>
- The first thing that is different here is the Java Server Facelet code at the beginning, which works with the <literal>@NotNull</literal> validation constraint of our <literal>todo</literal> class to enforce and indicate invalid input to the user.
- </para>
-
- <para>
- Also notice here that rather than requiring the use of a <literal>TodoBean</literal> class as we did in the EJB3/JSF example we back the form directly with a <literal>Todo</literal> entity bean. When this page is called, JSF asks Seam to resolve the variable <literal>todo</literal> due to JSF EL references such as <literal>#{todo.title}</literal>. Since there is no value already bound to that variable name, Seam will instantiate an entity bean of the <literal>todo</literal> class and return it to JSF, after storing it in the Seam context. The Seam context replaces the need for an intermediary bean.
- </para>
-
- <para>
- The form input values are validated against the Hibernate Validator constraints specified in the <literal>todo</literal> class. JSF will redisplay the page if the constraints are violated, or it will bind the form input values to the <literal>Todo</literal> entity bean.
- </para>
-
- <para>
- Entity beans shouldn't do database access or transaction management, so we can't use the <literal>Todo</literal> entity bean as a JSF action listener. Instead, creation of a new todo item in the database is accomplished by calling the <literal>persist</literal> method of a <literal>TodoDao</literal> session bean. When JSF requests Seam to resolve the variable <literal>todoDao</literal> through the JSF EL expression <literal>#{todoDao.persist}</literal>, Seam will either instantiate an object if one does not already exist, or else pass the existing stateful <literal>todoDao</literal> object from the Seam context. Seam will intercept the <literal>persist</literal> method call and inject the <literal>todo</literal> entity from the session context.
- </para>
-
- <para>
- Let's have a look at the <literal>TodoDao</literal> class (defined in <literal>TodoDao.java</literal>) to see how this injection capability is implemented.
- </para>
- </section>
-
- <section id="Using_Seam_Session_Bean">
- <title>
- Data Access using a Session Bean
- </title>
-
- <para>
- Let's go through a listing of the code for the <literal>TodoDao</literal> class.
- </para>
-
- <programlisting>@Stateful
- at Name("todoDao")
-public class TodoDao implements TodoDaoInt {
-
- @In (required=false) @Out (required=false)
- private Todo todo;
-
- @PersistenceContext (type=EXTENDED)
- private EntityManager em;
-
- // Injected from pages.xml
- Long id;
-
- public String persist () {
- em.persist (todo);
- return "persisted";
- }
-
- @DataModel
- private List <Todo> todos;
-
- @Factory("todos")
- public void findTodos () {
- todos = em.createQuery("select t from Todo t")
- .getResultList();
- }
-
- public void setId (Long id) {
- this.id = id;
-
- if (id != null) {
- todo = (Todo) em.find(Todo.class, id);
- } else {
- todo = new Todo ();
- }
- }
-
- public Long getId () {
- return id;
- }
-
- public String delete () {
- em.remove( todo );
- return "removed";
- }
-
- public String update () {
- return "updated";
- }
-
- @Remove @Destroy
- public void destroy() {}
-
-}</programlisting>
-
- <para>
- First of all notice that this is a stateful session bean. Seam can use both stateful and stateless session beans, the two most common types of EJB3 beans.
- </para>
-
- <para>
- The <literal>@In</literal> and <literal>@Out</literal> annotations define an attribute that is injected by Seam. The attribute is injected to this object or from this object to another via a Seam context variable named <literal>todo</literal>, a reference to the Seam registered name of our <literal>Todo</literal> class defined in <literal>Todo.java</literal>.
- </para>
-
- <para>
- The <literal>@PersistenceContext</literal> annotation injects the EJB3 Entity manager, allowing this object to persist objects to the database. Because this is a stateful session bean and the <literal>PersistenceContext</literal> type is set to <literal>EXTENDED</literal>, the same Entity Manager instance is used until the Remove method of the session bean is called. The database to be used (a <literal>persistence-unit</literal>) is defined in the file <filename>resources/META-INF/persistence.xml</filename>
- </para>
-
- <para>
- Note that this session bean has simultaneous access to context associated with web request (the form values of the <literal>todo</literal> object), and state held in transactional resources (the <literal>EntityManager</literal>). This is a break from traditional J2EE architectures, but Seam does not force you to work this way. You can use more traditional forms of application layering if you wish.
- </para>
-
- <para>
- The <literal>@DataModel</literal> annotation initializes the <literal>todos</literal> property, which will be outjected or "exposed" to the view. The <literal>@Factory</literal> annotated method performs the work of generating the <literal>todos</literal> list, and is called by Seam if it attempts to access the exposed <literal>DataModel</literal> property and finds it to be null. Notice the absence of property access methods for the <literal>todos</literal> property. Seam takes care of this for you automatically.
- </para>
-
- <para>
- Let's take a look at the JSF code that we use for displaying and editing the list of todos, to get an idea of how to use these interfaces in practice.
- </para>
-
- </section>
-
- <section id="Using_Seam_Display_and_Edit">
- <title>
- JSF Web Pages - todos.xhtml and edit.xhtml
- </title>
-
- <para>
- Using the <literal>DataModel</literal> exposed property of the Session Bean it becomes trivial to produce a list of todos:
- </para>
-
- <programlisting><h:form>
-
-<h:dataTable value="#{todos}" var="todo">
- <h:column>
- <f:facet name="header">Title</f:facet>
- #{todo.title}
- </h:column>
- <h:column>
- <f:facet name="header">Description</f:facet>
- #{todo.description}
- </h:column>
- <h:column>
- <a href="edit.seam?tid=#{todo.id}">Edit</a>
- </h:column>
-</h:dataTable>
-
-<center>
- <h:commandButton action="create"
- value="Create New Todo" type="submit"/>
-</center>
-
-</h:form>
-</programlisting>
-
- <para>
- When the JSF variable resolver encounters <literal>{#todos}</literal> and requests <literal>todos</literal>, Seam finds that there is no "todos" component in the current scope, so it calls the @Factory("todos") method to make one. The todos object is then outjected once the factory method is done since it is annotated with the @DataModel annotation. <!--Seam responses by finding the <literal>todos</literal> <literal>DataModel</literal> registered with it, and outjecting that from the bean.-->
- </para>
-
- <para>
- Constructing the view for the edit page is similarly straight forward:
- </para>
-
- <programlisting><h:form id="edit">
-
-<f:facet name="beforeInvalidField">
- <h:graphicImage styleClass="errorImg" value="error.png"/>
-</f:facet>
-<f:facet name="afterInvalidField">
- <s:message styleClass="errorMsg" />
-</f:facet>
-<f:facet name="aroundInvalidField">
- <s:div styleClass="error"/>
-</f:facet>
-
-<s:validateAll>
-
-<table>
-
- <tr>
- <td>Title:</td>
- <td>
- <s:decorate>
- <h:inputText id="title" value="#{todo.title}" size="15"/>
- </s:decorate>
- </td>
- </tr>
-
- <tr>
- <td>Description:</td>
- <td>
- <s:decorate>
- <h:inputTextarea id="description" value="#{todo.description}"/>
- </s:decorate>
- </td>
- </tr>
-
-</table>
-
-</s:validateAll>
-
-<h:commandButton type="submit" id="update" value="Update"
- action="#{todoDao.update}"/>
-
-<h:commandButton type="submit" id="delete" value="Delete"
- action="#{todoDao.delete}"/>
-</h:form>
- </programlisting>
-
- <para>
- Here we see the same factors in play. JSF validation code taking advantage of the validation constraints defined in our Entity Bean, and the use of the <literal>todoDao</literal> Session Bean's <literal>update</literal> and <literal>delete</literal> methods to update the database.
- </para>
-
- <para>
- The call from <filename>todos.xhtml</filename>: <literal>edit.seam?tid=#{todo.id}</literal> causes Seam to create a <literal>todoDao</literal> and set it's <literal>id</literal> property to <literal>tid</literal>. Setting its <literal>id</literal> property causes the <literal>todoDao</literal> to retrieve the appropriate record from the database.
- </para>
-
- <para>
- The functionality that allows the edit page to be called with a parameter in this way is implemented through <literal>pages.xml</literal>. Let's have a look at the <literal>pages.xml</literal> file and how it is used by Seam applications.
- </para>
- </section>
-
- <section id="Using_Seam_XML_Files">
- <title>
- Xml Files
- </title>
-
- <para>
- Seam drastically reduces the amount of xml coding that needs to be done. One file that is of interest is the <literal>pages.xml</literal>, packaged in the <literal>app.war</literal> file's <literal>WEB-INF</literal> directory. This file is available in the <literal>resources/WEB-INF</literal> directory in the source code bundle. The <literal>pages.xml</literal> file is used to define page descriptions including Seam page parameters (HTTP <literal>GET</literal> parameters), page actions, page navigation rules, error pages etc. <!--This file defines a number of attributes that affect global behaviour of the application.--> Among other things it can be used in a Seam application to define exception handlers and redirections.
- </para>
- <para>
- In the case of our sample application we are using it to define a Seam page parameter. The <literal>pages.xml</literal> in this example contains the following code:
- </para>
-
- <programlisting><page view-id="/edit.xhtml">
- <param name="tid" value="#{todoDao.id}"
- converterId="javax.faces.Long"/>
-</page></programlisting>
- <para>
- This defines a parameter named <literal>tid</literal> for the <literal>edit.xhtml</literal> page. When the <literal>edit.xhtml</literal> page is loaded, the HTTP <literal>GET</literal> request parameter <literal>tid</literal> is converted to a <literal>Long</literal> value and assigned to the <literal>id</literal> property of the <literal>todoDao</literal> object. You can have as many page parameters as required to bind HTTP <literal>GET</literal> request parameters to the back-end components in your application.
- </para>
- </section>
-
- <section id="Further_Information">
- <title>
- Further Information
- </title>
-
- <para>
- This completes our walkthrough of the sample Seam application. For further, detailed information on developing applications using the Seam framework, please refer to the <ulink url="http://docs.jboss.com/seam/2.0.0.GA/reference/en/html_single/">The Seam Reference Guide</ulink>.
- </para>
- </section>
-</chapter>
- <chapter id="Using_other_Databases">
- <title>Using other Databases</title>
- <para>
- 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.
- </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.
- </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 Application Server Guide available at <ulink url="http://labs.jboss.com/projects/docs/"/>.
- </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.
- </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.
- </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>
- </section>
-
- <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"/>.
- </para>
-
-
-
-
-
-
- <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).
- </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"?>
-<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>
- </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>
- </section>
-
-
-
- <section id="Using_MySQL_as_the_Default_DataSource-Testing_the_MySQL_DataSource">
- <title>Testing the MySQL DataSource</title>
- <para>
- Using the test client described in <xref linkend="creating_a_jdbc_client"/>, you may now verify the proper installation of your datasource.
- </para>
-
- </section>
-
- </section>
-
- <section id="Configuring_a_datasource_for_Oracle_DB">
- <title>Configuring a datasource for Oracle DB</title>
- <para>
- Oracle is one of the main players in the commercial database field and most readers will probably have come across it at some point. You can download it freely for non-commercial purposes from <ulink url="http://www.oracle.com/technology/products/database/xe/index.html"/>
- </para>
- <para>
- In this section, we'll connect the server to Oracle Database 10g Express Edition using the latest JDBC driver (11g) available at <ulink url="http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html"/>
- </para>
-
-
-
- <section id="Setting_up_an_XADataSource_with_Oracle_9i-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 JBoss Application Server, copy the archive ojdbc5.jar to the lib directory in the default server configuration (assuming that is the server configuration you’re running).
- </para>
- <para>
- Then create a text file in the <filename>deploy</filename> directory called <filename>oracle-ds.xml</filename> with the following datasource descriptor :
- </para>
-
-<programlisting role="XML"><?xml version="1.0" encoding="UTF-8"?>
-<datasources>
- <local-tx-datasource>
- <jndi-name>DefaultDS</jndi-name>
- <connection-url>jdbc:oracle:thin:@localhost:1521:xe</connection-url>
- <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
- <user-name>SYSTEM</user-name>
- <password>jboss</password>
- <valid-connection-checker-class-name>org.jboss.resource.adapter.jdbc.vendor.OracleValidConnectionChecker</valid-connection-checker-class-name>
- <metadata>
- <type-mapping>Oracle9i</type-mapping>
- </metadata>
- </local-tx-datasource>
-</datasources></programlisting>
-
- <para>
- The datasource is pointing at the database/SID called “xe” provided by default with Oracle XE.
- </para>
- <para>
- Of course, you need to update the connection url attributes as well as the username/password combination to match your environment setup.
- </para>
-
- </section>
-
-
-
-
-
-
-
-
-
-
-
- <section id="Setting_up_an_XADataSource_with_Oracle_9i-Testing_the_Oracle_DataSource">
- <title>Testing the Oracle DataSource</title>
- <para>
- Before you can verify the datasource configuration, Oracle XE should be reconfigured to avoid port conflict with JBossAS as by default they both start a web server on port 8080.
- </para>
- <para>Open up an Oracle SQLcommand line and execute the following commands:
- </para>
-<screen>
-<command>SQL> connect;
-Enter user-name: SYSTEM
-Enter password:</command>
-Connected.
-SQL> <command>begin
-2 dbms_xdb.sethttpport('8090');
-3 end;
-4 /</command>
-PL/SQL procedure successfully completed.
-SQL> <command>select dbms_xdb.gethttpport from dual;</command>
-GETHTTPPORT
------------
-8090
-</screen>
-
-<para>
- The web server started by Oracle XE to provide http-based administration tools is now running on port 8090.
- Start the JBossAS server instance as you would normally do. You are now ready to use the test client described in Chapter 6.5 to verify the proper installation of your datasource.
-</para>
-
- </section>
- </section>
-
-
- <section><title>Configuring a datasource for Microsoft SQL Server 200x</title>
- <para>In this section, we'll connect the server to MS SQL Server 2000 using the latest JDBC driver (v1.2) available at <ulink url="http://msdn2.microsoft.com/en-us/data/aa937724.aspx"/>.
- </para>
-
- <section><title>Installing the JDBC Driver and Deploying the DataSource</title>
- <para>
- To make the JDBC driver classes available to JBoss Application Server, copy the archive <filename>sqljdbc.jar</filename> from the <filename>sqljdbc_1.2</filename> distribution to the <filename>lib</filename> directory in the default server configuration (assuming that is the server configuration you’re running).
- </para>
- <para>
- Then create a text file in the <literal>deploy</literal> directory called <literal>mssql-ds.xml</literal> with the following datasource descriptor :
-<programlisting><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<datasources>
- <local-tx-datasource>
- <jndi-name>DefaultDS</jndi-name>
- <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=pubs</connection-url>
- <driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>
- <user-name>sa</user-name>
- <password>jboss</password>
- <check-valid-connection-sql>SELECT 1 FROM sysobjects</check-valid-connection-sql>
- <metadata>
- <type-mapping>MS SQLSERVER2000</type-mapping>
- </metadata>
- </local-tx-datasource>
-</datasources> ]]>
-</programlisting>
-
-The datasource is pointing at a database “pubs” provided by default with MS SQL Server 2000.
-</para>
-<para>
-Remember to update the connection url attributes as well as the username/password combination to match your environment setup.
-
-</para>
-
-<section id="testing_the_datasource"><title>Testing the datasource</title>
- <para>Using the test client described in <xref linkend="creating_a_jdbc_client"/>, you may now verify the proper installation of your datasource.
- </para>
-</section>
- </section>
-</section>
-
-
-<section id="configuring_jbossmessaging_persistence_manager"><title>Configuring JBoss Messaging Persistence Manager</title>
- <para>
- The persistence manager of JBoss Messaging uses the default datasource to create tables to store messages, transaction data and other indexes. Configuration of "persistence" is grouped in <filename>xxx-persistence-service.xml</filename> files. JBoss Application Server ships with a default <filename>hsqldb-persistence-service.xml</filename> file, which configures the Messaging server to use the Hypersonic database instance that ships by default with the JBoss Application Server.
- </para>
- <para>
- You can view the <filename>hsqldb-persistence-service.xml</filename> file in configurations based on the <emphasis>all</emphasis> or <emphasis>default</emphasis> configurations:
-
- <screen><JBoss_Home>/server/all/deploy/messaging/hsqldb-persistence-service.xml and
- <JBoss_Home>/server/default/deploy/messaging/hsqldb-persistence-service.xml</screen>
-
- </para>
-
-
- <warning><title>Warning</title>
- <para>Please note that the Hypersonic database is not recommended for production environments due to its limited support for transaction isolation and its low reliability under high load</para>
- </warning>
-
- <para>
- More information on configuring JBoss Messaging can be found in the <ulink url="http://www.jboss.org/file-access/default/members/jbossas/freezone/docs/Server_Configuration_Guide/beta500/html-single/index.html#d0e3471">JBoss AS Configuration Guide</ulink>.
-
- </para>
-
-
-</section>
-
-
-<section id="creating_a_jdbc_client"><title>Creating a JDBC client</title>
- <para>
- When testing a newly configured datasource we suggest using some very basic JDBC client code embedded in a JSP page.
- First of all, you should create an exploded WAR archive under the deploy directory which is simply a folder named "<literal>jdbcclient.war</literal>".
-In this folder, create a text document named client.jsp and paste the code below:
-<programlisting><![CDATA[
-<%@page contentType="text/html"
- import="java.util.*,javax.naming.*,javax.sql.DataSource,java.sql.*"
- %>
- <%
-
- DataSource ds = null;
- Connection con = null;
- PreparedStatement pr = null;
- InitialContext ic;
- try {
- ic = new InitialContext();
- ds = (DataSource)ic.lookup( "java:/DefaultDS" );
- con = ds.getConnection();
- pr = con.prepareStatement("SELECT USERID, PASSWD FROM JMS_USERS");
- ResultSet rs = pr.executeQuery();
- while (rs.next()) {
- out.println("<br> " +rs.getString("USERID") + " | " +rs.getString("PASSWD"));
- }
- rs.close();
- pr.close();
- }catch(Exception e){
- out.println("Exception thrown " +e);
- }finally{
- if(con != null){
- con.close();
- }
-}]]> %> </programlisting>
-
-Open up a web browser and hit the url: <ulink url="http://localhost:8080/jdbcclient/client.jsp"/>.
-A list of users and password should show up as a result of the jdbc query:
-<screen>
-dynsub | dynsub
-guest | guest
-j2ee | j2ee
-john | needle
-nobody | nobody
-</screen>
-
- </para>
-</section>
-
-</chapter>
- <appendix id="Book-Revision_History">
- <appendixinfo>
- <revhistory>
-
-<revision>
- <revnumber>5.0.0</revnumber>
- <date>Jan 08 2007</date>
- <author>
- <firstname>S</firstname>
- <surname>Kittoli</surname>
-
- </author>
- <revdescription>
- <simplelist>
- <member>Updated Content </member>
-
- </simplelist>
- </revdescription>
- </revision>
-
- <revision>
- <revnumber>5.0.0</revnumber>
- <date>Apr 07 2007</date>
- <author>
- <firstname>S</firstname>
- <surname>Kittoli</surname>
-
- </author>
- <revdescription>
- <simplelist>
- <member>Merge Content </member>
- </simplelist>
- </revdescription>
- </revision>
-</revhistory>
- </appendixinfo>
- <title>Revision History</title>
- <para>
- </para>
-</appendix>
- <appendix id="appendix2">
-
- <title>Further Information Sources</title>
- <para>
- Developers wanting to get familiar with software development and implementation in JBoss Application Server can read: <emphasis>JBoss: A Developer's Notebook</emphasis>. (O'Reilly, 2005. Norman Richards, Sam Griffith).
- </para>
- <para>
- For more comprehensive JBoss documentation covering advanced JBoss topics, refer to the manuals available online at <ulink url="http://www.jboss.org/jbossas/docs"/>.
- </para>
- <para>
- For general EJB instruction, with thorough JBoss coverage, see <emphasis> Enterprise JavaBeans, 4th Edition</emphasis>. (O'Reilly, 2004. Richard Monson-Haeful, Bill Burke, Sacha Labourey)
- </para>
- <para>
- To learn more about Hibernate, see <emphasis>Java Persistence With Hibernate</emphasis>. (Manning, 2007. Christian Bauer, Gavin King)
- </para>
- <para>
- For complete coverage of the JBoss Seam framework, we recommend <emphasis>JBoss Seam: Simplicity And Power Beyond Java EE</emphasis>. (Prentice Hall, 2007. Michael Yuan, Thomas Heute).
- </para>
-</appendix>
-
-</book>
More information about the jboss-cvs-commits
mailing list