WCB Sharing FTW!

One of the good things of Java is the “create once, use everywhere” message. The modular architecture of GX WebManager supports this message in the form of WCBs. But, given a nice source tree, how can you create a nice ZIP file that contains anything you need to share? You just add some additional things to your pom.xml and MaVeN will do it for you!

Generating JavaDoc

To help developers downloading your WCB finding their way through your functionality, you should generate JavaDoc and include this in the distribution package you create. MaVeN can start the generation process for you, but you can help a little by configuring some settings in the pom.xml file. Add the following snippet to the reporting plugins section:

<!-- plugin to create the javadoc -->
<plugin>
	<artifactId>maven-javadoc-plugin</artifactId>
	<configuration>
		<reportOutputDirectory>
			target/apidocs
		</reportOutputDirectory>
		<links>
			<link>http://java.sun.com/j2se/1.5.0/docs/api/</link>
			<link>http://java.sun.com/j2ee/1.5/docs/api/</link>
			<link>http://www.gxdeveloperweb.com/documentation/javadoc/</link>
		</links>
	</configuration>
</plugin>

With reportOutputDirectory you set the directory where the HTML files that JavaDoc generates have to be placed. By including a list of links to external JavaDoc sites, standard Java and WebManager class and method names are automatically linked to the online JavaDoc pages. For example, if you have a service with a method that returns a Page object, this return type will become a link to the Page class documentation on GX DeveloperWeb.

To run this step automatically, the following snippet can be added to the build plugins section:

<!-- plugin to create the javadoc on the package phase -->
<plugin>
	<artifactId>maven-javadoc-plugin</artifactId>
	<executions>
		<execution>
			<id>create-javadoc</id>
			<phase>package</phase>
			<goals>
				<goal>javadoc</goal>
			</goals>
		</execution>
	</executions>
</plugin>

Now there is only one catch left. JavaDoc generation will fail when it encounters an annotation in the source file that it cannot resolve in the classpath. Because WebManager uses annotation to define JCR nodetypes and for instructing the EntityManager, you need to add a dependency to the webmanager-api library.

Creating the distribution ZIP

Now we have everything we might want to include in our distrubition package: the source code, the compiled WCB and the generated JavaDoc  files. To automatically pack them up in a single ZIP file, you can use the assembly plugin. This plugin takes a XML file with instructions about which files and directories to include in the ZIP file. The example dist-assembly.xml file includes some files from the root, the documentation from /doc, the generated JavaDoc from /target/apidocs, the compiled WCB from the /target subdirectory and the source code from /src. You can modify this file to customize the ZIP file, for example if you don’t want the source code to be included. Most times, this examples is what you want when preparing a ZIP file for certification by Professional Services.

After preparing the assembly instructions file and placing it somewhere in the src directory (like src/main/assembly/dist-assembly.xml if you plan to use the snippet below), you need to instruct MaVeN to assemble the ZIP file by placing the following snippet to the build plugins section:

<!-- plugin to create the distribution zip on the package phase -->
<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>

For reference purposes I’ve prepared an example pom.xml which might help you figuring out some things.