Skip to content Skip to navigation

Developer Documentation

ePAD REST API (An Introduction)

  • Complete Resource List
  • Connecting to the ePAD REST API
  • Create Subjects via REST
  • Upload Files via REST
  • Download Files via REST
  • Query the Search Engine via REST
  • ePAD Session Management

AIM API

The AIM API is an open source application interface in Java for reading and writing AIM files. The software can be downloaded from SourceForge. The AIM API wiki includes documentation on how to read the write AIM files, save them to a native XML database, and query the database with the AIM Query Language (AimQL). The AIM API makes working with AIM easy in Java.

Spline is one of the drawing options of ePad. However, AIM structure does not contain Spline as a geometric shape. For that reason, we implemented an additional geometric shape class called as Spline in the AIM API. Instances of the Spline class are stored as TwoDimensionPolyLine in the AIM XML files. We append a keyword to uniqueIdentifier of the TwoDimensionPolyLine instance to identify if it is a Spline or not. While reading and writing AIM XML files this operation is done automatically by the AIM API.

Best Practices for ePAD Developers

Best Practices for ePAD Developers

ePAD Developer Tools

Use David Clunie’s dciodvfy validator from his dicom3tools kit. It can be downloaded from http://www.dclunie.com/dicom3tools.html

To validate a DICOM file:

dciodvfy [DICOM FILE]

To see all headers:

dciodvfy -dump [DICOM FILE]

The following page gives an explanation of common header errors: http://www.dclunie.com/dicom3tools/dciodvfy.html

Building ePAD Software Components

This page describes the process of downloading ePAD from GitHub and building it using Maven.

ePAD is composed of the following software components:

  • ePAD GWT-based GUI client
  • ePAD Web Server
  • AIM 4.0 XML processor
  • ePAD Tools

The process of building the ePAD system involves:

  • Downloading the software from GitHub
  • Building the software using Maven

This page will also outline how to:

  • Create Eclipse projects from the Maven build files
  • Use Git from Eclipse

All software is located on GitHub in an organization called RubinLab. The backend and infrastructure components of ePAD are open source, whereas the frontend user interface and the plugins are not. There is a nice git tutorial at learnGitBranching.

The core software repositories are:

  • epad Contains the ePAD client
  • epad-dto Contains definitions of data transfer objects passed between the ePAD server and client. OpenSource
  • epad-common Contains code that is shared between ePAD client and server components. OpenSource
  • epad-plugins Contains ePAD plugins
  • epad-ws Contains the ePAD web services. OpenSource
  • aim3api Contains the AIM 3.0 XML processing API (Will eventually be replaced with AIM 4.0 API.) OpenSource
  • aimapi Contains the AIM 4.0 XML processing API (Transition from AIM 3.0 API ongoing.) OpenSource

There is also a repository containing configuration and build information:

  • isis-epad-project Contains configuration and build information. OpenSource

Before downloading the software from GitHub you will need to download and configure Git client software.

If you want to access all repositories, you will need a GitHub user account that has been given access to these repositories. When you have created a GitHub user account you can request access from the owner of the RubinLab organization.

Open Source Access
Once you have set up the Git client software and access permissions you can download each repository to your machine. First, create a directory to contain the downloaded repositories (e.g., ~/workspace/rubin-lab), go to that directory, and then clone each project as follows:


git clone https://github.com/RubinLab/isis-epad-project.git
git clone https://github.com/RubinLab/aimapi.git
git clone https://github.com/RubinLab/epad-dto.git
git clone https://github.com/RubinLab/epad-common.git
git clone https://github.com/RubinLab/epad-ws.git

This will create subdirectories (isis-epad-project, aimapi, epad-dto, epad-common, epad-ws) containing the cloned projects. These directories should be siblings.

Full Access
Once you have set up the Git client software and access permissions you can download each repository to your machine. First, create a directory to contain the downloaded repositories (e.g., ~/workspace/rubin-lab), go to that directory, and then clone each project as follows:


