Search (Marvin API documentation (c) 1998-2020 ChemAxon Ltd.)

java.lang.Object
- chemaxon.sss.search.Search

All Implemented Interfaces:

SearchConstants, StereoConstants
```
@PublicAPI
public abstract class Search
extends java.lang.Object
implements StereoConstants, SearchConstants
```
Abstract base class of all structural search classes.

Author:

JChem Base team, Szilard Dorant, Szabolcs Csepregi, Robert Wagner, Tamas Csizmazia, Nore Mate

Field Summary

Fields
Modifier and Type	Field and Description
`protected static java.util.logging.Level`	`MRV_OUTPUT_LEVEL` MRV format of the query and target is logged at this level.
`protected java.util.Map<java.lang.Integer,java.lang.Integer>`	`preMatchMap` Map for storing pre-match data.
`protected MolSearchOptions`	`searchOptions` Object to store all search parameters.

Fields inherited from interface chemaxon.struc.StereoConstants
ANTI, ATOMSTEREO_EITHER, ATOMSTEREO_MASK, ATOMSTEREO_NONE, ATOMSTEREO_SPECIFIC, CHIRALITY_M, CHIRALITY_MASK, CHIRALITY_P, CHIRALITY_r, CHIRALITY_R, CHIRALITY_s, CHIRALITY_S, CHIRALITYSUPPORT_ALL, CHIRALITYSUPPORT_ALL_POSSIBLE, CHIRALITYSUPPORT_NONE, CHIRALITYSUPPORT_SELECTED, CIS, CIS_TRANS, CTUMASK, CTUNKNOWN, CTUNSPEC, DBS_ALL, DBS_MARKED, DBS_NONE, ENDO, EXO, PARITY_ALLENE, PARITY_EITHER, PARITY_EVEN, PARITY_MASK, PARITY_NONE, PARITY_ODD, PARITY_TETRAHEDRAL, PARITY_UNSPEC, STGRP_ABS, STGRP_AND, STGRP_NONE, STGRP_OR, SYN, TRANS

Fields inherited from interface chemaxon.sss.SearchConstants
ABS_STEREO_ALWAYS_ON, ABS_STEREO_CHIRAL_FLAG, ABS_STEREO_TABLE_OPTION, ATTACHED_DATA_MATCH_EXACT, ATTACHED_DATA_MATCH_GENERAL, ATTACHED_DATA_MATCH_IGNORE, ATTACHMENT_ATOM, ATTACHMENT_LABEL, ATTACHMENT_MAP, ATTACHMENT_NONE, ATTACHMENT_POINT, ATTACHMENT_RLABEL, CHARGE_MATCHING_DEFAULT, CHARGE_MATCHING_EXACT, CHARGE_MATCHING_IGNORE, DEFAULT_DISSIMILARITY_THRESHOLD, DEFAULT_SEARCHTYPE, DISSIMILARITY_PROPERTY_NAME, DUPLICATE, FULL, FULL_FRAGMENT, HCOUNT_MATCHING_AUTO, HCOUNT_MATCHING_EQUAL, HCOUNT_MATCHING_GREATER_OR_EQUAL, HIT_EXCLUDEDQ, HIT_LP, HIT_MULTICENTER, HIT_NON_R, HIT_ORDERING_NONE, HIT_ORDERING_UNDEF_R_MATCHING_GROUP_FIRST, HIT_R, HIT_R_EMPTY_MATCH, HIT_UNMAPABLE, IMPLICIT_H_MATCHING_DEFAULT, IMPLICIT_H_MATCHING_DISABLED, IMPLICIT_H_MATCHING_ENABLED, IMPLICIT_H_MATCHING_IGNORE, ISOTOPE_MATCHING_DEFAULT, ISOTOPE_MATCHING_EXACT, ISOTOPE_MATCHING_IGNORE, MARKUSH_HIT_INNER, MARKUSH_HIT_ORIGINAL, MATCH_COUNT_BETWEEN, MATCH_COUNT_RELATION, NO_ABAS, NO_SCREEN, POSITION_ON_0TH_HEAVY_ATOM, RADICAL_MATCHING_DEFAULT, RADICAL_MATCHING_EXACT, RADICAL_MATCHING_IGNORE, SEARCH_MODE_NAMES, SEARCH_TYPE_NAMES, SIMILARITY, STEREO_DIASTEREOMER, STEREO_ENANTIOMER, STEREO_EXACT, STEREO_IGNORE, STEREO_MODEL_COMPREHENSIVE, STEREO_MODEL_DEFAULT, STEREO_MODEL_GLOBAL, STEREO_MODEL_LOCAL, STEREO_SPECIFIC, SUBSTRUCTURE, SUPERSTRUCTURE, TAUTOMER_SEARCH_DEFAULT, TAUTOMER_SEARCH_OFF, TAUTOMER_SEARCH_ON, TAUTOMER_SEARCH_ON_IGNORE_TAUTOMERSTEREO, UNDEF_R_MATCHING_ALL, UNDEF_R_MATCHING_GROUP, UNDEF_R_MATCHING_GROUP_H, UNDEF_R_MATCHING_GROUP_H_EMPTY, UNDEF_R_MATCHING_UNDEF_R, VAGUE_BOND_DEFAULT, VAGUE_BOND_LEVEL_HALF, VAGUE_BOND_LEVEL1, VAGUE_BOND_LEVEL2, VAGUE_BOND_LEVEL3, VAGUE_BOND_LEVEL4, VAGUE_BOND_OFF

