Writing modules for EASE

While EASE is shipped with some basic functionality already implemented, the real benefit comes when we provide our own script modules. Today we will see how such modules are provided.

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.

Step 1: Get EASE

To write modules you either need to install EASE into your running IDE, provide a target platform containing EASE, or import the source (core repository is sufficient) directly. At the end of this tutorial we will create help pages automatically. If you want to use that feature directly go for the source code option.

If not sure which option to choose simply install EASE from the update site.

Step 2: A simple module

Modules are simple classes, that are registered using the org.eclipse.ease.modules extension point. Start with creating a new Plug-in Project and create the extension point. Create a new module extension with id, name and a class. visible sets the default module visibility, but can be changed by the user in the preferences anytime.

If you start providing more and more modules it is a good idea to cluster them by using categories. This results in a cleaner UI integration using trees instead of a flat list of modules. Categories are defined under the same extension point and are straight forward, so I will not explain in detail.

The implementation starts with a POJO class:

package com.codeandme.ease.modules;

import org.eclipse.ease.modules.WrapToScript;

/**
 * Provides basic mathematics operations.
 */
public class SimpleMathModule {

 /**
  * Provide sum of 2 variables.
  *
  * @param a
  *            summand 1
  * @param b
  *            summand 2
  * @return sum
  */
 @WrapToScript
 public double sum(double a, double b) {
  return a + b;
 }

 /**
  * Subtract b from a.
  */
 @WrapToScript
 public double sub(double a, double b) {
  return a - b;
 }

 /**
  * Multiply 2 values.
  */
 @WrapToScript
 public double mul(double a, double b) {
  return a * b;
 }

 /**
  * Divide a by b.
  */
 @WrapToScript
 public double div(double a, double b) {
  return a / b;
 }

 public void doNothing() {
  // not exposed as it lacks the @WrapToScript annotation
 }
}

The only addition to a plain class is the @WrapToScript annotation, which indicates methods to be exposed to scripting. In case a class does not contain any @WrapToScript annotation, all public methods will get exposed.
As modules are created dynamically, make sure that the default constructor exists and is visible!

Step 3: A more complex module

Our 2nd module will be a bit more complex as we introduce a dependency to the SimpleMathModule. Define the module the same way we did before, but add a dependency to com.codeandme.ease.modules.module.simpleMath.

The implementation now derives from AbstractScriptModule which allows us to retrieve the used script engine and the basic environment module, which keeps track of loaded modules. If you cannot extend your class you may also implement IScriptModule and populate the initialize() method on your own.

package com.codeandme.ease.modules;

import org.eclipse.ease.modules.AbstractScriptModule;
import org.eclipse.ease.modules.WrapToScript;

/**
 * High sophisticated mathematics operations.
 */
public class ComplexMathModule extends AbstractScriptModule {

 /** PI constant. */
 @WrapToScript
 public static final double PI = 3.1415926;

 /**
  * Get radus from circle area.
  *
  * @param area
  *            circle area
  * @return radius
  */
 @WrapToScript
 public double getRadius(double area) {
  double rSquare = getEnvironment().getModule(SimpleMathModule.class).div(area, PI);
  return Math.sqrt(rSquare);
 }
}

By querying the environment we can retrieve other module instances dynamically and make use of their functionality.

We also expose a constant PI here. Just remember that only constant fields can be wrapped.

Optional: Create documentation

Users typically will request for module documentation. EASE allows to create eclipse help pages automatically by using a special JavaDoc doclet. The doclet is available in source and binary from the EASE core repository. To use it you need to download at least the bin folder content (along with the directory structure).

Now open menu Project / Generate JavaDoc...  , provide the location of the javadoc binary, select your modules project and point to the custom doclet location.

On the 2nd page add a parameter that points to the Plug-in Project root folder:

-root /your/workspace/location/com.codeandme.ease.modules

Hit Finish to build the documentation. The doclet will alter your plugin.xml, MANIFEST.MF and adds a new help folder to your project.

The help pages are located under Scripting Guide/Loadable modules reference/<Category>/<ModuleName>.

If you are interested in building documentation automatically using maven, please ask on the ease-dev mailing list for details.