git clone https://github.com/RubinLab/isis-epad-project.git
git clone https://github.com/RubinLab/aimapi.git
git clone https://github.com/RubinLab/epad-dto.git
git clone https://github.com/RubinLab/epad-common.git
git clone https://github.com/RubinLab/epad-plugins.git
git clone https://github.com/RubinLab/epad-ws.git
git clone https://github.com/RubinLab/epad.git 
git clone https://github.com/RubinLab/lesion-tracking.git 

This will create subdirectories (isis-epad-project, aimapi, epad-dto, epad-common, epad-plugins, epad-ws, epad, lesiontracking) containing the cloned projects. These directories should be siblings.

The software is built using Maven.

You will need to download and configure Maven if you do not have it on your machine. Version 3.0.4 is currently used to build ePAD but more recent versions should also be fine.

Unlike Ant, Maven requires an initial configuration step. Primarily, Maven needs to know the location of each user's local repository, which is an area that Maven uses to store build artifacts.

In general, on Unix-like machines all a user needs to do is set their JAVA_HOME environment variable to point to their Java installation and set MAVEN_HOME to point to the Maven installation directory (e.g., /usr/share/maven).

Most defaults will then work out of the box. In particular, each user's Maven repository will by default be located at ~/.m2/repository. You can verify that Maven is happy by typing mvn -version on the command line.

Once Maven is installed, the ePAD projects can then be built from the command line. (Building from within the Elipse IDE is outlined later.)

The build process required that all ePAD directories are siblings (in, for example, a directory called ~/workspace/rubin-lab). The isis-epad-project directory has a Maven POM (Maven's equivalent to Ant's build.xml) that will build all ePAD software components.

To build, go to the isis-epad-project directory and type:

Open Source Access
mvn install -Popensource

Full Access
mvn install

The first time this may take several minutes because all required third party software components will be downloaded to each user's local repository. (Take a look at ./epad-ws/pom.xml to get a sense of the third party components used by the ePAD web service, for example.) You should see something like the following:

Open Source Access


