How to get Maven to build your web service into a WAR

It's often desirable to deploy a web service as a complete web application packaged in a web archive (WAR). Maven makes this quite easy so long as you follow its conventions, but those conventions are not well documented. This page lists the steps involved.

I'll use the astrogrid/warehouse project as an example as I'm working on that at present. I'm assuming that the web-app in question is based on Apache-Axis and runs in Jakarta-Tomcat, as is policy for all Astrogrid web-services.

Add source directories

Maven expects to find directories to do with the web-app in your source directory alongside your Java source-tree. You have to create these.

E.g., if you have a directory called

astrogrid/warehouse/src/java

and you have to create

astrogrid/warehouse/src/webapp
astrogrid/warehouse/src/webapp/WEB-INF

Note that webapp is singular, unlike the webapps directory in Tomcat.

Add files from Axis

Some of Axis, notably its jars of Java classes, should be added in by Maven as dependencies. Some, mainly HTML and XML stuff, you need to copy into the source tree of your project.

Copy files from Apache Axis until your source tree follows this pattern:

astrogrid/warehouse/src/webapp/EchoHeaders.jws
astrogrid/warehouse/src/webapp/SOAPMonitorApplet$SOAPMonitorData.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet$SOAPMonitorFilter.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet$SOAPMonitorPage.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet$SOAPMonitorTableModel.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet$SOAPMonitorTextArea.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet$ServiceFilterPanel.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet.class
astrogrid/warehouse/src/webapp/SOAPMonitorApplet.java
astrogrid/warehouse/src/webapp/StockQuoteService.jws
astrogrid/warehouse/src/webapp/WEB-INF/web.xml
astrogrid/warehouse/src/webapp/fingerprint.jsp
astrogrid/warehouse/src/webapp/happyaxis.jsp
astrogrid/warehouse/src/webapp/index.html

All this is going into CVS in your project, so the Java class files are cumbersome. If you don't want to run the SOAP-monitor applet (and it's disabled by default in Axis), then leave them out.

You may wish to edit index.html and web.xml to describe your service instead of simply describing Axis. The HTML file is easy. In web.xml, you would change the display-name element of the web-app in order to get a custom label in Tomcat's manager interface.

Include Axis jars

In order to build against Axis, you should already have dependency statements in project.xml for the various jars, like this:

    <dependency>
      <id>axis</id>
      <version>1.1</version>
    </dependency>

You may have the modern form of this using groupId and artifactId in place in place of id. In either case, maven will not load these jars into the WAR by default.

Edit your project.xml and extend each dependency on a jar used by axis like this:

    <dependency>
      <id>axis</id>
      <version>1.1</version>
      <properties>
        <war.bundle>true</war.bundle>
      </properties>
    </dependency>

to tell Maven to bundle the jar into the WAR.

Add server-config.wsdd

Your web-application needs a configuration file written in Web Services Deploment Descriptor language (WSDD, an XML vocabulary; seems to have been defined by Apache for Axis) that declares your service to the Axis engine. This file is called the deployment descriptor and its name is server-config.wsdd. It goes in the WEB-INF directory of your web application; e.g.

   astrogrid/warehouse/src/webapp/WEB-INF/server-config.wsdd

If you are used to deploying services using Axis' Admin or AdminClient classes, then you will have written WSDD fragments. In that technique, the fragment you provide as deploy.wsdd gets spliced into server-config.wsdd.

When building a Axis web-application in a WAR, the set of services is fixed at coding time, so you can write server-config.wsdd directly, tuning it for your application.

Here's the deployment descriptor for astrogrid/warehouse

• server-config.wsdd: Sample deployment descriptor

It's a copy of the deployment descriptor from a copy of Publisher's AstroGrid Library. Note the terrifying list of obscure settings! No, I don't know what they all do; I copied the file from the data-centre group.

You can create a deployment descriptor as follows if you don't want to code it from scratch.

1. Deploy to Tomcat a standard copy of Axis; the normal context-path is /axis.
2. Write a WSDD fragment that deploys your web service into standard Axis.
3. Deploy your service and check that it works as you expect.
4. Copy $CATALINA_HOME/webapps/axis/WEB-INF/server-config.wsdd to your source tree.

You may still need to alter the deployment descriptor by hand to get all the serialization operations to work, but at least you'll have a skeleton to work from.

Note that there is no WSDD code to undeploy a service. If you want to undeploy the service that you deployed in its own web-application, then you must remove that entire web-application from Tomcat using Tomcat's manager interface.

Maven does not include the deployment descriptor in the WAR by default. To get the descriptor into the WAR, edit project.xml and add this resource declaration:

  <resources>
    <resource>
      <directory>${basedir}</directory>
      <includes>
        <include>src/webapp/WEB-INF/server-config.wsdd</include>
      </includes>
    </resource>
  </resources>

directly inside the project element. If your project.xml already has a resources element, then add the resource element above to the existing resources element; don't add a second resources element.

Build the WAR

The command

   maven clean jar war

should now do what you need. It builds a WAR named according to the project name in your project.xml. E.g.

<project
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="maven-project.xsd">

  <pomVersion>3</pomVersion>
  <id>astrogrid-datawarehouse</id>
  <name>AstroGrid Data Warehouse</name>
  ...

gets you

   astrogrid/warehouse/target/astrogrid-datawarehouse.war

If you want some other name for the web-app (e.g. to shorten the context path when you deploy it), then rename the WAR file before you deploy it into Tomcat.

-- GuyRixon - 03 Dec 2003; updated on 04 Dec 2003

Alternative Approach

An alternative approach that attempts to automate some of the manual steps in this recipe is encapsulated by the Applications integration maven.xml file. The main points of note are

1. The axis files are downloaded fresh at build time (not stored in CVS) - see the axis.unpack goal
2. Dynamic generation of server-config.wsdd with the following fragment

 <java classname="org.apache.axis.utils.Admin"
            dir="${maven.war.webapp.dir}/WEB-INF"
            classpathref="fullapppath" fork="yes" failonerror="true">
        <arg value="server"/>
        <arg value="${generated.dir}/wsdd/ApplicationControllerService/deploy.wsdd"/>
   </java>

-- PaulHarrison - 04 Jan 2004