Building a Page Flow Web App
Introduction
Now that the theory of Java Page Flows has been explained, you need to know how to concretely put together a web-app that uses JPFs. Beehive ships with a set of Ant buildfiles to make the building of an application much easier.
Source Tree Layout
The layout of your project may be anywhere on your local disk. We will assume that the environment variable $WEBAPP_DIR points to the top-level of your application.
Here is a typical directory structure, an emandation of the core directory structure found in the web app template <BeehiveRoot>/samples/netui-blank. For instructions on using the web app template, see Project: Page Flow.
-
$WEBAPP_DIR/
- Controller.java
- index.jsp
- login.jsp
- signup.jsp
- mypage.jsp
- resources/
-
WEB-INF/
- classes/
- lib/
- src/
$WEBAPP_DIR/
The top-level of the web-app, at $WEBAPP_DIR should contain your JSP pages and a Controller.java. When built, the Controller.java will be compiled to WEB-INF/classes/Controller.class.
$WEBAPP_DIR/WEB-INF/
The $WEBAPP_DIR/WEB-INF/ directory is just as it is with any other servlet-based application.
$WEBAPP_DIR/WEB-INF/src/
The $WEBAPP_DIR/WEB-INF/src/ directory contains any other application source files that need to be compiled into Java classes. They will be compiled to $WEBAPP_DIR/WEB-INF/classes/. Additionally, any extra .properties or .xml files that need to be deployed with your application will be copied from the src/ directory to the classes/ directory during the build.
$WEBAPP_DIR/WEB-INF/src/ should also contain the build related files for the web app. See the web app template <BeehiveRoot>/samples/netui-blank/WEB-INF/src for an example build file and supporting build.properties file.
$WEBAPP_DIR/WEB-INF/lib/
As with any other web application, the $WEBAPP_DIR/WEB-INF/lib/ directory should contain the jars for each dependency of your application, including those required by Beehive itself. The jars required by Beehive are listed below.
Note: this Ant command will deploy the necessary JARs listed below (plus a few other optional control JARs) to the WEB-INF/lib directory.
ant -f $BEEHIVE_HOME\ant\beehive-runtime.xml -Dwebapp.dir=$WEBAPP_DIR deploy.beehive.webapp.runtime
Project | Jar | Version |
---|---|---|
XMLBeans | apache-xbean.jar | 2.0.0 |
Axis | axis.jar | 1.2RC2 |
Axis | axis-ant.jar | 1.2RC2 |
Beehive NetUI | beehive-netui-pageflow.jar | distribution |
Beehive NetUI | beehive-netuid-scoping.jar | distribution |
Beehive NetUI | beehive-netui-tags-databinding.jar | distribution |
Beehive NetUI | beehive-netui-tags-html.jar | distribution |
Beehive NetUI | beehive-netui-tags-template.jar | distribution |
Beehive NetUI | beehive-netui-util.jar | distribution |
Jakarta Commons Bean Utils | commons-beanutils | 1.6 |
Jakarta Commons Codec | commons-codec-1.3.jar | 1.3 |
Jakarta Commons Collections | commons-collections.jar | 2.1.1 |
Jakarta Commons Digester | commons-digester.jar | 1.5 |
Jakarta Commons Discovery | commons-discovery-0.2.jar | 0.2 |
Jakarta Commons EL | commons-el.jar | 1.0 |
Jakarta Commons Servlet File Upload | commons-fileupload.jar | 1.0 |
Jakarta Commons Logging | commons-logging.jar | 1.0.3 |
Jakarta Commons Validator | commons-validator.jar | 1.1.3 |
Beehive Controls | beehive-controls.jar | distribution |
Jakarta Commons ORO (Text Processing) | jakarta-oro.jar | 2.0.8 |
JAX RPC | jaxrpc.jar | 1.1 |
JSR 173 (Streaming API for XML) | jsr173_1.0_api.jar | 1.0 |
JSTL | jstl.jar | 1.1.0-D13 |
Log4J | log4j-1.2.8.jar | 1.2.8 |
SAAJ | saaj.jar | 1.2 |
JSTL | standard.jar | 1.1.0-D13 |
Struts | struts.jar | 1.2.4 |
Velocity | velocity-1.4.jar | 1.4 |
Velocity | velocity-dep-1.4.jar | 1.4 |
WSDL4J | wsdl4j.jar | 1.5 |
Beehive Web Services | beehive-wsdltypes.jar | distribution |
Beehive Web Services | beehive-wsm-axis.jar | distribution |
Beehive Web Services | beehive-wsm.jar | distribution |
Running Ant
The following section assumes that you are using the Ant build.xml file found at <BeehiveRoot>/samples/netui-blank/WEB-INF/src/. We assume either (1) that the build.xml file has been copied to $WEBAPP_DIR/WEB-INF/src/ or (2) that your web app has been developed by amending the template web app <BeehiveRoot/samples/netui-blank. (For instructions on starting a web with the template web app, see Project: Page Flow.)
You also set the following properties in a supporting build.properties file located at $WEBAPP_DIR/WEB-INF/src/build.properties.
- beehive.home -- points to the top-level directory of your Beehive installation
- servlet-api.jar -- for Tomcat, this value is $CATALINA_HOME/common/lib/servlet-api.jar
- jsp-api.jar -- for Tomcat, this value is $CATALINA_HOME/common/lib/jsp-api.jar
- context.path -- determines (1) part of the URL where your web app resides, e.g., http://some.domain/contextPath/someDirectory, and (2) the name of the compiled WAR file.
An example build.properties file appears below.
build.properties
beehive.home=C:/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=contextPath
Before you can build the web-app using Ant, you must ensure that the following variables are set: ANT_HOME, JAVA_HOME, and CATALINA_HOME.
Variable | Value |
---|---|
ANT-HOME | Top level of your Ant distribution |
JAVA_HOME | You must have JDK5 installed. |
CATALINA_HOME | Top level of the installed Tomcat server. |
Once these variables are set correctly, building the deployable web-app requires a single ant invocation using the build file at $WEBAPP_DIR/WEB-INF/src/build.xml. This build-file is invoked using ant's -f <buildfile-path> option. The directory of the web app is gleened from the supporting build.properties file. Finally, the clean, build, and war targets are invoked in turn.
ant -f $WEBAPP_DIR/WEB-INF/src/build.xml clean build war
The clean target deletes any old build artifacts from the WEB-INF/classes directory, and other directories.
The build target compiles new build artifacts from the source files.
Finally, the war target zips up the results into a WAR file, named contextPath.war.
Deploying the Web-app
The easiest way to deploy the web-app is to create a symlink/shortcut from $WEBAPP_DIR to $CATALINA_HOME/webapps.
ln -s $WEBAPP_DIR $CATALINA_HOME/webapps
Another way would be to simply copy $WEBAPP_DIR to $CATALINE_HOME/webapps.
cp -R $WEBAPP_DIR $CATALINE_HOME/webapps
Another way is to visit the following link in a browser. This method assumes that you have created the manager role in the configuration file CATALINA_HOME/conf/tomcat-users.xml. For details, see Installation and Setup. <Context-Path> is the desired URL path to the application. <Full-Path-to-Development-Dir> is the location of the application on your machine.
http://localhost:8080/manager/deploy?path=<Context-Path>&war=<Full-Path-to-Development-Dir>&update=true
Next...
Now that you've built and deployed an application, you can see how easy it is to modify the flow between pages, adding and removing pages.