8_-_Creating_a_plugin

Organisation X needs a repository to be set up to manage their digital records, and in doing so they will be using Xena to preserve them for the ages. Organisation X will be storing office documents and Foo records, so they will be using the Foo plugin developed in the first part of the tutorial, and the office plugin, developed by the National Archives of Australia. The Office plugin is available from SourceForge, along with Xena.

• Background
• Create an outline of the plugin
• Create the source folder
• Create an Ant build file
• Create the OrgXPlugin class
• Build the OrgX plugin

Background

Unfortunately, things are rarely as simple as they first sound. Records coming into the repository need to be named appropriately, and during preservation, meta data specific to the record and Organisation X needs to be added. To make this possible, Organisation X is creating its very own FileNamer and MetaDataWrapper plugin, to be used with Xena. These components will live in the Organisation X plugin - which will be called, orgx.

To create the orgx plugin, we are going perform the same process that we did to create the foo plugin. The following steps are identical to those for the creation of the foo plugin, excepting that the name has changed from foo to orgx.

Create an outline of the plugin

The very first step we will undertake is to create an outline of the plugin that will be loaded by Xena. Xena expects plugins to be loaded as JAR files, laid out in a specific way. To aid in this, the Apache Ant build tool will be used. To set up our plugin development directory, we will create a new folder, called orgx_plugin, at an arbitrary place in the filesystem. This folder will be called the home folder, and designated by "~/" so our plugin will be contained in ~/orgx_plugin. For Windows users, switch the "/" to "\", and the "~" to something like C:\Documents and Settings\UserName\My Documents.

So to start off with, we get all the components we need to make a plugin. The first is the "name.properties" file. This file should be loaded in the base directory of the JAR file, and should contain the fully qualified name of the plugin loader class, which is the class that will load all the components of the plugin. In this example, we will be putting all our classes in the package:

au.gov.naa.digipres.xena.demo.orgx

The plugin class loader will be called OrgXPlugin. So here is the content of our name.properties file:

classname=au.gov.naa.digipres.xena.demo.orgx.OrgXPlugin

Create the source folder

The next thing we have to do is create the source folder for the package, and put the name.properties file inside that.

In this example, the source will be created in the folder named 'src', and the output of any compiling will go to 'bin', and a dist folder will contain the built JAR file. Any configuration files will be put into a folder named 'etc', and finally, any required external libraries (probably in JAR form) will be stored in the 'ext' folder. At the end of setting up our folder structure, we should have the following entries in the "~/orgx_plugin" folder:

- /bin

- /dist

- /etc

- /src

- name.properties

Create an Ant build file

We will create an Ant build file to do it all automatically.

1. First up, we will set up a bunch of properties to set the name of the plugin, and match the folder structure used in our project.

<property name="pluginname" value="orgx"/>
<property name="srcdir" value="src"/>
<property name="etcdir" value="etc"/>
<property name="builddir" value="bin"/>
<property name="distdir" value="dist"/>

2. Set the location of the xena.jar file in a property named, xenajarlocation. This is the most likely property to need changing, unless you happen to have the xena file in the same relative location. This guide assumes that you have already built the xena.jar file. If this is not the case, please follow the build guide on the Xena SourceForge wiki. The default location for the xena.jar file is the xena directory of the root plugin-howto directory.

 <property name="xenajarlocation" value="../../xena/xena.jar" />

3. Create the compile path to be used when compiling our plugins:

<path id="compile.path">
        <pathelement location="${xenajar}"/>
</path>

4. Create the compile job, broken into a couple of lines:

<target name="compile" description="-->Compile the .java sources">
                <javac srcdir="${srcdir}" destdir="${builddir}" debug="on"
                        verbose="on" classpathref="compile.path"/>
</target>

5. Create the makejar job:

<target name="makejar" description="-->Make the jar file" depends="compile">
        <delete >
                <fileset file="${distdir}/${pluginname}.jar"/>
        </delete>
        <jar jarfile="${distdir}/${pluginname}.jar" manifest="etc/MANIFEST.MF">
                <fileset dir="${builddir}" ><include name="**/*.class"/ ></fileset>
                <fileset dir="." ><include name = "name.properties"/></fileset>
                <fileset dir="${srcdir}"><include name = "**/*.properties"/></fileset>
        </jar>
</target>

It turns out we have almost the whole Ant build file here. Inside the Ant file is also a clean job and an init job, which delete and recreate the bin and dist folders, respectively.

Note the reference to the manifest for the JAR file in the makejar target. Since there will be no main class in our plugin Jar, all we will include in our manifest file will be the line:

Manifest-Version: 1.0

The manifest file should be created and exist in the etc folder, as specified in the Ant build job. Also, the makejar job looks for the name.properties file in the base directory, and any properties files in the src directory tree.

Create the OrgXPlugin class

The OrgXPlugin class will tell Xena what it is we can expect to find in the plugin. It specifies any normalisers, types, guessers, file namers, meta data package wrappers, help sets, basically anything that can be in a normaliser. It will need to extend the XenaPlugin class, found in the au.gov.naa.digipres.xena.kernel.plugin package. For the moment, we will leave it almost entirely blank, we will just override the only two abstract methods in XenaPlugin - getName and getVersion.

So, our OrgXPlugin.java file content will be:

package au.gov.naa.digipres.xena.demo.orgx;

import au.gov.naa.digipres.xena.kernel.plugin.XenaPlugin;

public class OrgXPlugin extends XenaPlugin {

        public static final String ORGX_PLUGIN_NAME = "orgx";

        @Override
        public String getName() {
                return ORGX_PLUGIN_NAME;
        }

        @Override
        public String getVersion() {
                return "0.1";
        }

}

Now this file is expected to be in the JAR at the location: au/gov/naa/digipres/xena/demo/orgx. To make this happen, we will stick it into that location in the source tree. So, several make directory commands later, we now have the folder:

~/orgx_plugin/src/au/gov/naa/digipres/xena/demo/orgx

This folder contains the single file OrgXPlugin.java.

Build the OrgX plugin

It is time to build our (empty) orgx plugin for the first time. In a command shell, at the location ~/orgx_plugin, type ant. If everything works, a JAR file, named orgx.jar will now exist in the folder dist. Running the command jar -tvf orgx.jar reveals the contents of the JAR:

#jar -tvf orgx.jar
0 Wed Nov 21 15:03:48 EST 2007 META-INF/
106 Wed Nov 21 15:03:46 EST 2007 META-INF/MANIFEST.MF
0 Wed Nov 21 15:03:46 EST 2007 au/
0 Wed Nov 21 15:03:46 EST 2007 au/gov/
0 Wed Nov 21 15:03:46 EST 2007 au/gov/naa/
0 Wed Nov 21 15:03:46 EST 2007 au/gov/naa/digipres/
0 Wed Nov 21 15:03:46 EST 2007 au/gov/naa/digipres/xena/
0 Wed Nov 21 15:03:46 EST 2007 au/gov/naa/digipres/xena/demo/
0 Wed Nov 21 15:03:46 EST 2007 au/gov/naa/digipres/xena/demo/orgx/
606 Wed Nov 21 15:03:46 EST 2007 au/gov/naa/digipres/xena/demo/orgx/OrgXPlugin.class
39 Wed Nov 21 09:56:50 EST 2007 name.properties

Now it's time to write the Org X filenamer and meta data wrapper!