BundleWorks - Example 4

Examples
#1 - Build Environment
#2 - CI Server
#3 - WebApp Deployment
#4 - WebApp Build

Example 4 - WebApp Build

Overview

This example shows how a developer can bundle a Java web application using the BundleWorks ant tasks. The previous example showed a web application being deployed to multiple environments. This example shows how that same application is built using BundleWorks.

Unlike previous examples which looked at bundles and environments, this example looks at the source files used to build the helloweb web application. The helloweb application is a standard Java web application, with a single servlet class and single JSP page. It is configured by a properties file kept outside the war file. This allows the properties file to be more easily changed, and also allows changes to the properties file to be tracked by BundleWorks.

The web application is built using Ant, a popular build tool for Java developers. The build.xml file used by Ant in this example contains a target named war for building the war file. This target will be familiar to developers who have used Ant to build war files. The build.xml file defines two additional targets which use BundleWorks ant tasks: bundle and dist. The bundle target using the bw.bundle task to bundle the web application. The dist target uses the bw.add and bw.deploy tasks to actually deploy the web application into an environment.

Details

$HOME/ [1]

   projects/

      HelloWeb/ [2]

         bundle/ [3]

            actions/ [4]

               install.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_install_workdir
prompt_for_string "Enter a message to display:" HELLO_MESSAGE
prompt_for_choice "Select a color:" "red orange yellow green blue indigo violet" \
   "Enter selection:" HELLO_COLOR
replace_vars "$WORK_DIR/config/hello.properties"
java_webapp_install_war

               rollback.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

if [ `echo $TO_VERSION | grep '^1.0'` ]; then
   echo "Rolling back to version '$TO_VERSION'"
   remove_property "$WORK_DIR/config/hello.properties" "color"     
fi
java_webapp_rollback_war

               uninstall.sh

#!/bin/sh

. "BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

java_webapp_uninstall_war

               upgrade.sh

#!/bin/sh

. "$BUNDLEWORKS_INCLUDE/java_webapp_funcs.sh"

if [ `echo $FROM_VERSION | grep '^1.0'` ]; then
   echo "Upgrading from version '$FROM_VERSION'"
   prompt_for_choice "Select a color:" "red orange yellow green blue indigo violet" \
      "Enter selection:" color
   add_property "$WORK_DIR/config/hello.properties" "color" "$color"       
fi
java_webapp_upgrade_war

            config/

               hello.properties [5]

message=@{HELLO_MESSAGE}
color=@{HELLO_COLOR}

         lib/

            servlet-api.jar

         src/

            org/

               bundleworks/

                  tutorial/

                     HelloServlet.java

                  util/

                     StringUtils.java

         web/

            hello.jsp

            WEB-INF

               web.xml [6]

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app 
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" 
    "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
    <display-name>HelloWeb1</display-name>
    <description>Sample Web Application for BundleWorks</description>

    <context-param>
        <param-name>config.dir</param-name>
        <param-value>
            ${ENVIRONMENT_HOME}/helloweb/work/config
        </param-value>
    </context-param>

    <servlet>
        <servlet-name>hello</servlet-name>
        <description>Hello Servlet</description>
        <servlet-class>
            org.bundleworks.tutorial.HelloServlet
        </servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>hello</servlet-name>
        <url-pattern>/sayhello</url-pattern>
    </servlet-mapping>

</web-app>

         build.properties [7]

bundle.name=helloweb
bundle.version=2.0rc1

         build.xml [8]

<?xml version="1.0"?>
<project name="HelloWeb" default="bundle" basedir=".">
   <taskdef resource="org/bundleworks/ant/antlib.xml" />
   <property file="common.properties" />
   <property file="build.properties" />

   <target name="init">
      <mkdir dir="${build.dir}" />
   </target>

   <target name="war" depends="init">
      <property name="war.build.dir" location="${build.dir}/war" />
      <property name="war.dest.dir" location="${shared.dir}/war" />
      <mkdir dir="${war.build.dir}" />
      <copy todir="${war.build.dir}">
         <fileset dir="${web.dir}">
            <include name="**/**" />
         </fileset>
      </copy>
      <mkdir dir="${war.build.dir}/WEB-INF/classes" />
      <javac srcdir="${src.dir}" destdir="${war.build.dir}/WEB-INF/classes">
         <classpath location="${lib.dir}/servlet-api.jar" />
      </javac>
      <mkdir dir="${war.dest.dir}" />
      <jar destfile="${war.dest.dir}/${bundle.name}.war" basedir="${build.dir}/war" />
   </target>

   <target name="clean">
      <delete dir="${build.dir}" />
   </target>

   <target name="bundle" depends="clean, war">
      <bw.bundle bundler="java-webapp" dest="${dist.dir}" format="tgz" 
         name="${bundle.name}" version="${bundle.version}">
         <define name="bundle.dir" value="${bundle.dir}" />
         <define name="shared.dir" value="${shared.dir}" />
      </bw.bundle>
   </target>

   <target name="dist" depends="bundle">
      <bw.add archive="${dist.dir}/${bundle.name}-${bundle.version}.tgz" 
         path="/opt/bundles" />
      <bw.deploy bundle="/opt/bundles/${bundle.name}/${bundle.version}" 
         environment="/var/env/dev" input="upgrade.in" />
   </target>
