User: tcoleman
Date: 01/02/05 11:34:00
Added: documentation petstore-1.1.1-01.html
Log:
Add preliminary Pet Store 1.1.1 deployment documentation
Revision Changes Path
1.1 newsite/documentation/petstore-1.1.1-01.html
Index: petstore-1.1.1-01.html
===================================================================
<h1>HowTo: Deploying the Pet Store 1.1.1 Demo in jBoss</h1>
<h2>Introduction</h2>
The Pet Store sample application (demo) is a relatively robust, well-documented
demonstration of J2EE technology and concepts. It implements MVC
(Model-View-Controller) architecture.
<p>The Pet Store demo can allow developers to gain familiarity with J2EE
concepts including application portability, a key J2EE design objective.
<p><h4>Important: Please note</h4>
<p>This is preliminary documentation of a work in progress. There are
technical issues that need to be addressed before the Pet Store demo can be
considered completely operational in jBoss. The purpose of this documentation
is to describe how the application can be deployed in jBoss, providing a
framework to allow developers to address these issues.
<p>The Pet Store demo has been tested with jBoss configured with integrated Tomcat.
<p>This document describes how to deploy Pet Store 1.1.1 in JBoss.
<br>
<h2>Original contributor</h2>
Mike Leuders, Richard Gyger - Focus Technologies
<br>Aaron Mulder
<h2>Doc writer</h2>
Tom Coleman - [EMAIL PROTECTED]
<h2>Applicable to</h2>
JBoss 2.1 since 21st January 2001
<h2>Installation & Configuration</h2>
<ol>
<li>
<h3><a NAME="petstore1">Download the Pet Store</a></h3>
<p>You can get the source from
<a HREF="http://java.sun.com/j2ee/download.html#blueprints">Sun's J2EE
Download Page</a>. It's in the "J2EE Blueprints" package. Download
the 1.1.1 version. Unpack it anywhere. The root directory of the Pet
Store demo is referred to below as $PETSTORE.
<p>
<li>
<h3><a NAME="petstore2">Download the jBoss Pet Store patch file</a></h3>
<p>Running the Pet Store demo in jBoss currently requires that jBoss be patched to
support deployment of multiple Ejb's within an .ear file. It also requires
several minor changes to deployment files in the Pet Store application (.ear) file.
You can get the source from
<a HREF="petstore-1.1.1-patch.zip">
www.jboss.org/documentation/petstore-1.1.1-patch.zip</a>.
<p>Copy the patch file to a temporary directory and unzip it. The patch
contains two (2) zip files; one to patch jBoss, and another to patch the
Pet Store demo.
<p>
<li>
<h3><a NAME="petstore3">Rebuild jBoss</a></h3>
<p>Currently, three (3) jBoss java files have to be replaced, and jBoss rebuilt.
It is expected that these modifications will be added to the PRE-2.1 CVS
tree within several days of this patch becoming generally available. This
documentation and the patch file will be changed at that time.
<p>Copy the <code>petstore-jboss.zip</code> file to the root directory ($JBOSS) of
your jBoss distribution. Change to this directory and unzip the file.
<pre>
cd $JBOSS
unzip petstore-jboss.zip
cd src/build
sh build.sh
</pre>
<p>The $JBOSS/<code>dist</code> directory is your new $JBOSS_HOME.
<p>
<li>
<h3><a NAME="petstore4">Select a Database</a></h3>
<p>The Pet Store demo uses the <b>Cloudscape</b> database by default.
It also includes SQL scripts for building databases in
<b>Oracle</b> and <b>Sybase</b>, (though you may need to comment out the
<code>drop table</code> statements at the top for them to run the first time).
The jBoss Pet Store patch file includes a Firebird/InterBase script.
The Pet Store demo should work with just about any JDBC compliant database.
<p>The Pet Store demo is being tested with
<a HREF="http://firebird.sourceforge.net/fb_download.html">Firebird/InterBase
6.0.</a>
In order to use Firebird/Interbase, you will also need to install Interclient
2.0, which provides the JDBC inteface. Using the Reference J2EE server, the
Pet Store demo did not work correctly with Interclient 1.6.
<p>(Installing Firebird/InterBase and Interclient is beyond the scope of this
document.)
<p>
<li>
<h3><a NAME="petstore5">Rebuild the Pet Store application (petstore.ear)</a></h3><p>
<p>These steps add the file <code>jboss-web.xml</code> to the WEB-INF directory in
<code>petstore.war</code>, modify the <code>serverType</code> in the
<code>web.xml</code> file of that directory to allow the application to
recognize jBoss, and modify the <code>application.xml</code> file in the META-INF
directory of <code>petstore.ear</code>.
This preliminary documentation describes how to do this manually:
<p>
a. Copy the <code>petstore-jboss-mods.zip</code> file to the root directory
($PETSTORE)
of your Pet Store distribution. Change to this directory and unzip the file.
<p>
Note: This will overwrite the original <code>web.xml</code> file.
<pre>
cd $PETSTORE
unzip petstore-jboss-mods.zip
</pre>
<p>
b. Rebuild the Pet Store application. Run <code>build.sh</code> or
<code>build.bat</code> in the
<code>$PETSTORE/src/petstore/src/build directory</code>. The result is a new
<code>petstore.ear</code> in the <code>$PETSTORE/src/petstore/build</code> directory.
<p>
c. Copy the new <code>petstore.ear</code> to a clean temporary directory and unjar
it:
<p>
<pre>
cp $PETSTORE/src/petstore/build/petstore.ear $TEMP
cd $TEMP
jar xvf petstore.ear
</pre>
<p>
d. Edit the application.xml file. The <b>estore</b> context needs a leading
slash to work with Tomcat.
<p>
<pre>
<web>
<web-uri>petstore.war</web-uri>
<context-root><b>/estore</b></context-root>
<web>
</pre>
<p>
e. Rejar the application. The result is the application file you will deploy
in jBoss.
<p>
<pre>
rm petstore.ear
jar cvf petstore.ear *
</pre>
<p>
<li>
<h3><a NAME="petstore6">Add DB Pool to jBoss</a></h3>
<p>The jBoss Petstore patch file includes the file
<code>jboss.jcml.</code> The default configuration has
a Firebird/InterBase DB Pool. If you will be using a
different database, you should update or replace this with a
single DB pool that points to your database, and then edit the file
according to the procedures in the
<a HREF="../manual/adv_config.html#datasources">Data Sources</a> section.</p>
<p>
<li>
<h3><a NAME="petstore7">Prepare the Database</a></h3>
<p>Whichever product you're using, create a database or instance
or schema (the terminology varies) and then run the appropriate
script to populate it. Make sure your DB is running.</p>
<p>
<li>
<h3><a NAME="petstore8">Add JARS to jBoss</a></h3>
<p>Copy your DB driver JAR to the <code>lib/ext</code>directory of your
jBoss installation ($JBOSS_HOME).
<p>Copy <code>tools.jar</code> from the J2 SDK to the <code>lib/ext</code>
directory of your jBoss installation ($JBOSS_HOME).
<p>
<li>
<h3><a NAME="petstore9">Start jBoss</a></h3>
<p>Start jBoss and copy the new <code>petstore.ear</code> to the
<code>deploy</code> directory. You should see jBoss deploy the Pet Store
EJBs.</p>
<p>
<li>
<h3><a NAME="petstore10">Run the Pet Store</a></h3>
<p>Point your browser to http://<your-server-name.your-domain>:8080/estore to
start the Pet Store.
