Java & Maven variant

Overview

Project lead: Eric Ehret (@eehret)

Purpose

The Java & Maven variant is essentially a bundling of WET as a Maven module called a 'WAR overlay'. There is a WAR overlay for each available WET theme.

Providing WET for Java Web applications in this fashion provides the following main benefits:

  • Makes adoption of WET simpler, for anyone already using Maven
  • Specific version of WET can be clearly identified in your project metadata
  • Updates to WET are made easier; in some cases if the changes are minor it may be as simple as incrementing the version number and rebuilding your application

Background on Maven

For those unfamiliar with Maven, it is a tool similar to Ant in some respects, but with many other capabilities that help developers with things like dependency management, project structure consistency, quality control, and code modularity and reuse.

With Maven, a project is described by metadata, contained within a Project Object Model (POM) file. This metadata provides lots of useful information about the project, both technical and non-technical, including:

  • Project description
  • Main contact information
  • Location of source code (GitHub or SVN coordinates, for example)
  • Location of continuous integration server
  • List of developers and contributors
  • Dependencies required to build the project
  • and more...

Maven integrates with many different tools and technologies, and can provide powerful benefits in terms of configuration management of a project. With Maven, you can specify exactly which versions of different Java libraries your project depends on. Since this metadata is typically captured within your VCS, and tagged along with your releases, you will have the confidence of being able to rebuild your project any time with the correct libraries that you used at that point in time.

A lot of projects use Maven, and just about any Java open source component can be found online in the Maven Central repository. Maven is increasing in popularity, as indicated by Google Trends.

For more information about Maven, please see the official site, located at maven.apache.org.

Implementation

If you use Maven, this means that you can include WET as a Maven dependency simply by providing the appropriate dependency information in the <dependencies> section of your POM file, like so:

<dependency>
    <groupId>com.github.wet-boew</groupid>
    <artifactId>wet-gcwu-intranet-theme-overlay</artifactid>
    <version>3.0.3</version>
    <type>war</type>
    <scope>runtime</scope>
</dependency>

In this case we've specified the GC Web Usability Intranet theme from WET as a dependency. That's fine, but doing this alone will not affect the WEB-INF folder of your Java web application. What you probably want to do is "overlay" this dependency onto your project, hence the term 'WAR overlay'. What you can do is tell Maven to take the WET theme overlay you've specified as a dependency, extract it, and combine it with the code from your own project. This is done like so:

<build>
...
    <pluginManagement>
        <plugins>

            <plugin>
                <groupId>org.apache.maven.plugins</groupid>
                <artifactId>maven-war-plugin</artifactid>
                <configuration>
                    <overlays>
                        <overlay>
                            <groupId>com.github.wet-boew</groupid>
                            <artifactId>wet-gcwu-intranet-theme-overlay</artifactid>
                            <targetPath>static/WET</targetpath>
                        </overlay>
                    </overlays>
                </configuration>
            </plugin>
        </plugins>
    </pluginmanagement>
...
</build>

Notice above that within the <overlay> section, a <targetPath> is specified. If a <targetPath> is specified, then instead of the WAR contents being extracted under WEB-INF, they will be extracted under WEB-INF/<targetPath>. This is recommended so that you can maintain a clean separation between your own code and WET. Furthermore, having a dedicated folder under WEB-INF for static content will allow you to configure a caching strategy very easily, enhancing the performance of your application.

When you build your application, you should now find the folder indicated by <targetPath> in your WAR file, containing WET.

Be aware that if you happen to have some other content in your project, in the same location as the content from WET (e.g. /static/WET), by default the content from your project will override the content from the overlay. When the WET overlay is applied, those files will be skipped. This default behaviour can be changed, but requires additional configuration of the maven-war-plugin, which is beyond the scope of these instructions.

For more information, please read the Maven documentation on overlays.

Artifacts at the Maven Central Repository

Overlays