Constructor Summary

Constructors
Constructor and Description

Search()

Constructors
Constructor and Description
`Search()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addMatch(int[] queryAtoms, int[] targetAtoms, int length)` Specifies extra prerequisites of the structure search that queryAtoms[0] must match to targetAtoms[0] only AND queryAtoms[1] must match to targetAtoms[1], etc.
`void`	`clearMatch()` Clears the extra prerequisites of the structure search specified using addMatch calls.
`int[][]`	`findAll()` Looks for all matching patterns in the molecule.
`int[][][]`	`findAllGroups()` Returns the group hits corresponding to all hits.
`protected SearchHit[]`	`findAllHits()` Looks for all matching patterns in the molecule.
`int[]`	`findFirst()` Looks for the first matching pattern in the target molecule.
`int[][]`	`findFirstGroup()` Returns the group hit corresponding to the first hit.
`protected abstract SearchHit`	`findFirstHit()` Looks for the first matching pattern in the target molecule.
`int[]`	`findNext()` Looks for the next matching pattern in the target molecule.
`int[][]`	`findNextGroup()` Returns the group hit corresponding to the next hit.
`protected abstract SearchHit`	`findNextHit()` Searches for the next hit.
`int`	`getMatchCount()` The number of times the query molecule appears in the target molecule.
`abstract Molecule`	`getQuery()` Retrieves the query structure.
`protected static java.lang.String`	`getQueryAsString(Molecule qToPrint)` For internal purposes only.
`protected Molecule`	`getQueryToPrint()` For internal purposes only.
`MolSearchOptions`	`getSearchOptions()` Returns the `SearchOptions` object associated with this Search object.
`abstract Molecule`	`getTarget()` Retrieves the target molecule.
`protected static java.lang.String`	`getTargetAsString(Molecule tToPrint)` For internal purposes only.
`protected Molecule`	`getTargetToPrint()` For internal purposes only.
`boolean`	`isMatchCountBetween(int hitLimitLow, boolean isLowerLimitIncluded, int hitLimitHigh, boolean isHigherLimitIncluded)` Decides questions like "does the query match the target between 2 and 5 times (inclusively)" Makes this efficiently, which means it only searches for the number of hits necessary to decide the question.
`boolean`	`isMatchCountInRelation(java.lang.String relation, int hitLimit)` Decides questions like "does the query match the target at least 3 times", "[] up to 5 times", "[] exactly once".
`static boolean`	`isMatchCountInRelation(java.lang.String relation, int hitLimit, int foundHits)`
`abstract boolean`	`isMatching()` Checks if the query structure matches the target structure with respect to the search options.
`boolean`	`isVerbose()` For debugging purposes only.
`abstract void`	`setQuery(Molecule mol)` Specifies the query structure to search for.
`abstract void`	`setQuery(Molecule mol, int[] exclude)` Specifies the query structure to search for.
`void`	`setSearchOptions(SearchOptions options)` Sets search options.
`abstract void`	`setTarget(Molecule mol)` Specifies the target molecule.
`abstract void`	`setTarget(Molecule mol, int[] exclude)` Specifies the target molecule with excluded atoms.
`void`	`setVerbose(boolean verbose)` For debugging purposes only.
`abstract void`	`stop()` Tries to stop the running search as fast as possible.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - searchOptions
```
protected final MolSearchOptions searchOptions
```
    Object to store all search parameters.
  - preMatchMap
