26.1. How to organize your plug-in project

26.1.1. Using Ant
Directory and file layout
The build file
Building the plug-in
26.1.2. Make the plug-in compatible with the auto-installation wizard
Installing plug-in configurations

26.1.1. Using Ant

Here is a simple example of how you might organize your project using ant (http://ant.apache.org) as the build tool. This is just a recommendation that we have found to be working well. You may choose to do it another way.

Directory and file layout

Create a directory on your computer where you want to store your plug-in project. This directory is the pluginname/ directory in the listing below. You should also create some subdirectories:

 - /bin/
 - /lib/
 - /src/org/company/
   - /META-INF/extensions.xml
   - /META-INF/lib/

The bin/ directory is empty to start with. It will contain the compiled code. In the lib/ directory you should put base-core-3.x.x.jar and other library files that is needed when compiling the source code, but doesn't have to be distributed with your plug-in (since they are already included in the BASE distribution). In the META-INF/lib/ directory you should put other library files that are needed both when compiling and when distributing your plug-in.

The src/ directory contains your source code. In this directory you should create subdirectories corresponding to the package name of your plug-in class(es). See http://en.wikipedia.org/wiki/Java_package for information about conventions for naming packages. The META-INF/ directory contains metadata about the plug-in and are needed for easy installation. Typically you'll always need MANIFEST.MF and extensions.xml but, depending on what you are developing, other files are also needed.

The build file

In the root of your directory, create the build file: build.xml. Here is an example that will compile your plug-in and put it in a JAR file.

Example 26.1. A simple build file

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

   <!-- variables used -->
   <property name="plugin.name" value="MyPlugin" />
   <property name="src" value="src" />
   <property name="bin" value="bin" />

   <!-- set up classpath for compiling -->
   <path id="classpath">
      <fileset dir="lib">
         <include name="**/*.jar"/>
      <fileset dir="META-INF/lib">
         <include name="**/*.jar"/>

   <!-- main target -->
      description="Compiles the plug-in and put in jar"
         <!-- compiled source code -->
         <fileset dir="${bin}" />
         <!-- metadata and extra JAR files -->
         <fileset dir="." includes="META-INF/**" />

If your plug-in depends on JAR files not included with the standard BASE installation, you must create the META-INF/MANIFEST.MF file. List the other JAR files as in the following example. If your plug-in does not depend on other JAR files, you may remove the manifest attribute of the <jar> tag.

Manifest-Version: 1.0
Class-Path: lib/OtherJar.jar lib/ASecondJar.jar

See also Section 26.7, “How BASE load plug-in classes” for more information regarding class loading when a plug-in depends on a external JAR files.

To make installation of your plug-in easier it is a good idea to include the META-INF/extensions.xml. This file should include information about your plug-in, such as the name, author, version, and the main Java class for the plug-in. See Section 26.1.2, “Make the plug-in compatible with the auto-installation wizard” for get more information about this feature.

Building the plug-in

Compile the plug-in simply by typing ant in the console window. If all went well the MyPlugin.jar will be created in the same directory.

To install the plug-in copy the JAR file to the server's plug-in directory. For more information about the actual installation read Section 22.1, “Managing plug-ins and extensions”.

26.1.2. Make the plug-in compatible with the auto-installation wizard

BASE has support for automatically detecting new plug-ins with the auto-installation wizard. The wizard makes it very easy for a server administrator to install new plug-ins. See Section 22.1.1, “Automatic installation wizard”.

The auto-install feature requires that a plug-in provides some information about itself. The wizard looks in all JAR file for the file META-INF/extensions.xml. This file contains some information about the plug-in(s). Here is an example:

<?xml version="1.0" encoding="UTF-8" ?>
<extensions xmlns="http://base.thep.lu.se/extensions.xsd">
	<!-- information about the complete package (which may contain many plug-in definitions) -->
		<name>My plug-in package</name>
			This package contains some very useful plug-ins...
	<!-- Defines a single plug-in (can be repeated multiple times) -->
	<plugin-definition id="PluginX">
			<name>Plug-in X</name>
				Calculates the X transform of....
			<property name="everyone-use">1</property>

The first two lines should be the same in all extensions.xml files. The rest of the tags are described in following list.


The first <about> tag is information about the package as a whole. We recommend putting in as much information as possible here. Supported sub-tags are: <name>, <description>, <version>, <min-base-version>, <max-base-version>, <contact>, <email>, <url> and <copyright>

Each plug-in that is defined in this file may have it's <about> tag which override the global information. Typically, you'll only overide the name and description tags and maybe also the min/max BASE version tags.


This is the main element for defining a plug-in. It can override the global <about> information. We recommend that at least a <name> and <description> is provided.


The value is the fill class name of the plug-in's main class.

<min-base-version> <max-base-version>

Optional sub-tags in the <about> section. Values are two- or three-digits separated by a dot. For example, 3.0.0 and 3.1. If values are given the plug-in will only be installed if the server's BASE version is within the bounds.


Optional sub-tag that can contain one or more <property> tags. The settings can be used to configure some properties of the plug-in definition. So far, the following properties are recognized:

  • everyone-use: If set, the plug-in is shared to the EVERYONE group with use permissions.

  • immediate-execution: If set, the plug-in is given permissions to use the immediate execution feature. This is typically used for export plug-in that need to support immediate download.

  • max-memory: The maximum memory (in bytes) to give to the plug-in when it is executed on a job agent. This setting is ignored when plug-ins are executed within the web client.

  • deprecated: The plug-in has been deprecated. If it already exists on the BASE installation it will be disabled. If it doesn't exists, it will not be installed.

Installing plug-in configurations

The installation wizard has support for installing plug-in configurations. If some of your plug-ins has support for different configurations that you want to ship as part of the package, use the "Plug-in configuration exporter" in BASE and include the generated file in META-INF/plugin-configurations.xml inside your JAR file.

[Note] Note

As of BASE 3.3.2 the installation wizard can also install configurations for plug-ins defined by the BASE core or other extensions. Simply include the configuration settings for the plug-in as you would do with a configuration for a plug-in defined by your own extension.