Integration of third-party calculations into Marvin and JChem

This manual gives you a walk-through on how to integrate your own calculation into Chemaxon tools:

Introduction

Third-party calculations can be integrated into Marvin and JChem by using Chemaxon's Calculator Plugin system. By a third-party calculation we mean any calculation which is not provided by Chemaxon via Marvin Beans or JChem. The guides below describe how third-party calculations can be integrated into Chemaxon applications and toolkits, including GUI, applet, command line and API. All guides contain code examples and links to the related topics in developers guide.

MarvinSketch GUI offers a user-friendly way of integrating third-party calculations as a service via the Services module.

Example plugin

To create an example it is first required to extend the chemaxon.marvin.plugin.CalculatorPlugin class; the descendant class should call the third-party calculation. The steps of the implementation are described in the Calculator Plugins Developers Guide.

In the examples below the BemisMurckoPlugin will be used to showcase the third-party plugin implementation. The BemisMurckoPlugin will be able calculate the Bemis-Murcko framework of a molecule, return it as Molecule object, and also calculate the number of atoms and bonds in the generated Bemis-Murcko framework, returning them as integers.

A custom plugin implementation - of course - can call any Java library, native application (through JNI), or libraries written in other languages, such as C or C++ (through JNI). In the current example only MarvinBeans Java library is called from the code of the BemisMurckoPlugin.

General notes

In this document we will refer to the Marvin installation directory as MarvinBeans directory.

If Marvin's default installation was followed, Marvin installation directory is:

Windows: C:\Program Files\Chemaxon\MarvinBeans
Linux: $HOME/Chemaxon/MarvinBeans (e.g. /home/myusername/Chemaxon/MarvinBeans)
OS X: /Applications/Chemaxon/MarvinBeans

{info} In MarvinSketch and MarvinView Calculator Plugins can be accessed from the Tools menu.

Integration into different products

MarvinSketch/MarvinView

To integrate a calculation into MarvinSketch/MarvinView application the following steps should be made:

Implement a CalculatorPlugin class. Implement also a CalculatorPluginDisplay class, if required (see more here). We only implemented BemisMurckoPlugin.java. In the current example BemisMurckoPluginDisplay class is not required.

Compile the classes. Use the Marvin Beans package for compilation.


javac -classpath MarvinBeans/lib/MarvinBeans.jar BemisMurckoPlugin.java

