Introduction to Structure Checker API

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 an 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 wants to extend the list of 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 designates that this checker is not part of the ChemAxon built-in checker list and thus the runner framework will know that this checker's result had to be handled separately; 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 with the same error type as one of the built-in checkers, but in this case there can be ambiguous issues with the running framework and unexpected errors could happen. So in this case the proper work of the checker system cannot 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 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. Read more about checker and fixer customization, available from version 6.1.x.

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

A new attribute option has been added to the command line interface in version 5.9:

  • 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<StructureCheckerResult> results = runner.checkAndWait();
for (StructureChecekrResult result : results) {
List<StructureFixer> 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<StructureCheckerResult> results = runner.checkAndWait();
for (StructureCheckerResult result : results) {
runner.fix(result);
}

Customization and localiziation of checker or fixer descriptions

From Structure Checker version 6.1, the checkers and fixers of ChemAxon's Structure Checker can be personalized according to individual requirements, for example, they can be renamed, have special description texts, or distinctive warning messages. You can even simply rephrase or translate the standard checker or fixer messages into different languages. Learn more.

Tutorial

This documentation also provides a tutorial which contains three different class implementation. "DuplicateAtomMapChecker.java" shows how to create a new StructureChecker implementation. "DuplicateAtomMapCheckerEditor.java" presents an editor, which supports the checker configuration from GUI. "RemapReactionFixer.java" describes how easy to connect existing Structure Checker fixers to custom checker implementation. "ExternalRemoveAtomMapFixer.java" introduces how to develop a new fixer for your 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. Download custom.zip which contains the example.