<?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>NetUI Web App Project Model</title>
    </header>
    <body>
    <section id="introduction">
        <title>Introduction</title>
        <p>
        A NetUI enabled web application consists of the same resources as a Struts, servlet, or other J2EE webapp.  
        The elements that make a NetUI web application different are the build steps for processing annotated Java
        files and the JARs / resources that comprise the NetUI webapp runtime.  This document discusses several topics
        including possible web project layouts, the Ant tasks used to build Page Flows, the JARs / resources in 
        a NetUI web application, and the files that must be added to source control in order to commit a NetUI-enabled
        web project into SCM.
        </p>
    </section>
    <section id="projectLayout">
        <title>Project Layout</title>
        <p>
        J2EE web projects can be structured in a nearly limitless number of ways.  Virtually all webapps have both 
        source files and web addressable content.  In addition, there are a variety of configuration files and 
        deployment descriptors that are often stored in the <code>WEB-INF/</code> directory.  A fundamental 
        difference in how web projects are structured is where the web-addressable content and the source files live.  
        One web project model stores the source files in a sub-directory the web addressable content; another stores
        source files as a peer to the web addressable content.  When building Page Flows, the project layout affects
        the Ant calls used to build the annotated Java files.  Both project layouts and the Ant used to build are
        discussed here.
        </p>
        <section id="projectLayoutSourceOut">
            <title>Source Files peer to Web Content Root </title>
            <p>
            The classic web project layout is described by Tomcat <a href="http://jakarta.apache.org/tomcat/tomcat-4.1-doc/appdev/source.html">here</a> 
            and has the directories containing web-addressable content and web project source in peer directories.  For example, the following
            directory structure uses this layout and stores the Ant build file in the project's root directory:
            </p>
            <source>
fooWebProject/
    build/
    src/
        Controller.java
    web/
        page1.jsp
        page2.jsp
        WEB-INF/
            web.xml
    build.xml
    build.properties
            </source>
            <p>
            When using this layout, the source files in <code>src/</code> are often built into the <code>build/</code> directory under <code>WEB-INF/classes</code>.
            Page Flows can be added to this project in either the <code>src/</code> or <code>web/</code> directory.  When Page Flows are added to the <code>src/</code>
            directory, the following Ant can be used to build them into <code>build/WEB-INF/classes</code>:
            </p>
            <source><![CDATA[
    <import file="../../beehive-imports.xml"/>
    <import file="${beehive.home}/ant/beehive-tools.xml"/>
    <property file="build.properties"/>

    ...

    <build-pageflows srcdir="src/"
                     webcontentdir="web/"
                     destdir="build/WEB-INF/classes/"
                     tempdir="build/WEB-INF/.tmpbeansrc"
                     classpathref="webapp.classpath"/>
            ]]></source>
            <p>
            While unconventional, because a Page Flow is URL addressable and "owns" its JSPs it is sometimes useful to store Page Flow files in the 
            <code>web/</code> directory.  This makes it easier to visualize the Page Flow as both the pages and the controller source file.  In this case,
            the Ant build changes slightly:
            </p>
            <source><![CDATA[
    <import file="../../beehive-imports.xml"/>
    <import file="${beehive.home}/ant/beehive-tools.xml"/>
    <property file="build.properties"/>

    ...

    <build-pageflows srcdir="web/"
                     webcontentdir="web/"
                     destdir="build/WEB-INF/classes/"
                     tempdir="build/WEB-INF/.tmpbeansrc"
                     classpathref="webapp.classpath"/>
            ]]></source>
            <p>
            Be careful of the dependencies between the <code>src/</code> and <code>web/</code> directories when adding Page Flows to the 
            <code>web/</code> directory as building both source roots separately can be difficult they have circular dependencies on 
            each other.  
            </p>
            <p>
            In both of the above project layouts, the <code>tempdir</code> is used as a destination for artifacts generated by the 
            Beehive annotation processors including both resources and Java source files.  These are then compiled by the annotation
            processor into the classes stored in <code>build/WEB-INF/classes</code>.  This behavior can be changed by tweaking
            the build files to build into a different temporary directory or to create a JAR for the class files.  Also, the <code>build/</code> 
            directory is often deployed to an application container during development.  
            </p>
        </section>
        <section id="projectLayoutSourceIn">
            <title>Source Files in the Web Content Root</title>
            <p>
            An alternate web project layout stores Java sources in the <code>WEB-INF/src</code> sub-directory.  This project layout might look like:
            </p>
            <source>
