Driver Tutorial Rough Draft

How to write OpenJUMP drivers

History

JUMP has gone through three different I/O APIs: JUMPReader/JUMPWriter, DataSource, and DataStore. While all three are still valid and can be used to write custom drivers, it is recommended to use the DataStore framework for all new drivers. The JUMPReader/JUMPWriter API was designed to only support file access on the local machine's file system. DataSource was the first attempt at creating a way to access a database. DataStore was designed to be a simpler, more flexible replacement for DataSource. DataStore is the current standard for accessing remote data. Local data could either be accessed through a custom DataStore, or more simply through extending the Open File dialogue box.

Local vs Remote

There are two currently accepted methods to expand OpenJUMP's ability to access data: new file types can be added to the "Open File" dialogue box, or a new DataStore driver can be added to the "Open->Data Store Layer" dialogue box. The first method is used to allow OpenJUMP to read currently unsupported filetypes from the local filesystem while the second method allows OpenJUMP to connect to currently unsupported databases.

Adding a new file format to File->Open File

To add support for a new file type to OpenJUMP, a file layer loader class that extends org.openjump.core.ui.io.file.AbstractFileLayerLoader needs to be written. The primary method that needs to be written within the new file layer class is open, which takes in a TaskMonitor, a URI of the file to open, and a map of optional options. The method returns a boolean value that is true if the file is successfully loaded and false if the loading failed.

The open method is responsible for reading the file at the given URI, translating that data into an OpenJUMP layer then loading the layer using code similar to the following:

 <code>
// layer = new Layer of whatever type is being loaded
LayerManager layerManager = workbenchContext.getLayerManager();
Category category = TaskUtil.getSelectedCategoryName(workbenchContext);
layerManager.addLayerable(category.getName(), layer);
</code>

In order to register a new file type with OpenJUMP code similar to the following must be in the configure method within the PlugIn's Extension class:

<code>
// These are the valid extensions for your file type.
// For instance, .jpg and .jpeg are the standard extensions for the JPEG image format
ArrayList<String> extensions = new ArrayList<String>(1);
extensions.add(FILE_NAME_EXTENSION);  

// This registers your file type and associated file loader
context.getWorkbenchContext().getRegistry().createEntry(FileLayerLoader.KEY, 
     new YourFileLayerLoader(...));
</code>

Creating a new DataStore type

Creating a new DataStore requires that the following interfaces be implemented:

<code>
com.vividsolutions.jump.datastore.DataStoreDriver
com.vividsolutions.jump.datastore.DataStoreConnection
com.vividsolutions.jump.datastore.DataStoreMetadata
</code>

The new DataStoreDriver is registered with OpenJUMP using the following code within the configure method of the PlugIn's Extension class.

<code>
try {
     context.getWorkbenchContext().getRegistry().createEntry(
          DataStoreDriver.REGISTRY_CLASSIFICATION, new YourDataStoreDriver());
} catch (Throwable e) {
     context.getWorkbenchFrame().warnUser("YoulDataStoreDriver not loaded");
     context.getErrorHandler().handleThrowable(e);
}
</code>

The main method to implement within the DataStoreDriver class is createConnection which takes in a ParameterList containing the information entered by the user in the "Add Connection" dialogue box and returns the implementation of DataStoreConnection written for the new DataStore.

The major method to implement for DataStoreConnection is execute which takes in a query and returns a FeatureInputStream containing the features that satisfy the query.

DataStoreMetadata is an accessory class that can be queried to find the total extent of the DataStore, as well as any attributes, names, or other information that is associated with the dataset.