```
protected java.util.Map<java.lang.Integer,java.lang.Integer> preMatchMap
```
    Map for storing pre-match data. Keys are query atom indexes, values are target atom indexes.
  - MRV_OUTPUT_LEVEL
```
protected static final java.util.logging.Level MRV_OUTPUT_LEVEL
```
    MRV format of the query and target is logged at this level.
- Constructor Detail
  - Search
```
public Search()
```
- Method Detail
  - setTarget
```
public abstract void setTarget(Molecule mol)
```
    Specifies the target molecule.
    Note: If the molecule is changed, it will need to be reset for the searcher.
    
    Parameters:
    
    mol - the possibly standardized target molecule. See note on aromatic bonds
  - setTarget
```
public abstract void setTarget(Molecule mol,
                               int[] exclude)
```
    Specifies the target molecule with excluded atoms. Excluded atoms are not used during the search procedure. Atoms connected to excluded ones keep their stereo features.
    Note: If the molecule is changed, it will need to be reset for the searcher.
    
    Parameters:
    
    mol - the standardized target molecule. See note on aromatic bonds
    
    exclude - index of target atoms to exclude from search
  - getTarget
```
public abstract Molecule getTarget()
```
    Retrieves the target molecule.
    
    Returns:
    
    the target molecule
  - setQuery
```
public abstract void setQuery(Molecule mol)
```
    Specifies the query structure to search for. Note: If the molecule is changed, it will need to be reset for the searcher.
    
    Parameters:
    
    mol - the standardized query structure. See note on aromatic bonds
  - setQuery
```
public abstract void setQuery(Molecule mol,
                              int[] exclude)
```
    Specifies the query structure to search for. Excluded atoms are not used during the search procedure. Atoms connected to excluded ones keep their stereo features. Note: If the molecule is changed, it will need to be reset for the searcher.
    
    Parameters:
    
    mol - the standardized query structure. See note on aromatic bonds
    
    exclude - index of atoms to exclude from search
  - getQuery
```
public abstract Molecule getQuery()
```
    Retrieves the query structure.
    
    Returns:
    
    the query structure
  - isMatching
```
public abstract boolean isMatching()
                            throws SearchException
```
    Checks if the query structure matches the target structure with respect to the search options.
    
    Returns:
    
    true if a match is found.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    findFirstHit(), findNextHit(), findAllHits(), getQuery()
  - findFirst
```
public final int[] findFirst()
                      throws SearchException
```
    Looks for the first matching pattern in the target molecule. If the search object was previously used, this method re-initializes the search process, and starts returning the hits from the beginning.
    
    Returns:
    
    an array containing the atom indexes of the target atoms that match the query atoms (in the order of the appropriate query atoms) or null if there are no hits. See SearchHit.getSingleHit() for the description of special atom indexes.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    findNext(), findAll(), findFirstHit(), findNextHit(), findAllHits(), isMatching(), getQuery()
  - findNext
