<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" 
    "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
    <header>
        <title>Beehive Sample: Petstore</title>
    </header>
    <body>
        <section id="intro">
            <title>Introduction</title>
            <p>The Petstore sample demonstrates how to integrate all three 
                Beehive technologies (NetUI, Controls and Web Services) in 
                one application.</p>
            <p>NetUI provides customers with web access to the 
                Petstore. There are separate page flows for different customer 
                activities: the 'shop' page flow (located at: 
                <code>petstoreWeb/web/shop/</code>) lets users browse the catalog 
                of pets, the 'checkout' page flow (petstoreWeb/web/checkout) lets 
                users purchase selected items from a shopping cart, etc.</p>
            <p>A web service (located at <code>petstoreWeb/ws/PestoreInventoryManager.java</code>) 
                provides store managers access to the inventory.</p>
            <p>Most of the page flows have associated Control files (located 
                at: 
                <code>petstoreWeb/src/org/apache/beehive/samples/petstore/controls/</code>). 
                The Controls handle the backend data traffic and encapsulate 
                the operations of the web application, such as retrieving data 
                from a database and handling user orders.</p>
            <p>Petstore runs against a Derby database implementation.  See the instructions below
                for downloading Derby.</p>
        <section id="dir_struct">
            <title>Petstore Directory Structure</title>
            <p>The table below describes the functions of the most important 
                files in the Petstore web application.</p>
            <table>
                <tr>
                    <th>Directory</th>
                    <th>Description</th>
                </tr>
                <tr>
                    <td>petstoreWeb</td>
                    <td/>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;src</td>
                    <td>This directory contains the back-end data and controls used by the web app.
                        </td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;org</td>
                    <td>
                        </td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.../controller/AccountController.java</td>
                    <td>Class controls some of the internationalization settings for the site.</td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.../controls</td>
                    <td>Beehive Controls encapsulating different 
                        functionalities, including handling user account data, 
                        catalogue data, and order processing.</td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.../forms</td>
                    <td>Form Beans: each form bean is a server-side 
                        representation of an HTML form appearing in the user 
                        interface.</td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.../model</td>
                    <td>Java object classes (java beans) used to represent the basic 
                        types in the app:
                        addresses, orders, products, etc.</td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;.../resources</td>
                    <td>Various .properties files</td>
                </tr>
                <tr>
                    <td>
                        &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sql</td>
                    <td>A SQL file to initialize the database.</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;test-src</td>
                    <td>Java types used by the application's internal tests.</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;web</td>
                    <td>Contains the NetUI web application modules.</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;account</td>
                    <td>NetUI user interface for managing user accounts</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;auth</td>
                    <td>NetUI user interface for managing login</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;checkout</td>
                    <td>NetUI user interface for managing the shopping 
                        cart</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;search</td>
                    <td>NetUI user interface for searching the 
                        Petstore</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;shop</td>
                    <td>NetUI user interface for browsing the catalogue of 
                        pets</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;site</td>
                    <td>Contains the Petstore "skin", including the CSS file, 
                        HTML frameset, and template file</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;webappRoot</td>
                    <td>
                        <!--[todo]-->
                    </td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;WEB-INF</td>
                    <td>Contains configuration files for deployment, 
                        validation, security (web.xml), and generated Struts config files.</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tags</td>
                    <td>Contains <code>.tag</code> files.</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;lib</td>
                    <td>JAR resources -- this directory is created and populated when you call the ant target <code>deploy-beehive</code>.</td>
                </tr>
                <tr>
                    <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ws</td>
                    <td>Contains the web service interface for the web app.</td>
                </tr>
            </table>
        </section>
        <section><title>Build Targets</title>
             <p>The build file (located at <code>petstoreWeb/build.xml</code>) contains the following
            build targets.</p>
            <table>
                <tr><th><strong>Target</strong></th><th><strong>Description</strong></th></tr>
                <tr><td>deploy-beehive</td><td>Copies the Beehive runtime JARs into the webapp's
                    WEB-INF/lib directory.</td></tr>
                <tr><td>build</td><td>Compiles the webapp components:
                    XMLBean schemas, controls, page flows, and web services.</td></tr>
                <tr><td>scrub</td><td>Deletes the build directories and the test-related
                    directories.</td></tr>
                <tr><td>clean</td><td>Deletes the build directories from the web app.</td></tr>
                <tr><td>war</td><td>Builds a WAR file from the web app files.</td></tr>
            </table>
            </section>
        </section>
        <section id="running">
            <title>Running the PetStore Sample on Tomcat 5</title>
            <p>The following explains how to run the Petstore sample on Tomcat 5.  The Petstore sample
                will run on other web containers, but we have chosen Tomcat 5 for convenience.</p>
            <section id="set_up">
                <title>To Set up the Environment</title>
                <p>Before proceeding, complete all of the necessary and optional steps in the 
                    following topic: 
                    <a class="fork" href="site:docs/installation">Beehive Installation and Setup</a></p>
                <p>Open a command shell and confirm that you have set following variables:</p>
                    <ul>
                        <li><code>ANT_HOME</code></li>
                        <li><code>JAVA_HOME</code></li>
                        <li><code>CATALINA_HOME</code></li>
                    </ul>
                    <p>Also ensure that the following elements are on your <code>PATH</code>:</p>
                    <ul>
                        <li><code>ANT_HOME/bin</code></li>
                        <li><code>JAVA_HOME/bin</code></li>
                    </ul>
            </section>
            <section>
                <title>Download Derby Implementation</title>
                <p>The Petstore app runs against an imbedded Derby database.  You must
                    download a Derby implementation before building and running the Petstore.</p>
                <p>Download a Derby distribution at: <a href="http://db.apache.org/derby/derby_downloads.html">http://db.apache.org/derby/derby_downloads.html</a></p>
                
            </section>
            <section><title>(Optional) Dowload HTTPUnit Implementation</title>
                <p>If you want to run the HTTPUnit tests associated with Petstore,
                    you must download a HTTPUnit implementation from: 
                    <a href="http://httpunit.sourceforge.net/">http://httpunit.sourceforge.net/</a></p></section>
            <section id="copy_app">
                <title>To Copy the Petstore Application to a Project 
                    Folder (Optional Step)</title>
                <p>To keep your Beehive distribution directory 
                    pristine, you should copy the folder 
                    <code>&lt;BeehiveRoot>/samples/petstoreWeb</code> to another location before 
                    proceeding.</p>

                <note>&lt;BeehiveRoot> refers to the top-level directory of your Beehive installation.
                    A typical value for &lt;BeehiveRoot> would be <code>/apache/apache-beehive-1.0</code>. </note>                 
                <p>The following instructions assume that you have 
                    copied the folder <code>petstoreWeb</code> into the 
                    directory <code>/beehive_projects</code>, 
                    resulting in the following directory structure.</p>
                <source>/
  beehive_projects
    petstoreWeb</source>
    <note>Strictly speaking, you do not need to copy the <code>petstoreWeb</code>
        directory to another location.  If you wish to leave the <code>petstoreWeb</code> directory
        in place, in the instructions below you must
        replace occurrences of the path element <code>/beehive_projects</code>
        with this path element: <code>&lt;BeehiveRoot>/samples</code>.
        <br/><br/>
        For example, to build the sample, run the following Ant command:
        <br/><br/>
        &nbsp;&nbsp;&nbsp;<code>ant -f &lt;BeehiveRoot>/samples/petstoreWeb/build.xml clean build war</code>
        <br/><br/>
        To delete the sample's build directory, run the <code>clean</code> target:
        <br/><br/>
        &nbsp;&nbsp;&nbsp;<code>ant -f &lt;BeehiveRoot>/samples/petstoreWeb/build.xml clean</code></note>
            </section>
            <section id="edit_properties_file"><title>Edit the <code>build.properties</code> File</title>
                <p>Edit the <code>build.properties</code> file--the file
                    that sets the build-related properties for your web application.</p>
                <p>Open the file <code>/beehive_projects/petstoreWeb/build.properties</code>
                    in a text editor.</p>
                <p>At a minimum, you will need to edit the following two properties:</p>
                <ul><li>beehive.home</li><li>derby.jar</li></ul>
                <p>If you want to run the httpunit tests, you must set the following additional
                    property</p>
                <ul><li>httpunit.dir</li></ul>
                    <p>The following example shows typical values for these three properties.
                    Note that the property <code>derby.jar</code> points to a JAR file, not
                    to a directory.</p>
