[jboss-cvs] JBossAS SVN: r66207 - projects/docs/trunk/Getting_Started/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Oct 17 01:35:08 EDT 2007
Author: mhideo at redhat.com
Date: 2007-10-17 01:35:07 -0400 (Wed, 17 Oct 2007)
New Revision: 66207
Removed:
projects/docs/trunk/Getting_Started/en-US/Author_Group.xml
projects/docs/trunk/Getting_Started/en-US/Book_Info.xml
projects/docs/trunk/Getting_Started/en-US/Feedback.xml
projects/docs/trunk/Getting_Started/en-US/Getting_Started.xml
projects/docs/trunk/Getting_Started/en-US/Legal_Notice.xml
Log:
fixing again
Deleted: projects/docs/trunk/Getting_Started/en-US/Author_Group.xml
===================================================================
--- projects/docs/trunk/Getting_Started/en-US/Author_Group.xml 2007-10-17 04:54:27 UTC (rev 66206)
+++ projects/docs/trunk/Getting_Started/en-US/Author_Group.xml 2007-10-17 05:35:07 UTC (rev 66207)
@@ -1,5 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-
-<authorgroup><corpauthor> JBoss Community Documentation Project </corpauthor></authorgroup>
Deleted: projects/docs/trunk/Getting_Started/en-US/Book_Info.xml
===================================================================
--- projects/docs/trunk/Getting_Started/en-US/Book_Info.xml 2007-10-17 04:54:27 UTC (rev 66206)
+++ projects/docs/trunk/Getting_Started/en-US/Book_Info.xml 2007-10-17 05:35:07 UTC (rev 66207)
@@ -1,12 +0,0 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
- <!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
- %RH-ENTITIES;
-]>
-<bookinfo>
- <title>JBoss Application Server 4.2.2</title>
- <subtitle>Getting Started Guide</subtitle>
- <issuenum>4.2</issuenum>
- <productnumber>2</productnumber>
-
-</bookinfo>
Deleted: projects/docs/trunk/Getting_Started/en-US/Feedback.xml
===================================================================
--- projects/docs/trunk/Getting_Started/en-US/Feedback.xml 2007-10-17 04:54:27 UTC (rev 66206)
+++ projects/docs/trunk/Getting_Started/en-US/Feedback.xml 2007-10-17 05:35:07 UTC (rev 66207)
@@ -1,27 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-
-<section id="Book-We_Need_Feedback">
- <title>We Need Feedback</title>
- <para>
- If you find a typographical error in the <citetitle>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://bugzilla.redhat.com/bugzilla/">http://bugzilla.redhat.com/bugzilla/</ulink> against the component <citetitle>Getting Started Guide</citetitle>.
- </para>
- <para>
- To view current JIRA issues against <citetitle>Getting Started Guide</citetitle> Please examine JIRA here: <ulink url="http://jira.jboss.com/jira/secure/IssueNavigator.jspa?reset=true&&pid=10030&resolution=-1&component=12311310&sorter/field=priority&sorter/order=DESC">http://jira.jboss.com</ulink>
- </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>This content is taken from svn.jboss.org/repos/jbossas/projects/docs/trunk 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/trunk --username yourname
-</screen>
-
-
-</section>
-
-
Deleted: projects/docs/trunk/Getting_Started/en-US/Getting_Started.xml
===================================================================
--- projects/docs/trunk/Getting_Started/en-US/Getting_Started.xml 2007-10-17 04:54:27 UTC (rev 66206)
+++ projects/docs/trunk/Getting_Started/en-US/Getting_Started.xml 2007-10-17 05:35:07 UTC (rev 66207)
@@ -1,2151 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY % RH-ENTITIES SYSTEM "Common_Config/rh-entities.ent">
-]>
-<!-- DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3b2/docbookx.dtd" -->
-<book>
-
-
- <bookinfo>
- <title>JBoss Application Server 4.2.2</title>
- <subtitle>Getting Started Guide</subtitle>
- <issuenum>4.2</issuenum>
- <productnumber>2</productnumber>
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
-</bookinfo>
- <!--preface>
- <title>About this book</title>
- <para>The goal of this book is to get you up and running J2EE 1.4 applications on JBoss 4.0 as quickly as
- possible. At the time of writing, the latest release is version 4.0.4. You should use this version or later
- with the examples. We will use update 7 of Sun’s J2EE 1.4 tutorial examples (<ulink url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/"/>) to illustrate the deployment and configuration
- of J2EE applications in JBoss. While the book is not intended to teach you J2EE, we will be covering the
- subject from quite a basic standpoint, so it will still be useful if you are new to J2EE. If you would like
- to use JBoss to run the standard Sun J2EE tutorials then this is the book for you. It should ideally be read
- in parallel with the tutorial texts. </para>
- </preface-->
- <preface>
- <title>What this Book Covers</title>
- <para>
- <xref linkend="install"/> will show you how to install and run JBoss. Then <xref linkend="tour"/> will
- provide a quick tour of the server directory structure and layout, the key configuration files and services.
- Finally, <xref linkend="tutorial"/> introduces the J2EE tutorial code that is used throughout out the book. </para>
- <para> Moving on to the examples, <xref linkend="dukesbank"/> introduces the Duke’s Bank application from the
- Sun J2EE Tutorial. You will see JBoss in action get some exposure simple configuration and deployment
- issues. <xref linkend="ws"/> adds web services to the application. We work through how to expose EJB methods
- from the Duke’s Bank application through web services and then call them with a Java client.</para>
- <para>After that, <xref linkend="mdb"/> and <xref linkend="cmp"/> show additional applications showing JMS
- messaging with message-driven beans and a more in-depth container-managed persistence example. </para>
- <para>
- <xref linkend="db"/> explores database configuration using MySQL and Oracle as the database. We end with
- <xref linkend="hibernate"/>, which shows how to use Hibernate with JBoss. The example applies Hibernate
- persistence to one of the earlier applications. </para>
- <para>Of course, that barely scratches the surface of what you can do with JBoss. Once you feel comfortable with
- the information here, the <emphasis>JBoss 4 Application Server Guide</emphasis> can take you the rest of the
- way to total mastery of the JBoss. </para>
- <para>
- If you find a typographical error in the <citetitle>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/jira/secure/IssueNavigator.jspa?reset=true&&pid=10030&resolution=-1&component=12311310&sorter/field=priority&sorter/order=DESC">http://jira.jboss.com</ulink> against the project <citetitle>JBoss Application Server</citetitle> and component <citetitle>Getting Started Guide</citetitle>.
- </para>
- <para>
- To view current JIRA issues against <citetitle>Getting Started Guide</citetitle> Please examine JIRA here: <ulink url="http://jira.jboss.com/jira/secure/IssueNavigator.jspa?reset=true&&pid=10030&resolution=-1&component=12311310&sorter/field=priority&sorter/order=DESC">http://jira.jboss.com</ulink>
- </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>This content is taken from svn.jboss.org/repos/jbossas/projects/docs/trunk 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/trunk --username yourname
-</screen>
-
- </preface>
- <chapter id="install">
-
- <title>Getting Started</title>
-
- <section>
- <title>Downloading and Installing JBoss</title>
- <para>Before you download and run JBoss make sure you have an up-to-date version of Java on your machine.
- JBoss 4.0 requires either a Java 1.4 or Java 5 JVM. We recommend Java 5 for overall performance and
- the ability to work with the newer EJB3/Java EE 5 technologies.
- A full JDK install is not required to run JBoss, but you will need a full JDK
- to build and run the tutorial examples. Before gettings started, make sure you have an appropriate
- JDK installed and that your <literal>JAVA_HOME</literal> environment
- variable is set to the directory where you installed Java. </para>
- <para> The JBoss application server is available as a free download from the JBoss website. (<ulink url="http://www.jboss.org/downloads/index"/>) We provide both binary, source, and Web Start
- distributions. If you are just getting started with JBoss, the easiest way to get going is to use the
- Java Web Start Installer.</para>
- <para>The binary versions are available as a <literal>.zip</literal> archive, j<literal>boss-4.0.4.zip</literal> for example.
- Once it's downloaded, unpack the archive to a suitable location on
- your machine. It should all unpack into a single directory named <literal>jboss-4.0.4</literal>. Of
- course the version number suffix will be different if you are running a later release. Make sure you
- don't use a directory which has any spaces in the path (such as the <literal>Program Files</literal>
- directory on Windows) as this may cause problems. </para>
- <para>The installer versions are available as executable JAR files. The installer can also be launched using
- Web Start by following the <emphasis>Run Installer</emphasis> links from the JBoss AS downloads page.
- Follow the instructions of each
- page of the installer wizard and make sure you choose the <literal>All</literal> option on the
- <emphasis>Server Profile</emphasis> page, the configuration name <literal>default</literal> on the
- <emphasis>Configuration Name</emphasis> page and go ahead and select all the check boxes and then
- set a password for the <literal>admin</literal> account on the <emphasis>JMX Security</emphasis> page.
- The rest of the pages are pretty self explanatory.</para>
- </section>
- <section>
- <title>Starting the Server</title>
- <para> Our first step is to try running the server. You'll find a <literal>bin</literal> directory inside
- the main JBoss directory which contains various scripts. Execute the <literal>run</literal> script
- (<literal>run.bat</literal> if you're on Windows, <literal>run.sh</literal> if you're on Linux, OS
- X, or another UNIX-like system). You should then see the log messages from all the JBoss components as
- they are deployed and started up. The last message (obviously with different values for the time and
- start-up speed) should look like the following.</para>
- <programlisting>
-13:52:00,183 INFO [Server] JBoss (MX MicroKernel)
-[4.0.4.GA (build: CVSTag=JBoss_4_0_4_GA date=200605111311)] Started in 31s:941ms
-
- </programlisting>
- <para> You can verify that the server is running by going the JBoss web server, which is running on port
- 8080. (Make sure you don't have anything else already on your machine using that port) The default page
- has links to a few useful JBoss resources. </para>
- </section>
- <section id="jmxconsoleintro">
- <title>The JMX Console</title>
- <para> You can get a live view of the server by going to the JMX console application at <ulink url="http://localhost:8080/jmx-console"/>
- <footnote><para> Note that on some machines, the name <literal>localhost</literal> won’t resolve properly and
- you should use the local loopback address 127.0.0.1 instead.</para></footnote>. You should see something similar to <xref linkend="webconsole.fig"/>. </para>
- <para> This is the JBoss Management Console which provides a raw view of the JMX MBeans which make up the
- server. You don't really need to know much about these to begin with, but 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>. 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="webconsole.fig">
- <title>View of the JMX Management Console Web Application</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jmx-console.jpg"/>
- </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 and shouldn’t be able to do any permanent damage. </para>
- </section>
- <section>
- <title>Stopping the Server</title>
- <para> To stop the server, you can type Ctrl-C or you can run the shutdown script
- (<literal>shutdown.bat</literal> or <literal>shutdown.sh</literal>) from the <literal>bin</literal>
- directory. Alternatively, you can use the management console. Look for <literal>type=Server</literal>
- under the <literal>jboss.system</literal> domain and invoke the <literal>shutdown</literal> operation.
- </para>
- </section>
- <section>
- <title>Running as a Service</title>
- <para> In a real deployment scenario, you won’t want to stop and start JBoss manually but will want it to
- run in the background as a service or daemon when the machine is booted up. The details of how to do
- this will vary between platforms and will require some system administration knowledge and root
- privileges. </para>
- <para> On Linux or other UNIX-like systems, you will have to install a startup script (or get your system
- administrator to do it). There are examples in the JBoss <literal>bin </literal> directory called
- <literal> jboss_init_redhat.sh</literal> and <literal>jboss_init_suse.sh</literal> which you can
- modify and use. On a Windows system, you can use a utility like Javaservice <footnote><para>Javaservice is freely available from <ulink url="http://www.alexandriasc.com/software/JavaService/index.html"/>. </para></footnote> to manage JBoss as a system service. </para>
- </section>
- </chapter>
- <chapter id="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>
- <section>
- <title>Main Directories</title>
- <para>The binary distribution unpacks into a top-level <literal>jboss-4.0.4</literal> directory. There
- are four sub-directories immediately below this: </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">bin</emphasis>: contains startup and shutdown and other
- system-specific scripts. We’ve already seen the <literal>run</literal> script which starts
- JBoss. </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">client</emphasis>: stores configuration and JAR files which may be
- needed by a Java client application or an external web container. You can select archives as
- required or use <literal>jbossall-client.jar</literal>. </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">docs</emphasis>: contains the XML DTDs used in JBoss for reference
- (these are also a useful source of documentation on JBoss configuration specifics). There
- are also example JCA (Java Connector Architecture) configuration files for setting up
- datasources for different databases (such as MySQL, Oracle, Postgres). </para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">lib</emphasis>: JAR files which are needed to run the JBoss
- microkernel. You should never add any of your own JAR files here.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">server</emphasis>: each of the subdirectories in here is a different
- server configuration. The configuration is selected by passing <literal>-c
- <config-name></literal> to the run script. We’ll look at the standard
- server configurations next.</para>
- </listitem>
- </itemizedlist>
- <figure>
- <title>JBoss Directory Structure</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/directory-structure.jpg"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section>
- <title>Server Configurations</title>
- <para>Fundamentally, the JBoss architecture consists of the JMX MBean server, the microkernel, and a set
- of pluggable component services, the MBeans. This makes it easy to assemble different configurations
- and gives you the flexibility to tailor them to meet your requirements. 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 don’t need to do this to be able to run standard
- J2EE applications though. Everything you need is already there. You don’t need a detailed
- understanding of JMX 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>Within the <literal>server</literal> directory, you will find one or more configuration
- directories depending on which installer packages you choose when installing. If you ran the
- installer, you will only have a <literal>default</literal> configuration (This is because you choose
- a specific configuration in the installer for a setup like EJB3, EJB3 Clustered or J2EE 1.4 Full)
- and so the <literal>default</literal> configuration has all the services for the specific
- configuration you choose. If you downloaded a binary or source version you will see that there are
- three server configurations: <literal> all</literal>, <literal>default</literal> and
- <literal>minimal</literal>, each of which provides a different set of services. Not
- surprisingly, the <emphasis role="bold">default</emphasis> configuration is the one used if you
- don’t specify another one when starting up the server, so that’s the one we were running in the
- previous chapter. The configurations are explained below.</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">minimal</emphasis>: The <literal>minimal</literal> configuration
- contains 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 J2EE technologies.
- This is just the bare server. There is no web container, no EJB or JMS support.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">default</emphasis>: The default configuration consists of the standard
- services needed by most J2EE applications. It does not include the JAXR service, the IIOP
- service, or any of the clustering services.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">all</emphasis>: The <literal>all</literal> configuration starts all
- the available services. This includes the RMI/IIOP and clustering services, which aren’t
- loaded in the default configuration.</para>
- </listitem>
- </itemizedlist>
- <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>default</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 -c <emphasis role="bold">myconfig</emphasis></programlisting>
- <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 configuration. It’s where the log output goes, and it’s where you deploy your
- applications. Let’s take a look at the contents of the <literal>default</literal> server
- configuration directory. If you haven’t tried running the server yet, then do so now, as a few of
- the sub-directories are only created when JBoss starts for the first time. </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis role="bold">conf</emphasis>: This directory contains the
- <literal>jboss-service.xml</literal> file which specifies the core services. Also used
- for additional configuration files for these services.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">data</emphasis>: This directory holds persistent data for services
- intended to survive a server restart. Serveral JBoss services, such as the embedded
- Hypersonic database instance, store data there.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">deploy</emphasis>: The deploy directory contains the hot-deployable
- services (those which can be added to or removed from the running server) and applications
- for the current server configuration. You deploy your application code by placing
- application packages (JAR, WAR and EAR files) in the <literal>deploy</literal> directory.
- The directory is constantly scanned for updates, and any modified components will be
- re-deployed automatically. We’ll look at deployment in more detail later.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">lib</emphasis>: This directory contains JAR files needed by this
- server configuration. You can add required library files here for JDBC drivers etc.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">log</emphasis>: This is where the log files are written. JBoss uses
- the Jakarta log4j package for logging and you can also use it directly in your own
- applications from within the server.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">tmp</emphasis>: The <literal>tmp</literal> directory is used for
- temporary storage by JBoss services. The deployer, for example, expands application archives
- in this directory.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis role="bold">work</emphasis>: This directory is used by Tomcat for compilation of
- JSPs.</para>
- </listitem>
- </itemizedlist>
- <para> The <literal>data</literal>, <literal>log</literal>, <literal>tmp</literal> and
- <literal>work</literal> directories are created by JBoss and won’t exist until you’ve run the server
- at least once.</para>
- <para> We’ve touched briefly on the issue of hot-deployment of services in JBoss so let’s have a look at
- a practical example of this before we go on to look at server configuration issues in more detail.
- Start JBoss if it isn’t already running and take a look in the <literal>deploy</literal> directory
- again (make sure you’re looking at the one in the <literal>default</literal> configuration
- directory). Remove the <literal>mail-service.xml</literal> file and watch the output from the
- server:</para>
- <programlisting>13:10:05,235 INFO [MailService] Mail service 'java:/Mail' removed from JNDI</programlisting>
- <para> Then replace the file and watch the JBoss re-install the service:
- <programlisting>13:58:54,331 INFO [MailService] Mail Service bound to java:/Mail</programlisting>
- It's hot-deployment in action.</para>
- </section>
- </section>
- <section>
- <title>Basic Configuration Issues</title>
- <para> Now that we’ve examined the layout of the JBoss server, we’ll take a look at some of the main
- configuration files and what they’re used for. All paths are relative to the server configuration
- directory (<literal>server/default</literal>, for example).</para>
- <section>
- <title>Core Services</title>
- <para>The core services specified in the <literal>conf/jboss-service.xml</literal> file are started
- first when the server starts up. If you have a look at this file in an editor you'll see MBeans for
- various services including logging, security, JNDI (and the <literal>JNDIView</literal> service that
- we saw earlier). Try commenting out the entry for the <literal>JNDIView</literal> service. Please
- note that because the mbeans definition had nested comments, we had to comment out the mbean in in
- two sections, leaving the original comment as it was. </para>
- <programlisting>
-<![CDATA[<!-- 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’ll 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 <literal>deploy</literal>
- directory, which allows your service to be hot deployable.</para>
- </section>
- <section id="sect.logging">
- <title>Logging Service</title>
- <para> We mentioned already that log4j is used for logging. If you're not familiar with the log4j
- 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/"/>) Logging is controlled from a central
- <literal>conf/log4j.xml</literal>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 (<literal>server.log</literal>
- in the <literal>log</literal> directory). </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 <literal>server.log</literal> file, so all generated
- logging messages will be logged there. If things are going wrong and there doesn’t seem to be any
- useful information in the console, always check the log file to see if there are any debug messages
- which might help you 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,
- <literal>cmp.log</literal>, in order to analyze the generated SQL commands. You would add the
- following code to the <literal>log4j.xml</literal> 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>. This will be useful when we come to
- look at CMP (<xref linkend="cmp"/>).</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
- <literal>cmp.log</literal>. Older files have the date they were written added to the name. You
- will notice that the <literal>log</literal> directory also contains HTTP request logs which are
- produced by the web container.</para>
- </section>
- <section>
- <title>Security Service</title>
- <para>The security domain information is stored in the file <literal>login-config.xml</literal> 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 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, <literal>jboss.xml</literal> and/or
- <literal>jboss-web.xml</literal>. We'll quickly look at how to do this to secure the JMX Console
- application that ship with JBoss. </para>
- <para> We saw the JMX Console briefly in <xref linkend="jmxconsoleintro"/>. 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 had installed JBoss using Web Start 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 <literal>jboss-web.xml</literal> file for the JMX Console, which
- can be found in <literal>deploy/jmx-console.war/WEB-INF/</literal> 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 <literal>web.xml</literal> 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've provided the
- configuration for this in the <literal>conf/login-config.xml</literal>. </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 <literal>conf/props</literal> directory of your server configuration. The usernames and
- passwords are stored in <literal>jmx-console-users.properties</literal> in the directory 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. The existing file creates an
- <literal>admin</literal> user with the password <literal>admin</literal>. You'll want to remove
- that user or change the password to something stronger. </para>
- <para> JBoss will re-deploy the JMX Console whenever you update its <literal>web.xml</literal>. You can
- check the server console to verify that JBoss has seen your changes. If you've configured everything
- correctly and re-deployed the application, the next time you try to access the JMX Console, JBoss
- 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
- shut down your browser and come back in to see the login dialog come back up.</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 <literal>deploy/management/web-console.war</literal>.
- 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>
- <title>Additional Services</title>
- <para> The non-core, hot-deployable services are added to the <literal>deploy</literal> directory. They
- can be either XML descriptor files, <literal>*-service.xml</literal>, 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 a single archive.</para>
- <para>Detailed information on all these services can be found in the <emphasis>JBoss 4 Application
- Server 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>
- <title>The Web Container - Tomcat</title>
- <para>JBoss now comes with Tomcat 5.5 as the default web container. The embedded Tomcat service is the
- expanded SAR <literal>jbossweb-tomcat55.sar</literal> in the <literal>deploy</literal> directory. All
- the necessary jar files needed by Tomcat can be found in there, as well as a <literal>web.xml</literal>
- file which provides a default configuration set for web applications. If you are already familiar with
- configuring Tomcat, have a look at the <literal>server.xml</literal>, which contains a subset of the
- standard Tomcat format configuration information. As it stands, this includes setting up the HTTP
- connector on the default port 8080, an AJP connector on port 8009 (can be used if you want to connect
- via a web server such as Apache) and an example of how to configure an SSL connector (commented out by
- default).</para>
- <para> You shouldn’t need to modify any of this other than for advanced use. If you’ve used Tomcat before as
- a stand-alone server you should be aware that things are a bit different when using the embedded
- service. JBoss is in charge and you shouldn’t need to access the Tomcat directory at all. Web
- applications are deployed by putting them in the JBoss <literal>deploy</literal> directory and logging
- output from Tomcat can be found in the JBoss <literal>log</literal> directory.</para>
- </section>
- </chapter>
- <chapter id="tutorial">
- <title>About the Example Applications</title>
- <section>
- <title>The J2EE Tutorial</title>
- <para> To make it easy if your just starting out with J2EE using JBoss, we will make use of the example
- applications provided in the J2EE tutorial, in particular the <emphasis>Duke’s Bank</emphasis>
- application. The J2EE tutorial explains how to run the applications using the J2EE SDK Reference
- Implementation server. Our aim is to show how to deploy and run those same examples in JBoss, and we do
- so by supplementing the J2EE tutorial where necessary with JBoss-specific configuration information and
- deployment descriptors.</para>
- <para> You can find the J2EE tutorial on-line at <ulink url="http://java.sun.com/j2ee/1.4/docs/tutorial/doc/"/> and the example code can be found downloaded
- from <ulink url="http://java.sun.com/j2ee/1.4/download.html#tutorial"/>. You should download update 7 of
- the tutorial and Unpack/Uncompress the archive in a convenient location. You'll end up with a directory
- named <literal>j2eetutorial14</literal>. You can get the JBoss code on the JBoss documentation page,
- <ulink url="http://www.jboss.org/docs/index"/>. Unpack/Uncompress the JBoss example code into the
- J2EE tutorial directory <literal>j2eetutorial14</literal>. This code provides the JBoss specific
- configuration and deployment descriptors.</para>
- <para> Additionally, we also use the Apache Ant build tool, which you should download and install. You can
- get an up-to-date copy of Ant from <ulink url="http://ant.apache.org/"/>. We recommend using version
- 1.6.2 or later with this tutorial. Ant is almost universally used in Java projects these days so if you
- aren’t already familiar with its use then we recommend you spend some time reading the documentation
- that comes with it and learning the basics of Ant build files. The default file name is
- <literal>build.xml</literal>, and it contains a set of targets which you can use to perform
- automated tasks in your project. Usually all you will have to do is run the Ant command in the directory
- which contains the build file. The default target in the file will perform the necessary operations to
- build and deploy the tutorial applications.</para>
- </section>
- <section>
- <title>What’s Different?</title>
- <para> J2EE technologies are designed so that the code is independent of the server in which the application
- is deployed. The deployment descriptors for EJBs and web applications (<literal>ejb-jar.xml</literal>
- and <literal> web.xml</literal>, respectively) are standard and also do not need to change between
- different J2EE containers. However, there are still one or two things that need to be done in order to
- move the application to JBoss. In particular, we have to supply JBoss-specific descriptors and make sure
- that the database scripts will work.</para>
- <section>
- <title>Container-Specific Deployment Descriptors</title>
- <para>Container-specific information is usually contained in extra XML descriptors which map logical
- information used in the application (such as JNDI names and security role names) to actual values
- which are used in the server. JBoss uses separate files for the EJB and web modules of an
- application, called <literal>jboss.xml</literal> and <literal>jboss-web.xml</literal> respectively.
- There is also a client version of these files which fulfils the same role in a Java client, in
- combination with the J2EE <literal> application-client.xml</literal> descriptor. If
- container-managed persistence (CMP) is being used for entity EJBs, it is also possible to configure
- the JBoss persistence engine through the <literal>jbosscmp-jdbc.xml</literal> file.</para>
- </section>
- <section>
- <title>Database Changes</title>
- <para> The J2EE SDK comes with the Cloudscape database and this is used throughout the tutorials. We
- will be using the Hypersonic database which runs as an embedded service within JBoss.</para>
- <para> In a real-world situation, porting an application to a different databases is rarely
- straightforward, especially if proprietary features such as sequences, stored procedures and
- non-standard SQL are used. For these simple applications, though it is relatively easy. When we look
- at the Duke’s Bank application in the next chapter, you will see that there are only a few minor
- syntax changes required in the database scripts.</para>
- <para> We’ll look at how to configure JBoss to use a different database in <xref linkend="db"/>.</para>
- </section>
- <section>
- <title>Security Configuration</title>
- <para> J2EE defines how you specify security constraints within your application, but doesn’t say how
- the authentication and access control mechanisms are actually implemented by the server or how they
- are configured. As we mentioned earlier, JBoss uses JAAS to provide a pluggable means of
- incorporating different security technologies in your applications. It also comes with a set of
- standard modules for the use of file, database and LDAP-based security information. We’ll start out
- using file-based information as this is the simplest approach.</para>
- </section>
- </section>
- <section>
- <title>J2EE in the Real World</title>
- <para> The examples here are only intended to get you up and running with JBoss and to help you familiarize
- yourself with the basics. The applications definitely aren’t intended to reflect how you should go about
- writing production J2EE software - indeed there is a lot of differing opinion on this subject. Many
- people disagree on the use of EJBs for example, particularly the use of entity beans; the use of
- bean-managed persistence is especially controversial yet is convenient for examples. There is also
- endless debate about the use of different web technologies (it would be safe to say that not everyone
- loves JSPs) and the numerous different Model-2 frameworks that are out there. Struts was one of the
- first and is probably the best known but is not without its critics. We’ve provided some sources at the
- end of this chapter which you can check out for more information.</para>
- <para> If you’re starting out, your best bet is probably to look at some existing open-source projects and
- see how they are structured, and then pick something appropriate for your project.</para>
- <para> Finally, we hope you’ll realize that there’s a lot more depth to JBoss than we can hope to cover here
- and once you’ve worked your way through this basic introduction, we hope you’ll be eager to learn more.
- JBoss is also a continually evolving project with lots of plans for the future. So keep an eye on the
- bleeding-edge version, even if you’re running all your production applications on the stable 4.0
- series.</para>
- </section>
- </chapter>
- <chapter id="dukesbank">
- <title>The Duke’s Bank Application</title>
- <para> Now that you have the server running, we will use the Duke’s Bank example from the J2EE tutorial to
- illustrate how to get an application up and running in JBoss. Duke’s Bank demonstrates a selection of J2EE
- technologies working together to implement a simple on-line banking application. It uses EJBs and web
- components (JSPs and servlets) and uses a database to store the information. The persistence is
- bean-managed, with the entity beans containing the SQL statements which are used to manipulate the data.</para>
- <para> We won’t look in detail at its functionality or comment on the implementation but will concentrate on a
- step-by-step guide to building and deploying it in JBoss.</para>
- <section>
- <title>Building the Application</title>
- <para> You should have already downloaded the J2EE 1.4 tutorial, which includes Duke’s Bank. We’ll go
- through building and deploying the application first and then look at things in a bit more detail.</para>
- <section>
- <title>Preparing the Files</title>
- <para>You should be able to obtain the supplementary JBoss files from the same place as this document.
- The file is packaged as a ZIP archive called <literal>jbossj2ee-src.zip</literal>. Download this and
- unpack it into the <literal>j2eetutorial14</literal> directory, adding to the existing tutorial
- files. All the Duke’s Bank code is in a the <literal>examples/bank</literal> subdirectory. If you've
- unpacked the JBoss extensions correctly, you will see a <literal>jboss-build.xml</literal> there.
- This is our Ant build8 script for the JBoss version of the application. Rather than just overwriting
- the existing <literal>build.xml</literal> file, we’ve used a different name from the default. This
- means that Ant must now be run as <literal>ant -f jboss-build.xml</literal>. </para>
- <para> Before we can build, you'll need to edit the <literal>jboss-build.properties</literal> file in
- the <literal>j2eetutorial14</literal> to point to your JBoss install directory. Set the
- <literal>jboss.home</literal> property to the full path to your JBoss 4.0 installation. If
- you’ve unpacked JBoss 4.0 in the <literal>C:</literal> drive on a windows machine, you would set it
- as follows. </para>
- <programlisting># Set the path to the JBoss directory containing the JBoss application server
-# (This is the one containing directories like "bin", "client" etc.)
-jboss.home=C:/jboss-4.0.4</programlisting>
- </section>
- <section>
- <title>Compiling the Java Source</title>
- <para> At the command line, go to the <literal>bank</literal> directory. All the build commands will be
- run from here. Compilation is pretty straightforward; just type the following command to invoke the
- <literal>compile</literal> Ant target.</para>
- <para>
- <programlisting>ant -f jboss-build.xml compile</programlisting>
- </para>
- <para>If there aren’t any errors, you will find a newly created <literal>build</literal> directory with
- the class files in it.</para>
- </section>
- <section>
- <title>Package the EJBs</title>
- <para> The application has one EJB jar, <literal>bank-ejb.jar</literal>, which contains the code and
- descriptors (<literal>ejb-jar.xml</literal> and <literal>jboss.xml</literal>) for the entity beans
- and associated controller session beans which the clients interact with. The
- <literal>package-ejb</literal> Ant target will create them in the <literal>jar</literal> directory.</para>
- <para>
- <programlisting>ant -f jboss-build.xml package-ejb</programlisting>
- </para>
- </section>
- <section>
- <title>Package the WAR File</title>
- <para>The next target is the web application which provides the front end to allow users to interact
- with the business components (the EJBs). The web source (JSPs, images etc.) is contained in the
- <literal>src/web</literal> directory and is added unmodified to the archive. The Ant
- <literal>war</literal> task also adds a <literal>WEB-INF</literal> directory which 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
- <literal>jboss-web.xml</literal>), class files, (e.g. servlets and EJB interfaces) and extra
- jars and the extra JSP tag-library descriptors required by the web application. The
- <literal>package-web</literal> Ant target builds the web client WAR file.</para>
- <para>
- <programlisting>ant -f jboss-build.xml package-web </programlisting>
- </para>
- </section>
- <section>
- <title>Package the Java Client</title>
- <para>In addition to the web interface, there is a standalone Java client for administering customers
- and accounts. You can build it using the <literal>package-client</literal> Ant target.</para>
- <para>
- <programlisting>ant -f jboss-build.xml package-client</programlisting>
- </para>
- <para> The generated WAR file contains the <literal>application-client.xml</literal> and
- <literal>jboss-client.xml</literal> descriptors as well as the client
- <literal>jndi.properties</literal> file. The client JAR will also be included as an additional
- module in the EAR file and the server.</para>
- </section>
- <section>
- <title>Assembling the EAR </title>
- <para> The EAR file is the complete application, containing the three EJB modules and the web module. It
- must also contain 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. The <literal>assemble-app</literal> Ant target will produce the final file
- <literal>JBossDukesBank.ear</literal>.</para>
- <para>
- <programlisting>ant -f jboss-build.xml assemble-app </programlisting>
- </para>
- </section>
- <section>
- <title>The Database</title>
- <para>Before we can deploy the application, we need to populate the database it will run against. If you
- are writing an application that uses container-managed persistence, you can configure the CMP engine
- to create the tables for you at deployment, but otherwise you will need have to have a set of
- scripts to do the job. This is also a convenient place pre-populating the database with data.</para>
- <section id="X-10278">
- <title>Enabling the HSQL MBean and TCP/IP Connections</title>
- <para> The HSQL database can be run in one of two modes: in-process or client-server (the HSQL
- documentation refers to this as server mode). Since we are going to be running the SQL scripts
- using a tool that connects to the database, we want to make sure the database is running in
- client-server mode and will accept TCP/IP connections. In later versions of JBoss, client-server
- mode is disabled to prevent direct database access, which could be a security risk if the
- default login and password have not been modified. Open the <literal>hsqldb-ds.xml</literal>
- file which you’ll find in the <literal>deploy</literal> directory and which sets up the default
- datasource. Near the top of the file, you’ll find the <literal>connection-url</literal> element.
- Make sure the value is set to <literal>jdbc:hsqldb:hsql://localhost:1701</literal> and that any
- other <literal>connection-url</literal> elements are commented out. </para>
- <programlisting><!-- The jndi name of the DataSource, it is prefixed with java:/ -->
-<!-- Datasources are not available outside the virtual machine -->
-<jndi-name>DefaultDS</jndi-name>
-
-<!-- for tcp connection, allowing other processes to use the hsqldb
-database. This requires the org.jboss.jdbc.HypersonicDatabase mbean. -->
-
-<emphasis role="bold"><connection-url>jdbc:hsqldb:hsql://localhost:1701</connection-url> </emphasis>
-<!-- for totally in-memory db, not saved when jboss stops.
-The org.jboss.jdbc.HypersonicDatabase mbean is unnecessary
-<connection-url>jdbc:hsqldb:.</connection-url>
--->
-<!-- for in-process db with file store, saved when jboss stops. The
-org.jboss.jdbc.HypersonicDatabase is unnecessary
-
-<connection-url>jdbc:hsqldb:${jboss.server.data.dir}/hypersonic/localDB
-</connection-url>
---></programlisting>
- <para> Now scroll down to the bottom of the file, and you should find the MBean declaration for the
- Hypersonic service.</para>
- <programlisting><mbean code="org.jboss.jdbc.HypersonicDatabase" name="jboss:service=Hypersonic">
- <attribute name="Port">1701</attribute>
- <attribute name="Silent">true</attribute>
- <attribute name="Database">default</attribute>
- <attribute name="Trace">false</attribute>
- <attribute name="No_system_exit">true</attribute>
-</mbean>
- </programlisting>
- <para> Make sure this is also uncommented so JBoss will start the database in the correct mode. If
- you choose to delete the other MBean definition, make sure to change the dependency on the
- datasource from <literal>jboss:service=Hypersonic,database=localDB</literal> to
- <literal>jboss:service=Hypersonic</literal>.</para>
- </section>
- <section>
- <title>Creating the Database Schema</title>
- <para>We have supplied scripts to run with HSQL in the <literal>sql</literal> directory. The
- database tasks in the build file will try to contact the HSQL database. If JBoss isn’t already
- running, you should start it now, so that the database is available. </para>
- <para>First we need to create the necessary tables with the <literal>db-create-table</literal>
- target.</para>
- <para>
- <programlisting>ant -f jboss-build.xml db-create-table </programlisting>
- </para>
- <para>Then run the <literal>db-insert</literal> target to populate them with the required data.</para>
- <para>
- <programlisting>ant -f jboss-build.xml db-insert </programlisting>
- </para>
- <para>Finally, if everything has gone according to plan, you should be able to view some of the data
- using the <literal>db-list</literal> target, which lists the transactions for a specific
- account. </para>
- <para>
- <programlisting>ant -f jboss-build.xml db-list </programlisting>
- </para>
- </section>
- <section id="X-22013">
- <title>The HSQL Database Manager Tool</title>
- <para>Just as a quick aside at this point, start up the JMX console application web 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 service is enabled as
- described in <xref linkend="X-10278"/>. </para>
- <figure>
- <title>The HSQL Database Manger </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/hsql-manager.jpg"/>
- </imageobject>
- </mediaobject>
- </figure>
- <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>
- </section>
- </section>
- <section>
- <title>Deploying the Application</title>
- <para>Deploying an application in JBoss is easy. You just have to copy the EAR file to the
- <literal>deploy</literal> directory. The <literal>deploy</literal> target in the build file does
- this for our application.</para>
- <para>
- <programlisting>ant -f jboss-build.xml deploy </programlisting>
- </para>
- <para>You should see something close to the following output from the server:</para>
- <programlisting>18:07:53,923 INFO [EARDeployer] Init J2EE application:
-file:/private/tmp/jboss-4.0.4/server/default/deploy/JBossDukesBank.ear
-18:07:55,024 INFO [EjbModule] Deploying CustomerBean
-18:07:55,103 INFO [EjbModule] Deploying AccountBean
-18:07:55,142 INFO [EjbModule] Deploying TxBean
-18:07:55,403 INFO [EjbModule] Deploying NextIdBean
-18:07:55,439 INFO [EjbModule] Deploying AccountControllerBean
-18:07:55,478 INFO [EjbModule] Deploying CustomerControllerBean
-18:07:55,503 INFO [EjbModule] Deploying TxControllerBean
-18:07:56,950 INFO [EJBDeployer] Deployed: file:/private/tmp/jboss-4.0.4/server/default/t
-mp/deploy/tmp15097JBossDukesBank.ear-contents/bank-ejb.jar
-18:07:57,267 INFO [TomcatDeployer] deploy, ctxPath=/bank, warUrl=file:/private/tmp/jboss
--4.0.4/server/default/tmp/deploy/tmp15097JBossDukesBank.ear-contents/web-client.war/
-18:08:00,784 INFO [EARDeployer] Started J2EE application: file:/private/tmp/jboss-4.0.4/
-server/default/deploy/JBossDukesBank.ear
-</programlisting>
- <para> If there are any errors or exceptions, make a note of the error message and at what point it
- occurs (e.g. during the deployment of a particular EJB, the web application or whatever). Check that
- the EAR is complete and inspect the WAR file and each of 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/bank/main"/>
- </para>
- <para> You will be forwarded to the application login page. As explained in the tutorial, you can login
- with a customer ID of <literal>200</literal> and the password <literal>j2ee</literal>. <xref linkend="dukesbank.fig"/> shows the Duke's Bank application in action. </para>
- <figure id="dukesbank.fig">
- <title>Duke's Bank</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/dukesbank.jpg"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para> If you got an error at this point, check again that you have set up the database correctly as
- described in <xref linkend="X-10278"/>. In particular, check that the
- <literal>connection-url</literal> is correct and that you have populated the database with data.</para>
- <para> You can also run the standalone client application using the <literal>run-client</literal>
- target.</para>
- <programlisting>ant -f jboss-build.xml run-client </programlisting>
- <para> This is a Swing GUI client which allows you to administer the customers and accounts.</para>
- </section>
- </section>
- <section>
- <title>JNDI and Java Clients</title>
- <para> It’s worth taking a brief look at the use of JNDI with standalone clients. The example makes use of
- the J2EE Application Client framework, which introduces the concept of a client-side local environment
- naming context within which JNDI names are resolved with the prefix <literal>java:/comp/env</literal>.
- This is identical to the usage on the server side; the additional level of indirection means you can
- avoid using hard-coded names in the client. The name mapping is effected by the use of the proprietary
- <literal>jboss-client.xml</literal> which resolves the references defined in the standard
- <literal>application-client.xml</literal>. </para>
- <section>
- <title>The jndi.properties File</title>
- <para> One issue with a Java client is how it bootstraps itself into the system, how it manages to
- connect to the correct JNDI server to lookup the references it needs. The information is supplied by
- using standard Java properties. You can find details of these and how they work in the JDK API
- documentation for the <literal>javax.naming.Context</literal> class. The properties can either be
- hard-coded, or supplied in a file named <literal>jndi.properties</literal> on the classpath. The
- file we’ve used is shown below.</para>
- <programlisting>java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
-java.naming.provider.url=jnp://localhost:1099
-java.naming.factory.url.pkgs=org.jboss.naming.client
-j2ee.clientName=bank-client</programlisting>
- <para> The first three are standard properties, which are set up in order to use the JBoss JNDI
- implementation. The <literal>j2ee.clientName</literal> property identifies the client deployment
- information on the server side. The name must match the <literal>jndi-name</literal> specified in
- the <literal>jboss-client.xml</literal> descriptor:</para>
- <programlisting><jboss-client>
- <jndi-name><emphasis role="bold">bank-client</emphasis></jndi-name>
- <ejb-ref>
- <ejb-ref-name>ejb/customerController</ejb-ref-name>
- <jndi-name>MyCustomerController</jndi-name>
- </ejb-ref>
- <ejb-ref>
- <ejb-ref-name>ejb/accountController</ejb-ref-name>
- <jndi-name>MyAccountController</jndi-name>
- </ejb-ref>
-</jboss-client>
-</programlisting>
- <para> Of course if you were only building a simple web application, you wouldn't need to worry about
- remote clients</para>
- </section>
- <section>
- <title>Application JNDI Information in the JMX Console</title>
- <para> While we’re on the subject of JNDI, let’s take a quick look at the JBoss JMX console again and
- see what information it shows about our application. This time click on the
- <literal>service=JNDIView</literal> link and then invoke the <literal>list()</literal>
- operation, which displays the JNDI tree for the server. You should see the EJB modules from Duke’s
- Bank listed near the top and the contents of their private environment naming contexts as well as
- the names the entries are linked to in the server. Here's an abbreviated view:</para>
- <programlisting><![CDATA[
-Ejb Module: bank-ejb.jar
-
-java:comp namespace of the CustomerBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
-
-java:comp namespace of the AccountBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
-
-java:comp namespace of the TxBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
-
-java:comp namespace of the NextIdBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
-
-java:comp namespace of the AccountControllerBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
- | +- ejb (class: org.jnp.interfaces.NamingContext)
- | | +- tx[link -> MyTx] (class: javax.naming.LinkRef)
- | | +- nextId[link -> MyNextId] (class: javax.naming.LinkRef)
- | | +- account[link -> MyAccount] (class: javax.naming.LinkRef)
- | | +- customer[link -> MyCustomer] (class: javax.naming.LinkRef)
-
-java:comp namespace of the CustomerControllerBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
- | +- ejb (class: org.jnp.interfaces.NamingContext)
- | | +- tx[link -> MyTx] (class: javax.naming.LinkRef)
- | | +- nextId[link -> MyNextId] (class: javax.naming.LinkRef)
- | | +- account[link -> MyAccount] (class: javax.naming.LinkRef)
- | | +- customer[link -> MyCustomer] (class: javax.naming.LinkRef)
-
-java:comp namespace of the TxControllerBean bean:
- +- env (class: org.jnp.interfaces.NamingContext)
- | +- ejb (class: org.jnp.interfaces.NamingContext)
- | | +- tx[link -> MyTx] (class: javax.naming.LinkRef)
- | | +- nextId[link -> MyNextId] (class: javax.naming.LinkRef)
- | | +- account[link -> MyAccount] (class: javax.naming.LinkRef)
- | | +- customer[link -> MyCustomer] (class: javax.naming.LinkRef)
-
-java: Namespace
- +- XAConnectionFactory (class: org.jboss.mq.SpyXAConnectionFactory)
- +- DefaultDS (class: org.jboss.resource.adapter.jdbc.WrapperDataSource)
- +- SecurityProxyFactory (class: org.jboss.security.SubjectSecurityProxyFactory)
- +- DefaultJMSProvider (class: org.jboss.jms.jndi.JNDIProviderAdapter)
- +- comp (class: javax.naming.Context)
- +- JmsXA (class: org.jboss.resource.adapter.jms.JmsConnectionFactoryImpl)
- +- ConnectionFactory (class: org.jboss.mq.SpyConnectionFactory)
- +- jaas (class: javax.naming.Context)
- | +- HsqlDbRealm (class: org.jboss.security.plugins.SecurityDomainContext)
- | +- jmx-console (class: org.jboss.security.plugins.SecurityDomainContext)
- | +- jbossmq (class: org.jboss.security.plugins.SecurityDomainContext)
- | +- JmsXARealm (class: org.jboss.security.plugins.SecurityDomainContext)
- +- timedCacheFactory (class: javax.naming.Context)
- Failed to lookup: timedCacheFactory, errmsg=org.jboss.util.TimedCachePolicy
- +- TransactionPropagationContextExporter
- (class: org.jboss.tm.TransactionPropagationContextFactory)
- +- StdJMSPool (class: org.jboss.jms.asf.StdServerSessionPoolFactory)
- +- Mail (class: javax.mail.Session)
- +- TransactionPropagationContextImporter
- (class: org.jboss.tm.TransactionPropagationContextImporter)
- +- TransactionManager (class: org.jboss.tm.TxManager)]]>
-</programlisting>
- <para> Note that these objects are created on demand, so the <literal>dukesbank</literal> entry will
- only appear if you have configured the application to use the <literal>dukesbank</literal> domain
- and have tried to log in to the application.</para>
- </section>
- </section>
- <section>
- <title>Security</title>
- <para>When you first access Duke's Bank, you are prompted for an account number and password using a simple
- login form. J2EE security always requires some configuration in the application server. The
- authentication logic which decides whether a login succeeds or fails is outside the scope of the J2EE
- specification. The actual authentication mechanism is controlled by the security domain that the
- application is linked to. In this section we will see how the security domain is configured for Duke's
- Bank. </para>
- <section>
- <title>Configuring the Security Domain</title>
- <para>The standard J2EE security declarations for the web and EJB tiers are declared in the
- <literal>web.xml</literal> and <literal>ejb-jar.xml</literal> files, respectively. However, the
- JBoss security configuration needs to go in the companion JBoss deployment descriptors.</para>
- <para>The configuration is quite straightforward. In both cases, a single
- <literal>security-domain</literal> element is all that is needed. The following fragment from
- <literal>jboss-web.xml</literal> illustrates the usage in the web application. </para>
- <programlisting><jboss-web>
- <security-domain>java:/jaas/dukesbank</security-domain>
- ...
-</jboss-web></programlisting>
- <para>The configuration looks the same on the EJB side. The following <literal>jboss.xml</literal> file
- shows how this works.</para>
- <programlisting><jboss>
- <security-domain>java:/jaas/dukesbank</security-domain>
-
- <enterprise-beans>
- ...
- </enterprise-beans>
-</jboss> </programlisting>
- <para>In both cases, we've linked to a security domain located by the
- <literal>java:/jaas/dukesbank</literal> JNDI name. All security domains are bound under the
- <literal>java:/jaas</literal> context, so we would really just say that the application is using
- the <literal>dukesbank</literal> security domain. </para>
- <para>Security domains are configured by a corresponding application policy in the
- <literal>conf/login-config.xml</literal> file. But, if you look, you won't see a
- <literal>dukesbank</literal> policy. When JBoss doesn't find a matching policy, it defaults to
- using the <literal>other</literal> policy, which is shown below. </para>
- <programlisting><application-policy name="other">
- <authentication>
- <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
- flag="required" />
- </authentication>
-</application-policy></programlisting>
- <para>The login module used here uses local properties files for authentication. There are two files;
- one provides usernames and passwords, and other provides the roles assigned to the users. The
- following listing shows the <literal>users.properties</literal> file used for Duke's Bank. </para>
- <programlisting># users.properties file for use with the UsersRolesLoginModule
-# Format is:
-#
-# username=password
-
-200=j2ee</programlisting>
- <para>The format is simple. Each line takes the form <literal>username=password</literal>. So, this file
- contains one user named <literal>200</literal> whose password is <literal>j2ee</literal>. That is
- the name and password you used to access the application. Try changing the password and deploying
- the application again.</para>
- <para>J2EE application security isn't driven only by a username and password. Users are assigned to
- roles, and the application can only only give access to a user based on that user's roles. Duke's
- bank can only be accessed by users that are customers, as indicated by the
- <literal>bankCustomer</literal> role. The following listing shows the
- <literal>roles.properties</literal> file used to assign the <literal>bankCustomer</literal> role to
- the user. </para>
- <programlisting># A roles.properties file for use with the UsersRolesLoginModule
-#
-# Format is
-#
-# username=role1,role2,role3
-
-200=bankCustomer</programlisting>
- <para> To complete the application, you should actually define the <literal>dukesbank</literal> security
- domain rather than letting the server fall back to the default security domain. All you need to do
- is add the following policy to the <literal>conf/login-config.xml</literal> file. </para>
- <programlisting><application-policy name="dukesbank">
- <authentication>
- <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
- flag="required" />
- </authentication>
-</application-policy></programlisting>
- <para>You will, unfortunately, need to restart JBoss to make the changes to
- <literal>login-config.xml</literal> visible.</para>
- </section>
- <section>
- <title>Security Using a Database</title>
- <para>As you can well imagine, password files are not a very flexible method for maintaining security.
- In a real project you will want to use a more sophisticated approach to authentication. Since the
- user accounts are in the database, it would be very convenient to be able to store the passwords
- there too. We'll do that now.</para>
- <para>JBoss comes with a login module called <literal>DatabaseServerLoginModule</literal> that can use
- authentication information stored in a relational database. The following database schema mirrors
- the information in the properties files. </para>
- <programlisting>CREATE TABLE Users(username VARCHAR(64) PRIMARY KEY, passwd VARCHAR(64))
-CREATE TABLE UserRoles(username VARCHAR(64), userRoles VARCHAR(32))
-
-INSERT INTO Users VALUES ('200','j2ee')
-INSERT INTO UserRoles VALUES ('200','bankCustomer')</programlisting>
- <para>You can use they Hypersonic database manager we looked at earlier to create these tables and load
- the data. Once you have the data, we'll need to configure the
- <literal>DatabaseServerLoginModule</literal>. The login module requires the appropriate queries to
- retrieve the password and roles for a particular user and a reference to the datasource that those
- queries should be issued on. For Duke's Bank, the following configuration should be added to
- <literal>login-config.xml</literal>. </para>
- <programlisting><application-policy name="dukesbank">
- <authentication>
- <login-module code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
- flag="required">
- <module-option name="dsJndiName">java:/DefaultDS</module-option>
- <module-option name="principalsQuery">
- select passwd from Users where username=?
- </module-option>
- <module-option name="rolesQuery">
- select userRoles,'Roles' from UserRoles where username=?
- </module-option>
- </login-module>
- </authentication>
-</application-policy> </programlisting>
- <para> The query to retrieve the password is straightforward. However, there is an additional field with
- value <literal>Roles</literal> in the roles query. This is the role group. It allows you to store
- additional roles (for whatever purpose) classified by the role group. The ones which will affect
- JBoss permissions are expected to have the value <literal>Roles</literal>. In this simple example we
- only have a single set of roles in the database and no role group information. The details aren't
- critical to understand here. Just remember that the roles query should return the text
- <literal>Roles</literal> in the second column. </para>
- <para>You will need to restart JBoss for changes to <literal>login-config.xml</literal> to take effect.
- Do that and access Duke's bank. </para>
- </section>
- <section>
- <title>Using Password Hashing</title>
- <para> The login modules we’ve used so far all have support for password hashing; rather than storing
- passwords in plain text, a one-way hash of the password is stored (using an algorithm such as MD5)
- in a similar fashion to the <literal>/etc/passwd</literal> file on a UNIX system. This has the
- advantage that anyone reading the hash won’t be able to use it to log in. However, there is no way
- of recovering the password should the user forget it, and it also makes administration slightly more
- complicated because you also have to calculate the password hash yourself to put it in your security
- database. This isn’t a major problem though. To enable password hashing in the database example
- above, you would add the following module options to the configuration</para>
- <programlisting><module-option name="hashAlgorithm">MD5</module-option>
-<module-option name="hashEncoding">base64</module-option></programlisting>
- <para> This indicates that we want to use MD5 hashes and use base64 encoding to covert the binary hash
- value to a string. JBoss will now calculate the hash of the supplied password using these options
- before authenticating the user, so it’s important that we store the correctly hashed information in
- the database. If you’re on a UNIX system or have Cygwin installed on Windows, you can use
- <literal>openssl</literal> to hash the value.</para>
- <programlisting>$ echo -n "j2ee" | openssl dgst -md5 -binary | openssl base64
-glcikLhvxq1BwPBZN0EGMQ==</programlisting>
- <para>You would then insert the resulting string, <literal>glcikLhvxq1BwPBZN0EGMQ==</literal>, into the
- database instead of the plaintext password, <literal>j2ee</literal>. If you don’t have this option,
- you can use the class <literal>org.jboss.security.Base64Encoder</literal> which you’ll find in the
- <literal>jbosssx.jar</literal> file. </para>
- <programlisting>$ java -classpath ./jbosssx.jar org.jboss.security.Base64Encoder j2ee MD5
-[glcikLhvxq1BwPBZN0EGMQ==]</programlisting>
- <para> With a single argument it will just encode the given string but if you supply the name of a
- digest algorithm as a second argument it will calculate the hash of the string first.</para>
- </section>
- </section>
- </chapter>
- <chapter id="ws">
- <title>J2EE Web Services</title>
- <para>From the start, web services have promised genuine interoperability by transmitting XML data using
- platform and language-independent protocols such as SOAP over HTTP. While the early days of multiple
- competing standards and general developer confusion may have made this more of a dream than a reality, web
- services have matured and standardized enough to have been incorporated into the J2EE 1.4 specification. </para>
- <para>Keeping with the spirit of this guide, we'll assume you have some experience with web services already. If
- you don't, we would recommend you do some reading in advance. A good place to start would be <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossWS"/> on the JBoss wiki, which covers web services on
- JBoss in more depth. We also recommend <emphasis>J2EE Web Services</emphasis> by Richard Monson-Haefel for
- more general coverage of J2EE web services. </para>
- <section>
- <title>Web services in JBoss</title>
- <para>JBossWS is the JBoss module responsible for providing web services in JBoss 4.0, replacing the
- previous JBoss.NET package. Like its predecessor, it is also based on Apache Axis (<ulink url="http://ws.apache.org/axis"/>). However, JBossWS provides the complete set of J2EE 1.4 web
- services technologies, including SOAP, SAAJ, JAX-RPC and JAXR. </para>
- <para>J2EE web services provides for two types of endpoints. If you think of a web service as a
- platform-independent invocation layer, then the endpoint is the object you are exposing the operations
- of and invoking operations on. Naturally, J2EE web services support exposing EJBs as web services, but
- only stateless session beans can be used. That makes sense given the stateless nature of web services
- requests. Additionally, J2EE web services provide for JAX-RPC service endpoints, (JSEs) which are
- nothing more than simple Java classes. We'll only be working with EJB endpoints in this example. </para>
- </section>
- <section>
- <title>Duke’s Bank as a Web Service</title>
- <para>We'll continue working with the Duke's Bank application from <xref linkend="dukesbank"/> and create a
- simple web service for querying accounts and balances. The <literal>AccountController</literal> session
- bean provides this functionality to the Duke's Bank web application. Unfortunately the application uses
- stateful session beans as its external interface, so we can't expose the
- <literal>AccountController</literal> session bean directly. Instead, we'll create a new stateless
- session bean, the <literal>TellerBean</literal>, which will provide a more suitable web service
- endpoint. </para>
- <para>Before we start, make sure that you have built and deployed Duke's Bank according to the instructions
- in <xref linkend="dukesbank"/>. As with that example, we'll be working from the
- <literal>examples/bank</literal> directory. Although <literal>TellerBean</literal> will have already
- been compiled when you deployed Duke's Bank, you'll need to remember to invoke the
- <literal>compile</literal> target to compile any changes you might make. </para>
- <programlisting>ant -f jboss-build.xml compile</programlisting>
- <para>The magic of J2EE is in the deployment descriptors. We've seen how to deploy session beans already.
- Deploying a session bean as a web service is as simple as adding a <literal>service-endpoint</literal>
- element to the session bean definition in <literal>ejb-jar.xml</literal>. The service-endpoint specifies
- the class that provides the interface corresponding to the methods on the session bean being exposed as
- a web service.</para>
- <programlisting><session>
- <ejb-name>TellerBean</ejb-name>
- <service-endpoint>com.jboss.ebank.TellerEndpoint</service-endpoint>
- <ejb-class>com.jboss.ebank.TellerBean</ejb-class>
- <session-type>Stateless</session-type>
- <transaction-type>Container</transaction-type>
- <ejb-ref>
- <ejb-ref-name>ejb/account</ejb-ref-name>
- <ejb-ref-type>Session</ejb-ref-type>
- <home>com.sun.ebank.ejb.account.AccountControllerHome</home>
- <remote>com.sun.ebank.ejb.account.AccountController</remote>
- </ejb-ref>
- <security-identity>
- <run-as>
- <role-name>bankCustomer</role-name>
- </run-as>
- </security-identity>
-</session></programlisting>
- <para> You might have noticed that we didn't declare a home or remote interface for
- <literal>TellerBean</literal>. If your session bean is only accessed by the web services interface, you
- don't need one, so we've left them out here. Instead, we've declared the
- <literal>TellerEndpoint</literal> class as our endpoint interface. Our web service interface exposes two
- operations, both of which map onto the equivalent methods on <literal>TellerBean</literal>. </para>
- <programlisting>public interface TellerEndpoint
- extends Remote
-{
- public AccountList getAccountsOfCustomer(String customerId)
- throws RemoteException;
-
- public BigDecimal getAccountBalance(String accountID)
- throws RemoteException;
-}</programlisting>
- <para>The required web services deployment descriptors (WSDL file, JAX-RPC mapping file, webservices deployment
- descriptor) can be generated using the wstools generator that comes with JBossWS.
- The <literal>wstools</literal>
- target runs the generator. </para>
- <programlisting>ant -f jboss-build.xml wstools</programlisting>
- <para>The wstools program uses the <literal>wstools-config.xml</literal> file to guide the generation
- project.</para>
- <programlisting><configuration xmlns="http://www.jboss.org/jbossws-tools">
- <java-wsdl>
- <service name="TellerService" style="rpc" endpoint="com.jboss.ebank.TellerEndpoint"/>
- <namespaces target-namespace="http://ebank.jboss.com/teller"
- type-namespace="http://ebank.jboss.com/teller/types"/>
- <mapping file="jaxrpc-mapping.xml"/>
- <webservices ejb-link="TellerBean"/>
- </java-wsdl>
-</configuration></programlisting>
- <para>The following artificats are generated by this configuration.</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="bold">TellerService.wsdl</emphasis>: This is the WSDL definition that describes the web service.
- Some values, like the SOAP address, will be filled in at runtime by JBossWS.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">jaxrpc-mapping.xml</emphasis>: This mapping file describes the mapping
- between the WSDL types and the underlying Java implementation. Since the client program happens to use
- the same Java classes, we will re-use this file for the client-side mappings.</para>
- </listitem>
- <listitem>
- <para><emphasis role="bold">webservices.xml</emphasis>: This file declares the webservice. It links
- the endpoint to a server-side component (in this case a session bean) and points to the location of the
- related deployment files.</para>
- </listitem>
- </itemizedlist>
- <para>This web service is a simple session bean, so deploying it only requires us to package up the bean and
- the associated deployment descriptors into an EJB JAR file. The <literal>package-ws</literal> task
- accomplishes this, and the <literal>deploy-ws</literal> target deploys the EJB JAR to JBoss.</para>
- <programlisting>ant -f jboss-build.xml package-ws
-ant -f jboss-build.xml deploy-ws</programlisting>
- <para> Once the service is deployed you can view the WSDL (Web Service Description Language) for it by
- browsing to the URL <ulink url="http://localhost:8080/bankws-ejb/TellerService?wsdl"/>. In this example
- we generate the WSDL, but it would also have been possible to write the WSDL for the service by hand and
- then generate a Java endpoint interface for it using <literal>wsdl2java</literal>, which is also
- provided with JBossWS.</para>
- </section>
- <section>
- <title>Running the Web Service Client</title>
- <para> We’ve also supplied a Java client which accesses the web service from a non-J2EE environment. </para>
- <programlisting>public class WSClient {
- public static void main(String[] args)
- throws Exception
- {
- URL url =
- new URL("http://localhost:8080/bankws-ejb/TellerBean?wsdl");
-
-
- QName qname = new QName("http://ebank.jboss.com/teller",
- "TellerService");
-
- File mapping = new File("dd/ws/jaxrpc-mapping.xml");
-
- ServiceFactoryImpl factory = new ServiceFactoryImpl();
- Service service = factory.createService(url, qname, mapping.toURL());
-
- TellerEndpoint endpoint = (TellerEndpoint)
- service.getPort(TellerEndpoint.class);
-
- String customer = "200";
- System.out.println("Customer: " + customer);
-
- AccountList accounts = endpoint.getAccountsOfCustomer(customer);
- String[] ids = accounts.getAccounts();
- for (int i=0; i<ids.length; i++) {
- System.out.println("account[" + ids[i] + "] " +
- endpoint.getAccountBalance(ids[i]));
- }
- }
-}</programlisting>
- <para>The client can be run using the <literal>run-ws</literal> target.</para>
- <programlisting>ant -f jboss-build.xml run-ws</programlisting>
- <para>The client will display the balance for each account belonging to the given customer.</para>
- <programlisting> [java] Customer: 200
- [java] account[5005] 3300.00
- [java] account[5006] 2458.32
- [java] account[5007] 220.03
- [java] account[5008] 59601.35</programlisting>
- </section>
- <section>
- <title>Monitoring webservices requests</title>
- <para>When processing web services requests, it is often useful to be able and observe the actual messages
- being passed between the client and the server. JBossWS logs this information in the
- <literal>org.jboss.ws.server.ServiceEndpoint</literal> category. To enable web services
- logging, add the following debug category to the <literal>log4j.xml</literal> file: </para>
- <programlisting><category name="org.jboss.ws.server.ServiceEndpoint">
- <priority value="DEBUG"/>
-</category></programlisting>
- <para>When enabled, all SOAP requests and responses will be logged to the <literal>server.log</literal>
- file. Here is a log of a call to the <literal>getAccountsOfCustomer</literal> method.</para>
- <programlisting>
-2005-05-16 17:50:43,479 DEBUG [org.jboss.axis.transport.http.AxisServlet]
-<?xml version="1.0" encoding="UTF-8"?>
-<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
- xmlns:xsd="http://www.w3.org/2001/XMLSchema"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <soapenv:Body>
- <ns1:getAccountsOfCustomer xmlns:ns1="http://ebank.jboss.com">
- <in0>200</in0>
- </ns1:getAccountsOfCustomer>
- </soapenv:Body>
-</soapenv:Envelope>
-...2006-05-23 14:51:51,710 DEBUG [org.jboss.ws.server.ServiceEndpoint] Outgoing SOAPMessage
-<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
- <env:Header/>
- <env:Body>
- <ns1:getAccountsOfCustomerResponse xmlns:ns1='http://ebank.jboss.com/teller'>
- <result xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
- <accounts>5005</accounts>
- <accounts>5006</accounts>
- <accounts>5007</accounts>
- <accounts>5008</accounts>
- </result>
- </ns1:getAccountsOfCustomerResponse>
- </env:Body>
-</env:Envelope></programlisting>
- </section>
- </chapter>
- <chapter id="mdb">
- <title>JMS and Message-Driven Beans</title>
- <para> One thing that’s missing from the Duke’s Bank application is any use of JMS messaging, so we’ll work
- through the tutorial example on Message Driven Beans (MDBs) to see how to use messaging in JBoss. We’ll
- assume you’re already familiar with general JMS and MDB concepts. The J2EE tutorial code for the MDB is in
- <literal>j2eetutorial14/examples/ejb/simplemessage</literal>. We’ve supplied a
- <literal>jboss-build.xml</literal> file in the <literal>simplemessage</literal> directory which will allow
- you to build the example from scratch and run it in JBoss.</para>
- <para> The example code is very simple. There are only two classes, one for the client and one for the bean
- (unlike normal EJBs, MDBs don’t need any interfaces). The client publishes messages to a JMS Queue and the
- MDB handles them via its standard <literal>onMessage</literal> method. The messages are all of type
- <literal>javax.jms.TextMessage</literal> and the bean simply prints out the text contained in each
- message. </para>
- <para> The only container-specific tasks required are setting up the Queue in JBoss, and configuring the MDB to
- accept messages from it.</para>
- <section>
- <title>Building the Example</title>
- <section>
- <title>Compiling and Packaging the MDB and Client</title>
- <para>To compile the files, invoke the <literal>compile-mdb</literal> target from the
- <literal>simplemessage</literal> directory.</para>
- <programlisting>ant -f jboss-build.xml compile-mdb</programlisting>
- <para> Then run the following targets to produce archives for the bean and the client and a combined EAR
- file in the <literal>jar</literal> directory. </para>
- <programlisting>ant -f jboss-build.xml package-mdb
-ant -f jboss-build.xml package-mdb-client
-ant -f jboss-build.xml assemble-mdb</programlisting>
- <para> We’ve retained the same layout we used in the Duke’s Bank build, with a <literal>dd</literal>
- directory containing the deployment descriptors and the <literal>jar</literal> directory containing
- the archives produced by the build. </para>
- <section>
- <title>Specifying the Source Queue for the MDB</title>
- <para> As with other container-specific information, the queue name for the MDB is specified in the
- <literal>jboss.xml</literal> file:</para>
- <programlisting><jboss>
- <enterprise-beans>
- <message-driven>
- <ejb-name>SimpleMessageBean</ejb-name>
- <destination-jndi-name>queue/MyQueue</destination-jndi-name>
- </message-driven>
- </enterprise-beans>
-</jboss> </programlisting>
- <para> The MDB will receive messages from the queue with JNDI name
- <literal>queue/MyQueue</literal>.</para>
- </section>
- </section>
- </section>
- <section>
- <title>Deploying and Running the Example</title>
- <para> To deploy the MDB, copy the <literal>SimpleMessage.ear</literal> file to the JBoss deploy directory.
- The <literal>deploy-mdb</literal> target does this:</para>
- <programlisting>ant -f jboss-build.xml deploy-mdb</programlisting>
- <para> A successful deployment should look something like this:</para>
- <programlisting>
-08:20:08,188 INFO [EARDeployer] Init J2EE application:
-file:/tmp/jboss-4.0.4.GA/server/default/deploy/SimpleMessage.ear
-08:20:08,370 INFO [EjbModule] Deploying SimpleMessageEJB
-08:20:08,565 INFO [ClientDeployer] Client ENC bound under: SimpleMessageClient
-08:20:08,712 WARN [JMSContainerInvoker] Could not find the queue
-destination-jndi-name=queue/MyQueue
-08:20:08,719 WARN [JMSContainerInvoker] destination not found: queue/MyQueue
-reason: javax.naming.NameNotFoundException: MyQueue not bound
-08:20:08,719 WARN [JMSContainerInvoker] creating a new temporary destination: queue/MyQueue
-08:20:08,772 INFO [MyQueue] Bound to JNDI name: queue/MyQueue
-08:20:08,952 INFO [EJBDeployer] Deployed:
-file:/tmp/jboss-4.0.4.GA/server/default/tmp/deploy/tmp51464SimpleMessage.ear-contents
-/simplemessage.jar
-08:20:08,996 INFO [EARDeployer] Started J2EE application:
-file:/tmp/jboss-4.0.4.GA/server/default/deploy/SimpleMessage.ear
- </programlisting>
- <para> If you look more closely at this, you will see warnings that the message queue specified in the
- deployment doesn’t exist. In this case JBoss will create a temporary one for the application and bind it
- under the supplied name. You can check it exists using the <literal>JNDIView</literal> MBean again. Look
- under the <literal>global</literal> JNDI namespace. We’ll look at how to explicitly create JMS
- destinations below.</para>
- <para>Run the client with the <literal>run-mdb</literal> Ant target.</para>
- <programlisting>ant -f jboss-build.xml run-mdb</programlisting>
- <para>You should see output in both the client and server windows as they send and receive the messages
- respectively.</para>
- </section>
- <section>
- <title>Managing JMS Destinations</title>
- <para> As with most things in JBoss, JMS Topics and Queues are implemented using MBeans. There are two ways
- you can create them: you can add MBean declarations to the appropriate configuration file, or you can
- create them dynamically using the JMX Console. However, if you use the latter method, they won’t survive
- a server restart.</para>
- <section>
- <title>The jbossmq-destinations-service.xml File</title>
- <para> You’ll find this file in the <literal> jms</literal> directory inside the
- <literal>deploy</literal> directory. It contains a list of JMS destinations and sets up a list of
- test topics and queues which illustrate the syntax used. To add the queue for our example, you would
- simply add the following MBean declaration to the file.</para>
- <programlisting><mbean code="org.jboss.mq.server.jmx.Queue"
- name="jboss.mq.destination:service=Queue,name=MyQueue">
-</mbean> </programlisting>
- </section>
- <section>
- <title>Using the DestinationManager from the JMX Console</title>
- <para> With JBoss running, bring up the JMX Console in your browser and look for the section labelled
- <literal>jboss.mq</literal> in the main agent view. Click on the link which says
- <literal>service=DestinationManager</literal>. The <literal>DestinationManager</literal> MBean
- is the main JMS service in JBoss and you can use it to create and destroy queues and topics at
- runtime. Look for the operation called <literal>createQueue</literal>. There will be two operations
- by that name, both of which take a different number of arguments. Look for the one that takes only
- one argument. That argument is the name of the queue. This takes two parameters. Enter
- <literal>MyQueue</literal> and click the <literal>Invoke</literal> button. This will create a
- queue bound under the JNDI name <literal>queue/MyQueue</literal>, assuming it doesn't already
- exist.</para>
- </section>
- <section>
- <title>Administering Destinations</title>
- <para>You can access the attributes and operations that the MBeans representing a queue or topic exposes
- via JMX. Look at the main JMX Console view again and you’ll find a separate
- <literal>jboss.mq.destination</literal> section which should contain an entry for our Queue (no
- matter how it was created). Click on this and you’ll see the attributes for the queue. One of them
- is <literal>QueueDepth</literal>, which is the number of messages which are currently on the queue.</para>
- <para> As an exercise, you can try temporarily stopping the delivery of messages to the MDB. Locate the
- section called <literal>jboss.j2ee</literal> in the JMX console and you should find an MBean listed
- there which is responsible for invoking your MDB. The name will be
- <literal>binding=message-driven-bean, jndiName=local/SimpleMessageEJB,
- plugin=invoker,service=EJB</literal>
- </para>
- <para> You can start and stop the delivery of messages using the corresponding MBean operations which it
- supports. Invoke the <literal>stopDelivery()</literal> method, and then run the client a few times.
- You will see the <literal>QueueDepth</literal> increase as the messages accumulate. If you re-start
- message delivery, with the <literal>startDelivery()</literal> method, you should see all the
- messages arriving at once.</para>
- </section>
- </section>
- </chapter>
- <chapter id="cmp">
- <title>Container-Managed Persistence</title>
- <para>In this chapter we’ll use the <literal>RosterApp</literal> example application from the J2EE tutorial to
- explore container-managed persistence in a bit more depth than we did with Duke's Bank. You should read
- through the CMP tutorial notes before proceeding so that you have a good overview of the beans and their
- relationships.</para>
- <para> You’ll find the code in <literal>j2eetutorial14/examples/ejb/cmproster</literal>. The application
- implements a player roster for sports teams playing in leagues. There are three entity beans
- <literal>PlayerEJB</literal>, <literal>TeamEJB</literal> and <literal>LeagueEJB</literal> and a single
- session bean, <literal>RosterEJB</literal>, which manipulates them and provides the business methods
- accessed by the client application. Only the session bean has a remote interface.</para>
- <section>
- <title>Building the Example</title>
- <para> The EJBs are packaged in two separate JAR files, one for the entity beans and one for the session
- bean. As before, we’ve provided an <literal>ejb-jar.xml</literal> file for each one. You don’t need a
- <literal>jboss.xml</literal> file for this example. All the CMP information needed to build the
- database schema is included in the standard descriptor. We’ll look at JBoss-specific customization
- later.</para>
- <para> To compile the code, first make sure you’re in the <literal>examples</literal> directory. Running the
- <literal>compile-cmp</literal> target will compile all the code in one go.</para>
- <para>
- <programlisting>ant -f jboss-build.xml compile-cmp</programlisting>
- </para>
- <para>Run the following <literal>package-team</literal> to build the team JAR file which contains the entity
- beans.</para>
- <para>
- <programlisting>ant -f jboss-build.xml package-team </programlisting>
- </para>
- <para> The <literal>package-roster</literal> target builds the <literal>roster</literal> JAR. </para>
- <para>
- <programlisting>ant -f jboss-build.xml package-roster</programlisting>
- </para>
- <para> Both JAR files will be created in the <literal> jar</literal> directory. Build the client jar using
- the <literal>package-roster-client</literal> target.</para>
- <para>
- <programlisting>ant -f jboss-build.xml package-roster-client </programlisting>
- </para>
- <para> Finally assemble the RosterApp EAR using the <literal>assemble-roster</literal> target.</para>
- <para>
- <programlisting>ant -f jboss-build.xml assemble-roster</programlisting>
- </para>
- </section>
- <section id="X-91007">
- <title>Deploying and Running the Application</title>
- <para>Deploying the application is done with the <literal>deploy-cmp</literal> Ant target. </para>
- <para>
- <programlisting>ant -f jboss-build.xml deploy-cmp</programlisting>
- </para>
- <para> Copy the <literal>RosterApp.ear</literal> file from the <literal>jar</literal> directory to the JBoss
- <literal>deploy</literal> directory (or run Ant with the <literal>deploy-cmp</literal> target) and
- check the output from the server.</para>
- <programlisting>13:49:11,044 INFO [EARDeployer] Init J2EE application: file:/private/tmp/jboss-4.0.4/serv
-er/default/deploy/RosterApp.ear
-13:49:11,884 INFO [EjbModule] Deploying RosterBean
-13:49:13,366 INFO [EjbModule] Deploying TeamBean
-13:49:13,751 INFO [EjbModule] Deploying LeagueBean
-13:49:13,842 INFO [EjbModule] Deploying PlayerBean
-13:49:14,377 INFO [EJBDeployer] Deployed: file:/private/tmp/jboss-4.0.4/server/default/tm
-p/deploy/tmp29312RosterApp.ear-contents/roster-ejb.jar
-13:49:17,931 INFO [EJBDeployer] Deployed: file:/private/tmp/jboss-4.0.4/server/default/tm
-p/deploy/tmp29312RosterApp.ear-contents/team-ejb.jar
-13:49:17,991 INFO [EARDeployer] Started J2EE application: file:/private/tmp/jboss-4.0.4/s
-erver/default/deploy/RosterApp.ear</programlisting>
- <para> There are a few things worth noting here. In the Duke’s Bank application, we specified the JNDI name
- we wanted a particular <literal>EJBHome</literal> reference to be bound under in the
- <literal>jboss.xml</literal> file. Without that information JBoss will default to using the EJB name. So
- the session bean is bound under <literal>RosterBean</literal> and so on. You can check these in the JMX
- Console as before.</para>
- <para>The first time you deploy the application, JBoss will automatically create the required database
- tables. If you take a look at the database schema using the Hypersonic database manager (see <xref linkend="X-22013"/>), you will see that JBoss has created one table for each entity bean and an
- addition join table needed to handle the many-to-many relationship between players and teams. The table
- and column names correspond the names of the entity beans and their attributes. If these names are
- suitable, you won't need to further refine the schema. In this case we've had to manually map the
- <literal>position</literal> field on <literal>PlayerBean</literal> to a column named
- <literal>pos</literal> because the default column name, <literal>position</literal>, is a reserved token
- in HSQL. The schema is in the <literal>jbosscmp-jdbc.xml</literal> file.</para>
- <para>Note that if you increase the logging level for the <literal>org.jboss.ejb.plugins.cmp</literal>
- package (<xref linkend="sect.logging"/>) to <literal>DEBUG</literal>, the engine will log the SQL
- commands which it is executing. This can be useful in understanding how the engine works and how the
- various tuning parameters affect the loading of data.</para>
- <section>
- <title>Running the Client</title>
- <para> The client performs some data creation and retrieval operations via the session bean interface.
- It creates leagues, teams and players which will be inserted into the database. The session bean
- methods it calls to retrieve data are mainly wrappers for EJB finder methods. The command to run the
- client and the expected output are shown below.</para>
- <programlisting>$ ant -f jboss-build.xml run-cmp
-Buildfile: jboss-build.xml
-
-run-cmp:
-[java] P10 Terry Smithson midfielder 100.0
-[java] P6 Ian Carlyle goalkeeper 555.0
-[java] P7 Rebecca Struthers midfielder 777.0
-[java] P8 Anne Anderson forward 65.0
-[java] P9 Jan Wesley defender 100.0
-
-[java] T1 Honey Bees Visalia
-[java] T2 Gophers Manteca
-[java] T5 Crows Orland
-
-[java] P2 Alice Smith defender 505.0
-[java] P22 Janice Walker defender 857.0
-[java] P25 Frank Fletcher defender 399.0
-[java] P5 Barney Bold defender 100.0
-[java] P9 Jan Wesley defender 100.0
-
-[java] L1 Mountain Soccer
-[java] L2 Valley Basketball </programlisting>
- <para>The client doesn’t remove the data, so if you run it twice it will fail because it tries to create
- entities which already exist. If you want to run it again you’ll have to remove the data. The
- easiest way to do this (if you’re using HSQL) is to delete the contents of the
- <literal>data/hypersonic</literal> directory in the server configuration you are using (assuming
- you don’t have any other important data in there) and restart the server. We’ve also provided a SQL
- script to delete the data. You can run it with the <literal>db-delete</literal> target.</para>
- <programlisting>ant -f jboss-build.xml db-delete</programlisting>
- <para> You could also use SQL commands directly through the HSQL Manager tool to delete the data.</para>
- </section>
- </section>
- <section>
- <title>CMP Customization</title>
- <para> There are many ways you can further customize the CMP engine’s behaviour by using the
- <literal>jbosscmp-jdbc.xml</literal> file. It is used for basic information such as the datasource
- name and type-mapping (Hypersonic, Oracle etc.) and whether the database tables should be automatically
- created on deployment and deleted on shutdown. You can customize the names of database tables and
- columns which the EJBs are mapped to and you can also tune the way in which the engine loads the data
- depending on how you expect it to be used. For example, by using the <literal>read-ahead</literal>
- element you can get it to read and cache blocks of data for multiple EJBs with a single SQL call,
- anticipating further access. Eager-loading groups can be specified, meaning that only some fields are
- loaded initially with the entity; the others are lazy-loaded if and when they are required. The
- accessing of relationships between EJBs can be tuned using similar mechanisms. This flexibility is
- impossible to achieve if you are using BMP where each bean must be loaded with a single SQL call. If on
- top of that you include having to write all your SQL and relationship management code by hand then the
- choice should be obvious. You should rarely, if ever, have to use BMP in your applications.</para>
- <para> The details of tuning the CMP engine are beyond the scope of this document but you can get an idea of
- what’s available by examining the DTD (<literal>docs/dtd/jbosscmp-jdbc_4_0.dtd</literal>) which is well
- commented. There is also a standard setup in the <literal>conf</literal> directory called
- <literal>standardjbosscmp-jdbc.xml</literal> which contains values for the default settings and a
- list of type-mappings for common databases. The beginning of the file is shown below.</para>
- <programlisting><jbosscmp-jdbc>
- <defaults>
- <datasource>java:/DefaultDS</datasource>
- <datasource-mapping>Hypersonic SQL</datasource-mapping>
-
- <create-table>true</create-table>
- <remove-table>false</remove-table>
- <read-only>false</read-only>
- <read-time-out>300000</read-time-out>
- <row-locking>false</row-locking>
- <pk-constraint>true</pk-constraint>
- <fk-constraint>false</fk-constraint>
- <preferred-relation-mapping>foreign-key</preferred-relation-mapping>
- <read-ahead>
- <strategy>on-load</strategy>
- <page-size>1000</page-size>
- <eager-load-group>*</eager-load-group>
- </read-ahead>
- <list-cache-max>1000</list-cache-max>
-... </programlisting>
- <para> You can see that, among other things, this sets the datasource and mapping for use with the embedded
- Hypersonic database and sets table-creation to true and removal to false, so the schema will be created
- if it doesn’t already exist. The <literal>read-only</literal> and <literal>read-time-out</literal>
- elements specify whether data should be read-only and the time in milliseconds it is valid for. Note
- that many of these elements can be used at different granularities such as per-entity or even on a
- field-by-field basis (consult the DTD for details). The <literal>read-ahead</literal> element uses an
- <literal>on-load</literal> strategy which means that the EJB data will be loaded when it is accessed
- (rather than when the finder method is called) and the <literal>page-size</literal> setting means that
- the data for up to 1000 entities will be loaded with one SQL command. You can override this either in
- your own <literal>jbosscmp-jdbc.xml</literal> file’s list of default settings or by adding the
- information to a specific query configuration in the file.</para>
- <para> A comprehensive explanation of the CMP engine and its various loading strategies can be found in the
- full <emphasis>JBoss 4 Application Server Guide</emphasis>.</para>
- <section>
- <title>XDoclet</title>
- <para> Writing and maintaining deployment descriptors is a labour-intensive and error-prone job at the
- best of times, and detailed customization of the CMP engine can lead to some large and complex
- files. If you are using CMP (or indeed EJBs) in anger then it is worth learning to use the XDoclet
- code generation engine (<ulink url="http://xdoclet.sourceforge.net/"/>). Using Javadoc-style
- attribute tags you place in your code, XDoclet will generate the deployment descriptors for you as
- well as the EJB interfaces and other artifacts if required. It fully supports JBoss CMP, and though
- the learning curve is quite steep, its use is thoroughly recommended (almost essential in fact) for
- real projects.</para>
- </section>
- </section>
- </chapter>
- <chapter id="db">
- <title>Using other Databases</title>
- <para>In the previous chapters, we’ve just been using the JBoss default datasource in our applications. This is
- provided by the embedded HSQL database instance and is bound to the JNDI name
- <literal>java:/DefaultDS</literal>. Having a database included with JBoss is very convenient for running
- examples and HSQL is adequate for many purposes. However, at some stage you will want to use another
- database, either to replace the default datasource or to access multiple databases from within the server.</para>
- <section>
- <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 <emphasis>JBoss 4 Application Server Guide</emphasis>. </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>Next, we’ll work through some step-by-step examples to illustrate what’s involved setting up a
- datasource for a specific.</para>
- </section>
- <section>
- <title>Using MySQL as the Default DataSource</title>
- <para>MySQL is a one of the most popular open source databases around and is used by many prominent
- organizations from Yahoo to NASA. The official JDBC driver for it is called
- <emphasis>Connector/J</emphasis>. For this example we’ve used MySQL 4.1.7 and Connector/J 3.0.15. You
- can download them both from <ulink url="http://www.mysql.com"/> .</para>
- <section>
- <title>Creating a Database and User</title>
- <para> We’ll assume that you’ve already installed MySQL and that you have it running and are familiar
- with the basics. Run the <literal>mysql</literal> client program from the command line so we can
- execute some administration commands. You should make sure that you are connected as a user with
- sufficient privileges (e.g. by specifying the <literal>-u root</literal> option to run as the MySQL
- root user).</para>
- <para> First create a database called <literal>jboss</literal> within MySQL for use by JBoss.</para>
- <programlisting>mysql> CREATE DATABASE jboss;
-Query OK, 1 row affected (0.05 sec) </programlisting>
- <para> Then check that it has been created.</para>
- <programlisting>mysql> SHOW DATABASES;
-+----------+
-| Database |
-+----------+
-| jboss |
-| mysql |
-| test |
-+----------+
-3 rows in set (0.00 sec) </programlisting>
- <para> Next, create a user called <literal>jboss</literal> with password <literal>password</literal> to
- access the database.</para>
- <programlisting>mysql> GRANT ALL PRIVILEGES ON jboss.* TO jboss at localhost IDENTIFIED BY 'password';
-Query OK, 0 rows affected (0.06 sec) </programlisting>
- <para>Again, you can check that everything has gone smoothly.</para>
- <programlisting>mysql> select User,Host,Password from mysql.User;
-+-------+-----------+------------------+
-| User | Host | Password |
-+-------+-----------+------------------+
-| root | localhost | |
-| root | % | |
-| | localhost | |
-| | % | |
-| jboss | localhost | 5d2e19393cc5ef67 |
-+-------+-----------+------------------+
-5 rows in set (0.02 sec) </programlisting>
- </section>
- <section>
- <title>Installing the JDBC Driver and Deploying the DataSource</title>
- <para> To make the JDBC driver classes available to JBoss, copy the file
- <literal>mysql-connector-java-3.0.15-ga-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 configuration you’re running, of course). Then create a file in the
- <literal>deploy</literal> directory called <literal>mysql-ds.xml</literal> with the following
- datasource configuration. The database user name and password corresponds the MySql user we created
- in the previous section. </para>
- <programlisting><datasources>
- <local-tx-datasource>
- <jndi-name>MySqlDS</jndi-name>
- <connection-url>jdbc:mysql://localhost:3306/jboss</connection-url>
- <driver-class>com.mysql.jdbc.Driver</driver-class>
- <user-name>jboss</user-name>
- <password>password</password>
- </local-tx-datasource>
-</datasources> </programlisting>
- <para> Because we have added a new JAR file to the <literal>lib</literal> directory, you will need to
- JBoss to make sure that the server is able to find the MySQL driver classes.</para>
- </section>
- <section>
- <title>Testing the MySQL DataSource</title>
- <para> We’ll use the CMP roster application from <xref linkend="cmp"/> to test the new database
- connection. In order to use MySql in our application, we'll need to set the datasource name a nd
- type-mapping in the <literal>jbosscmp-jdbc.xml</literal> file in the <literal>dd/team</literal>
- directory of the CMP roster application. Edit the file and add the following
- <literal>datasource</literal> and <literal>datasource-mapping</literal> elements to the
- <literal>defaults</literal> element. to <literal>mySQL</literal>.</para>
- <programlisting><jbosscmp-jdbc>
- <defaults>
- <datasource>java:/MySqlDS</datasource>
- <datasource-mapping>mySQL</datasource-mapping>
- </defaults>
-
- <enterprise-beans>
-...
- </enterprise-beans>
-</jbosscmp-jdbc></programlisting>
- <para> After restarting JBoss, you should be able to deploy the application and see the tables being
- created as we did in <xref linkend="X-91007"/>. The tables should be visible from the MySQL client.</para>
- <programlisting>mysql> show tables;
-+-----------------------------------+
-| Tables_in_jboss |
-+-----------------------------------+
-| LeagueBean |
-| PlayerBean |
-| PlayerBean_teams_TeamBean_players |
-| TeamBean |
-+-----------------------------------+
-4 rows in set (0.00 sec) </programlisting>
- <para> You can see the JMS persistence tables in there too since we’re using MySQL as the default
- datasource.</para>
- </section>
- </section>
- <section>
- <title>Setting up an XADataSource with Oracle 9i</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"/>
- </para>
- <para> Installing and configuring Oracle is not for the faint of heart. It isn’t really just a simple
- database, but it is heavy on extra features and technologies which you may not actually want (another
- Apache web server, multiple JDKs, Orbs etc.) but which are usually installed anyway. So we’ll assume you
- already have an Oracle installation available. For this example, we’ve used Oracle 10g.</para>
- <section>
- <title>Padding Xid Values for Oracle Compatibility</title>
- <para> If you look in the <literal>jboss-service.xml</literal> file in the <literal>
- default/conf</literal> directory, you’ll find the following service MBean.</para>
- <programlisting><!-- The configurable Xid factory. For use with Oracle, set pad to true -->
-<mbean code="org.jboss.tm.XidFactory"
- name="jboss:service=XidFactory">
- <!--attribute name="Pad">true</attribute-->
-</mbean>
-</programlisting>
- <para> The transaction service uses this to create XA transactions identifiers. The comment explains the
- situation: for use with Oracle you have to include the line which sets the attribute
- <literal>Pad</literal> to true. This activates padding the identifiers out to their maximum length
- of 64 bytes. Remember that you’ll have to restart JBoss for this change to be put into effect, but
- wait until you’ve installed the JDBC driver classes which we’ll talk about next.</para>
- </section>
- <section>
- <title>Installing the JDBC Driver and Deploying the DataSource</title>
- <para>The Oracle JDBC drivers can be found in the directory <literal>$ORACLE_HOME/jdbc/lib</literal>.
- Older versions, which may be more familiar to some users, had rather uninformative names like
- <literal>classes12.zip</literal> but at the time of writing the latest driver version can be
- found in the file <literal>ojdbc14.jar</literal>. There is also a debug version of the classes with
- <literal>_g</literal> appended to the name which may be useful if you run into problems. Again,
- you should copy one of these to the <literal>lib</literal> directory of the JBoss
- <literal>default</literal> configuration. The basic driver class you would use for the non-XA setup
- is called <literal>oracle.jdbc.driver.OracleDriver</literal>. The <literal>XADataSource</literal>
- class, which we’ll use here, is called <literal>oracle.jdbc.xa.client.OracleXADataSource</literal>. </para>
- <para> For the configuration file, make a copy of the <literal>oracle-xa-ds.xml</literal> example file
- and edit it to set the correct URL, username and password.
- </para>
- <programlisting><datasources>
- <xa-datasource>
- <jndi-name>XAOracleDS</jndi-name>
- <track-connection-by-tx>true</track-connection-by-tx>
- <isSameRM-override-value>false</isSameRM-override-value>
- <xa-datasource-class>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
- <xa-datasource-property name="URL">
- jdbc:oracle:thin:@monkeymachine:1521:jboss
- </xa-datasource-property>
- <xa-datasource-property name="User">jboss</xa-datasource-property>
- <xa-datasource-property name="Password">password</xa-datasource-property>
- <exception-sorter-class-name>
- org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
- </exception-sorter-class-name>
- <no-tx-separate-pools/>
- </xa-datasource>
-
- <mbean code="org.jboss.resource.adapter.jdbc.vender.oracle.OracleXAExceptionFormatter"
- name="jboss.jca:service=OracleXAExceptionFormatter">
- <depends optional-attribute-name="TransactionManagerService">
- jboss:service=TransactionManager
- </depends>
- </mbean>
-</datasources></programlisting>
- <para> We’ve used the Oracle thin (pure java) driver here and assumed the database is running on the
- host <literal>monkeymachine</literal> and that the database name (or SID in Oracle terminology) is
- <literal>jboss</literal>. We’ve also assumed that you’ve created a user <literal>jboss</literal>
- with all the sufficient privileges. You can just use <literal>dba</literal> privileges for this
- example.</para>
- <programlisting>SQL> connect / as sysdba
-Connected.
-SQL> create user jboss identified by password;
-User created.
-SQL> grant dba to jboss;
-Grant succeeded. </programlisting>
- <para> Now copy the file to the <literal>deploy</literal> directory. You should get the following
- output.</para>
- <programlisting>11:33:45,174 INFO [WrapperDataSourceService] Bound connection factory for resource adapter
-for ConnectionManager 'jboss.jca:name=XAOracleDS,service=DataSourceBinding to JNDI name
-'java:XAOracleDS'</programlisting>
- <para>If you use the <literal>JNDIView</literal> service from the JMX console as before, you should see
- the name <literal>java:/XAOracleDS</literal> listed.</para>
- </section>
- <section>
- <title>Testing the Oracle DataSource</title>
- <para> Again we’ll use the CMP example to test out the new database connection. The
- <literal>jbosscmp-jdbc.xml</literal> file should contain the following.</para>
- <programlisting><jbosscmp-jdbc>
- <defaults>
- <datasource>java:/XAOracleDS</datasource>
- <datasource-mapping>Oracle9i</datasource-mapping>
- </defaults>
-</jbosscmp-jdbc> </programlisting>
- <para> There are other Oracle type-mappings available too. If you’re using an earlier version, have a
- look in the <literal>conf/standardjbosscmp-jdbc.xml</literal> file to find the correct name</para>
- <para>Deploy the application as before, check the output for errors and then check that the tables have
- been created using Oracle SQLPlus again from the command line.</para>
- <programlisting>SQL> select table_name from user_tables;
-
-TABLE_NAME
-------------------------------
-TEAMBEAN
-LEAGUEBEAN
-PLAYERBEAN
-PLAYERBEAN_TEAMS_TEAM_1OFLZV8</programlisting>
- </section>
- </section>
- </chapter>
- <chapter id="hibernate">
- <title>Using Hibernate</title>
- <para> Hibernate is a popular persistence engine that provides a simple, yet powerful, alternative to using
- standard entity beans. Hibernate runs in almost any application server, or even outside of an application
- server completely. However, when running inside of JBoss, you can choose to deploy your application as a
- Hibernate archive, called a HAR file, and make Hibernate's simple usage even simpler. JBoss can manage your
- Hibernate session and other configuration details, allowing you to use Hibernate objects with minimal setup. </para>
- <para> In this chapter, we will return the CMP roster application from <xref linkend="cmp"/> and show how to
- access the roster database tables with Hibernate. We'll demonstrate how to create a HAR file to package your
- Hibernate objects, and then we'll show how to access them from a web application in a WAR file. The entire
- project will be bundled in an EAR file, just like all of our previous examples. </para>
- <para> The code for this section is in the <literal>examples/hibernate</literal> directory. However, the
- Hibernate example here is intended to be run along side of the CMP roster application in <xref linkend="cmp"/>. If you don't have the roster application deployed, go back and follow the instructions there. Make sure
- that you follow the instructions for creating the database schema and populating the database. We will be
- using the schema and data from that task. </para>
- <para> Also, please keep in mind that we'll only be looking at the steps required to deploy a Hibernate
- application in JBoss. If you need a more general guide to Hibernate, we recommend <emphasis>Hibernate in
- Action</emphasis> by Christian Bauer and Gavin King (Manning, 2004). </para>
- <section>
- <title>Creating a Hibernate archive</title>
- <para> The Hibernate portion of the application consists of a single Java class,
- <literal>org.jboss.roster.Player</literal>, that maps onto the <literal>PlayerBean</literal> entity
- bean from the CMP roster application. The <literal>Player</literal> object is a simple POJO object with
- no direct coupling to Hibernate. The details of the Hibernate mapping are specified in the
- <literal>Player.hbm.xml</literal> file, shown below. </para>
- <programlisting><!DOCTYPE hibernate-mapping PUBLIC
- "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
- "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">
-
-<hibernate-mapping>
- <class name="org.jboss.roster.Player" table="PlayerBean">
- <id name="id" type="string" column="playerID">
- <generator class="assigned" />
- </id>
-
- <property name="position" type="string" column="POS" />
- <property name="name" type="string" column="name" />
- <property name="salary" type="float" column="salary" />
- </class>
-</hibernate-mapping></programlisting>
- <para> In addition to the <literal>Player</literal> object and its mapping file, we also need to provide a
- <literal>hibernate-service.xml</literal> file that creates an MBean that will manage the Hibernate
- configuration. The following is the <literal>hibernate-service.xml</literal> files we are using. </para>
- <programlisting><server>
- <mbean code="org.jboss.hibernate.jmx.Hibernate"
- name="jboss.har:service=Hibernate">
- <attribute name="DatasourceName">java:/DefaultDS</attribute>
- <attribute name="Dialect">org.hibernate.dialect.HSQLDialect</attribute>
- <attribute name="SessionFactoryName">java:/hibernate/SessionFactory</attribute>
- <attribute name="CacheProviderClass">
- org.hibernate.cache.HashtableCacheProvider
- </attribute>
- <!-- <attribute name="Hbm2ddlAuto">create-drop</attribute> -->
- </mbean>
-</server></programlisting>
- <para> This configuration information should be familiar to any Hibernate user. The JBoss specific details
- are the mapping to our <literal>java:/DefaultDS</literal> and the JNDI location where we want our
- Hibernate <literal>SessionFactory</literal> bound. </para>
- <para>To compile the project and build the hibernate archive, use the <literal>compile</literal> and
- <literal>package-har</literal> Ant targets. </para>
- <programlisting>ant -f jboss-build.xml compile
-ant -f jboss-build.xml package-har</programlisting>
- <para> The contents of the create HAR file look like the following: </para>
- <programlisting>$ jar tf jar/roster.har
-META-INF/
-META-INF/MANIFEST.MF
-META-INF/hibernate-service.xml
-org/
-org/jboss/
-org/jboss/roster/
-org/jboss/roster/Player.class
-org/jboss/roster/Player.hbm.xml</programlisting>
- <para> Experienced Hibernate users may be wondering where we've told Hibernate what our persistent objects
- are. The Hibernate deployer determines the set of persistent objects by searching the HAR file for
- hibernate mapping files. All hibernate objects found are added to the configuration with no further
- effort required. </para>
- </section>
- <section>
- <title>Using the hibernate objects</title>
- <para> By deploying the Hibernate archive, we have created a fully configured
- <literal>SessionFactory</literal> for use in other parts of our application. In this example, we have
- created a simple JSP which creates a <literal>Session</literal> from the
- <literal>SessionFactory</literal> and issues a query directly. Normally it would be preferable to put
- the Hibernate access code in a servlet or in a session bean, but for example purposes we'll keep the
- code together in the JSP. For reference, the following code fragment shows how we are accessing the
- Hibernate session in the JSP. </para>
- <programlisting>InitialContext ctx = new InitialContext();
-SessionFactory factory = (SessionFactory)
-ctx.lookup("java:/hibernate/SessionFactory");
-Session hsession = factory.openSession();
-try {
- Query query = hsession.createQuery("from org.jboss.roster.Player order by name");
- request.setAttribute("players", query.list());
-} finally {
- hsession.close();
-} </programlisting>
- <para> To package the complete web application, use the <literal>package-web</literal> Ant target. </para>
- <programlisting>ant -f jboss-build.xml package-web</programlisting>
- <para> This creates <literal>roster.war</literal> in the <literal>jar</literal> directory containing our
- simple web application. </para>
- </section>
- <section>
- <title>Packaging the complete application</title>
- <para> Next, we need to package the entire application into an EAR file. The <literal>assemble</literal> Ant
- target does this. </para>
- <programlisting>ant -f jboss-build.xml assemble</programlisting>
- <para> This creates the <literal>HibernateRoster.ear</literal> file. The contents of the EAR file our our
- <literal>roster.har</literal> and <literal>roster.war</literal> files, along with the appropriate
- deployment descriptors. </para>
- <programlisting>$ jar tf jar/HibernateRoster.ear
-META-INF/
-META-INF/MANIFEST.MF
-META-INF/application.xml
-META-INF/jboss-app.xml
-roster.har
-roster.war</programlisting>
- <para> Just as we need to declare the WAR file in the <literal>application.xml</literal> file, we also need
- to declare the HAR file. However, since Hibernate archives are not a standard J2EE deployment type, we
- need to declare it in the <literal>jboss-app.xml</literal> file. </para>
- <programlisting><!DOCTYPE jboss-app PUBLIC "-//JBoss//DTD J2EE Application 1.4//EN"
- "http://www.jboss.org/j2ee/dtd/jboss-app_4_0.dtd">
-<jboss-app>
- <module>
- <har>roster.har</har>
- </module>
-</jboss-app></programlisting>
- <para> Now our application is ready to be deployed. </para>
- </section>
- <section>
- <title>Deploying Running the application</title>
- <para> Once the EAR file is created, we need to deploy it using the <literal>deploy</literal> Ant target.
- This copies the EAR file to the appropriate JBoss deploy directory.</para>
- <programlisting>ant -f jboss-build.xml deploy</programlisting>
- <para> The deployed application can be accessed at <ulink url="http://localhost:8080/roster/players.jsp"/>.
- When the page is loaded, you will see a list of players sorted by name. If you don't see any data, make
- sure that you have deployed the CMP roster application from <xref linkend="cmp"/> and run it to populate
- the tables with the shared player data. </para>
- </section>
- </chapter>
-<!--
- <appendix id="webconsole-appendix">
- <title>The Web Console</title>
- <para>Throughout this guide, we have been using to the JMX Console web application to inspect and manage the
- server. However there is another management console application which offers extended functionality such as
- live graphs, alerts, and statistics on deployed J2EE components such as EJBs and servlets.</para>
- <para> The URL for the web console is <ulink url="http://localhost:8080/web-console"/>. You will get more out of
- it if you have some applications deployed and been running them to accumulate some statistics. For example,
- with the Duke’s Bank application deployed you’ll see something like <xref linkend="X-87433"/>, which shows
- the statistics for the AccountController stateful session bean. The invocation statistics are
- self-explanatory; you have a list of methods and the max, min, average time per invocation as well as the
- total time spent in the method and the number of invocations. The number of concurrent invocations is shown
- underneath the table of methods.</para>
- <para> The information in the <emphasis>Bean Statistics</emphasis> section shows information on the bean
- instance numbers. The details vary depending on the type of bean and the possible values are shown in <xref
- linkend="beandata.fig"/>. For a complete description of the bean states (method-ready, pooled, ready
- etc.) see the EJB specification.</para>
- <figure id="X-87433">
- <title>Web Admin. Console Showing Stateful Session Bean Statistics. </title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="images/jbossj2ee.book-20.gif"/>
- </imageobject>
- </mediaobject>
- </figure>
- <table id="beandata.fig">
- <title>Bean Statistics Data</title>
- <tgroup cols="2">
- <tbody>
- <row>
- <entry>
- <emphasis role="bold">Stateless Session Bean</emphasis>
- </entry>
- <entry>
- <emphasis role="bold">Description</emphasis>
- </entry>
- </row>
- <row>
- <entry> MethodReadyCount </entry>
- <entry> Number of beans in the <literal>method-ready</literal> state. </entry>
- </row>
- <row>
- <entry> CreateCount </entry>
- <entry> Number of times the create method has been called. </entry>
- </row>
- <row>
- <entry> RemoveCount </entry>
- <entry> Number of times the remove method has been called. </entry>
- </row>
- <row>
- <entry>
- <emphasis role="bold">Stateful Session Bean</emphasis>
- </entry>
- <entry/>
- </row>
- <row>
- <entry> MethodReadyCount </entry>
- <entry> The number of beans in the <literal>method-ready</literal> state. </entry>
- </row>
- <row>
- <entry> CreateCount </entry>
- <entry> The number of beans that have been created </entry>
- </row>
- <row>
- <entry>RemoveCount<footnote>
- <para>Note that the <literal>RemoveCount</literal> may not equal
- <literal>CreateCount</literal> over time as the beans may be passivated and then
- time-out with the <literal>remove</literal> method being called.</para>
- </footnote>
- </entry>
- <entry> The number of beans that have been explicitly removed. </entry>
- </row>
- <row>
- <entry> PassiveCount </entry>
- <entry> The number of beans that have been passivated by the container. </entry>
- </row>
- <row>
- <entry>
- <emphasis role="bold">Entity Bean</emphasis>
- </entry>
- <entry/>
- </row>
- <row>
- <entry> CreateCount </entry>
- <entry> Number of entities that have been created by calls to create method. </entry>
- </row>
- <row>
- <entry> RemoveCount </entry>
- <entry> Number of entities that have been removed (deleted) by calling remove method. </entry>
- </row>
- <row>
- <entry> ReadyCount </entry>
- <entry> Number of beans that are in the <literal>ready</literal> state, assigned an entity
- object and ready to handle invocations. </entry>
- </row>
- <row>
- <entry> PooledCount </entry>
- <entry> Number of beans in the <literal>pooled</literal> state. JBoss doesn’t use entity
- instance pooling so this will be zero. </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para> The web-console isn’t a pure web application but uses a Java applet for the tree view on the left-hand
- side. So you’ll need to have the Java plugin installed and have Java enabled to make it work.</para>
- </appendix>
- -->
- <appendix>
- <title>Further Information Sources</title>
- <para>For a longer introduction to JBoss, see <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, see <emphasis>JBoss 4
- Application Server Guide</emphasis>, available at <ulink url="http://docs.jboss.org/"/>. A print version
- of the guide is available as <emphasis>JBoss 4.0: The Official Guide</emphasis>. (Sams, 2005) </para>
-<!--
- <para> For information on how to run clustered JBoss servers for performance and high
- availability, see <emphasis>JBoss Clustering</emphasis> (Sacha Labourey and Bill Burke)
- also available at <ulink url="http://www.jboss.org/docs/index"/>
- </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>For additional, but dated, EJB instruction, we also recommend the classic <emphasis>Mastering Enterprise
- JavaBeans, Second Edition</emphasis>. (Wiley, 2001. Ed. Roman et al.) A free PDF version of the first
- edition is available online at <ulink url="http://www.theserverside.com/books/masteringEJB/index.jsp"/>. </para>
- <para>For complete coverage of the new J2EE 1.4 web services, see <emphasis>J2EE Web Services</emphasis>.
- (Addison-Wesley, 2003. Richard Monson-Haefel )</para>
- <para>For more information about using XDoclet to simplify J2EE development, see <emphasis>XDoclet in
- Action</emphasis>. (Manning, 2003. Craig Walls, Norman Richards) </para>
- <para>To learn more about Hibernate, see <emphasis>Hibernate in Action</emphasis>. (Manning, 2004. Christian
- Bauer, Gavin King) </para>
- </appendix>
-</book>
Deleted: projects/docs/trunk/Getting_Started/en-US/Legal_Notice.xml
===================================================================
--- projects/docs/trunk/Getting_Started/en-US/Legal_Notice.xml 2007-10-17 04:54:27 UTC (rev 66206)
+++ projects/docs/trunk/Getting_Started/en-US/Legal_Notice.xml 2007-10-17 05:35:07 UTC (rev 66207)
@@ -1,17 +0,0 @@
-<?xml version='1.0'?>
-<!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-
-<legalnotice id="Book-Legal_Notice">
- <title>Legal Notice</title>
- <para>
- <address>
- <street>1801 Varsity Drive</street>
- <city>Raleigh</city>, <state>NC</state><postcode>27606-2072</postcode><country>USA</country><phone>Phone: +1 919 754 3700</phone>
- <phone>Phone: 888 733 4281</phone>
- <fax>Fax: +1 919 754 3701</fax>
- <pob>PO Box 13588</pob><city>Research Triangle Park</city>, <state>NC</state><postcode>27709</postcode><country>USA</country>
- </address>
- </para>
-</legalnotice>
-
More information about the jboss-cvs-commits
mailing list