```
public final int[] findNext()
                     throws SearchException
```
    Looks for the next matching pattern in the target molecule. If the search object was not used previously, it also initializes the search. (So findFirst() call is not necessary prior to a findNext() call.)
    
    Returns:
    
    an array containing the atom indexes of the target atoms that match the query atoms (in the order of the appropriate query atoms) or null if there are no more hits. See SearchHit.getSingleHit() for the description of special atom indexes.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    findFirst(), findAll(), findFirstHit(), findNextHit(), findAllHits(), isMatching(), getQuery()
  - findAll
```
public final int[][] findAll()
                      throws SearchException
```
    Looks for all matching patterns in the molecule.
    
    Returns:
    
    an array containing the matches as arrays or null if there are no hits. The match arrays contain the atom indexes of the target atoms that match the query atoms (in the order of the appropriate query atoms). See SearchHit.getSingleHit() for the description of special atom indexes.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    See Also:
    
    findFirst(), findNext(), findFirstHit(), findNextHit(), findAllHits(), isMatching()
  - findFirstGroup
```
public final int[][] findFirstGroup()
                             throws SearchException
```
    Returns the group hit corresponding to the first hit.
    See SearchHit.getGroupHit() for more information on group hits.
    
    Returns:
    
    the group hit corresponding to the first hit
    
    Throws:
    
    SearchException - when an error is encountered.
    
    Since:
    
    JChem 5.3
    
    See Also:
    
    findNextGroup(), findAllGroups(), findFirstHit(), findNextHit(), findAllHits(), isMatching(), getQuery(), findFirst(), findNext(), findAll()
  - findNextGroup
```
public final int[][] findNextGroup()
                            throws SearchException
```
    Returns the group hit corresponding to the next hit.
    See SearchHit.getGroupHit() for more information on group hits.
    
    Returns:
    
    the group hit corresponding to the next hit
    
    Throws:
    
    SearchException - when an error is encountered.
    
    Since:
    
    JChem 5.3
    
    See Also:
    
    findFirstGroup(), findAllGroups(), findFirstHit(), findNextHit(), findAllHits(), isMatching(), getQuery(), findFirst(), findNext(), findAll()
  - findAllGroups
```
public final int[][][] findAllGroups()
                              throws SearchException
```
    Returns the group hits corresponding to all hits.
    See SearchHit.getGroupHit() for more information on group hits.
    
    Returns:
    
    the group hits corresponding to all hits, each element of the array is a group hit glove array
    
    Throws:
    
    SearchException - when an error is encountered.
    
    Since:
    
    JChem 5.3
    
    See Also:
    
    findFirstGroup(), findNextGroup(), findFirstHit(), findNextHit(), findAllHits(), isMatching(), findFirst(), findNext(), findAll()
  - findFirstHit
```
protected abstract SearchHit findFirstHit()
                                   throws SearchException
```
    Looks for the first matching pattern in the target molecule. If the search object was previously used, this method re-initializes the search process, and starts returning the hits from the beginning.
    See SearchHit for more information.
    
    Returns:
    
    the search hit or null if there is not hit
    
    Throws:
    
    SearchException - when an error is encountered.
    
    Since:
    
    JChem 5.4
    
    See Also:
    
    findNextHit(), findAllHits(), isMatching(), getQuery(), findNext(), findAll(), findFirstGroup(), findNextGroup(), findAllGroups()
  - findNextHit
