Author: ekoneil
Date: Thu Sep 8 12:13:09 2005
New Revision: 279601
URL: http://svn.apache.org/viewcvs?rev=279601&view=rev
Log:
Complete rewrite of the NetUI project model documentation. This now includes
more detail about:
- two primary web project models
- how to configure the <build-pageflows> Ant macro to build such projects
- add a "Required" column to the JAR list
- add a list of required / optional XML resources including those for validation
- add information about what JARs to commit to source control (if using)
- add information about what is produced when building a Page Flow
- removing information about deploying an application to Tomcat
- remove the Ant build file that was at the end of the doc
BB: self
Test: build.release runs
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
Modified:
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
URL:
http://svn.apache.org/viewcvs/beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml?rev=279601&r1=279600&r2=279601&view=diff
==============================================================================
---
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
(original)
+++
beehive/trunk/docs/forrest/release/src/documentation/content/xdocs/netui/projects.xml
Thu Sep 8 12:13:09 2005
@@ -8,446 +8,364 @@
<section id="introduction">
<title>Introduction</title>
<p>
- Now that the basics of NetUI have been explained, you need to know
how to put together a web project that
- uses NetUI Page Flow and the NetUI JSP tags. Beehive ships with a
set of Ant build files to help with this task.
+ 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="sourceTreeLayout">
+ <section id="projectLayout">
<title>Project Layout</title>
<p>
- Your project may live anywhere on your local disk. For now, we will
assume that you have a simple project layout
- in the style of the blank sample NetUI project (<a
href="site:netui-blank">Project: NetUI</a>). In this
- case, you can modify and use the build.xml and build.properties
files from that project. For a discussion of
- alternate project layouts, see <a
href="#alternateProjectLayouts">Alternate Project Layouts</a>, below.
+ 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>
- <p>
- Let's assume that your project looks like this:
- </p>
- <source>
-project/
- myPageFlow/
+ <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/
- classes/
- lib/
- src/
- build.properties
- build.xml
- web.xml</source>
- <section id="projectRoot">
- <title><code>project/</code></title>
- <p>
- The <code>project</code> directory is the root of the web
project. All web content (JSPs, etc.) lives under
- this directory. Page Flow controller source files also live
under this directory, alongside the JSPs they
- own.
+ 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>
- </section>
- <section id="myPageFlow">
- <title><code>project/myPageFlow/</code></title>
+ <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/"
+ weboutputdir="build/"
+ tempdir="build/WEB-INF/.tmpbeansrc"
+ classpathref="webapp.classpath"/>
+ ]]></source>
<p>
- The <code>project/myPageFlow</code> directory is a <em>page
flow</em>: a controller class and a set of pages
- that go with it. The <code>Controller.java</code> file is
compiled to
-
<code>project/WEB-INF/classes/myPageFlow/Controller.class</code>, and it
generates a Struts config
- file at
<code>project/WEB-INF/.pageflow-struts-generated/jpf-struts-config-myPageFlow.xml</code>.
+ 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/"
+ weboutputdir="build/"
+ 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="webinfSrc">
- <title><code>project/WEB-INF/src</code></title>
+ <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>
- The <code>project/WEB-INF/src</code> directory contains both
Java source code and resources such
- as <code>.xml</code> and <code>.properties</code> files.
During the build, Java source code is compiled
- to classes in <code>project/WEB-INF/classes</code>, and
resources are copied into directories under
- <code>project/WEB-INF/classes</code>.
+ 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"/>
- </section>
- <section id="webinfLib">
- <title><code>project/WEB-INF/lib/</code></title>
+ ...
+
+ <build-pageflows srcdir="fooWebProject/"
+ tempdir="fooWebProject/WEB-INF/.tmpbeansrc"
+ classpathref="webapp.classpath"/>
+ ]]></source>
<p>
- As with any other web application, the
<code>project/WEB-INF/lib</code> directory contains the JAR files
- used by your application, including those required by Beehive
itself. The jars required by Beehive are
- listed below.
- </p>
- <note>
- These JAR files are installed automatically during the <a
href="#building">build</a>. The list below is
- for reference only; you do not need to install the JARs by
hand. If you want, you can always install
- them into a web project using the following command:
- <code><![CDATA[
-ant -f <beehive-home>/ant/beehive-runtime.xml
-Dwebapp.dir=<full-path-to-project-directory> deploy.beehive.webapp.runtime
- ]]></code>
- </note>
- <table>
- <tr>
- <th>Project</th>
- <th>Jar</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 (when using NetUI JSP tags)</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 (Text Processing)</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>JSR 173 (Streaming API for XML)</td>
- <td>jsr173_1.0_api.jar</td>
- <td>1.0</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>JSTL</td>
- <td>jstl.jar</td>
- <td>1.1.0-D13</td>
- <td>Yes (when using JSTL tags)</td>
- </tr>
- <tr>
- <td>JSTL</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>
- <tr>
- <td>XMLBeans</td>
- <td>apache-xbean.jar</td>
- <td>2.0.0</td>
- <td>Yes</td>
- </tr>
- </table>
+ The difference between this <code><build-pageflows></code> call
and the previous examples is that the <code>webcontentdir</code> and
+ <code>weboutputdir</code> directories are implicitly set by only
using the <code>srcdir</code> attribute. This causes the web projec
+ 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="building">
- <title>Building</title>
+ <section id="creatingNetUIProjects">
+ <title>Creating a new NetUI Project</title>
<p>
- This section assumes that you are using
<code>project/WEB-INF/src/build.xml</code>, which should like the
- file found at
<em>beehive-home</em><code>/samples/netui-blank/WEB-INF/src/build.xml</code>.
(For
- instructions on starting with the template web project, see <a
href="site:netui-blank">Project: NetUI</a>.)
+ 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>
- The build.xml file depends on properties that you have set up in
the file
- <code>project/WEB-INF/src/build.xml</code>. You need to provide
values for the following properties:
+ This command will create a webapp using the project layout described
<a href="#projectLayoutSourceIn">here</a>. This webapp is basically
+ just a copy of the
</p>
- <ul>
- <li><code>beehive.home</code>: points to the top-level directory
of your Beehive installation</li>
- <li><code>servlet-api.jar</code>: for Tomcat, this value is
$CATALINA_HOME/common/lib/servlet-api.jar</li>
- <li><code>jsp-api.jar</code>: for Tomcat, this value is
$CATALINA_HOME/common/lib/jsp-api.jar</li>
- <li>
- <code>context.path</code>: determines (1) the context path for
your deployed webapp (e.g.,
- http://some.domain/<em>context.path</em>/someDirectory), and
(2) the name of the compiled WAR file.
- </li>
- </ul>
- <p>An example <code>build.properties</code> file appears below.</p>
- <source>
-beehive.home=/apache/apache-beehive-1.0
-servlet-api.jar=${os.CATALINA_HOME}/common/lib/servlet-api.jar
-jsp-api.jar=${os.CATALINA_HOME}/common/lib/jsp-api.jar
-context.path=myWebApp</source>
+ </section>
+ <section id="runtimeArtifacts">
+ <title>Runtime JARs / Resources</title>
<p>
- Before you can build the web project using Ant, you must ensure
that the
- following variables are set: <code>ANT_HOME</code>,
<code>JAVA_HOME</code>,
- and <code>CATALINA_HOME</code>.
+ 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>Variable</th>
- <th>Value</th>
- </tr>
- <tr>
- <td>ANT_HOME</td>
- <td>Top level of your Ant distribution</td>
- </tr>
- <tr>
- <td>JAVA_HOME</td>
- <td>You must have JDK5 installed.</td>
- </tr>
- <tr>
- <td>CATALINA_HOME</td>
- <td>Top level of the installed Tomcat server (optional; required
only if you use Tomcat).</td>
- </tr>
+ <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 (when using NetUI JSP tags)</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>JSR 173 (Streaming API for XML)</td>
+ <td>jsr173_1.0_api.jar</td>
+ <td>1.0</td>
+ <td>Yes</td>
+ </tr>
+ <tr>
+ <td>JSTL 1.1</td>
+ <td>jstl.jar</td>
+ <td>1.1.0-D13</td>
+ <td>Yes (when using JSTL tags)</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>
+ <tr>
+ <td>XMLBeans</td>
+ <td>apache-xbean.jar</td>
+ <td>2.0.0</td>
+ <td>Yes</td>
+ </tr>
</table>
- <p>
- Once these variables are set correctly, you can build the project
and generate a deployable <code>war</code>
- file using the following command (assuming you are in the
<code>project</code> directory):
- </p>
- <source>ant -f WEB-INF/src/build.xml clean build war</source>
- <p>
- This cleans the project, builds it, and packages it into a
deployable unit (<code>myWebApp.war</code>, in
- this case, since <code>context.path=myWebApp</code> in
<code>build.properties</code>).
- </p>
- </section>
- <section id="deploying">
- <title>Deploying the Web Project</title>
- <p>
- To deploy your project, you have two options:
- </p>
- <ul>
- <li>deploy the <code>war</code> file (<code>myWebApp.war</code>),
or,</li>
- <li>deploy the actual web project directory.</li>
- </ul>
<note>
- Deploying the web project directory is useful when you in an
iterative development; once the directory is
- deployed as a webapp, you can see changes by running <code>ant -f
WEB-INf/src/build.xml build</code>, then
- redeploying the webapp.
+ As of this release, the NetUI runtime <em>can not</em> be shared
between web applications by storing the
+ runtime in a location that is class loads NetUI JARs in such a way
that shares the same class instances
+ between webapps. This is because in some cases, NetUI caches
information in class instances
+ rather than in the <code>ServletContext</code>.
</note>
- <p>
- Instructions for deploying a project vary from server to server.
One way to deploy using Tomcat is to
- hit the following URL in your browser:
- </p>
-
<source>http://localhost:8080/manager/deploy?path=<em>context-path</em>&war=<em>URL-to-project-directory-or-war</em>&update=true</source>
- <p>
- An example <em>context-path</em> might be <code>/myWebApp</code>,
and an example URL (on Windows) might be
- <code>file:///C:/temp/project</code>.
- </p>
- <note>
- The Tomcat instructions assume that you have created the
<code>manager</code> role in the configuration file
- <code>$CATALINA_HOME/conf/tomcat-users.xml</code>.
- </note>
- </section>
- <section id="next">
- <title>Next...</title>
- <p>
- Now that you've built and deployed a project, you can see how easy
it is to modify the flow between pages.
- </p>
- <ul>
- <li><a href="site:pageflow_altering">Altering a Page Flow</a></li>
- </ul>
+ </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><beehive-root>/samples/netui-blank/WEB-INF/</code></td><td>Yes</td>
+ </tr>
+ <tr>
+
<td>validator-rules.xml</td><td><code><beehive-root>/samples/netui-blank/WEB-INF/</code></td><td>Yes</td>
+ </tr>
+ <tr>
+ <td>beehive-netui-config.xml</td>
+ <td>See <a href="site:reference/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="alternateProjectLayouts">
- <title>Alternate Project Layouts</title>
+ <section id="building">
+ <title>Building a Web Project</title>
<p>
- The Beehive build tools support many project layouts (see
- <a href="site:ant-macros">Beehive Ant Macros</a>). The
project layout described above is a very
- simple one; web source, content, and generated files are all mixed
in the same directory. An alternate
- project model might separate these out in a structure like this:
+ 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>
-project/
- build/
- webapp/
- src/
- java/ <em>(contains pure Java source code)</em>
- web/ <em>(contains JSPs and controller source files)</em>
- build.properties
- build.xml</source>
+foo/
+ Controller.java
+ page1.jsp
+ page2.jsp
+ </source>
<p>
- Here, the full webapp is built to project/build/webapp, while
source and content directories are
- untouched. The build.xml file would look like this:
+ in any of the project models above, the following artifacts will be
produced by the build:
</p>
- <source><![CDATA[
-<project name="AlternateProjectModel" default="usage" basedir=".">
-
- <property environment="os"/>
- <property file="${basedir}/build.properties"/>
-
- <import file="${beehive.home}/beehive-imports.xml"/>
- <import file="${beehive.home}/ant/beehive-tools.xml"/>
-
- <property name="build.dir" location="${basedir}/build"/>
- <property name="build.webapp.dir" location="${build.dir}/webapp"/>
- <property name="src.dir" location="${basedir}/src"/>
- <property name="src.java.dir" location="${src.dir}/java"/>
- <property name="src.content.dir" location="${src.dir}/web"/>
- <property name="webinf.dir" location="${build.webapp.dir}/WEB-INF"/>
- <property name="build.classes.dir" location="${webinf.dir}/classes"/>
- <property name="tmp.sourcegen.dir" value="${build.dir}/tmpbeansrc"/>
-
- <!-- Define the classpath used to build the webapp -->
- <path id="webapp.build.classpath">
- <pathelement location="${servlet-api.jar}"/>
- <pathelement location="${jsp-api.jar}"/>
- <pathelement location="${build.classes.dir}"/>
- <fileset dir="${webinf.dir}/lib">
- <include name="*.jar"/>
- </fileset>
- </path>
-
- <!-- Define the sourcepath used to build the webapp -->
- <path id="webapp.build.sourcepath">
- <pathelement location="${src.java.dir}"/>
- </path>
-
- <target name="deploy-beehive" description="Copy the Beehive NetUI rutime
into the target webapp">
- <mkdir dir="${build.webapp.dir}"/>
- <deploy-netui webappDir="${build.webapp.dir}"/>
- </target>
-
- <target name="build" depends="deploy-beehive" description="Build the
webapp">
- <available property="src.dir.available" file="${src.dir}" type="dir"/>
- <fail unless="src.dir.available" message="Can't find the source
directory ${src.dir}"/>
-
- <!--
- this directory needs to get whacked before every build so
- that control interface repackagings don't cause stale
- files to be compiled
- -->
- <delete dir="${tmp.sourcegen.dir}" includeEmptyDirs="true"/>
-
- <mkdir dir="${build.classes.dir}"/>
-
- <!-- compile XSDs -->
- <build-schemas srcdir="${src.dir}/schemas"
destdir="${build.classes.dir}"/>
-
- <!-- compile controls -->
- <build-controls srcdir="${src.java.dir}"
- destdir="${build.classes.dir}"
- tempdir="${tmp.sourcegen.dir}"
- classpathref="webapp.build.classpath"/>
-
- <!--
- compile page flows (note: controller source files live inside the
web content
- directory, but they are not included in the built webapp.)
- -->
- <build-pageflows srcdir="${src.content.dir}"
- webcontentdir="${src.content.dir}"
- weboutputdir="${build.webapp.dir}"
- classoutputdir="${build.classes.dir}"
- tempdir="${tmp.sourcegen.dir}"
- classpathref="webapp.build.classpath"
- sourcepathref="webapp.build.sourcepath"/>
-
- <!-- Copy the content to the build directory. -->
- <copy todir="${build.webapp.dir}">
- <fileset dir="${src.content.dir}">
- <include name="**"/>
- <exclude name="**/*.java"/>
- </fileset>
- </copy>
- </target>
-
- <target name="clean" description="Clean the webapp">
- <delete dir="${build.dir}" includeEmptyDirs="true"/>
- </target>
-
- <target name="war" description="Build a compressed WAR file that can be
deployed to an application container">
- <property name="archive.dir" value="${build.webapp.dir}/.."/>
-
- <!-- this does *not* exclude source from the archive -->
- <war destfile="${archive.dir}/${context.path}.war"
webxml="${webinf.dir}/web.xml">
- <fileset dir="${webinf.dir}">
- <exclude name="web.xml"/>
- </fileset>
- </war>
- </target>
-
- <target name="usage" description="Print usage information for this build
file">
- todo
- </target>
-
-</project>]]>
+ <source>
+WEB-INF/classes/
+ foo/
+ Controller.class
+ /.pageflow-struts-generated
+ jpf-struts-config-foo.xml
</source>
<p>
- Note that the Page Flow controller source files live among web
content, e.g.,
+ 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>
- <source>
-project/
- build/
- webapp/
- src/
- java/
- web/
- myPageFlow/
- Controller.java
- page1.jsp
- page2.jsp
- build.properties
- build.xml</source>
+ </section>
+ <section id="deploying">
+ <title>Deploying a Web Project</title>
<p>
- Keeping the controller .java files next to their associated JSPs
is a convenience; they are <em>not</em>
- included in the built webapp. You could just as easily put these
files under a directory like
- project/src/pageflow.
+ 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, and JCP are trademarks or registered trademarks of Sun
Microsystems, Inc. in the United States and other countries.<br/>
- © 2004, Apache Software Foundation
+ Java, J2EE, Servlet, and JCP are trademarks or registered trademarks
of Sun Microsystems, Inc. in the United States
+ and other countries.<br/>© 2005, Apache Software Foundation
</legal>
</footer>
</document>
