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.
