JForum is an open source forum or bulletin-board webapp written in Java. Recently was required by work to produce a customised version for deployment. The customised version would integrate with the Single Sign On solution employed, namely CAS, and would be decorated with the skin or template of the web site. In this article I describe using the Maven2 tool to apply my modifications in a separate source tree from JForum.

There are two methods of performing customisations:

  1. Modifying the existing source code and packaging a new war file. This is the simplest approach, and allows you to use the build scripts provided by the JForum download. Combining the source code of JForum and your modifications makes it harder to apply bug fixes later on, and makes it hard to identify your customisations.
  2. Use Maven2 to overlay your customisations over the existing WAR file distributed by JForum.

The advantages of the second approach are:

  • It keeps your modifications separate
  • Allows you to upgrade JForum easily
  • It integrates well with existing build tools

Install JForum to your local repository

$ mvn install:install-file -DartifactId=jforum -Dversion=2.1.8 -Dfile=jforum-2.1.8.war -DgroupId=net.jforum -DgeneratePom=true -Dpackaging=war

Create a basic pom.xml for the JForum customisations

Use the webapp archetype create a basic Maven project which will contain your customisations.

$ mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp -DgroupId=com.company.jforum -DartifactId=jforum -Dversion=2.1.8

Unless you envisage customising the web.xml, delete the auto-generated version.

$ rm  src/main/webapp/WEB-INF/web.xml

Remove the auto-generated index.jsp. The equivalent of this file within the JForum war redirects to the list page. There shouldn’t be any need to customise this file.

$ rm src/main/webapp/index.jsp

It’s worth using some version control system to manage the changes to this project:

$ git init
$ echo "target" > .gitignore
$ git add pom.xml src .gitignore
$ git commit -m "Initial code import"

Because this is Maven project I’m excluding the target folder from any commits.

Dependencies and WAR overlay

Remove the JUnit dependency created by the archetype. Our project won’t have any tests, so it’s unnecessary.

Add the JForum artifact we added to our local repository as a dependency:

<dependency>
  <groupId>net.jforum</groupId>
  <artifactId>jforum</artifactId>
  <version>2.1.8</version>
  <type>war</type>
</dependency>

Add a configuration to the maven-war-plugin to overlay the JForum WAR.

Ensure that a jforum.war is generated within the target folder when the mvn package command is run.

Applying customisations

The majority of JForum customisations will be modifications to the .properties files. Currently these are packaged within the JForum war file. To apply our customisations we create a duplicate of each .properties and place them within the src/main/resources folder.

Database configuration

When we ran the mvn package command Maven extracted the war file into the target folder. We can copy resources from this location into the source folder. The following creates a customised mysql.properties file.

$ mkdir -p src/main/webapp/WEB-INF/config/database/mysql/
$ cp target/jforum/WEB-INF/config/database/mysql/mysql.properties src/main/webapp/WEB-INF/config/database/mysql/

Once running the above make some changes to mysql.properties and ensure they are packaged within the war.

$ nano src/main/webapp/WEB-INF/config/database/mysql.properties
$ mvn clean package
$ # Extract the mysql.properties from the war file
$ unzip target/jforum.war /WEB-INF/config/database/mysql.properties
$ # Check that modified properties appear within the extracted file
$ nano WEB-INF/config/database/mysql.properties
$ # Clean up
$ rm -rf WEB-INF

You need to extract and install the MySQL schema onto your chosen database before deploying.

Skins and visual changes

Copy the default skin from the war file and place it within the src/main/webapp folder.

$ mkdir -p src/main/webapp/templates
$ cp target/war/work/net.jforum/jforum/templates/default src/main/webapp/templates/default

You can then modify any of the files within the templates/default directory to alter the skin.

Once you have made all your modifications it’s a good idea to diff the templates/default folder in src with the one in target and remove any files in src which are unchanged. By doing this you are reducing the amount of code changes between your customisations and the vanilla JForum. This will make it easier to apply any bug-fixes to your customisations.

Jetty configuration

The jforum.war file generated should now be deployable onto a Java application server. To test my changes I’ve just deployed it onto Tomcat6.

For development however I want to start using the Jetty Maven plugin. This will allow me to run the forum quickly.

Modify the pom.xml and add the following configuration to the __ section:

<plugins>
  <plugin>
    <groupId>org.mortbay.jetty</groupId>
    <artifactId>maven-jetty-plugin</artifactId>
    <version>6.1.10</version>
    <configuration>
      <webApp>${basedir}/target/jforum.war</webApp>
    </configuration>
  </plugin>
</plugins>

Now when you run the following command Jetty will be run and will deploy the war file.

$ mvn jetty:run-war

Making modifications to the Java source

You may need to make some modifications to the Java source code of JForum. This may be required if you want to implement a custom Single Sign On (SSO) provider.

Add the following target to the Ant build.xml of JForum:

<target name="jar" depends="compile">
    <jar destfile="${build.dir}/${filename}.jar" basedir="${classes.dir}"/>
</target>

Run the following command to build the sources:

$ ant clean jar

This will create a JAR file within jforum/build/. This JAR will need to be imported to the Maven repository.

mvn install:install-file -Dpackaging=jar -DartifactId=jforum -Dversion=2.1.8 -Dfile=jforum-2.1.8.jar -DgroupId=net.jforum -DgeneratePom=true -Dpackaging=jar

The JAR can now be added as a dependency to our JForum pom.xml. You’ll also need to add the dependencies required your code modifications to the pom.xml.