Instant JChem Developer's Guide

Table of contents

• Overview
• Working with IJC Architecture
• Scripting
  • Groovy Scripts
  • Groovy Scriptlets
  • Current Limitations
• Java Plugins

Overview

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):

• Groovy Scripting: This level of scripting happens within IJC, and is the easiest mechanism for end users. IJC comes with a simple script editor, and built in variables to help drive script development. This scripting ability can be used in several locations within the IJC architecture: on a dataTree, as part of a schema, as a form button, or as part of a calculated field. Because they are located on objects, they can be distributed as part of a shared project. However, if they are not in a shared environment, they can only be placed on another project by copying and pasting via email or document. Scripting within IJC is a new feature under continuous development. Currently, the editor is very simple, with limited feedback.
• Java based plugins: Java based plugins are a NetBeans style module that allows extension of the IJC functionality, offering a level of power and complexity above Groovy scripting. For instance new items can be added to menus, and new wizards created. The more wide spread use of Java is often more comfortable to hard core Java developers, as well as having the option of writing in an IDE (with all that they offer). Plugins can be easily distributed to end users as part of the IJC distribution or as an update via the update center (distribution using Java Web start is currently not so simple). However, plugins are more complex than IJC-based Groovy scripts (see the basic Hello World script).
• Stand-alone code: It is also possible to write your own code on top of the IJC platform. This is most suitable for command line tools or wanting to access the DIF without the GUI. This approach is not used often, but if you are interested, please contact IJC support.

Working with IJC Architecture

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

• IJC terminology
• How IJC items fit together
• The information presented in the IJC User's Manual

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.

Scripting

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.

• Simple SDF Exporter: A basic and easily customizable exporter of molecules to a SD file.
• Relational SDF Exporter: Writes structures and data from a relational data tree to a SD file.
• CDX File Importer: Recursively searches a directory for Chemdraw CDX files and loads the structures.
• Data Merger or Inserter from an SDF: Merges or inserts new data from a SD file to an existing table.
• Markush DCR Structures Exporter: Works within Markush Thompson-Reuters data sets and exports the example DCR structures for selected inventions.
• Select the Representative Member of Clusters: Will pick a representative member of a cluster based on some condition (such as activty).
• Table Standardizer and Reporter: Applies a standardizer XML to a table and outputs a column with the standardized structure, and the rules that were used.
• Populate table with pH Microspecies: Populates a table with microspecies of compounds from another table based on pH conditions
• Create Diverse Subset: Creates a diverse subset of compounds based on an overlap analysis.
• Pearson Linear Correlation Co-efficient Calculator: Calculates the PLC for selected input fields.
• PDF Trawler: Trawls a directory for PDF files, extracts the molecules and inserts them into a structure entity.
• Simple Substructure Search: A very simple script for performing a substructure search on a structures table. A good example for those more familiar with Java.
• Intersecting Sets: This script works on the Wombat data set, and calculates the number of compounds that belong to the intersection three sets. This is another good example for those who are more familiar with Java.
• Finding duplicated values: This script works on the Data tree level, and finds all entries with duplicated field value. It works on text, number and chemical terms fields. It is analogical to Overlap analysis functionality used for structure field.
• Importing multiple SDF files: Scan a directory and its subdirectories for SDF files and import all these files to one new entity.
• Calling external tools: Two examples that show how to call tools/processes that are external to IJC and how to deal with the I/O associated with each.
• Create relational data tree: This complex example shows how to create entity, populate it with data, make relation between entities, use edge and display as data tree.

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.

• Create New Form: The basic demonstration of Forms Model concepts. Will create a simple form view with a few widgets.
• Create New Grid: A new simple grid view.
• Create New Panel: Shows how to work with the panel widget.
• Create New Tabbed Pane: This script creates a tabbed pane widget and adds widgets to its tabs.
• Copy Existing Form: Makes a copy of an existing form view, modifies the copy and saves it as a new form view. This can be used for cloning and tweaking view templates.

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.

• Execute first permanent query: A button script which executes the first permanent query it finds in data tree and shows results in form.
• Patent Fetcher for Markush Thompson-Reutors Data Button: Provides many ways to view original patents in Inventions of the Markush TR data set.
• Batch Searching of Structures Button: Will search a SD file of compounds against the Markush Thompson-Reuters data set.
• Import/Export Batch Query Results Button: Two buttons that allow you to export the query results of the above batch search, or load the results back in.
• Back/Next Form Buttons: Simple back and next buttons for forms.
• Add Annotations to Molecules Button: A system for adding annotations to molecules and searching based on these annotations.

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.

• Drop Down Input Dialog: Opens an input dialog for the TextField widget and let you choose from predefined values.

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.

• Buttons vs. Scripts, interchanging the two
• Creating a new entity (table list)
• Creating a new field (column)
• Reading in molecules from a file
• Inserting or updating rows of data
• Using Evaluator and ChemJEP to use chemical terms
• Create or locate a relationships between two tables
• Add an edge to a table with an existing relationship
• Export data to a file
• Connect to an external database
• Create a new chemical terms field
• Create a new dynamic URL field
• Create a new static URL field

• Groovy web site
• Groovy JDK
• Mr. Haki's Groovy goodness blog

Current Limitations

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

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.

• IJC Plugin Quick Start - This tutorial is the must for anybody wishing to start developing IJC plugins. It introduces the tools essential for IJC plugin development and shows how to compile and run IJC example plugins, which gives you a starting point for your own experiments.
• IJC Plugin "Hello World!" - In this tutorial you will create your own simple IJC plugin, build it and deploy it to Instant JChem. In the first part the tutorial shows how to setup your environment for IJC plugin development and then walks you through the process of creating a simple 'Hello World!' plugin.
• IJC Plugin tutorial: MyAddField plugin - This tutorial will introduce you to the basics of IJC plugin development and using Instant JChem APIs. It will walk you step by step through the process of creating 'Add Field' IJC plugin included in IJC API Examples suite.
• IJC Plugin tutorial: MyMathCalc plugin - This tutorial shows how to add an action, invoked by a menu item, for reading values from the grid view selection and calculating averages or sums.
• Renderer example - Simple example of plugging in a new type of renderer. This one colours the cells in the grid view based on some user specified cutoff value.
• Structure Checker Web Service - An advanced example that shows how an IJC plugin can interact with a RESTful web service to process molecule structures and apply results back to IJC entity. This example has two parts - the RESTful web service implemented as a J2EE web application StructureCheckerServer and an IJC plugin StructureCheckerClient that consumes the web service.