[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] ePAD Project ...................................... SUCCESS [0.494s]
[INFO] AIM 4 API ......................................... SUCCESS [4.514s]
[INFO] ePAD Common Components ............................ SUCCESS [0.832s]
[INFO] ePAD Web Services ................................. SUCCESS [4.604s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Full Access


[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] ePAD Project ...................................... SUCCESS [0.494s]
[INFO] AIM 4 API ......................................... SUCCESS [4.514s]
[INFO] ePAD Common Components ............................ SUCCESS [0.832s]
[INFO] ePAD Plugins Project .............................. SUCCESS [0.009s]
[INFO] ePAD TEDSeg Plugin ................................ SUCCESS [1.020s]
[INFO] ePAD JJVector Plugin .............................. SUCCESS [0.698s]
[INFO] ePAD Web Services ................................. SUCCESS [4.604s]
[INFO] ePAD Front End .................................... SUCCESS [1:39.260s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

The Maven install step will compile all the code, generate JAR and WAR files for the full access, just JAR file for the open source access, and put the generated component in the local repository (e.g., ~/.m2/repository).

Individual projects can also be built by going to the relevant project directory and running Maven from that directory.

Eclipse has several plugins that allow projects to be created from Maven build files. These plugins also support just-in-time compilation for Java projects.

The mostly widely used plugin is called M2E. The plugin is installed in the same way as other Eclipse plugins (using the Help->Install New Software... menu option). The main Eclipse download site for M2E is http://download.eclipse.org/technology/m2e/releases/. (For the Juno version of Eclipse http://download.eclipse.org/releases/juno/ can be used.)

Once the plugin has been installed you need to tell it where to find the user's local Maven repository. This can be done manually by settings the M2_REPO variable in Eclipse (using the Eclipse->Preferences->Java->Build Path->Classpath Variables menu option) or, more easily, on the command line as follows:

mvn -Declipse.workspace=~/workspace eclipse:configure-workspace

You will need to restart Eclipse for this to take effect. You can then verify that the variable was set correctly by navigating to the Classpath Variables option in Eclipse as outlined above. It should be something like ~/.m2/repository.

Now new Eclipse projects can be created from Maven projects. The ePAD project contains a master Maven project for all sub projects. This projects is located in the isis-epad-project repository. The POM file in the base of this directory contains definitions for recursively building all ePAD sub-projects. The M2E plugin will create all necessary ePAD Eclipse projects using this master Maven project.

To create these projects, go to File->Import->Existing Maven Projects... in Eclipse and select the Maven POM file in the root of the isis-epad-project directory (something like ~/workspace/rubin-lab/isis-epad-project/pom.xml).

This should create and immediately compile all ePAD projects. Individual projects may also be loaded in this way.

If you want to create and compile only the ePAD viewer, you can select the Maven POM file in the epad-viewer-project subdirectory of the isis-epad-project directory (something like ~/workspace/rubin-lab/isis-epad-project/epad-viewer-project/pom.xml). As mentioned, Eclipse's just-in-time compilation should work if any edits are made to Java source code.

It is important that the Maven POM file remains the master build specification for a project. Any modifications to class paths, build configurations and the like should be made (either directly or indirectly) to the Maven POM file. An Eclipse project can be updated to reflect any manual changes to the POM file by right clicking on the relevant project and selecting Maven->Update Project.

For this reason, no Eclipse project artifacts should be held in the Git repository. The .gitignore file at the base of each project is configured to ensure that Git ignores Eclipse project files. Obviously, each user can maintain Eclipse projects files locally and make any non-project-specific changes within their Eclipse environment (such as, for example, font preferences and the like).

Recent versions of Eclipse come come prepackaged with Git plugins. Using these plugins, Eclipse will automatically detect that a project is using Git for source code management and will display summary Git status information about each project (such as, for example, the current branch).

Right clicking on a project that used Git and selecting the Team option will reveal an array of Git options.

If Eclipse does not automatically recognize a Git project, you can manually add it. A tutorial on adding an existing Git existing project to Eclipse can be found here: http://bsnyderblog.blogspot.com/2012/01/how-to-add-existing-git-project-...

First install the GWT Developer Mode plugin from http://dl.google.com/eclipse/plugin/4.3. Select Google Plugin for Eclipse and import.

To convert the ePAD project to a GWT project, right click on the project and select Google. Alternatively, select Project->Properties->Google.

Fill in the Web Toolkit and Web Application subtabs.

In the Web Toolkit subtab, select Use Google Web Toolkit. Then specify the GWT SDK. The SDK from Maven repository is good.

Entry Point Modules should specify the ePAD entry point. May be detected automatically.

In the Web Application subtab select This project has a WAR directory. Set WAR directory to src/main/webapp. Unselect Lauch and deploy from this directory....

Go to Run->Run Configurations and select Web Application and then press New.

In the Main tab in Run Configurations set Name to something meaningful, then set Main Class to com.google.gwt.dev.DevMode.

The defaults in the other Run Configurations tabs should work.

Right click on the ePAD project and select Google->GWT Compile to verify that it compiles.

Execute the run configuration you created and click on the URL listed in the Development Mode windows.

You may need to manually set the webapps directory for the the development mode run configuration in some versions of Eclipse. To do this, in the Run Configuration configuration set the working directory in the Arguments tab to ${workspace_loc:epad/src/main/webapp}.

eXist Database Backup and Restore

In your Docker instance, eXist directory located under the root as 'app/eXist'.

To backup your data, you can use the following command under the eXist directory;

java -jar start.jar backup 
			-u [admin_username] 
			-p [admin_password] 
                        -b [collection_path] 
                        -d [target_path]
                        -ouri=[xml_uri]

Example

java -jar start.jar backup 
		-u [admin_username] 
		-p [admin_password] 
                -b /db
                -d /var/backup/eXist102315
                -ouri=xmldb:exist://localhost:8899/exist/xmlrpc

If you are using the Admin Client, do the following:

1. Select either the Backup Icon (arrow pointed upward) in the toolbar OR Tools » Backup from the menu.

2. From the Collection drop-down menu, select the collection to backup. To backup the entire database, select /db. Otherwise, select the topmost collection that should be stored. Note, however, that user data and permissions will only be exported if you backup the entire database.

3. In the Backup-Directory field, enter the full directory path to the where you want the backup database files to be stored or the path to a zip file into which the backup will be written. In general, if the file name ends with .zip, the client will attempt to write to a ZIP. Otherwise, it tries to create the specified directory.

4. Click OK.

To restore the database files from a backup, you can again use either the Admin Client, or the backup command line utility.

Using the Command Line

java -jar start.jar backup 
		-u [admin_username]  
		-p [admin_password]   
		-r /var/backup/eXist102315/db/__contents__.xml

If you are using the Admin Client, do the following:

1. Select either the Restore Icon (arrow pointed downward) in the toolbar OR Tools » Restore from the menu.

2. The dialog box shown below will then prompt you to select the backup descriptor __contents__.xml from the topmost directory you want restored. To restore the entire database, select the __contents__.xml from the db/ directory.
eXist 1.3 allows to directly select the ZIP archive of a backup.

3. A second dialog box will then prompt you for an admin password to use for the restore process. This password is required ONLY IF the password of the "admin" user set during the backup differs from the log-in password for the current session. (If you provide an incorrect password, the restore will be aborted.) If the passwords are different, note that restoring the user settings from the backup will cause the current user password to become invalid.

4. If the restore was accepted, a progress dialog box will display the restored file.

Writing an ePAD MATLAB Plugin

A MATLAB-based ePAD plugin consists of a plugin wrapper, written in Java, and the processing code itself, which will be written in MATLAB. The plugin is typically embedded in an ePAD server and is invoked via an ePAD REST service call.

When an ePAD plugin is invoked it is typically passed three things:

  1. The ID of an AIM file, which contains some parameters (e.g., a region of interest) that is passed to the plugin algorithm.
  2. The identifier of a DICOM image or series, that can be used to download raw image data.
  3. An (optional) set of attribute-value pairs containing parameters for the plugin.

The plugin wrapper will take the AIM file identifier and use ePAD's REST API (https://epad.stanford.edu/documentation/developer/rest-api) to download the AIM file.

The plugin wrapper will then extract some information from it. For example, a region of interest polygon may be extracted. ePAD uses the Java-based AIM API Java library to read and write AIM to process AIM files. This API can be downloaded from GitHub (https://github.com/RubinLab/aimapi).

The plugin wrapper may also use the supplied parameters to further configure the plugin task.

The plugin must read the DICOM file (or files) that have been specified, again using ePAD's REST API. This API can return the images in PNG or JPG format.

It will then take the configuration information extracted from the AIM file and content of the DICOM images and convert them into a format that MATLAB can process.
MATLAB's Java API (http://www.mathworks.com/help/matlab/using-java-libraries-in-matlab.html) contains data structures that can be used to store information that can be passed to MATLAB code.

These MATLAB routines that are invoked must first be converted to a Java. This conversion is done via the MATLAB Builder JA product. See the "MATLAB Java Code Generation for Plugins" section on this page for details of this process.

The plugin wrapper will then invoke the MATLAB code, passing the converted AIM and image information. The MATLAB routine will generate a result and pass it back to the invoking plugin wrapper. These results can be simple data structures or may include generated images.

ePAD also has an API that allows MATLAB plugins to pass status messages back to the ePAD server. These messages can be displayed by the ePAD front end to allow users to monitor the state of long-running plugins.

Again using the MATLAB Java API, the plugin must take the results of the MATLAB routine and convert the results to Java data structures.

The results can then be inserted into an AIM file, again using the AIM API.

You can download an example ePAD Plugin from epad-sample-plugin. Import the code into eclipse as a maven project. Please use the source in this project as a model to create your own plugin - you use any package/classname you wish as long as the handler extends AbstractPluginServletHandler.

The resources directory contains a template for the plugin. Please change the template uid, template name and template codeValue when creating your own template (codeMeaning should remain as "epad-plugin")

Installing an ePAD Plugin

After you build the ePAD plugin eclipse project using maven, it will create a jar in the target directory. If your plugin uses MATLAB, a second jar needs to be created for the MATLAB (see below). These two jars along with the template file need to be installed on the ePAD system in order to run your plugin.

  • First install an ePAD system using the current ePAD VM image or ePAD Docker images.(See the Installation section)
  • Copy your generated jars (one for the java plugin and one for MATLAB code) into DicomProxy/lib/plugins (there is no need to copy the epad-common or aimapi jar file - they are in the project, just for linking your java code).
  • Upload your template xml file to the ePAD system.
  • Define your new plugin through the ePAD UI.
  • Restart epad (alias epad-start), in order to load your jars..

If you now create an annotation, using your new template, the server will run your plugin code

MATLAB Java Code Generation for Plugins

In order to deploy MATLAB-based plugins in ePAD their code must first be converted to Java. Recent versions of MATLAB contain an optional code generation component called the MATLAB Compiler for generating code in various languages from MATLAB source. The Builder JA subcomponent is used to generate Java from MATLAB.

These instructions outline how to generate Java using the R2016B version of MATLAB using its graphically-driven Builder JA tool. It also describes how to to integrate the resulting code into ePAD.

The conversion process essentially takes one or more MATLAB functions and converts them to Java methods. For example, if we have the following MATLAB function:

function y = square(x)
%
%  calculate the square of the given number 'x'
%  
%  Arguments:
%  
%       x           (input)   value to be squared
%       y           (output)  the result of the square

  y = x*x;

% end of square function

the conversion process will generate a Java method in within a user-specified Java class that contains a Java implementation of this method. This generated code is packaged as a Java JAR. This JAR can be included in standard Java programs and its included methods can be invoked.

The inputs parameters and return values of the generated Java methods use MATLAB-defined types, which are supplied by a JAR supplied by the MATLAB BuilderJA too.. This JAR, which is called javabuilder.jar, supplied all the types necessary to convert to and from standard Java types to MATLAB-specific types.

Detailed documentation of the process may be found here.

Since ePAD is deployed on a CentOS server and the Builder JA code generation tool does not always produce platform-independent Java JARs, we must generate the code from a CentOS-installed version of MATLAB (We do not recommend using other platforms for building the jars). First, install the R2016B version of MATLAB on CentOS. The installation should include the Builder JA component, which is packaged with the MATLAB Compiler component.

The deployment machine must also have the same version of the MATLAB Compiler Runtime installed.

Note that the R2016B version of Builder JA requires a Java 7 runtime on the deployment machine.

Installing MATLAB Runtime on CentOS/Unix

(Please note that Matlab runtime is already installed on ePad VM. You are not required to do these unless you install on a new machine.)

See: http://www.vision.caltech.edu/cadabra/CADABRA%201.03B/ANALYSIS/readme.txt

Download from http://www.mathworks.com/products/compiler/mcr/

e.g., MCR_R2016b_glnxa64_installer.zip

Create a directory, go it that directory, unzip and on Unix systems install by executing the following command on the command line..

./install -mode silent -agreeToLicense yes -destinationFolder /opt/MATLAB/MATLAB_Compiler_Runtime/ 

NOTE: there may already be an install command on system so make sure to qualify the ./install invocation.

Final report of installer should list required libraries, e.g.,
On the target computer, append the following to your LD_LIBRARY_PATH environment variable:

/opt/MATLAB/MATLAB_Compiler_Runtime/v91/runtime/glnxa64:/opt/MATLAB/MATLAB_Compiler_Runtime/v91/bin/glnxa64:/opt/MATLAB/MATLAB_Compiler_Runtime/v91/sys/os/glnxa64:/opt/MATLAB/MATLAB_Compiler_Runtime/v91/sys/java/jre/glnxa64/jre/lib/amd64/native_threads:/opt/MATLAB/MATLAB_Compiler_Runtime/v91/sys/java/jre/glnxa64/jre/lib/amd64/server:/opt/MATLAB/MATLAB_Compiler_Runtime/v91/sys/java/jre/glnxa64/jre/lib/amd64

Next, set the XAPPLRESDIR environment variable to the following value:

/opt/MATLAB/MATLAB_Compiler_Runtime/v91/X11/app-defaults

For earlier versionf os MATLAB (e.g, 2010b) on Unix do: MatlabR2010b.bin -console

Run MATLAB and click on the Apps icon and then select the MATLAB Compiler. The first step is to create a project for our code generation task. Click on the New button, select Library Project. Then specify Java Package for the Application Type. You will be presented with the following screen.

The main artifact of the code generation process is an installer for installing the generated JAR file. For the purposes of ePAD we are only interested in the JAR itself so we do not care about the installer options. For this reason, we can ignore the runtime options at the top of the screen. For the same reason, we can ignore the Additional Installer Options area.

We can now add MATLAB code to our project and set some configuration options. First fill in the name field (e.g., regiongrow_java) in the Application Information area. This name corresponds to the name of the generated Java JAR. That is, in this case the end result of the code generation process will be a JAR called regiongrow_java.jar. You can optionally fill in other high level information in the first section of the Application Information area, though nothing else is required here.

In the second section of the Application Information area, change the class name of the main Java class in the JAR from Class1 to something meaningful, e.g., RegionGrow. This class will be the core class generated in the JAR. Individual MATLAB files included in the project will correspond to methods in this class. For example, if we have a MATLAB file called getindex.m a corresponding method called getindex will be generated in the RegionGrow class.

Now add the source MATLAB files to the Exported Functions area. Each added MATLAB file should also generate a listing in the Method Name section of the Application Information.

The Files Required for your Application to Run and Files Installed with your Application fields should be filled in automatically by the tool.

The final step is to specify the output directory for the generated artifacts. Click on the Settings icon and select and fill in Testing and Distribution Folders fields.

Example testing and redistribution directories could be:

 ~/workspace/tegseg/matlab/regiongrow_java/for_testing
 ~/workspace/tedseg/matlab/regiongrow_java/for_redistribution

Before initiating the code generation process we should save the project. Click on the Save icon and select a location for the project.

We can now generate the code. Click on the Package icon and the process will start. On completion the artifacts should be generated in the testing and redistribution directories specified earlier.

The directory ./for_redistribution_files_only will contain the generated JAR, e.g., regiongrow_java.jar.

Before deploying the JAR we must create and build a java wrapper. We then deploy this jar and the jar produced by matlab to an ePAD VM. As mentioned above, the deployment machine must have the MATLAB Runtime Compiler installed. This compiler must be of the same version as the Builder jA tool used to generate the Java JAR. (The current Matlab version in the vm is 2013b. Please remember to change/update the vm matlab version if you wish to use another version and note that other plugins may not work in that case)

The plugin wrapper creates the interface between ePAD and the MATLAB-generated Java code. The wrapper will be invoked with an AIM ID and a DICOM image ID. Then, it downloads the AIM file and the DICOM PNG image from ePAD using REST API. Using the AIM API, it extracts a point from the AIM file (or something different depending on the plugin’s need). The wrapper has to convert these points and the PNG image to MATLAB’s Java input data structures.

After the MATLAB routine is finished, the wrapper converts the return value to Java data structures. It saves the result in an AIM file (or something different) and gives a signal that the call is terminated.

There are some requirements that your Java wrapper needs to take care of for integrating with ePad. (You can download and use an example ePAD Plugin from epad-sample-plugin which already has the settings below which may need some name changes.)
Your main class must extend edu.stanford.epad.common.plugins.AbstractPluginServletHandler and override the necessary methods. You must insert the header @PluginHandler above the class and you must add your adaption of the following code to your pom.xml file:


<dependencies>
<!-- This is in a local project repository (in ./lib) because we could 
            not find a public Maven repository containing it. -->
<dependency>
        <groupId>com.mathworks</groupId>
    <artifactId>javabuilder</artifactId>
        <version>${matlab.release.number.sampleplugin}</version>
    </dependency>
<!-- Here goes the MATLAB-generated JAR. --> 
    <dependency>
        <groupId>edu.stanford.epad.plugins.sampleplugin</groupId>
        <artifactId>readDICOM</artifactId>
       <version>${matlab.release.number.sampleplugin}</version>
    </dependency>
    <dependency>
        <groupId>edu.stanford.hakan.aim4api</groupId>
        <artifactId>aimapi</artifactId>
       <version>${aimapi.version}</version>
    </dependency>
</dependencies>

You must create a ./lib directory in your project to place the local Maven repository by following the steps in Integrating Matlab Java JAR into Wrapper Project section. You could do this by simply copying the folder that was created and pasting it to the lib folder. By using Maven repository, every time one clones your code from the repository and builds it, the person will have the dependency in its local repository.

We now need to incorporate this JAR into the wrapper project. If we already have a previous version of the JAR the first step is to copy it to the local Maven repository in the project, e.g.,

cp regiongrow_java.jar ~/workspace/tedseg/lib/edu/stanford/epad/plugins/tedseg/regiongrow_java/R2013b/regiongrow_java-R2013b.jar

We then copy it to our local Maven reposository., e.g.,

cp regiongrow_java.jar ~/.m2/repository/edu/stanford/epad/plugins/tedseg/regiongrow_java/R2013b/regiongrow_java-R2013b.jar

If we do not have a previous version of this JAR we need to generate a Maven-compliant installation of it in ePAD.

You can find detailed instructions for this process here.

Basically, for each ePAD plugin we need to generate Maven artifacts for the generated JAR and for an associated Java JAR called javabuilder.jar. This latter JAR is provided by MATLAB and contains MATLAB APIs that are used by the generated JAR.

An example ePAD-specific Maven artifact generation instruction for this JAR is:

mvn install:install-file -Dfile=javabuilder.jar -DgroupId=com.matlab -DartifactId=javabuilder -Dversion=R2013b -Dpackaging=jar -DgeneratePom=true

This JAR can be shared by multiple plugins. We arbitrarily selected com.matlab as the group identifier of this JAR.

An example ePAD-specific Maven artifact generation instruction for a generated JAR called regiongrow_java.jar is:

mvn install:install-file -Dfile=regiongrow_java.jar -DgroupId=edu.stanford.epad.plugins.tedseg -DartifactId=regiongrow_java -Dversion=R2013b -Dpackaging=jar -DgeneratePom=true

To wire the wrapper to ePAD, mvn clean install your wrapper project and place your wrapper jar file and matlab jar file inside the plugins directory(~/DicomProxy/lib/plugins) in the vm.

You should also add an entry of your plugin, so the web service will know about it. Use the tools window from the gear on right upper corner to add your plugin. Make sure you put your plugin handler class name correctly including the package. As soon as the web service starts, it will read the plugins and run the init() method of each loaded plugin.

Lastly, you must create a template for the plugin so you can invoke it from ePAD. Upload your template using the templates window from the gear on right upper corner. Please note that the abbreviation you type when you add your plugin is used as the pluginID and it should be the put in the codeValue attribute in the template so that your plugin can be triggered.

Everything set! Just restart the web service: ~/DicomProxy/bin/epad-start.sh. Remember, it’s extremely important that you build your wrapper project in the same machine that you have generated the JAR file from MATLAB.

  • Start with Sample Plugin for your wrapper.
  • Always build your project using mvn clean install.
  • Make sure you are using the right version of Java. You can do this in the terminal: mvn/java/javac -version. In Eclipse, go to Preferences > Java > Installed JRE’s (and > Execution Environment).
  • If you are getting errors about dependencies while building the project, try deleting your local Maven repository (~/.m2/repository), or part of it.
  • If you are getting errors in Eclipse after building the project, do a Refresh (F5) and a Maven Refresh (Alt + F5).
  • If you get blank errors in Eclipse, go to Preferences > Validator and uncheck Web (2.2 - 2.4) Validator.
  • Do a tail -f ~/DicomProxy/log/epad-ws.log to tail the web service log file.
  • If ~/DicomProxy/bin/epad-start.sh doesn’t work properly, do: cd ~/DicomProxy/bin/ and then screen -d -m -S ePADWebService sh epad-server-start.sh.
  • Make use of Maven archetype for pure Java or GWT projects when start creating a new project.
  • Use repository in ${project.basedir}/lib for JARs that can not be found in public Maven repositories. Each project ./lib directory should contain dependencies that may be used by that project. See: http://blog.dub.podval.org/2010/01/maven-in-project-repository.html.
  • The name of the plugin (tool) should be specified also in the plugin wrapper (in getName() method). This name is used as the url of the plugin at the plugin endpoint to trigger the plugin
  • For being able to trigger the plugin with template, the id (abbreviation) of the plugin should be equal to the codeValue of the template. And the template’s codeMeaning should be "epad-plugin”. The name of the template is not relevant in plugin triggering process.