This article is intended as a step by step guide for automating the
construction of a WAR file from your GWT application using an Ant
script. It covers the following steps
- Establishing the project structure
- Compiling the source - Java & Javascript
- Packaging and accessing static resources - Images, CSS, property files
- Packaging the deployment archives - JAR & WAR files
Establishing the project structure
Create a new GWT Web Application project and setup the directory structure as per the following screenshot
com.rubiconred.buildtutorial: This is where the
.gwt.xml module
file lives and we have added a public directory. The public directory
is where we will place all of our static resources (e.g. Image files)
that are accessed directly from within our GWT source code (see further
below).
com.rubiconred.buildtutorial.client: This is
where we place our GWT source code that is not referenced anywhere in
our server code. This code will be compiled to Javascript but not to
.class files. Note that you should not be putting
RemoteService classes in here as these interfaces are implemented by server-side
RemoteServiceServlet classes.
com.rubiconred.buildtutorial.shared: This
is where we place our GWT source code that is referenced by both client
and server code. This code will be compiled to both Javascript and to
.class files. This is the place to put
RemoteService classes.
com.rubiconred.buildtutorial.server: This is where we have access to the full Java APIs and will be the location for our
RemoteServiceServlet classes. This code will not be compiled to Javascript but only to .class files.
Note: To ensure the client & shared packages will both be compiled to Javascript the following must be present in your
.gwt.xml module file (generated by default if using Eclipse plugin)
<!-- Specify the paths for translatable code -->
<source path=
'client'/>
<source path=
'shared'/>
war/client_resources: We will use this directory to store our static resources that are accessed directly from the BuildTutorial.html or BuildTutorial.css files. Remember static resources accessed from within the GWT code should be placed in the public directory as described above.
war/server_resources: We will use this directory to store static resources used by our server code, such as properties or XML files.
build.xml: Create a new file build.xml and
place it on the project root directory. Following is the skeleton of
this build script which we will flesh out over the next few steps to
automate the build and packaging process for us.
<?xml version="1.0"?>
<project name="BuildTutorial" basedir="." default="war">
<target name="prepare"/>
<target name="clean"/>
<!-- Compile the java source code using javac -->
<target name="compile" depends="prepare/">
<!-- Invoke the GWT compiler to create the Javascript for us -->
<target name="gwt-compile" depends="compile"/>
<!-- Package the compiled Java source into a JAR file -->
<target name="jar" depends="compile"/>
<!-- Copy the static server resources into the required
directory ready for packaging -->
<target name="copy-resources"/>
<!-- Package the JAR file, Javascript, static resources
and external libraries into a WAR file -->
<target name="war" depends="gwt-compile, jar, copy-resources"/>
<!-- Deploy the WAR file (optional) -->
<target name="deploy" depends="war"/>
</project>
Compiling the project source
We
will begin by establishing the Ant tasks in our build script that will
compile our source code. For a GWT app this includes the additional task
of invoking the GWT compiler to build our client and shared code to Javascript.
First we should establish the properties that we will reference throughout the build script. Add the following to the top of build.xml and update the property values to match your own project and domain names.
<property name="gwt.module.name" value="com.rubiconred.buildtutorial.BuildTutorial"/>
<property name="server.resources.name" value="server_resources"/>
<property name="jar.name" value="buildtutorial.jar"/>
<property name="war.name" value="buildtutorial.war"/>
<property name="src.dir" location="src"/>
<property name="server.resources.dir" location="war/${server.resources.name}"/>
<property name="build.dir" location="build"/>
<property name="build.server.resources.dir" location="war/WEB-INF/classes/server_resources"/>
<property name="lib.dir" location="war/WEB-INF/lib"/>
<property name="gwt.client.dir" location="com/rubiconred/soauiext/client"/>
Next
add the following to establish the classpath that we will reference
when compiling. Any third party JARs you are using in your project
should be available in the
war/WEB-INF/lib directory.
<path id="project.classpath">
<fileset dir="${lib.dir}">
<include name="**/*.jar"/>
</fileset>
</path>
Setup
Ant tasks to create and delete the build directory. The build directory
is used as a temporary staging area for the compiled source code during
the build process.
<target name="prepare">
<mkdir dir="${build.dir}"/>
</target>
<target name="clean">
<delete dir="${build.dir}"/>
</target>
Next is the Ant task to invoke the Java compiler. Note that while we are compiling everything in the src dir (client, shared, server) later when we package this into the JAR we will exclude the client classes. The client classes are only included here as they are required by the GWT compiler in the next task.
<target name="compile" depends="prepare">
<javac srcdir="${src.dir}" destdir="${build.dir}">
<classpath refid="project.classpath"/>
</javac>
</target>
Now
we are ready to invoke the GWT compiler. In order for the GWT compiler
to work the following JAR files must be on the classpath
Add these files to the
war/WEB-INF/lib directory.
You should find them in your Eclipse installation directory (GWT 2.2)
ECLIPSE_HOME\plugins\com.google.gwt.eclipse.sdkbundle.2.2.0_2.2.0.v201102111811\gwt-2.2.0
<target name="gwt-compile" depends="compile">
<java failonerror="true" fork="true" classname="com.google.gwt.dev.Compiler">
<classpath>
<!-- src dir is added to ensure the module.xml file(s) are on the classpath -->
<pathelement location="${src.dir}"/>
<pathelement location="${build.dir}"/>
<path refid="project.classpath"/>
</classpath>
<jvmarg value="-Xmx256M"/>
<arg value="${gwt.module.name}"/>
</java>
</target>
Packaging and accessing static resources
One
of the trickiest parts of packaging and deploying a GWT app is figuring
out where to place the various types of static resource files and how
to access them in your code so that they can be located after you have
deployed to an application server just as they are in your development
environment. The following list shows a strategy that I have found
effective
Resource Type
Client resources accessed directly within your GWT code
e.g. Image files used by an Image widget
Access Method
Image image =
new Image(GWT.getModuleBaseURL() +
"/images/myImage.png");
Resource Type
Client resources accessed from the HTML or CSS files
Access Method
background-image:
url(client_resources/images/light_blue_vert.png);
Resource Type Server resources accessed from server side code
e.g. Properties file
Access Method
InputStream in =
this.getClass().getClassLoader().getResourceAsStream(
"server_resources/serverProps.properties");
props =
new Properties();
props.load(in);
As part of the build process we need to copy the server_resources into the
WEB-INF/classes directory
so that they will be properly packaged into the WAR file and can be
accessed when we deploy. The following Ant task will take care of this.
It may also be necessary to invoke this target during development to
keep the resource directories in sync so that they can be accessed when
running in development mode too.
<target name="copy-resources">
<copy todir="${build.server.resources.dir}" preservelastmodified="true">
<fileset dir="${server.resources.dir}"/>
</copy>
</target>
Packaging the deployment archives
The first step here is to package the compiled Java source into a JAR file that will then be packaged into the WAR file in the WEB-INF/lib directory as part of the next step. Because we don't want to deploy any unnecessary code to the server we exclude the client classes from the package.
<target name="jar" depends="compile">
<jar jarfile="${lib.dir}/${jar.name}" basedir="${build.dir}/">
<!-- Don't wrap any of the client only code into the JAR -->
<exclude name="${gwt.client.dir}/**/*.class"/>
</jar>
</target>
Now
we are ready to build the WAR file. The following task packages the
JAR, Javascript, static resources and third party JAR files (excluding
gwt-dev.jar & gwt-user.jar) that we established during the previous
build targets into the deployable WAR file that we require.
<target name="war" depends="gwt-compile, jar, copy-resources">
<war basedir="war" destfile="${war.name}" webxml="war/WEB-INF/web.xml">
<exclude name="WEB-INF/**" />
<exclude name="${server.resources.name}/**"/>
<webinf dir="war/WEB-INF/">
<include name="classes/${server.resources.name}/**" />
<include name="**/*.jar" />
<exclude name="**/gwt-dev.jar" />
<exclude name="**/gwt-user.jar" />
</webinf>
</war>
</target>
Final Steps
Run the default task by right clicking on the
build.xml file
and selecting Run As > Ant Build. If you refresh the project
directory in Eclipse you will notice a new build directory containing
your compiled source has been added. You can remove this using the Ant
target
clean if you wish. You will also find
buildtutorial.war has
been added to the root directory of your project. If you copy this WAR
file over to your server and deploy it onto the application server you
will be able to run your GWT app in the deployed environment. It is also
possible to automate the deployment step with Ant but that is beyond
the scope of this article.
And here is the final
build.xml contents
<?xml version="1.0"?>
<project name="BuildTutorial" basedir="." default="war">
<property name="gwt.module.name" value="com.rubiconred.buildtutorial.BuildTutorial"/>
<property name="server.resources.name" value="server_resources"/>
<property name="jar.name" value="buildtutorial.jar"/>
<property name="war.name" value="buildtutorial.war"/>
<property name="src.dir" location="src"/>
<property name="server.resources.dir" location="war/${server.resources.name}"/>
<property name="build.dir" location="build"/>
<property name="build.server.resources.dir" location="war/WEB-INF/classes/server_resources"/>
<property name="lib.dir" location="war/WEB-INF/lib"/>
<property name="gwt.client.dir" location="com/rubiconred/soauiext/client"/>
<path id="project.classpath">
<fileset dir="${lib.dir}">
<include name="**/*.jar"/>
</fileset>
</path>
<target name="prepare">
<mkdir dir="${build.dir}"/>
</target>
<target name="clean">
<delete dir="${build.dir}"/>
</target>
<!-- Compile the java source code using javac -->
<target name="compile" depends="prepare">
<javac srcdir="${src.dir}" destdir="${build.dir}">
<classpath refid="project.classpath"/>
</javac>
</target>
<!-- Invoke the GWT compiler to create the Javascript for us -->
<target name="gwt-compile" depends="compile">
<java failonerror="true" fork="true" classname="com.google.gwt.dev.Compiler">
<classpath>
<!-- src dir is added to ensure the module.xml file(s) are on the classpath -->
<pathelement location="${src.dir}"/>
<pathelement location="${build.dir}"/>
<path refid="project.classpath"/>
</classpath>
<jvmarg value="-Xmx256M"/>
<arg value="${gwt.module.name}"/>
</java>
</target>
<!-- Package the compiled Java source into a JAR file -->
<target name="jar" depends="compile">
<jar jarfile="${lib.dir}/${jar.name}" basedir="${build.dir}/">
<!-- Don't wrap any of the client only code into the JAR -->
<exclude name="${gwt.client.dir}/**/*.class"/>
</jar>
</target>
<!-- Copy the static server resources into the required
directory ready for packaging -->
<target name="copy-resources">
<copy todir="${build.server.resources.dir}" preservelastmodified="true">
<fileset dir="${server.resources.dir}"/>
</copy>
</target>
<!-- Package the JAR file, Javascript, static resources
and external libraries into a WAR file -->
<target name="war" depends="gwt-compile, jar, copy-resources">
<war basedir="war" destfile="${war.name}" webxml="war/WEB-INF/web.xml">
<exclude name="WEB-INF/**" />
<exclude name="${server.resources.name}/**"/>
<webinf dir="war/WEB-INF/">
<include name="classes/${server.resources.name}/**" />
<include name="**/*.jar" />
<exclude name="**/gwt-dev.jar" />
<exclude name="**/gwt-user.jar" />
</webinf>
</war>
</target>
</project>
