Structure Checker Developer's Guide

Contents

• Introduction
• Architecture
• Annotation
• Example
• Tutorial
• Links

Introduction

Structure Checker is an API which provides functionality (through StructureChecker implementations ) to check properties, features or errors on a Molecule object and with the help of the Structure Fixer classes it provides fixing mechanism for the detected problems.

Architecture

The most important interface in the Structure Checker API is StructureChecker. Every StructureChecker instance has a method called check(Molecule mol) which provides the mechanism to check for problem in the molecule. This method returns a StructureCheckerResult if any problem is found in the molecule or null otherwise. This result contains all the information needed for fixing the problem. All other methods of StructureChecker provide properties for GUI based representation. Every StructureChecker instance has any error type which signs the kind of the problem it checks. This error type has to be unique for every implementation.

For a developer who'd like to extend the list of the existing checker tools the best choice is to extend from ExternalStructureChecker class. It is a descendant of AbstractStructureChecker so it already implements all GUI property based functionalities (such as name handling, error message handling, icon handling etc.) and automatically sets the error type of the checker to EXTERNAL which signs that this checker isn't part of the ChemAxon built-in checker list and thus the runner framework will know that this checker's result had to be handled separated. And of course with this super class the developer have to implement only the checker mechanism for the problem. Structure Checker classes use annotations to store UI related information since version 5.7.x.
WARNING! Of course any developer can implement a checker which will have the same error type as one of the built-in checkers but at this case there can be ambiguous issues with the running framework and unexpected errors could happened. So in this case the proper work of the checker system can not be guaranteed.

StructureFixer implementations provide the functionality to fix a problem signed by a StructureCheckerResult. A fixer can modify anything in the molecule as the result has a reference to the Molecule and also contains a list of atoms and bonds affected by the problem. Structure Fixer classes use annotations to store UI related information since version 5.9.x.

CheckerRunner provides the functionality to run a set of checkers automatically on a molecule to collect all the results produced by the checkers and to find the related fixers for the problems or fix the problems automatically.

Annotations

Compared to the previously used property files, Structure Checker classes have been using annotations to store UI related information since version 5.7.x, while Structure Fixer classes have been using annotations since version 5.9.x. Applying annotations, the usage of external descriptors is optional in case of structure checkers and fixers. To provide backward compatibility and custom definitions, property files are still available for both custom checkers and fixers.

Annotation of Stucture Checkers

The name of the annotation class is CheckerInfo, and the following attributes can be specified:

• name (String): name of the structure checker
• localMenuName (String): printed name of the structure checker in local menus.
• description (String): description of the structure checker
• noErrorMessage (String): the message printed by the structure checker, when a structure does not contain errors, defined by this structure checker
• oneErrorMessage (String): postfix of the message printed - the prefix is 1 in this case - by the structure checker, when a structure contains one error defined by this structure checker.
• moreErrorMessage (String): postfix of the message printed - the prefix is the count of errors in this case - by the structure checker, when a structure contains more than one error defined by this structure checker.
• editorClassName (String): name of the class of the property-list editor for the structure checker
• helpText (String): the help text for the structure checker
• iconPath (String): the path of the icon for the structure checker
• severity (CheckerSeverity): the severity of the structure checker, instance of CheckerSeverity class

• actionStringToken (String): the actionstring token used by command line interface for this structure checker

Annotation of Stucture Fixers

The name of the annotation class is FixerInfo, and the following attributes can be specified:

• name (String): name of the structure fixer
• description (String): description of the structure fixer
• actionStringToken (String): the actionstring token used by comman line interface for this structure fixer

Example

To initiate a checker instance and to check a molecule object for problems developer has to do the following:

	//This example assumes that mol is chemaxon.struc.Molecule object 
	...
	//BondLengthChecker is one of the ChemAxon built-in checker implementations
	StructureChecker checker = new BondLengthChecker(); 
	StructureCheckerResult result = checker.check(mol);
	...

A valid annotation for a structure checker is as follows:

	@CheckerInfo(
	name="Molecule Charge Checker",
	localMenuName="Molecule Charge",
	description="Detects non-neutral molecules in which the total charge is not zero",
	noErrorMessage="No charged molecule found",
	oneErrorMessage="charged molecule found",
	moreErrorMessage="charged molecules found",
	actionStringToken="moleculecharge",
	editorClassName="chemaxon.marvin.sketch.swing.modules.checker.editors.ExplicitHydrogenCheckerEditor",
	severity=CheckerSeverity.WARNING
	)
	public class MoleculeChargeChecker{
	...

The next code example shows how to apply a StructureFixer to an existing StructureCheckerResult

	//This example assumes that result is a chemaxon.checkers.result.StructureCheckerResult object
	//Could be a continuation of the previous example
	...
	//CleanFixer is one of the ChemAxon built-in fixer implementations
	StructureFixer fixer = new CleanFixer();
	fixer.fix(result);
	...

A valid annotation for a structure fixer is as follows:

	@Fixes({StructureCheckerErrorType.ALIAS, StructureCheckerErrorType.ALIAS_ATOM})
	@FixerInfo(	
	name="Convert to Atom",
	description="Converts to an atom.",
	actionStringToken="aliastoatom"
	)
	public class ConvertToAtomFixer{
	...

CheckerRunner provides automatic checking and fixing features. Usage of this class is the following:

	CheckerRunner runner;

	//... (initialize/initiate the current CheckerRunner instance)
	List results = runner.checkAndWait();
	for (StructureChecekrResult result : results) {
		List fixers = runner.getFixers(result);
		//execute one of the fixers
	}

CheckerRunner supports executing the default fixer of a {@link StructureCheckerResult}

	CheckerRunner runner;
	... (initialize/initiate the current CheckerRunner instance)
	List results = runner.checkAndWait();
	for (StructureCheckerResult result : results) {
		runner.fix(result);
	}

Tutorial

This documentation also provides a tutorial which contains three different class implementation. "MyFirstStructureFixer.java" describes how easy it is to extend the existing Structure Checker framework with custom fixers. "MyFirstStructureChecker.java" shows how to create a new StructureChecker implementation. "MyFixerForMyChecker.java" introduces how to develop a new fixer for our own checker. All classes have their own JUNIT test file to test with. This tutorial only works with the current version of the properly installed Marvin and with MarvinBeans.jar, MarvinBeans-license.jar and MarvinBeans-checkers.jar in the classpath during compile.

Links

List of available checkers
Structure Checker GUI
structurecheck Command Line Application
Structure Checker in MarvinSketch