Maven secrets: assembling a WCB zip

WCB distribution guidelines

The official WCB development guidelines define that a WCB must be distributed as a zip archive that contains several additional (documentation) resources. Obviously this is not required to build and run your project, but when you want to certify the WCB or publish it on WCMExchange this is what you need to do. In short the guidelines define the following minimal layout:

     /bin             contains the WCB
     /doc             contains the javadoc
     /readme.txt      readme file
     /changelog.txt   changelog file

Wouldn't is be nice if this could be filtered and packaged all in one go? Well, guess what..

The default WCB Maven project

When creating a WCB in the SDK by default you use a standard Maven project, as  defined by the archetype, with packaging type osgi-bundle. This means that during the build packaging will be handled by the Apache Felix OSGi plugin that will create a valid OSGi bundle that can be deployed into the GX WebManager OSGi runtime. This is very nice because it saves a lot of manual labor, but it does not provide you with a complete zip distribution. You need the additional resources and then put it all together. Doing that by hand would be... well silly.

A small sidestep. Before we can start building the zip distribution we need to have the additional resources present in the build somewhere. Let have a quick look at how to do that.

First, the readme.txt and changelog.txt are resources that need to be maintained by hand (although you can obviously filter them during build time to substitude version numbers etc). Put them in the source tree somewhere. I will assume that they are under src/main/doc in the following examples.

Second, the javadoc has to be generated. You may do that in advance by calling the javadoc plugin by hand, but here is how you attach this to the standard package phase so that it will be generated on the fly when you package your project.

<project...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
        <executions>
          <execution>
            <id>create-javadocjar</id>
            <phase>compile</phase>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

Note: due to a small inheretence problem in the standard WCB parent pom, for now, you will have to add the following snippet as well.This is a known issues and reported under GXWM-4679.

<project...>
  ...
  <reporting>
  ...
    <plugins>
  ...
      <plugin>
        <artifactId>maven-javadoc-plugin</artifactId>
      </plugin>
  ...
    </plugins>
  ...
  </reporting>
  ...
</project...>

Now that we have our documentation recources in place let's go back to creating the zip file distribution. The process of creating binary distributions in Maven is called assembly and this is used throughout default maven packaging. However, it is also possible to configure custom assemblies and, as with any plugin, you may attach executions of this plugin to standard lifecycle phases.

First, you need to define the assembly. This is done in a seperate xml descriptor file that we'll put in our project under src/main/assembly/dist-assembly.xml. Below you an examples of this minimal assembly descriptor is shown.

<assembly>
  <id>dist</id>
  <formats>
      <format>zip</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <includeSiteDirectory>false</includeSiteDirectory>
  <fileSets>
    <!-- include and filter text files -->
    <fileSet>
      <directory>src/main/doc</directory>
      <filtered>true</filtered>
      <useStrictFiltering>true</useStrictFiltering>
      <outputDirectory>/</outputDirectory>
      <includes>
        <include>changelog.txt</include>
        <include>readme.txt</include>
      </includes>
    </fileSet>
    <!-- include and do not filter javadoc -->
    <fileSet>
      <directory>target</directory>
      <filtered>false</filtered>
      <outputDirectory>doc</outputDirectory>
      <includes>
        <include>${pom.artifactId}-${pom.version}-javadoc.jar</include>
      </includes>
    </fileSet>
    <!-- include and do not filter WCB jar -->
    <fileSet>
      <directory>target</directory>
      <filtered>false</filtered>
      <outputDirectory>bin</outputDirectory>
      <includes>
        <include>${pom.artifactId}-${pom.version}.jar</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

Finally, all you need to do is to configure the assembly plugin to perform this assembly and attach it to the build lifecycle so that it gets executed on the fly. To do so simply add the following code to the pom file.

<project...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-assembly-plugin</artifactId>
        <executions>
          <execution>
            <id>assemble-zip</id>
            <phase>package</phase>
            <goals>
              <goal>attached</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <descriptors>
            <descriptor>src/main/assembly/dist-assembly.xml</descriptor>
          </descriptors>
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

By attaching javadoc generation and assembly to the default package phase of the Maven build lifecycle and defining an assembly descriptor a WCB distribution zip is now created on the fly from the build. Obvisouly this is just a basic example. You might consider to tweak it a little by putting this in a seperate profile so that is does not get executed at each package phase? Give it a try and you'll see how flexible Maven really is!

Happy coding
Bram