July 12, 2011

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 manor.

9 comments:

Unknown said...

Mike-
Your maven blog is helping me a bit, but I am struggling with maven. Are you interested in a couple hours of contract work?

Mike! said...

Please contact me at:

mike 'at' clickconcepts {dot} com

Anonymous said...

I have two separate war files that should be deployed independently. (war A and war B)
Now I have requirement war A to use some of the classes (entities, beans) that already exist in war B.
Can you please guide me how to achieve this requirement?

Jas

Mike! said...

Hey Jas,

From what I can tell, it looks like you only need the classes from War B, so what I would do is to publish the classes and then set War A to have a dependency on the classes of War B.

http://communitygrids.blogspot.com/2007/11/maven-making-war-and-jar-at-same-time.html

That blog should help you out, really all you're doing is setting the artifact to be WAR and then creating a JAR as well.

Mike!

Anonymous said...

Thank you for your help Mike. That worked very good.

Jas

Anonymous said...

Hello Mike,

I have one more question regarding the packaging. Apparently the war from which I create also jar (war b) is CDI based and has beans.xml file in WEB-INF.
war a, that has a dependency to jar b, searches this file in META-INF, thinking that the jar is ejb.
I managed to put beans.xml twice in (war b), once in WEB-INF and once in META-INF, and it seems that both of the applications are working fine.
But I am curious if this is a good approach. Do you have any idea how can this be solved? (The idea is to force beans.xml to packaged in META-INF through the maven-jar-plugin, even though the real location is in WEB-INF)

Thank you in advance,
Jas

Chad said...

Mike,
I am a little confused on your Skinny WAR example. So you separate the classes into a JAR, but then excluse the same JAR? Wouldn't it be easier to just exclude the .java/.class files instead?
What am I missing?
Thanks in advance,
-Chad

Anonymous said...

Hi Mike,

is there an easy way to include the sources of the overlayed war's to be able to debug from an IDE like NetBeans?
I already included the source-jar in the local maven-repository and Netbeans picks it up, but cannot resolve the source-file for the classes in WEB-INF/classes...

Thanks,

Markus

Annu S said...

Very Nice Blog!
I have multi-module maven project. I'm using overlay to create single main war from 3 overlay war modules. These 3 overlay modules are using different version of xx.jar file. since I'm overlaying and creating war. My WEB_INF/lib has all 3 version of xx.jar and overlay failing to read from specific version of xx.jar file.
Any suggestions?

~Annu