<source>beehive.home=<strong>/apache/apache-beehive-1.0</strong>

context.path=petstoreWeb

servlet-api.jar=${os.CATALINA_HOME}/common/lib/servlet-api.jar
jsp-api.jar=${os.CATALINA_HOME}/common/lib/jsp-api.jar

derby.jar=<strong>/apache/derby/derby.jar</strong>

# Set this path in order to run HTTPUnit tests against the webapp
httpunit.dir=<strong>/httpunit-1.6</strong></source>
<note>Windows users must use forwardslashes (/) not backslashes (\) in the 
    <code>build.properties</code> file.</note>

                    </section>
            <section id="compile">
                <title>To Compile the Petstore Application</title>
                <p>To compile the Petstore app, enter the following Ant command:</p>
<source>ant -f /beehive_projects/petstoreWeb/build.xml clean build war
</source>
<p>A WAR file named <code>petstoreWeb.war</code> will be created at <code>/beehive_projects/petstoreWeb/petstoreWeb.war</code>.</p>
            </section>
            <section id="start_tomcat">
                <title>To Start Tomcat</title>
                <p>To start Tomcat, run the following command:</p>
                <source>%CATALINA_HOME%\bin\startup.bat</source>
                <p>On non-Windows systems:</p>
                <source>$CATALINA_HOME/bin/startup.sh</source>
            </section>
            <section id="deploy">
                <title>To Deploy to Tomcat</title>
    <p>To deploy the web application, copy the WAR file to Tomcat's webapps directory.</p>
    <p>On Windows:</p>
    <source>copy C:\beehive_projects\petstoreWeb\petstoreWeb.war %CATALINA_HOME%\webapps /Y</source>
                <note>
                    On Windows, there are file-locking issues that Tomcat versions 5.5.x and above are sensitive to.
                    In particular, any web application that uses Struts will <strong>fail to redeploy</strong> if you
                    copy in a new .war file as described here.  The Commons Digester team is adding a workaround for the
                    issue (see
                    <a href="http://issues.apache.org/bugzilla/show_bug.cgi?id=37034">this bug</a>), but in the meantime,
                    you can work around it with the <code>antiResourceLocking</code> option in Tomcat.  Just add a file
                    called <code>context.xml</code> in a directory called <code>META-INF</code> inside the
                    <code>web</code> directory before building (so it will end up as <code>META-INF/context.xml</code>
                    in your <code>controls_tutorial.war</code>):
                    <br/>
                    <br/>
                    <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;?xml version="1.0" encoding="UTF-8"?></code><br/>
                    <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;Context antiResourceLocking="true"></code><br/>
                    <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/Context></code>
                </note>
    <p>Everywhere else:</p>
    <source>cp /beehive_projects/petstoreWeb/petstoreWeb.war $CATALINA_HOME/webapps</source>
    
            </section>
            <section id="running_url">
                <title>Running Petstore</title>
                <p>Visit the following URL:</p>
                <p><a class="fork" href="http://localhost:8080/petstoreWeb">http://localhost:8080/petstoreWeb</a></p>
            </section>
        </section>
            <section id="testing">
                <title>Running the Petstore Tests</title>
                <p>The Petstore app ships with associated junit tests.
                    Before running the tests, ensure that the web app is up and running, i.e,
                    accessible at http://localhost:8080/petstoreWeb.</p>
                <p>To run the tests, enter the following Ant command:</p>
                <source>ant -f /beehive_projects/petstoreWeb/build.xml test.run</source>
            </section>
    </body>
    <footer>
        <legal>Java, J2EE, and JCP are trademarks or registered trademarks of 
            Sun Microsystems, Inc. in the United States and other 
            countries.<br/> &copy; 2004, Apache Software Foundation </legal>
    </footer>
</document>