Create the plugin options panel description in XML file (for details, please email to the Chemaxon's support). Copy the created BemisMurckoPluginParameters.xml to a directory named xjars .
Pack the created class and XML files into a JAR. In the next command BemisMurckoPlugin.txt refers to JAR manifest file, which also has to be created. The BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file.
```
jar cmf BemisMurckoPlugin.txt BemisMurckoPlugin.jar BemisMurckoPlugin.class xjars/BemisMurckoPluginParameters.xml
```
Copy the JAR file into the plugins directory. The created JAR file (BemisMurckoPlugin.jar) has to be copied to the MarvinBeans/plugins directory.
Create/edit the Tools menu configuration file. Create your own instance of plugins.properties in the MarvinBeans/plugins directory. This properties file describes the structure of the Tools menu in MarvinSketch/MarvinView. If this file exists, it overwrites the default Tools menu. There is a template for plugins.properties in this directory. Just make a copy of it and edit it. To add a new menu item for the new plugin add the following line to the file:
```
plugin_999=$BemisMurckoPlugin$BemisMurckoPlugin.jar$Bemis Murcko Framework$B$$
```
Run MarvinSketch/MarvinView. You can run the example plugin by selecting the Bemis-Murcko Framework from the Tools menu.

{info} The plugin class has to be referenced with full name (including the name of the package that contains the class).

Marvin applets

Integration into MarvinSketch and MarvinView applets is quite similar to the application integration, only the compilation process and the JAR file creation is different. In this section marvin will refer to the root directory of Marvin Applets:

Implement a CalculatorPlugin class (see more). Implement also a CalculatorPluginDisplay class, if required (see more).

We only implemented BemisMurckoPlugin.java. In the current example BemisMurckoPluginDisplay class is not required.
Compile the classes. Use JAR files from Marvin Applets package for compilation of the new plugin. Since Marvin Applets classes are compiled with 1.5 compatible compiler, additional code has to compile with 1.5 compatible JDK. To provide compatibility, set the source and the target attributes to 1.5.
```
javac -source 1.5 -target 1.5 -classpath "marvin/jmarvin.jar:marvin/sjars/Plugin.jar:marvin/sjars/PluginGUI.jar" BemisMurckoPlugin.java
```
Create the plugin options panel description in XML file (for details, mail to Chemaxon's support).

Copy the created BemisMurckoPluginParameters.xml to a directory named xjars.
Pack the created class and XML files into a JAR. Marvin applets accept custom plugins from certain location: marvin/plugin/extensions.jar . Therefore, wrap resources for your plugin into extensions.jar. In this example, BemisMurckoPlugin.txt is the manifest file for the JAR file, BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file.
```
jar cmf BemisMurckoPlugin.txt extensions.jar BemisMurckoPlugin.class xjars/BemisMurckoPluginParameters.xml
```
The JAR files that Marvin applets load have to be signed.
```
jarsigner -keystore "<keystorepath>" -storepass <password> extensions.jar <alias>
```
In the above statement, the <keystorepath> is the location of the keystore file where your signing key is stored. The<password> gives the password for the keystore. The <alias> is the alias of the certification key in the keystore.
Copy the JAR file into the plugins directory. The created JAR file (extensions.jar - note: the downloadable jar is not signed) has to be copied to the marvin/pluginsdirectory.
Create/Edit the Tools menu configuration file (see more).

Create your own instance of plugins.properties in the marvin/plugins directory. This properties file describes the structure of the Tools menu in MarvinSketch/MarvinView. If this file exists, it overwrites the default Tools menu. There is a template for plugins.properties (plugins.properties.sample.txt) in this directory. Just make a copy of it, and edit it.

To add a new menuitem for the new plugin add the following line to the file:
```
plugin_999=$BemisMurckoPlugin$BemisMurckoPlugin.jar$Bemis Murcko Framework$B$$
```
Now, you are ready. In MarvinSketch/MarvinView applet the new plugin will display in the Tools menu.

cxcalc

Cxcalc is Chemaxon's application for performing the plugin calculations in batch mode. Integration with cxcalc goes as follows:

Implement a CalculatorPlugin class (see more). Implement also a CalculatorPluginOutput class if required (see more).

We only implemented BemisMurckoPlugin.java. In the current example BemisMurckoPluginOutput class is not required.

Compile the classes. Use the Marvin Beans package for compilation:


javac -classpath MarvinBeans/lib/MarvinBeans.jar BemisMurckoPlugin.java

Pack the created class file(s) into a JAR. In the next command BemisMurckoPlugin.txt refers to JAR manifest file, which also has to be created.
```
jar cmf BemisMurckoPlugin.txt BemisMurckoPlugin.jar BemisMurckoPlugin.class
```
Copy the JAR file into the plugins directory. The created JAR file (BemisMurckoPlugin.jar) has to be copied to the MarvinBeans/plugins directory.
Create/edit the calc.properties configuration file (see more). Create your own instance of calc.properties in the MarvinBeans/plugins directory. This properties file should contain the configurations (parameters, help text, etc.) of the third-party calculations. If this file exists, then the calculations defined in it are added to default calculations. There is a template for calc.properties (calc.properties.sample.txt) in this directory; just make a copy of it and edit it.

The new calculations can be run with the following commands:

Generate the Bemis-Murcko framework
```
cxcalc bemismurcko testmols.sdf
```

Count atoms of the Bemis-Murcko framework


cxcalc bemismurckoatomcount testmols.sdf

Count bonds of the Bemis-Murcko framework


cxcalc bemismurckobondcount testmols.sdf

Chemical Terms

Chemical Terms is a language for adding advanced chemical intelligence to cheminformatics applications. It is an additional interface to access plugin calculations, and is integrated into a number of Chemaxon's applications (e.g. Instant JChem, JChem Base, JChem Cartridge, Reactor). Chemical Terms can also be used with Marvin applets through JavaScript.

In case of Chemical Terms, integration means adding a new Chemical Terms function. After the function is added, it can be used from all applications that uses Chemical Terms.

The integration steps are the following:

Implement a CalculatorPlugin class (see more).

We implemented BemisMurckoPlugin.java already.

Compile the classes. Use the Marvin Beans package for compilation.


javac -classpath MarvinBeans/lib/MarvinBeans.jar BemisMurckoPlugin.java

Pack the created class files into a JAR. In the next command BemisMurckoPlugin.txt refers to JAR manifest file, which also has to be created. The BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file.
```
jar cmf BemisMurckoPlugin.txt BemisMurckoPlugin.jar BemisMurckoPlugin.class
```
Copy the JAR file into the plugins directory. The created JAR file (BemisMurckoPlugin.jar) has to be copied to the MarvinBeans/plugins directory.
Create/edit the evaluator.xml configuration file.

Create your own instance of the evaluator.xml file in the MarvinBeans/config directory (see the Evaluator manual for alternative location). This XML file describes the Chemical Terms functions. If this file exists, then the functions defined in it are added to default functions. There is a template for evaluator.xml (evaluator.xml.sample.txt) in this directory; just make a copy of it, and edit it.

Test the new functions with Chemical Terms Evaluator:

Generate the Bemis-Murcko framework
```
evaluate -e bemisMurcko() testmols.sdf
```

Count atoms of the Bemis-Murcko framework


evaluate -e bemisMurckoAtomCount() testmols.sdf

Count bonds of the Bemis-Murcko framework


evaluate -e bemisMurckoBondCount() testmols.sdf

Applets

After performing the steps above the Chemical Terms functions will be accessible via JavaScript from MarvinSketch/MarvinView applet. In this section marvin will refer to the root directory of Marvin Applets.

Implement a CalculatorPlugin class (see more).

We implemented BemisMurckoPlugin.java .
Compile the classes. Use JAR files from Marvin Applets package for compilation of the new plugin. Since Marvin Applets classes are compiled with 1.5 compatible compiler, additional code has to be compiled with 1.5 compatible JDK. To provide compatibility set the source and the target attributes to 1.5.
```
javac -source 1.5 -target 1.5 -classpath "marvin/jmarvin.jar:marvin/sjars/Plugin.jar:marvin/sjars/PluginGUI.jar" BemisMurckoPlugin.java
```
Pack the created class files into a JAR. Marvin applets accept custom plugins from certain location: marvin/plugin/extensions.jar. Therefore, wrap resources for your plugin into extensions.jar. In this example, BemisMurckoPlugin.txt is the manifest file for the JAR file, BemisMurckoPlugin.class file is the result of the compilation of BemisMurckoPlugin.java into class file.
```
jar cmf BemisMurckoPlugin.txt extensions.jar BemisMurckoPlugin.class
```
The JAR files that Marvin applets load have to be signed.
```
jarsigner -keystore "<keystorepath>" -storepass <password> extensions.jar <alias>
```
In the above statement, the <keystorepath> is the location of the keystore file where your signing key is stored. The <password> gives the password for the keystore. The <alias> is the alias of the certification key in the keystore.
Copy the JAR file into the plugins directory. The created JAR file (extensions.jar) has to be copied to the marvin/pluginsdirectory.
Create/edit the evaluator.xml configuration file (see more).

Create your own instance of evaluator.xml file in the marvin/config directory (see the Chemical Terms Language Reference for alternative location). This XML file describes the Chemical Terms functions. If this file exists, then the functions defined in it are added to default functions. There is a template for evaluator.xml (evaluator.xml.sample.txt) in this directory; just make a copy of it, and edit it.

After performing these steps the new calculations can be called from the applet via JavaScript.

API

The implemented BemisMurckoPlugin.java provides also java Application Programming Interface, so it can be used from other Java code. For details see Calculator Plugins Code Examples.