```
protected abstract SearchHit findNextHit()
                                  throws SearchException
```
    Searches for the next hit. If the search object was not used previously, it also initializes the search. (So findFirstHit() call is not necessary prior to a findNextHit() call.)
    See SearchHit for more information.
    
    Returns:
    
    the next search hit or null if there is no more hit
    
    Throws:
    
    SearchException - when an error is encountered.
    
    Since:
    
    JChem 5.4
    
    See Also:
    
    findFirstHit(), findAllHits(), isMatching(), getQuery(), findFirst(), findAll(), findFirstGroup(), findNextGroup(), findAllGroups()
  - findAllHits
```
protected SearchHit[] findAllHits()
                           throws SearchException
```
    Looks for all matching patterns in the molecule.
    See SearchHit for more information.
    
    Returns:
    
    the search hits or null if there are no hits.
    
    Throws:
    
    SearchException - when an error is encountered.
    
    Since:
    
    JChem 5.4
    
    See Also:
    
    findFirstHit(), findNextHit(), isMatching(), findFirst(), findNext(), findFirstGroup(), findNextGroup(), findAllGroups()
  - addMatch
```
public void addMatch(int[] queryAtoms,
                     int[] targetAtoms,
                     int length)
```
    Specifies extra prerequisites of the structure search that queryAtoms[0] must match to targetAtoms[0] only AND queryAtoms[1] must match to targetAtoms[1], etc. If this is impossible, the search methods will report no matching. The use of this method makes the search more effective than checking the hits afterwards.
    Several addMatch() calls represent conditions connected by boolean operator AND.
    The effect of all addMatch() calls can be canceled by clearMatch().
    
    Parameters:
    
    queryAtoms - the query atom indexes
    
    targetAtoms - the target atom indexes
    
    length - the length for which queryAtoms/targetAtoms should be interpreted.
    
    Since:
    
    JChem 2.2
  - clearMatch
```
public void clearMatch()
```
    Clears the extra prerequisites of the structure search specified using addMatch calls.
    
    Since:
    
    JChem 2.2
  - isMatchCountInRelation
```
public final boolean isMatchCountInRelation(java.lang.String relation,
                                            int hitLimit)
                                     throws SearchException
```
    Decides questions like "does the query match the target at least 3 times", "[] up to 5 times", "[] exactly once". Makes this efficiently, which means it only searches for the number of hits necessary to decide the question.
    Example:
    isMatchCountInRelation("<", 2) - true if the query can be found in the target less than two times.
    
    Parameters:
    
    relation - The relational operation of the question. This operation will be used to compare the number of hits to hitLimit. Available values:
    
    "=" - tests equality to hitLimit.
    "<" - returns true if the number of found hits is less than hitLimit.
    "<=" - less than or equality
    ">" - greater than
    ">=" - greater than or equality
    
    hitLimit - The limit for the number of hits.
    
    Returns:
    
    "actual number of hits (of query in target)" <relation> hitLimit
    
    Throws:
    
    SearchException - if encountered during the search.
    
    See Also:
    
    getMatchCount()
  - isMatchCountInRelation
```
@Beta
public static boolean isMatchCountInRelation(java.lang.String relation,
                                                   int hitLimit,
                                                   int foundHits)
                                            throws SearchException
```
    Throws:
    
    SearchException
  - isMatchCountBetween
```
public final boolean isMatchCountBetween(int hitLimitLow,
                                         boolean isLowerLimitIncluded,
                                         int hitLimitHigh,
                                         boolean isHigherLimitIncluded)
                                  throws SearchException
```
    Decides questions like "does the query match the target between 2 and 5 times (inclusively)" Makes this efficiently, which means it only searches for the number of hits necessary to decide the question.
    Example:
    isMatchCountBetween(2, true, 4, true) - true if the query can be found in the target exactly 2, 3 or 4 times.
    isMatchCountBetween(2, false, 4, false) - true if the query can be found in the target exactly 3 times.
    
    Parameters:
    
    hitLimitLow - The lower limit for the number of hits.
    
    isLowerLimitIncluded - If true, equality is allowed with hitLimitLow.
    
    hitLimitHigh - The upper limit for the number of hits. If you pass Integer.MAX_VALUE, it will be treated as infinity. (I.e. only the lower limit is applied.)
    
    isHigherLimitIncluded - If true, equality is allowed with hitLimitHigh.
    
    Returns:
    
    Whether the "actual number of hits (of query in target)" is between hitLimitLow and hitLimitHigh, inclusively.
    
    Throws:
    
    SearchException - if encountered during the search.
    
    See Also:
    
    getMatchCount()
  - getMatchCount
