chemaxon.naming

Interface NameConverter

@PublicAPI
public interface NameConverter

The interface of a converter from names to structures.

Author:

Daniel Bonniot

Method Summary

Modifier and Type	Method and Description
default Molecule	convert(java.lang.String name) Deprecated. This method is deprecated, because implementations of this interface are potentially used in multi-threaded environments, so they should not store a call-site-dependent state. The method is no longer called by the Name to Structure algorithm, convert(String, boolean) is used instead. The default implementation of this method throws UnsupportedOperationException to enable users to remove the implementing methods before this method is removed.
default Molecule	convert(java.lang.String name, boolean prefixMode) Convert a name into the corresponding structure.
default boolean	isPrefixModeSupported() Returns true if prefix mode is supported.
default boolean	setPrefixMode(boolean prefixMode) Deprecated. This method is deprecated, because implementations of this interface are potentially used in multi-threaded environments, so they should not store a call-site-dependent state. The method is no longer called by the Name to Structure algorithm, isPrefixModeSupported() and convert(String, boolean) is used instead. The default implementation of this method throws UnsupportedOperationException to enable users to remove the implementing methods before this method is removed.

Method Detail

convert

@Deprecated
 @SubjectToRemoval(date=JAN_01_2022)
default Molecule convert(java.lang.String name)
                                                                   throws NameFormatException

Deprecated. This method is deprecated, because implementations of this interface are potentially used in multi-threaded environments, so they should not store a call-site-dependent state. The method is no longer called by the Name to Structure algorithm, convert(String, boolean) is used instead. The default implementation of this method throws UnsupportedOperationException to enable users to remove the implementing methods before this method is removed.

Throws:

NameFormatException

setPrefixMode

@Deprecated
 @SubjectToRemoval(date=JAN_01_2022)
default boolean setPrefixMode(boolean prefixMode)

Deprecated. This method is deprecated, because implementations of this interface are potentially used in multi-threaded environments, so they should not store a call-site-dependent state. The method is no longer called by the Name to Structure algorithm, isPrefixModeSupported() and convert(String, boolean) is used instead. The default implementation of this method throws UnsupportedOperationException to enable users to remove the implementing methods before this method is removed.

convert

default Molecule convert(java.lang.String name,
                         boolean prefixMode)
                  throws NameFormatException

Convert a name into the corresponding structure.

The failure to convert the name can be indicated either by returning null, or by throwing a NameFormatException.

When a converter fails by returning null or throwing NameFormatException, converters of lower priority will be called with the same name. To prevent that and guarantee that the name is not converted at all, a converter should throw NameFormatException.FilteredCase.

This method should always be implemented. The default implementation calls convert(String) for backward-compatibility, but this method will become abstract when the other version is removed.

Parameters:

name - the chemical name to be converted

prefixMode - true if prefix mode should be used. If isPrefixModeSupported() returns false, this parameter is guaranteed to be false and can be safely ignored.

Returns:

the Molecule object corresponding to the name, or null if the name is not recognized.

Throws:

NameFormatException - when the name does not correspond to a structure

NameFormatException.FilteredCase - when the name does not correspond to a structure, and not other converter should be tried on this name.

NamePrefixException - when the name does not correspond to a structure, but is a possible prefix of a valid name.

isPrefixModeSupported

default boolean isPrefixModeSupported()

Returns true if prefix mode is supported.

The prefix mode is an optimization, only used when extracting structures from text documents. It is irrelevant when converting a single name to a structure.

When converting a document, it is not directly possible to know where name start and end. For instance, suppose that a converter knows the structure for "Prussian Blue" by looking it up in a database. Given the sentence "The Prussian Blue chemical was used to color textiles in blue", the word "Prussian" alone would be passed to the converter. In prefix mode, the converter should throw a NamePrefixException, indicating that it knows a name starting with this prefix.

The prefix mode is an optional optimization. If a converter does not support it, it can return false to this call. In this case, the system will always try to call again after concatenating several words (up to a limit or a detected end of sentence). This ensures that names containing spaces will be recognized, at the cost of more conversion attempts.

The default implementation of this method returns true. If a converter only accepts names without whitespace characters, then it is always safe to return true. Otherwise, you should implement prefix mode support or override this method to return false.

Returns:

true if prefix mode is supported, false otherwise.