See also:

• JSPWikiPublicAPI
• DevelopmentEnvironment

An extension is simply a java .jar file which interacts with JSPWiki classes. It may be a plugin, a page filter or a page provider. As such, Apache Maven will be used on this page to build it, although any other build tool is ok too.

Base project template for extensions#

The most straightforward way is to create the default archetype by executing mvn archetype:generate and select the pre-set archetype (normal jar file).

Edit the pom.xml file and add the following dependencies:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycorp.jspwiki.extensions</groupId>
  <artifactId>awesome-extension</artifactId>
  <version>1.0-SNAPSHOT</version>
  <name>My JSPWiki extension</name>
  
  <properties>
    <junit.version>5.8.0</junit.version>
    <jspwiki.latest.version>WHATEVER_LATEST_JSPWIKI_IS</jspwiki.latest.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.apache.jspwiki</groupId>
      <artifactId>jspwiki-api</artifactId>
      <version>${jspwiki.latest.version}</version>
      <scope>provided</scope>
    </dependency>
    
    <dependency>
      <groupId>org.apache.jspwiki</groupId>
      <artifactId>jspwiki-main</artifactId>
      <type>test-jar</type>
      <version>${jspwiki.latest.version}</version>
      <scope>test</scope>
    </dependency>

    <dependency> <!-- or whatever other unit testing framework you see fit -->
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-params</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-engine</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

Notice how the scope of the jspwiki-api dependency is provided, as this will be available in the application container (i.e. Tomcat). As for the jspwiki-main:test-jar artifact, see extensions' unit testing.

And that's it, you're ready to go! You can import the project into your favourite IDE. Also, you might find useful reading the following pages next:

• How to write a plugin
• How to write a page filter
• How to write a page provider
• How to write an engine lifecycle extension

Packaging#

The process for packaging an extension is always the same:

• Run mvn clean install.
• You will find ./target/awesome-extension-1.0-SNAPSHOT.jar .
• The extension will also be installed on your local .m2 repository.

Building a customized .war file with your extensions#

We'll use Maven again to get a consistent way of regenerating a JSPWiki .war which bundles custom extension(s). This time we will take advantage of maven's wars overlays feature.

The basic idea is that we will have a pom.xml defining a project of type war, with a dependency on JSPWiki war and the amount of dependencies necessary to bring all the custom extensions you want. The cool/strange thing of this module is that there won't be an src/main/webapp folder (unless you want to bring in some custom webapp resources too), as that will be provided by the JSPWiki war itself. Conversely, it is common for this kind of war modules to have an src/main/resources folder where the different files needed to activate this customizations (jspwiki-custom.properties, filter.xml, etc.) are placed.

As an example is worth a thousand words, you can take a look at the war's pom.xml file of this example repository, which uses this technique to generate a customized JSPWiki war which integrates the Apache Tika based search provider.

Category.Documentation