Maven's WAR Overlays: How to manage dependencies

If you're stumbling on this post looking for a way to manage dependencies with WAR overlays, please make sure you check out part one of this blog posting to get the background about how to apply and use WAR overlays in your POM file. This post picks up from the last post and it's assumed that you understand how to apply a WAR to an existing master project.

Quick recap

Why a quick recap? We're going to go into depth on how dependencies and libraries are applied to the master project. In order to have a WAR overlay, you must include the WAR as a dependency to the master project and must be overlayed during the war-plugin package phase.

Where do the dependency libraries go?

As mentioned in part one of this blog posting, files are placed in their parent's locations if it exists. What this means is that if, in your overlay WAR you have a .jsp file in /WEB-INF/welcome.jsp, the master WAR will then have a file named "welcome.jsp" in the /WEB-INF. Furthermore, if there is already a file named "welcome.jsp", that file will not be overwritten. If we extrapolate this a bit more, the libraries in the /WEB-INF/lib folder from the overlay will be placed inside the /WEB-INF/lib folder of the master project. This is great and all except when different versions of libraries exist causing runtime failures. Good news, there are ways to manage the dependencies in both the overlay WAR and the master project.

How to see your main artifact's libraries?

In order to determine what libraries are in which artifact, there are two simple ways. First, determine what libraries are in your master WAR.

mvn clean package 

ls -al target/YOUR_ARTIFACT_WAR/WEB-INF/lib

NOTE: adding "-DskipTests" when added to the above maven command would skip tests and would make this step a bit faster, though, it is strictly optional

Secondly, add the "workDirectory" parameter to the configuration portion of your war-plugin when applying the overlay. Example: <workDirectory>target/extract_here</workDirectory>

In your master project's POM file:

<plugins>
...
...
<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1.1</version>
        <configuration>
                <workDirectory>target/overlay-war-folder</workDirectory>
                <overlays>
                        <overlay>
                                <groupId>com.yourcompany</groupId>
                                <artifactId>branded-templates</artifactId>
                        </overlay>
                </overlays>
        </configuration>
</plugin>
...
...
</plugins>

This additional property will place each overlay's exploded contents into the specified folder to help debug library conflicts.

How to exclude dependencies/libraries at build time?

It can be a pain to manage the dependencies between each of the overlays, especially if the overlay is not under your development control. One method would be to manage the dependencies within the two POM files by utilizing the "provided" and "optional" dependencies that maven provides. However, if the overlay project can also stand as stand-alone project, this method will not work because the libraries are not considered to be provided or optional when running independently. This is common when trying to test each of the overlays independently. An additional option to control the libraries is to exclude them from the master WAR during the package phase. This is achieved by using the "excludes" parameter in each of the overlay sections. For example, to remove all of the spring libraries, you could exclude "spring*.jar"

<plugins>
...
...
<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1.1</version>
        <configuration>
                <workDirectory>target/overlay-war-folder</workDirectory>
                <overlays>
                        <overlay>
                                <groupId>com.yourcompany</groupId>
                                <artifactId>branded-templates</artifactId>
                                <excludes>
                                        <exclude>WEB-INF/lib/spring*.jar</exclude>
                                </excludes>
                                <excludes>
                                        <exclude>WEB-INF/lib/log4j*.jar</exclude>
                                </excludes>
                        </overlay>
                </overlays>
        </configuration>
</plugin>
...
...
</plugins>

You might start asking yourself, this is going to get complicated really quickly, and you're right, there are other options.

Skinny vs Fat WAR Overlays

Up until now, all of our overlays have been considered "fat" because they contain all of it's dependencies which get overlaid onto the master WAR file. There is an alternative that is more commonly known as the "skinny WAR". A skinny WAR is a combination between most of this post's tactics. NOTE: The method I am showing you is known as a "skinnier WAR" because the dependency libraries do exist in the overlay's WAR file, however, the classes will be externalized and the libraries can be removed during final packaging of the master project.

Achieving the "skinny WAR"

First, in the overlay project, during the package phase, tell maven to build the project's classes as an extra artifact in addition to the WAR file. This set of classes will become a jar file which will be used as a second dependency in the master project's POM.

In the Overlay's POM file (add to the existing war plugin):

<plugins>
...
...
<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1.1</version>
        <configuration>
                <attachClasses>true</attachClasses>
        </configuration>
</plugin>
...
...
</plugins>

After successfully installing/deploying the overlay project, we will add the classes/jar file and the WAR dependency to the master project's POM file.

In the master project's POM file:

<dependency>  
   <groupId>com.yourcompany</groupId>  
   <artifactId>branded-templates</artifactId>  
   <type>war</type>  
</dependency>  


<dependencies>
...
...
<dependency>
        <groupId>com.yourcompany</groupId>
        <artifactId>branded-templates</artifactId>
        <version>1.1</version>
        <type>war</type>
</dependency>
<dependency>
        <groupId>com.yourcompany</groupId>
        <artifactId>branded-templates</artifactId>
        <version>1.1</version>
        <type>jar</type>
        <classifier>classes</classifier>
</dependency>
...
...
</dependencies>

And finally, combine the excludes learned in the last example section above to exclude all .jar files from the overlay WAR.

<plugins>
...
...
<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>2.1.1</version>
        <configuration>
                <workDirectory>target/overlay-war-folder</workDirectory>
                <overlays>
                        <overlay>
                                <groupId>com.yourcompany</groupId>
                                <artifactId>branded-templates</artifactId>
                                <excludes>
                                        <exclude>WEB-INF/lib/*.jar</exclude>
                                </excludes>
                        </overlay>
                </overlays>
        </configuration>
</plugin>
...
...
</plugins>

NOTE: Dependencies that exist in the Overlay will need to be added as dependencies to the master project because they have been removed from the overlay's /WEB-INF/lib folder. This is the main known risk of using skinny war overlays

Congratulations!

You now have a project with limited library conflicts and can better manager the main project and it's stability.

Thank you for reading part one and this post, part two. Please feel free too leave comments or questions and I will do my best to answer them in a timely manner.

From http://www.ensor.cc/2011/07/mavens-war-overlays-how-to-manage.html