Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Panel

This manual gives you a walk-through on how to use local services.

Table of Contents
maxLevel3


Introduction
 

A local service is for accessing third party calculations implemented in Java. It does not require server or network connection. A Java Archive (JAR) file acts as "server", any public class with default constructor acts as "service", and all public methods can be called. Please keep in mind that the build-in editor may hide methods that requires unsupported argument type. Direct access of the Marvin Services API does not have this restriction, any type can be used.

...

Warning

Classes used via service call should be stateless, as each service call will create a new instance of the class by the default constructor before calling the function.

 

Examples
 

Example #1 
 

In this basic example we implement a method that returns the string "Hello <molecule name>!", where <molecule name> is the name of the molecule generated by ChemAxon's S2N (Structure to Name) converting tool. The following code will do this:

...

Having compiled this code, pack the created class file(s) into a Java Archive (JAR) file. All Java IDEs can export Java files in a JAR file. In Eclipse it can be done by the File > Export menu item. 

Anchor
fig.1
fig.1

...

After creating the JAR file, open MarvinSketch. Please note that version 5.6 or later is required. Select Edit > Preferences > Services from the menu. Then press the + button to add a new service.

...

To add a new service then proceed to press the Accept button. It will appear in the list of services.

Anchor
fig.3
fig.3

Fig. 3 Adding new services to the list of services

...

As a result of these steps the new service will be available from the Tools > Services menu.

Anchor
fig.4
fig.4

Fig. 4 Looking up the new services in MarvinSketch 

...

Finally, to use the new service, select the Tools > Services > Hello1 menu item with an input molecule on the canvas. The calculation result appears in a new dialog.

Anchor
fig.5
fig.5

...

Create a JAR file as above and name it hello2.jar. Call the new method (as a local service) from this JAR file. The name of the service, the description and the parameter names will be automatically filled during the setup.

Anchor
fig.6
fig.6

Fig. 6 Setting us the new service from the JAR source

...

Note that the result molecule format can be modified on the result display panel. Try it !

 

Example #2

 

The next example will be a bit more complicated as we will implement some microspecies related calculations. We want to 

...

Pack the MicrospeciesCalculator class into a JAR file as already described (mscalc.jar). Add all methods as local services to the service list. Finally you should have a list like follows:

 

The result of running the MMS calculation is the major microspecies molecule at a given pH. 

...

The MSReport calculation generates the source code of an HTML page and returns it as a string. The HTML page is then rendered on the fly by the result display component.

...

Changes made on the molecule in MarvinSketch will be automatically updated on the results display (both structure and results), if the Calculate Automatically option is enabled.

 

Calling Local Services from API

 

The following code snippet calls the Integer countAtoms(Molecule) function of the example.services.SampleService class located in localserviceexample.jar.

...

Code Block
languagejava
linenumberstrue
 // input molecule
	Molecule input = MolImporter.importMol("c1ccncc1");

	// initialize descriptor
	LocalServiceDescriptor descriptor = new LocalServiceDescriptor();
	descriptor.setURL("/path/to/localserviceexample.jar");
	descriptor.setClassName("example.services.SampleService");
	descriptor.setMethodName("countAtoms");
	descriptor.addArgument(ServiceArgument.createArgument(new Molecule()));

	// asynchronous call
	descriptor.getServiceHandler().callService(descriptor, new AsyncCallback<Integer>() {

	    @Override
	    public void onSuccess(Integer result) {
	        System.out.println("Asynchronous call returned " + result);
	    }

	    @Override
	    public void onFailure(ServiceException caught) {
	        System.err.println("Asynchronous call failed.");
	    }
	}, input);

	// synchronized call
	Object result = null;
	try {
  	    result = descriptor.getServiceHandler().callService(descriptor, input);
	} catch (ServiceException e) {
	    System.err.println("Service call failed.");
	}
	System.out.println("Synchronized call returned " + result);
		
	

Use annotations to define default names and description

 

A Local Service can look up default service and argument names, as well as description information from annotations. These values are used in MarvinSketch when adding the Local Service to the list of services by automatically completing the form. The values can be edited manually, but the defaults are always available from Chemical Terms or cxcalc - as well as the optionally overwritten ones.

...