WAR Notes

Russell Bateman
January 2013
last update: 03/25/2022 16:31:32

Hierarchical JARs

It's very conveniently self-documenting to subsume JAR files in a project under subdirectories named for the origin of those JARs. However, ...

Because the Java class loader doesn't search recursively all subdirectories, when you deploy a WAR file with such hierarchically arranged JARs, you will not get them: their symbols will go missing.

  $ jar -xf project.war
  $ tree WEB-INF/lib
  WEB-INF/lib
  |-- ant-contrib
  |   `-- ant-contrib-1.0b3.jar
  |-- ant-tasks
  |   `-- sqlscriptpreprocessor.jar
  |-- apache
  |   |-- commons-collections-3.1.jar
  |   |-- commons-configuration-1.7.jar
  |   |-- commons-lang-2.6.jar
  |   |-- log4j-1.2.16.jar
  |   `-- servlet-api.jar
  |-- gson
  |   `-- gson-1.7.1.jar
  |-- hibernate
  |   |-- antlr-2.7.6.jar
  |   |-- c3p0-0.9.1.jar
  |   |-- hibernate3.jar
  |   |-- hibernate-jpa-2.0-api-1.0.1.Final.jar
  |   |-- javassist-3.12.0.GA.jar
  |   |-- jta-1.1.jar
  |   |-- slf4j-api-1.6.1.jar
  |-- jboss
  |   `-- webplatform-servicelocator-1.0.jar
  |-- jersey
  |   |-- asm-3.1.jar
  |   |-- jersey-client-1.6.jar
  |   |-- jersey-core-1.6.jar
  |   |-- jersey-json-1.6.jar
  |   |-- jersey-server-1.6.jar
  |   |-- oauth-server-1.10.jar
  |   `-- oauth-signature-1.10.jar
  |-- mockito
  |   |-- mockito-all-1.8.5.jar
  |   `-- powermock-mockito-1.4.9-full.jar
  |-- mongo
  |   |-- mongo-2.6.3.jar
  |   `-- morphia-0.99.jar
  |-- mysql
  |   `-- mysql-connector-java-5.1.16-bin.jar
  |-- postgres
  |   `-- postgresql-9.1-901.jdbc4.jar
  `-- spring
      `-- org.springframework.transaction-3.0.6.RELEASE.jar

  12 directories, 30 files

No, this will never work. Instead, you must copy all of the JARs to some flat place and thence include them in the WAR. Here are some targets to put into build.xml to achieve this in bold below. The very cookie jar itself is in green.

    ...
    <property name="deployed_libraries" value="deployed-libraries" />
    ...

    <target name="clean">
        <echo message="==== Cleaning up old targets... ====" />
        ...
        <delete dir="${deployed_libraries}" />   <!-- Remove deployed_libraries subdirectory if there -->
        ...
        <echo message="==== Cleaning complete ====" />
    </target>

    <target name="init" depends="clean">
        <echo message="==== Initializing... ====" />
        ...
        <mkdir dir="${deployed_libraries}" />    <!-- Create deployed_libraries subdirectory -->
        ...
        <echo message="==== Initialization complete ====" />
    </target>

    <target name="deploy" depends="compile,updatedb">
        <echo message="==== Creating WAR file and deploying... ====" />
        <!-- Copy all the files needed to build WAR: -->
        <copy todir="${build}/classes/resources">
            <fileset dir="${src}/resources">
            <include name="**/*" />
        </fileset>
        </copy>
        <copy file="${src}/log4j.properties" todir="${build}/classes"/>
        <copy file="webplatform-servicelocator.log" todir="${build}/classes"/>

        <copy todir="${deployed_libraries}" flatten="true">
            <fileset dir="${lib}">
                <include name="**/*.jar" />
                <exclude name="**/*ant-contrib*" />    <!-- only used by build.xml -->
                <exclude name="**/*sqlscript*" />      <!-- only used by build.xml -->
                <exclude name="**/*mockito*" />        <!-- only used in testing -->
            </fileset>
        </copy>

        <war destfile="${dist}/blackpearl.war" webxml="${web}/WEB-INF/web.xml">
            <fileset dir="${web}" />
            <lib dir="${deployed_libraries}" />
            <classes dir="${build}/classes/" />
            <manifest>
                 <attribute name="Built-By"               value="Snapfish Web Platform Team" />
                 <attribute name="Implementation-Title"   value="User Account Service" />
                 <attribute name="Implementation-Version" value="0.9" />
                 <attribute name="Implementation-Vendor"  value="Hewlett-Packard Development Company, LP." />
             </manifest>
        </war>

        <copy file="${dist}/blackpearl.war" todir="${deploy}" />
        <echo message="==== Deploy complete ====" />
    </target>

