Instant JChem Developer's Guide

Table of contents


The primary intention here is to allow customers and 3rd party developers to extend Instant JChem and to build upon the core functionality in several different ways. IJC provides much of the basic functionality needed for chemical database work, with a number of ways to add specialized utilities on top of the existing API. This high level of extension and customizability provides a suite of chemistry-based research and registration tools which we hope can fit all your needs.

Developer documentation (mainly the JavaDocs) updated at a regular basis to keep the API in sync with the latest version of IJC. The IJC forums are an excellent place to see if your development needs have already been met by other users, or get advice on the best approach to developing your extension. We also maintain a list of suggested 'good practices' to encapsulate suggestions and tricks to improve your code.

There are three main approaches to extending IJC. They all share the same API, needing only language based interpretation (eg Groovy vs. Java implementation):

Working with IJC Architecture

This manual is an extension to basic IJC information provided earlier. We strongly recommend the developer have an understanding of:

Instant JChem essentially has three different layers:

  1. The DIF model and persistence tier
  2. The core IJC application (based on the NetBeans platform)
  3. Modules that add functionality to the core application

Whilst the 2nd a 3rd layers are based on the NetBeans platform, the DIF layer is not dependent on it (it does use some NetBeans libraries, but these are generic libraries and can be used outside the NetBeans platform). This makes the DIF tier suitable for creating non-NetBeans platform based applications.

To use the 2nd and 3rd tier you should get a good understanding of the NetBeans platform. Note: you do not need to use the NetBeans IDE to work with Instant JChem or DIF, but it does provides some useful features for developing NetBeans platform based applications, so you may wish to look at this if you are not already a NetBeans IDE user

Further discussion of IJC API and the JavaDocs can be found in the IJC API Discussion page.


Groovy Scripts

The best way to learn how scripting works in IJC is to study some examples. Below is our ever-growing repository of scripts with brief explanations. There is further discussion about the utility and function on the individual script page. We welcome submissions from IJC users to include in this list.

Scripts are executed in the context of a data tree or schema. When the script is executed the data tree or schema is 'injected' into the script as a variable that can be used by the script. The variable name is 'schema' when scripting a schema and 'dataTree' when scripting a data tree. The built-in 'Getter and Setter' syntax simply translates dataTree.getRootVertex().getEntity() to dataTree.rootVertex.entity. The two key injected variables are dataTree and schema, which follow the API for DFDataTree and DFSchema.

The editor opens with a very simple example script that demonstrates a number of fundamental uses for this variable.

Since IJC 5.10 scripts can be cancelled at any point during their execution. The Cancel button is located in the bottom right corner of the status bar. When pressed for a running script, it is interrupted and forced to halt execution. We provided a simple mechanism for cancelling several scripts (e.g. Simple SDF Exporter) previously. You can see additional lines in the source code, that are well commented there. This "manual" approach is no longer needed since a ThreadInterrupt transformation is injected for key syntactical elements of any script, which force to check for an interrupt at those points. More information about the details, can be found at Groovy website.

Schema/DataTree Scripts

These appear in the project explorer in a 'Scripts' folder under the appropriate schema or data tree. To create a new script right click on the schema, data tree or script folder and choose 'New script...'. You can then copy and paste the script into the script editor.

Forms Model Scripts

These are data tree scripts that are focused on working with the Forms Model. They show how to programatically work with form and grid views and their widgets.

Button Scripts

These are buttons on a form which execute the script when the user clicks on the button. The script can access the underlying data in the form.

Form Scripts

These are edited in the Code tab of the form/grid view. Script will be executed when defined event take place on the widget.

Groovy Scriptlets

Scriptlets are the minimal Groovy code snippets required to do common tasks, such as adding a new field, importing molecules from a file, or creating a new entity. Any scriptlet is unlikely to be of any use on its own. A complete script would typically combine various of these tasks to do some useful work. Scriptlets are provided as reference, a HOWTO for these common tasks.

Each link contains an explanation of the scriptlet with links to the relevant API.

Learn more about Groovy here:

Current Limitations

Scripting within IJC is a continously developing process. Current limitations that are in a process of development.

Editor support Scripts are edited using a pretty basic editor. Improved editor support (with better syntax highlighting, formatting and code completion etc.) is in the pipeline.
A script cannot easily access multiple schemas While a script can access the data or structure from another schema, it is not a trivial task. Please contact us if you have need for the feature.
Forms have limited scripting capability Several things can be scripted on the forms currently. There is the 'Button' widget for running scripts. Also double-click event on following widgets can be customized: MolPane, MolMatrix, TextField, TextArea, Table and GridView. We plan to support more widgets and events in the near future.
Improved syntax Groovy allows easy generation of Domain Specific Languages (DSLs) which can provide a simpler approach that a traditional Java API. We plan to provide DSLs for accessing the IJC APIs to make working with scripts easier.

Java Plugins

The API examples contain source code for several IJC plugins. In order to compile these plugins and install them to Instant JChem you should follow IJC Plugin Quick Start tutorial. This tutorial will walk you through the process of installing and setting up tools required for IJC plugin development and will show you how to download, compile and run the IJC example plugins.

If you don't want to follow the IJC Plugin Quick Start tutorial you can download the source code of IJC example plugins directly from here. The ZIP file contains NetBeans IDE projects for all IJC example plugins as well as any other utility or library modules required in the examples. The starting point is the api-examples-suite project, which is a modules suite with all the example plugins. Building and running the suite will build and run all the examples included in the suite.

Copyright © 1999-2013 ChemAxon Ltd.    All rights reserved.