</project>

         common.properties [9]

dist.dir=${user.home}/dist
src.dir=src
lib.dir=lib
web.dir=web
build.dir=build
bundle.dir=bundle
shared.dir=${build.dir}/shared

         upgrade.in [10]

This example uses the user's home directory to contain all source files. Typically, these files are kept under source code control and checked out to a local directory for development.
The HelloWeb directory contains all of the files need to build the helloweb application. This includes source files (src), libraries (lib), jsp pages (web), and build files. These are found in most, if not all, web application projects and are not BundleWorks-specific.
The HelloWeb directory also contains a bundle directory for storing bundle scripts and configuration. This directory is used to create a BundleWorks bundle.
The actions directory contains the scripts needed to install, uninstall, upgrade, and rollback the helloweb application. If these scripts are not provided, BundleWorks will generate standard ones based on the specified bundler. In this example, scripts are provided since they perform additional tasks like prompting for values that are not part of the standard Java webapp scripts.
The hello.properties file here is a template configuration file. It contains the tokens @{HELLO_MESSAGE} and @{HELLO_COLOR}, which are replaced with values entered by the user during installation. This is done in the install.sh script using the built-in BundleWorks functions prompt_for_string, prompt_for_choice, and replace_vars.
The web.xml for this web application is standard. The following context parameter define inside the web.xml file is related to BundleWorks:
```
    <context-param>
        <param-name>config.dir</param-name>
        <param-value>
            ${ENVIRONMENT_HOME}/helloweb/work/config
        </param-value>
    </context-param>
```
The parameter value contains ${ENVIRONMENT_HOME}, which is replaced inside the helloweb servlet with the value of the environment variable "ENVIRONMENT_HOME". This environment variable is set by BundleWorks when an instance of Tomcat is started (or when any other deployment action is run). This allows all web applications running in that instance of Tomcat to locate configuration files. Similarly, this environment variable can be used to choose a directory for log files.
This build.properties file contains two properties used by build.xml file: bundle.name and bundle.version. These are passed to the bw.bundle ant task to build the web application bundle.
The build.xml file is file used by Ant to build the web application and create the BundleWorks bundle. It includes the following targets: init, war, clean, bundle, and dist. These targets rely on properties set inside build.properties and common.properties. Two of these targets, bundle and dist, use BundleWorks ant tasks. These are shown here:
```
   <target name="bundle" depends="clean, war">
      <bw.bundle bundler="java-webapp" dest="${dist.dir}" format="tgz" 
         name="${bundle.name}" version="${bundle.version}">
         <define name="bundle.dir" value="${bundle.dir}" />
         <define name="shared.dir" value="${shared.dir}" />
      </bw.bundle>
   </target>

   <target name="dist" depends="bundle">
      <bw.add archive="${dist.dir}/${bundle.name}-${bundle.version}.tgz" 
         path="/opt/bundles" />
      <bw.deploy bundle="/opt/bundles/${bundle.name}/${bundle.version}" 
         environment="/var/env/dev" input="upgrade.in" />
   </target>
```
These targets rely on BundleWorks ant tasks (bw.bundle, bw.add, and bw.deploy) to not only build the web application bundle but to deploy it to an environment (/var/env/dev, in this case). The following line at the start of the build.xml 'imports' the BundleWorks tasks for use by Ant:
```
   <taskdef resource="org/bundleworks/ant/antlib.xml" />
```
One difference between using BundleWorks commands at the command line and the equivalent BundleWorks ant tasks is that the ant tasks do not prompt for confirmation, as they are assumed to be running in a script that may be unattended. This can be an issue during deployment of bundles that prompt for values. This is handled by the input property which can be used to specify input from a file and not a user. In the 'dist' target above, the bw.deploy task sets input to 'upgrade.in' to fill in the any values needed during an upgrade from this file.
The common.properties contains properties used by the build.xml file. This file defines standard locations for source files, libraries, etc.
The upgrade.in file was discussed in note #8. This file is use to fill in values prompted by upgrade script of the helloweb 2.0 application. In this case, there is only one value (number of color choice) that is needed.