fooWebProject/
    page1.jsp
    page2.jsp
    WEB-INF/
        web.xml
        src/
            Controller.java
            build.xml
            build.properties
            </source>
            <p>
            When building this type of web project, classes are often generated into the <code>WEB-INF/classes</code> directory and the webapp deployed
            from the <code>fooWebProject</code> directory.  This is different from the previous project models which build and deploy an external <code>build/</code>
            directory.  The Ant used to build Page Flows in this project structure might appear as:
            </p>
            <source><![CDATA[
    <import file="../../beehive-imports.xml"/>
    <import file="${beehive.home}/ant/beehive-tools.xml"/>
    <property file="build.properties"/>

    ...

        <build-pageflows srcdir="fooWebProject/" 
                         tempdir="fooWebProject/WEB-INF/.tmpbeansrc"
                         classpathref="webapp.classpath"/>
            ]]></source>
            <p>
            The difference between this <code>&lt;build-pageflows></code> call and the previous examples is that the <code>webcontentdir</code> and 
            <code>destdir</code> directories are implicitly set by only using the <code>srcdir</code> attribute.  This causes the web project
            to build directly into the <code>fooWebProject/</code> directory and to generate classes into <code>fooWebProject/WEB-INF/classes</code>.
            </p>
        </section>
    </section>
    <section id="creatingNetUIProjects">
        <title>Creating a new NetUI Project</title>
        <p>
        A new NetUI project can be created from a Beehive distribution by running two commands to first create a NetUI-enabled web project and 
        then copy the Beehive runtime JARs into that project.
        </p>
        <source><![CDATA[
cp -r <beehive-root>/samples/netui-samples <project-directory>
ant -f <beehive-root>/ant/beehive-runtime.xml -Dwebapp.dir=<project-directory> deploy.beehive.webapp.runtime
        ]]></source>
        <p>
        This command will create a webapp using the project layout described <a href="#projectLayoutSourceIn">here</a>.  This webapp is 
        essentially a copy of the <code>&lt;beehive-root&gt;/samples/netui-blank</code> web application.
        </p>
    </section>
    <section id="runtimeArtifacts">    
        <title>Runtime JARs / Resources</title>
        <p>
        All web applications require runtime resources.  Often, these are stored in a web project's <code>WEB-INF/lib</code>
        directory.  In order to use NetUI in a J2EE web application, a variety of JARs must be stored in this
        directory.  
        </p>
        <section id="jars">
            <title>JARs</title>
        <p>
        Since NetUI is built atop <a href="http://struts.apache.org">Struts</a>, the Struts JARs must be present in order
        for the web application to function.  This table lists both the Struts and Beehive JARs; all of these JARs are
        available as part of the Beehive distribution.  
        </p>
        <table>
          <tr><th>Name</th><th>JAR file</th><th>Version</th><th>Required</th></tr>
          <tr>
            <td>Beehive Controls</td>
            <td>beehive-controls.jar</td>
            <td><em>distribution</em></td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Beehive NetUI</td>
            <td>beehive-netui-core.jar</td>
            <td><em>distribution</em></td>
            <td>Yes for NetUI JSP tag support; no otherwise</td>
          </tr>
         <tr>
            <td>Beehive NetUI</td>
            <td>beehive-netui-tags.jar</td>
            <td><em>distribution</em></td>
            <td>No</td>
          </tr>
          <tr>
            <td>Jakarta Commons Bean Utils</td>
            <td>commons-beanutils.jar</td>
            <td>1.6</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons Codec</td>
            <td>commons-codec-1.3.jar</td>
            <td>1.3</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons Collections</td>
            <td>commons-collections.jar</td>
            <td>2.1.1</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons Digester</td>
            <td>commons-digester.jar</td>
            <td>1.6</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons Discovery</td>
            <td>commons-discovery-0.2.jar</td>
            <td>0.2</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons EL</td>
            <td>commons-el.jar</td>
            <td>1.0</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons File Upload</td>
            <td>commons-fileupload.jar</td>
            <td>1.0</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons Logging</td>
            <td>commons-logging.jar</td>
            <td>1.0.4</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons ORO</td>
            <td>jakarta-oro.jar</td>
            <td>2.0.7</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>Jakarta Commons Validator</td>
            <td>commons-validator.jar</td>
            <td>1.1.4</td>
            <td>Yes</td>
          </tr>
          <tr>
            <td>JSTL 1.1</td>
            <td>jstl.jar</td>
            <td>1.1.0-D13</td>
            <td>Yes for JSTL tag support; no otherwise</td>
          </tr>
          <tr>
            <td>JSTL 1.1</td>
            <td>standard.jar</td>
            <td>1.1.0-D13</td>
            <td>Yes for JSTL support; no otherwise</td>
          </tr>
          <tr>
            <td>Log4J</td>
            <td>log4j-1.2.8.jar</td>
            <td>1.2.8</td>
            <td>No</td>
          </tr>
          <tr>
            <td>Struts</td>
            <td>struts.jar</td>
            <td>1.2.7</td>
            <td>Yes</td>
          </tr>
        </table>
        <note>
        For the 1.0 release, the NetUI runtime <em>can not</em> be shared between multiple web applications; the runtime
        for every web application must be isolated inside of its own web application classloader.  This is because in some 
        cases, NetUI caches information in statics or class instances rather than in the <code>ServletContext</code>.
        </note>
        </section>
        <section id="otherResources">
            <title>Other Resources</title>
            <p>
            NetUI also uses several additional XML files used to configure various NetUI and Struts sub-systems.  These are detailed
            in the table below.
            </p>
            <table>
              <tr><th>Name</th><th>Location</th><th>Required</th></tr>
              <tr>
                  <td>beehive-netui-validator-rules.xml</td><td><code>&lt;beehive-root&gt;/samples/netui-blank/web/WEB-INF/</code></td><td>Yes</td>
              </tr>
              <tr>
                  <td>validator-rules.xml</td><td><code>&lt;beehive-root&gt;/samples/netui-blank/web/WEB-INF/</code></td><td>Yes</td>
              </tr>
              <tr>
                  <td>beehive-netui-config.xml</td>
                  <td>See <a href="site:reference/netui/netui_config">here</a> for more information.</td>
                  <td>No (unless modified)</td>
              </tr>
            </table>
            <p>
            Also, the NetUI runtime requires a set of <code>web.xml</code> entries to register the Page Flow servlet, filters, and mappings.
            In any NetUI-enabled web project, be sure that these entries are present.
            </p>
        </section>
        <section id="sourceControl">
            <title>NetUI-enabled Web Projects and Source Control</title>
            <p>
            When adding a NetUI-enabled web project to source control, all resources marked <em>Required</em> in the JAR <a href="#jars">table</a> and 
            the resources <a href="#otherResources">table</a> should be checked into SCM.  In addition, the optional resources may be required for certain 
            features to function correctly.  If a web project uses the Beehive System Controls, those JARs should also be checked into source control.
            </p>
        </section>
    </section>
    <section id="building">
        <title>Building a Web Project</title>
        <p>
        When a NetUI enabled web project builds, two processing steps happen to the Page Flow annotated Java files.  The first is
        annotation processing which produces a Struts module config file and the second is a Java class file for the Controller class.  
        For example, given a Page Flow in some directory:
        </p>
        <source>
foo/
    Controller.java
    page1.jsp
    page2.jsp
        </source>
        <p>
        in any of the project models above, the following artifacts will be produced by the build:
        </p>
        <source>
WEB-INF/classes/
             foo/
                 Controller.class
             _pageflow/
                 struts-config-foo.xml
        </source>
        <p>
        By default, the Struts module config file is placed in the <code>WEB-INF/.pageflow-struts-generated</code> directory and the 
        Java class file is placed in <code>WEB-INF/classes/</code>.  In cases where these values need to change, the Beehive Ant
        build macros are documented <a href="site:reference/infra/ant-macros">here</a>.
        </p>
    </section>
    <section id="deploying">
        <title>Deploying a Web Project</title>
        <p>
        Once built, a Beehive web project can be deployed to a Servlet container just as with any other J2EE web application.  On
        Tomcat, this can be done by copying the web project directory to <code>$CATALINA_HOME/webapps</code> or by using the 
        Tomcat deployer to deploy the webapp.  See your application container's documentation for details on how to deploy
        web applications.
        </p>
    </section>
    </body>
    <footer>
        <legal>
        Java, J2EE, Servlet, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States 
        and other countries.<br/>&copy; 2005, Apache Software Foundation 
        </legal>
    </footer>
</document>