Once the lib subdirectory is flattened and unused JARs are excluded, this is the result.

  $ jar -xf project.war
  $ tree WEB-INF/lib
  WEB-INF/lib
  |-- antlr-2.7.6.jar
  |-- asm-3.1.jar
  |-- c3p0-0.9.1.jar
  |-- commons-collections-3.1.jar
  |-- commons-configuration-1.7.jar
  |-- commons-lang-2.6.jar
  |-- gson-1.7.1.jar
  |-- hibernate3.jar
  |-- hibernate-jpa-2.0-api-1.0.1.Final.jar
  |-- javassist-3.12.0.GA.jar
  |-- jersey-client-1.6.jar
  |-- jersey-core-1.6.jar
  |-- jersey-json-1.6.jar
  |-- jersey-server-1.6.jar
  |-- jta-1.1.jar
  |-- log4j-1.2.16.jar
  |-- mongo-2.6.3.jar
  |-- morphia-0.99.jar
  |-- mysql-connector-java-5.1.16-bin.jar
  |-- oauth-server-1.10.jar
  |-- oauth-signature-1.10.jar
  |-- org.springframework.transaction-3.0.6.RELEASE.jar
  |-- postgresql-9.1-901.jdbc4.jar
  |-- servlet-api.jar
  |-- slf4j-api-1.6.1.jar
  `-- webplatform-servicelocator-1.0.jar

MANIFEST.MF information

Without further specification, the maven-war-plugin generates the following information:

Manifest-Version
Created-By Apache Maven + version number
Build-Jdk + the Java version

The manifest generated by the maven-war-plugin contains the following bits of information derived from the noted Maven property.

Manifest property	Corresponding Maven property
`Manifest-Version`
`Created-By: Apache Maven`	`${maven.version}`
`Build-Jdk`	`${java.version}`
`Specification-Title`	`${project.name}`
`Specification-Version`	`${project.artifact.selectedVersion.majorVersion}` . `${project.artifact.selectedVersion.minorVersion}`
`Specification-Vendor`	`${project.organization.name}`
`Implementation-Title`	`${project.name}`
`Implementation-Version`	`${project.version}`
`Implementation-Vendor`	`${project.organization.name}`

Reading MANIFEST.MF...

You might wish to do this in order to display some copyright and status information at some point in your web application, something like this:

view source
print?
01.protected static String readManifest( ServletContext servletContext )
02.{
03.  StringBuilder sb = new StringBuilder();
04. 
05.  try
06.  {
07.    Manifest   manifest   = new Manifest( servletContext.getResourceAsStream( MANIFEST_PATH ) );
08.    Attributes attributes = manifest.getMainAttributes();
09.    String     line;
10. 
11.    if( isNotEmpty( line = attributes.getValue( "Manifest-Version" ) ) )
12.      sb.append( "        Manifest-Version: " ).append( line ).append( '\n' );
13.    if( isNotEmpty( line = attributes.getValue( "Implementation-Title" ) ) )
14.      sb.append( "    Implementation-Title: " ).append( line ).append( '\n' );
15.    if( isNotEmpty( line = attributes.getValue( "Implementation-Version" ) ) )
16.      sb.append( "  Implementation-Version: " ).append( line ).append( '\n' );
17.    if( isNotEmpty( line = attributes.getValue( "Specification-Title" ) ) )
18.      sb.append( "     Specification-Title: " ).append( line ).append( '\n' );
19.    if( isNotEmpty( line = attributes.getValue( "Implementation-Vendor-Id" ) ) )
20.      sb.append( "Implementation-Vendor-Id: " ).append( line ).append( '\n' );
21.    if( isNotEmpty( line = attributes.getValue( "Build-Time" ) ) )
22.      sb.append( "              Build-Time: " ).append( line ).append( '\n' );
23.    if( isNotEmpty( line = attributes.getValue( "Created-By" ) ) )
24.      sb.append( "              Created-By: " ).append( line ).append( '\n' );
25.    if( isNotEmpty( line = attributes.getValue( "Build-Jdk" ) ) )
26.      sb.append( "               Build-JDK: " ).append( line ).append( '\n' );
27.    if( isNotEmpty( line = attributes.getValue( "Specification-Version" ) ) )
28.      sb.append( "   Specification-Version: " ).append( line ).append( '\n' );
29. 
30.    return sb.toString();
31.  }
32.  catch( IOException ex )
33.  {
34.    return "Problem reading META-INF/MANIFEST.MF";
35.  }
36.}
37. 
38.private static boolean isNotEmpty( final String string )
39.{
40.  return ( nonNull( string ) && string.length() > 0 );
41.}

Naming the WAR file in Maven

This is only a matter of configuration of maven-war-plugin. Here is a sample pom.xml. (Sorry for the mess; it's a very old, working file that I'm not going to clean up.) Highlighted are the relevant contributing lines to naming the WAR file.

view source
print?
001.<?xml version="1.0" encoding="UTF-8"?>
002.<project xmlns="http://maven.apache.org/POM/4.0.0"
003.         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
004.         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
005.                             http://maven.apache.org/xsd/maven-4.0.0.xsd">
006. 
007.  <modelVersion>4.0.0</modelVersion>
008.  <groupId>com.windofkeltia.mdht</groupId>
009.  <artifactId>hl7v3-generator</artifactId>
010.  <version>3.2.0</version>
011.  <packaging>war</packaging>
012. 
013.  <properties>
014.    <!-- JEE and Java-relevant versions: -->
015.    <jersey2.version>2.27</jersey2.version>
016.    <jersey-bundle.version>1.19.4</jersey-bundle.version>
017.    <jaxrs.version>2.0.1</jaxrs.version>
018.    <servlet-api.version>4.0.0</servlet-api.version>
019.    <logback-version>1.2.3</logback-version>
020.    <slf4j.version>1.7.7</slf4j.version>
021.    <log4j.version>1.2.17</log4j.version>
022.    <junit.version>4.12</junit.version>
023.    <restassured.version>2.9.0</restassured.version>
024.    <maven-antrun-plugin.version>3.0.0</maven-antrun-plugin.version>
025.    <maven-compiler-plugin.version>3.2</maven-compiler-plugin.version>
026.    <maven-javadoc-plugin.version>3.2.0</maven-javadoc-plugin.version>
027.    <maven-war-plugin.version>3.2.0</maven-war-plugin.version>
028.    <maven-surefire-plugin.version>2.21.0</maven-surefire-plugin.version>
029.    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
030. 
031.    <!-- MDHT, Eclipse and other MDHT-relevant versions: -->
032.    <eclipse-emf.version>2.12.0.v20160420-0247</eclipse-emf.version>
033.    <eclipse-mdht.version>3.0.0.201802220601</eclipse-mdht.version>
034.    <openhealthtools.version>3.0.3.20180222</openhealthtools.version>
035.  </properties>
036. 
037.  <repositories>
038.    <repository>
039.      <!-- These are the dependencies listed as "MDHT third-party, Core, CDA, etc." -->
040.      <id>MDHT libraries (static)</id>
041.      <name>mdht</name>
042.      <url>file://${project.basedir}/lib</url>
043.    </repository>
044.  </repositories>
045. 
046.  <dependencies>
047.    <dependency>
048.      <groupId>com.sun.jersey</groupId>
049.      <artifactId>jersey-bundle</artifactId>
050.      <version>${jersey-bundle.version}</version>
051.    </dependency>
052.    <dependency>
053.      <groupId>javax.activation</groupId>
054.      <artifactId>activation</artifactId>
055.      <version>1.1.1</version>
056.    </dependency>
057.    <dependency>
058.      <groupId>javax.servlet</groupId>
059.      <artifactId>javax.servlet-api</artifactId>
060.      <version>${servlet-api.version}</version>
061.      <scope>provided</scope>   <!-- (provided by Tomcat) -->
062.    </dependency>
063.    <dependency>
064.      <groupId>com.sun.xml.bind</groupId>
065.      <artifactId>jaxb-core</artifactId>
066.      <version>2.3.0.1</version>
067.    </dependency>
068.    <dependency>
069.      <groupId>javax.xml.bind</groupId>
070.      <artifactId>jaxb-api</artifactId>
071.      <version>2.3.1</version>
072.    </dependency>
073.    <dependency>
074.      <groupId>com.sun.xml.bind</groupId>
075.      <artifactId>jaxb-impl</artifactId>
076.      <version>2.3.1</version>
077.    </dependency>
078. 
079.    <!-- MDHT third-party dependencies -->
080.    <dependency>
081.      <groupId>lpg.runtime.java</groupId>
082.      <artifactId>lpg.runtime.java</artifactId>
083.      <version>2.0.17.v201004271640</version>
084.    </dependency>
085.    <dependency>
086.      <groupId>org.eclipse.emf.ecore.xmi</groupId>
087.      <artifactId>org.eclipse.emf.ecore.xmi</artifactId>
088.      <version>${eclipse-emf.version}</version>
089.    </dependency>
090.    <dependency>
091.      <groupId>org.eclipse.emf.ecore</groupId>
092.      <artifactId>org.eclipse.emf.ecore</artifactId>
093.      <version>${eclipse-emf.version}</version>
094.    </dependency>
095.    <dependency>
096.      <groupId>org.eclipse.emf.common</groupId>
097.      <artifactId>org.eclipse.emf.common</artifactId>
098.      <version>${eclipse-emf.version}</version>
099.    </dependency>
100.    <dependency>
101.      <groupId>org.eclipse.ocl</groupId>
102.      <artifactId>org.eclipse.ocl</artifactId>
103.      <version>3.6.0.v20160523-1914</version>
104.    </dependency>
105.    <dependency>
106.      <groupId>org.eclipse.ocl.common</groupId>
107.      <artifactId>org.eclipse.ocl.common</artifactId>
108.      <version>1.4.0.v20160521-2033</version>
109.    </dependency>
110.    <dependency>
111.      <groupId>org.eclipse.ocl.ecore</groupId>
112.      <artifactId>org.eclipse.ocl.ecore</artifactId>
113.      <version>3.6.0.v20160523-1914</version>
114.    </dependency>
115.    <dependency>
116.      <groupId>org.eclipse.uml2.common</groupId>
117.      <artifactId>org.eclipse.uml2.common</artifactId>
118.      <version>2.1.0.v20170227-0935</version>
119.    </dependency>
120.    <dependency>
121.      <groupId>org.eclipse.uml2.types</groupId>
122.      <artifactId>org.eclipse.uml2.types</artifactId>
123.      <version>2.0.0.v20170227-0935</version>
124.    </dependency>
125. 
126.    <!-- MDHT Core dependencies -->
127.    <dependency>
128.      <groupId>org.eclipse.mdht.emf.runtime</groupId>
129.      <artifactId>org.eclipse.mdht.emf.runtime</artifactId>
130.      <version>${eclipse-mdht.version}</version>
131.    </dependency>
132. 
133.    <!-- MDHT CDA dependencies -->
134.    <dependency>
135.      <groupId>org.eclipse.mdht.uml.hl7.vocab</groupId>
136.      <artifactId>org.eclipse.mdht.uml.hl7.vocab</artifactId>
137.      <version>${eclipse-mdht.version}</version>
138.    </dependency>
139.    <dependency>
140.      <groupId>org.eclipse.mdht.uml.hl7.datatypes</groupId>
141.      <artifactId>org.eclipse.mdht.uml.hl7.datatypes</artifactId>
142.      <version>${eclipse-mdht.version}</version>
143.    </dependency>
144.    <dependency>
145.      <groupId>org.eclipse.mdht.uml.hl7.rim</groupId>
146.      <artifactId>org.eclipse.mdht.uml.hl7.rim</artifactId>
147.      <version>${eclipse-mdht.version}</version>
148.    </dependency>
149.    <dependency>
150.      <groupId>org.eclipse.mdht.uml.cda</groupId>
151.      <artifactId>org.eclipse.mdht.uml.cda</artifactId>
152.      <version>${eclipse-mdht.version}</version>
153.    </dependency>
154. 
155.    <!-- MDHT CDA Implementation Guide dependencies -->
156.    <dependency>
157.      <groupId>org.openhealthtools.mdht.uml.cda.consol2</groupId>
158.      <artifactId>org.openhealthtools.mdht.uml.cda.consol2</artifactId>
159.      <version>${openhealthtools.version}</version>
160.    </dependency>
161. 
162.    <!-- HL7 CDA dependencies -->
163.    <dependency>
164.      <groupId>org.hl7.cbcc.privacy.consentdirective</groupId>
165.      <artifactId>org.hl7.cbcc.privacy.consentdirective</artifactId>
166.      <version>1.0.0.20170920</version>
167.    </dependency>
168.    <dependency>
169.      <groupId>org.hl7.security.ds4p.contentprofile</groupId>
170.      <artifactId>org.hl7.security.ds4p.contentprofile</artifactId>
171.      <version>3.0.0.20170920</version>
172.    </dependency>
173. 
174.    <!-- Various other dependencies -->
175.    <dependency>
176.      <groupId>ch.qos.logback</groupId>
177.      <artifactId>logback-classic</artifactId>
178.      <version>${logback-version}</version>
179.      <exclusions>
180.        <exclusion>
181.          <groupId>org.slf4j</groupId>
182.          <artifactId>slf4j-log4j12</artifactId>
183.        </exclusion>
184.      </exclusions>
185.    </dependency>
186.    <dependency>
187.      <!-- provide HTTP-access log functionality -->
188.      <groupId>ch.qos.logback</groupId>
189.      <artifactId>logback-access</artifactId>
190.      <version>${logback-version}</version>
191.    </dependency>
192.    <dependency>
193.      <groupId>org.slf4j</groupId>
194.      <artifactId>slf4j-api</artifactId>
195.      <version>${slf4j.version}</version>
196.    </dependency>
197.    <dependency>
198.      <groupId>log4j</groupId>
199.      <artifactId>log4j</artifactId>
200.      <version>${log4j.version}</version>
201.    </dependency>
202.    <dependency>
203.      <groupId>junit</groupId>
204.      <artifactId>junit</artifactId>
205.      <version>${junit.version}</version>
206.      <scope>test</scope>
207.    </dependency>
208.  </dependencies>
209. 
210.  <build>
211.    <finalName>mdht-restlet</finalName>
212.    <plugins>
213.      <plugin>
214.        <groupId>org.apache.maven.plugins</groupId>
215.        <artifactId>maven-compiler-plugin</artifactId>
216.        <configuration>
217.          <source>1.8</source>
218.          <target>1.8</target>
219.        </configuration>
220.        <version>${maven-compiler-plugin.version}</version>
221.      </plugin>
222.      <plugin>
223.        <groupId>org.apache.maven.plugins</groupId>
224.        <artifactId>maven-war-plugin</artifactId>
225.        <version>${maven-war-plugin.version}</version>
226.        <configuration>
227.          <warName>${project.artifactId}-${project.version}</warName>
228.          <webResources>
229.            <resource>
230.              <!-- this is relative to the pom.xml directory -->
231.              <directory>src/main/webapp</directory>
232.            </resource>
233.          </webResources>
234. 
235.          <!-- Magic for maintaining a build timestamp in MANIFEST.MF: -->
236.          <archive>
237.            <manifest>
238.              <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
239.              <addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
240.            </manifest>
241.            <manifestEntries>
242.              <Build-Time>${maven.build.timestamp}</Build-Time>
243.            </manifestEntries>
244.          </archive>
245. 
246.        </configuration>
247.      </plugin>
248.      <plugin>
249.        <groupId>org.apache.maven.plugins</groupId>
250.        <artifactId>maven-antrun-plugin</artifactId>
251.        <version>${maven-antrun-plugin.version}</version>
252.        <executions>
253.          <execution>
254.            <phase>compile</phase>
255.            <configuration>
256.              <target>
257.                <!-- How to echo out properties and their definitions; uncomment this!
258.                <echoproperties /> -->
259.              </target>
260.            </configuration>
261.            <goals>
262.              <goal>run</goal>
263.            </goals>
264.          </execution>
265.        </executions>
266.      </plugin>
267.      <plugin>
268.        <groupId>org.apache.maven.plugins</groupId>
269.        <artifactId>maven-surefire-plugin</artifactId>
270.        <version>${maven-surefire-plugin.version}</version>
271.        <configuration>
272.          <systemPropertyVariables>
273.            <catalina.home>${project.build.directory}</catalina.home>
274.            <buildDirectory>${project.build.directory}</buildDirectory>
275.          </systemPropertyVariables>
276.        </configuration>
277.      </plugin>
278.      <plugin>
279.        <groupId>org.apache.maven.plugins</groupId>
280.        <artifactId>maven-javadoc-plugin</artifactId>
281.        <version>${maven-javadoc-plugin.version}</version>
282.        <configuration>
283.          <noqualifier>all</noqualifier>
284.          <destDir>javadoc</destDir>
285.          <show>private</show>
286.        </configuration>
287.        <executions>
288.          <execution>
289.            <id>aggregate</id>
290.            <goals>
291.              <goal>aggregate</goal>
292.            </goals>
293.            <configuration>
294.              <reportOutputDirectory>${user.dir}</reportOutputDirectory>
295.              <destDir>javadoc</destDir>
296.            </configuration>
297.          </execution>
298.        </executions>
299.      </plugin>
300.    </plugins>
301.  </build>
302.</project>

Adding version to the WAR name has consequences...

This results (against Tomcat, at least) in needing to use the version also in the URL:

http://hostname:port/hl7v3-generator-3.2.0

This is not handy because (HTTP-client) code will have to be updated to reflect this. Instead, Tomcat Parallel deployment suggests this naming scheme:


<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-war-plugin</artifactId>
  <version>${maven-war-plugin.version}</version>
  <configuration>
    <warName>${project.artifactId}##${project.version}</warName>
    <webResources>
      <resource>
        <!-- this is relative to the pom.xml directory -->
        <directory>src/main/webapp</directory>
      </resource>
    </webResources>
    ...

...which results in a name like hl7v4-generator##3.2.0. This is ugly, but it still accomplishes the same goal of advertising the version. And, for the URL, everything past and also the ## will not be required.

Tomcat's deployment will respect the basic name (hl7v3-generator). Also, multiple deployments will accumulate in /opt/tomcat/webapps and you must delete them, but, if you do not delete them or you delete them slowly or cautiously, you will have the older versions to go back to. That might be a good thing. Meanwhile, when you bump the version and deploy, your requests will go to the latest (there are some caveats—read the link above).