```
public final int getMatchCount()
                        throws SearchException
```
    The number of times the query molecule appears in the target molecule.
    If you would like to decide a simple relation regarding this number, you should consider method isMatchCountInRelation( String, int), because it is more efficient than this method.
    
    Returns:
    
    the above occurrence number.
    
    Throws:
    
    SearchException - If encountered during the search.
    
    See Also:
    
    isMatchCountInRelation(java.lang.String, int)
  - isVerbose
```
public boolean isVerbose()
```
    For debugging purposes only.
    
    Returns:
    
    true if verbose mode is on.
  - setVerbose
```
public void setVerbose(boolean verbose)
```
    For debugging purposes only.
    
    Parameters:
    
    verbose - enables or disables verbose mode.
  - stop
```
public abstract void stop()
```
    Tries to stop the running search as fast as possible. (E.g. used in another thread.)
    
    Since:
    
    JChem 3.0
  - getSearchOptions
```
public MolSearchOptions getSearchOptions()
```
    Returns the SearchOptions object associated with this Search object. The object returned is linked with this Search object, so modifications in the returned SearchOptions object will also change the behavior of this Search object!
    
    Returns:
    
    the current search settings as a SearchOptions object.
    
    Since:
    
    JChem 5.0
    
    See Also:
    
    setSearchOptions(SearchOptions)
  - setSearchOptions
```
public void setSearchOptions(SearchOptions options)
```
    Sets search options. This function makes a copy of the given search options object, thus modification of the original object does not affect future searches unless this method is called again.
    
    Parameters:
    
    options - search options. A copy of this object will be stored.
    
    Since:
    
    JChem 5.0
    
    See Also:
    
    getSearchOptions()
  - getQueryToPrint
```
protected Molecule getQueryToPrint()
```
    For internal purposes only.
    
    Returns:
    
    the query to be displayed for debug purposes only.
  - getTargetToPrint
```
protected Molecule getTargetToPrint()
```
    For internal purposes only.
    
    Returns:
    
    the target to be displayed for debug purposes only.
  - getTargetAsString
```
protected static java.lang.String getTargetAsString(Molecule tToPrint)
```
    For internal purposes only.
    
    Parameters:
    
    tToPrint - the molecule to be flattened to a string array
    
    Returns:
    
    the target to be displayed for debug purposes only.
  - getQueryAsString
```
protected static java.lang.String getQueryAsString(Molecule qToPrint)
```
    For internal purposes only.
    
    Parameters:
    
    qToPrint - the molecule to be flattened to a string array
    
    Returns:
    
    the query to be displayed for debug purposes only.

Class Search

Field Summary

Fields inherited from interface chemaxon.struc.StereoConstants

Fields inherited from interface chemaxon.sss.SearchConstants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

searchOptions

preMatchMap

MRV_OUTPUT_LEVEL

Constructor Detail

Search

Method Detail

setTarget

setTarget

getTarget

setQuery

setQuery

getQuery

isMatching

findFirst

findNext

findAll

findFirstGroup

findNextGroup

findAllGroups

findFirstHit

findNextHit

findAllHits

addMatch

clearMatch

isMatchCountInRelation

isMatchCountInRelation

isMatchCountBetween

getMatchCount

isVerbose

setVerbose

stop

getSearchOptions

setSearchOptions

getQueryToPrint

getTargetToPrint

getTargetAsString

getQueryAsString