How to use and make own Plugins

Introduction

The first part of this page will describe how one can make its own plugins for JUMP/OpenJUMP. In part B we will outline how the plugins are used. Either internally from Eclipse using the workbench-properties.xml file or externally as jar for distributing.

How to make your own plugin

First of all: To make coding easier you should use a Integrated Developement Environment (IDE) like Eclipse or NetBeans (of course you can also use commercial IDEs). Such an IDE shows you errors in your code already during programming and has nice properties like proposing you commands or paths.

Now have a look here: FAQ OpenJump and Eclipse

Note: If you use Eclipse for the first time, then have a look on this very good tutorial on how to use the Eclipse IDE: Eclipse Tutorial

Finally lets start.. :)

If you have installed Eclipse see also How to make your plugin in ECLIPSE

• create a new Java project (eg. call it "Helloi18n")
• go to the project properties, and look where you can set the Java BuildPath. Look for an option called like "add JAR". Now use this to add the JUMP kernel file jumpxxx.jar which should be located in your Jump (OpenJUMP) folder. (nota bene: xxx is used a placeholder for different names)

Further add also all the jar files which are in the JUMPxxx/lib/ folder.

• now you can start coding - preferably make a "hello world" plugin like it is described in the jump developer manual. (see also code below of HelloWorldPlugIn.java)
  • basically you have to know that a plugin has to have

the class ending "PlugIn" and inherits methods using "extends AbstractPlugIn"

• • further it has always 2 methods which are called by Jump to interact:
    1. the method initialize() is necessary to register and to create a menu item (for the example it is done in the View menu)
    2. the method execute() contains the code which should be evaluated if the menu entry/button is activated. (see below)

/*
 * created on 		04.10.2005
 * last modified: 	05.10.2005 comments added
 * 
 * author:			sstein
 * 
 **/

package ch.unizh.geo.degen;

import com.vividsolutions.jump.workbench.WorkbenchContext;
import com.vividsolutions.jump.workbench.plugin.AbstractPlugIn;
import com.vividsolutions.jump.workbench.plugin.EnableCheckFactory;
import com.vividsolutions.jump.workbench.plugin.MultiEnableCheck;
import com.vividsolutions.jump.workbench.plugin.PlugInContext;
import com.vividsolutions.jump.workbench.ui.plugin.FeatureInstaller;

/**
 * @description:
 * 	testplugin for jump<p>
 *  	shows hello world - window in Jump
 *  
 * @author sstein
 *
 */
public class HelloWorldPlugIn extends AbstractPlugIn{
	
	public HelloWorldPlugIn() {
		// empty constructor
	}
	
	public void initialize(PlugInContext context) throws Exception {
		FeatureInstaller featureInstaller = new FeatureInstaller(context.getWorkbenchContext());
		featureInstaller.addMainMenuItem(
				this,			//exe
				new String[] {"View"}, 	//menu path
				this.getName(), //name methode .getName recieved by AbstractPlugIn 
				false,			//checkbox
				null,			//icon
				createEnableCheck(context.getWorkbenchContext())); //enable check        
	}
		
	public static MultiEnableCheck createEnableCheck(WorkbenchContext workbenchContext) {
		EnableCheckFactory checkFactory = new EnableCheckFactory(workbenchContext);
		
		return new MultiEnableCheck()
		.add(checkFactory.createWindowWithLayerNamePanelMustBeActiveCheck());
	}	
	
	/**
	 * Action on menu item selection:
	 * creates doc to show
	 */
	public boolean execute(PlugInContext context) throws Exception{
		
		context.getWorkbenchFrame().getOutputFrame().createNewDocument();
		context.getWorkbenchFrame().getOutputFrame().addText("Hello, World!");
		context.getWorkbenchFrame().getOutputFrame().surface();
		
		return true;
	}
	
}

Example For Eclipse i have done an example Project, which needs OpenJump (donwload here). To use that in Eclipse:

• download it and unpack. Put it into your Eclipse workspace folder
• use the following menu entry to load "\File\Import\". Select "Existing Project into Workspace"
• After importing don't forget to set the java build path entries in the project properties.

Another example, that shows how to create buffers from features in a layer has been posted here: Example Plugin For Buffering Features in a Layer

How to use own plugins

To load a plugin in Jump we have two options:

• either we create a library for the Jump\lib\ext\Folder
• or we load our plugin by using a workbench-properties.xml file

If you have installed Eclipse see also

• How to create a jar plugin in ECLIPSE and
• How to use a plugin with a properties file in ECLIPSE

Version 1

This option is a bad choice for finding errors, but necessary to deploy our work.

1. to load an external plugin on Jump start we have to create a class

HelloWorldExtension.java (see also the downloadable example). The Extension class is necessary to register the plugin in Jump. Note: The class name must end with Extension, (see below)

1. export the compiled directory/files to a jar file (it is like

zipping the project and renaming the ending to jar)

1. then put the jar file in Jumpi18n/lib/ext and start jump as usual (example myhelloi18nplugin.jar)

How does such an Extension class look like:

/*
 * created on 		04.10.2005
 * last modified: 	
 * 
 * author:			sstein
 * 
 *************************************************/
package ch.unizh.geo.degen;

import com.vividsolutions.jump.workbench.plugin.Extension;
import com.vividsolutions.jump.workbench.plugin.PlugInContext;

/**
 * @description
 *  - this class loads the PlugIn into Jump <p>
 *  - class has to be called "Extension" on the end of classname
 *    to use the PlugIn in Jump
 * 
 *  @author sstein 
 */
public class HelloWorldExtension extends Extension{

	/**
	 * calls PlugIn using class method xplugin.initialize() 
	 */
	public void configure(PlugInContext context) throws Exception{
		new HelloWorldPlugIn().initialize(context);
	}
	
}

Version 2

This option is a good choice for debugging errors but not for deployment.

note: for this version is might be good to have the original openjump sources in a project (since one can better trace errors and has good examples on programming). The Jump sources can be obtained from the Jump or OpenJUMP SVN or as zip files. If you create your own Openjump project, don't forget to include the libraries into your project (using the "Buildpath" properties). Further you have to create a dependency of the Helloi18 project on the new Jump (OpenJump) project, which can be also done in the project properties of Helloi18

• 1 - create in your project a new file and call it workbench-properties.xml (example workbench file)
• 2 - write the package path to your plugin inside the file (see file)
• 3 - create a new run entry: the class which is the entry point for OpenJUMP

is com.vividsolutions.jump.workbench.JUMPWorkbench

• 4 - add to the "Arguments" of the run entry:

-properties C:\myRealProjectPath\workbench-properties.xml
-plug-in-directory C:\Programme\Jumpi18n\lib\ext

• 5 - add to your "run entry" the "classpaths" for the jar files in

jump/lib/ (as Bootstrap Entries) and the project you just created (as User Entries)

• 6 - start the run entry

Notes

the examples above use the parent class AbstractPlugIn which has disadvatanges for long computations. For such a case use "implements ThreadedPlugIn". Here also a _monitor_ can be used to send messages to the user. Apart from that a second method run() has to be implemented which contains the now the time consuming code while execute() should contain dialogs for initial interatcion. (I will make this clearer in future - hopefully)

Please don't forget to document your plugin. I've done a template that can be downloaded: here

have fun, Stefan (sstein)