Package chemaxon.jchem.db

Class JChemSearch

  • All Implemented Interfaces:
    TableTypeConstants, chemaxon.license.Licensable, SearchConstants
    @PublicAPI
public class JChemSearch
extends ErrorHandler
implements SearchConstants, TableTypeConstants, chemaxon.license.Licensable
    JavaBean for structure searching in structure tables of relational databases. For more information, see the corresponding section of the user's guide.

    Example for using the class: 

     searcher = new JChemSearch();
 searcher.setQueryStructure("c1cnccc1Cl");
 searcher.setConnectionHandler(conHandler);
 searcher.setStructureTable("cduser.structures");
 
 searchOptions = new JChemSearchOptions(JChemSearch.SIMILARITY);
 searchOptions.setDissimilarityThreshold(0.8F);
 searchOptions.setMaxResultCount(100);
 searcher.setSearchOptions(searchOptions);
 
 searcher.setRunMode(JChemSearch.RUN_MODE_SYNCH_COMPLETE);
 searcher.run();

    • Field Detail

      • NO_RESULT_TABLE

        public static final int NO_RESULT_TABLE
        Constant for the generation of result tables. Meaning: Don't store the results in a table. (Value=0)
        See Also:
        Constant Field Values

      • CREATE_OR_REPLACE_RESULT_TABLE

        public static final int CREATE_OR_REPLACE_RESULT_TABLE
        Constant for the generation of result tables. Meaning: Create a result table. If a table with same name exists, replace it with the new one. (Value=2)
        See Also:
        Constant Field Values

      • APPEND_TO_RESULT_TABLE

        public static final int APPEND_TO_RESULT_TABLE
        Constant for the generation of result tables. Meaning: Append to an existing result table. Create a new one if it doesn't exist (Value=3)
        See Also:
        Constant Field Values

      • NO_ORDERING

        public static final int NO_ORDERING
        Constant for ordering the result. Meaning: Don't order the result (Value=0)
        See Also:
        Constant Field Values

      • ORDERING_BY_ID

        public static final int ORDERING_BY_ID
        Constant for ordering the result. Meaning: Order the result according to the cd_id values (Value=1)
        See Also:
        Constant Field Values

      • ORDERING_BY_ID_OR_SIMILARITY

        public static final int ORDERING_BY_ID_OR_SIMILARITY
        Constant for ordering the result. Meaning: Order the result according to the calculated dissimilarity in the case of dissimilarity searching, use the cd_id values otherwise (Value=2)
        See Also:
        Constant Field Values

      • ORDERING_BY_FILTER_ID_LIST

        public static final int ORDERING_BY_FILTER_ID_LIST
        Constant for ordering the result. Meaning: Order the result according to the filterIDList
        See Also:
        Constant Field Values

      • searchOptions

        protected final JChemSearchOptions searchOptions
        Object to store all search parameters. This is used during the search and stores the settings of the previous search.

    • Constructor Detail

      • JChemSearch

        public JChemSearch()
        Creates new JChemSearch class

      • JChemSearch

        public JChemSearch​(String indexedTable,
                   String indexedColumn)
        For internal use only.
        Parameters:
        indexedTable - the name of the table
        indexedColumn - the name of the column

      • JChemSearch

        public JChemSearch​(chemaxon.jchem.db.distributed.DistributedNodes distributedNodes,
                   String indexedTable,
                   String indexedColumn)
        For internal use only.
        Parameters:
        distributedNodes - the distributed nodes
        indexedTable - the name of the table
        indexedColumn - the name of the column

      • JChemSearch

        public JChemSearch​(chemaxon.jchem.db.distributed.DistributedNodes distributedNodes)
        Creates a new JChemSearch class for distributed search. For internal use only.
        Parameters:
        distributedNodes - the distributed nodes

    • Method Detail

      • checkException

        public void checkException()
                    throws Exception
        Description copied from class: ErrorHandler
        Throws the exception stored in the object. Needed because Tomcat errorpages don't handle errors of type Throwable that are not inheritors of Exception.
        Overrides:
        checkException in class ErrorHandler
        Throws:
        Exception - the exception stored, boxed as Exception

      • getConnectionHandler

        public ConnectionHandler getConnectionHandler()
        Getter for property connectionHandler.
        Returns:
        Value of property connectionHandler.

      • setConnectionHandler

        public void setConnectionHandler​(ConnectionHandler connectionHandler)
        Sets the database connection.
        Parameters:
        connectionHandler - a ConnectionHandler object containing a live connection to the database

      • getConnection

        public Connection getConnection()
        Getter for property connection.
        Returns:
        Value of property connection.

      • getCacheError

        public String getCacheError()
        For checking for cache errors. Should be called after the search is finished.
        Returns:
        the error text, or null in case of normal execution.
        Since:
        JChem 3.0

      • getQueryStructure

        public String getQueryStructure()
        Getter for property queryStructure.
        Returns:
        Value of property queryStructure.

      • setQueryStructure

        public void setQueryStructure​(String queryStructure)
        Setter for property queryStructure. The query structure may be in MDL Molfile, Smiles or other format recognized by JChem. If the specified value is null or empty string, then it is interpreted as an empty query structure. (For more information, see the user's guide.)

        NOTE for Daylight formats: If search type is SearchConstants.DUPLICATE, SearchConstants.SUPERSTRUCTURE or SearchConstants.SIMILARITY, treats SMILES/SMARTS input strings as SMILES, otherwise as SMARTS.

        Parameters:
        queryStructure - New value of property queryStructure.

      • setQueryStructure

        public void setQueryStructure​(Molecule queryMol)
        Sets the query structure. If the specified value is null, then it is interpreted as an empty query structure. (For more information, see the user's guide.)
        Parameters:
        queryMol - the query structure.

      • setQueryFingerprint

        public void setQueryFingerprint​(int[] queryFp)
        Currently internal use only.
        Parameters:
        queryFp - the query fingerprint.

      • getStructureTable

        public String getStructureTable()
        Getter for property structureTable.
        Returns:
        Value of property structureTable.

      • setStructureTable

        public void setStructureTable​(String structureTable)
        Setter for property structureTable. It specifies the name of the table to be searched for structures containing the query.
        Parameters:
        structureTable - New value of property structureTable.

      • setFilterIDList

        public void setFilterIDList​(int[] ids)
        Specifies a list of cd_id values that are allowed to be included in the result set. Useful for narrowing the result set of the search (e.g., based on the {#getResults() results} of a previous search).

        If the given array is empty, no hits will be returned. Resetting the list is possible by calling the method with null parameter.

        Parameters:
        ids - the cd_id values in an array
        Since:
        JChem 3.1

      • setFilterIDNotList

        public void setFilterIDNotList​(int[] ids)
        Specifies a list of cd_id values that should not be included in the result set.
        Parameters:
        ids - the cd_id values in an array
        Since:
        JChem 3.1.2

      • isInfoToStdError

        public boolean isInfoToStdError()
        Getter for property infoToStdError.
        Returns:
        Value of property infoToStdError.

      • setInfoToStdError

        public void setInfoToStdError​(boolean infoToStdError)
        Setter for property infoToStdError. If set to true, information useful for testing will be written in the servlet server's error log file. (Default: false)
        Parameters:
        infoToStdError - New value of property infoToStdError.

      • getRunMode

        public int getRunMode()
        Retruns the current run mode.
        Returns:
        the current run mode.
        Since:
        JChem 5.0
        See Also:
        setRunMode(int)

      • setSearchOptions

        public void setSearchOptions​(JChemSearchOptions options)
        Sets search parameters.
        Parameters:
        options - search options. Will be copied, modification of the original object does not affect future searches unless this method is called again. The timeout limit of the new options will be applied to further searches.
        Since:
        JChem 5.0
        See Also:
        getSearchOptions()

      • getSearchOptions

        public JChemSearchOptions 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 (e.g timeout limit) will change directly the behaviour of this Search object.
        Returns:
        the current serarch options.
        Since:
        JChem 5.0
        See Also:
        setSearchOptions(JChemSearchOptions)

      • getOrder

        public int getOrder()
        Getter for property order.
        Returns:
        Value of property order.

      • setResultTable

        public void setResultTable​(String resultTable)
        Setter for property resultTable. Sets the result table that will contain the cd_id of hits. In the case of searching similar structures, the similarity value is also stored in column similarity.
        Parameters:
        resultTable - New value of property resultTable.
        See Also:
        setResultTableMode, getResult

      • getResultTableMode

        public int getResultTableMode()
        Getter for property resultTableMode.
        Returns:
        Value of property resultTableMode.

      • setResultTableMode

        public void setResultTableMode​(int resultTableMode)
        Setter for property resultTableMode. It instructs the searcher about the way of handling the result table. Modes: (Default: NO_RESULT_TABLE)
        Parameters:
        resultTableMode - New value of property resultTableMode.
        See Also:
        setResultTable

      • getResultTable

        public String getResultTable()
        Getter for property resultTable.
        Returns:
        Value of property resultTable.

      • setNumberOfProcessingThreads

        public void setNumberOfProcessingThreads​(int threads)
        Sets the number of processing threads.
        Parameters:
        threads - the number of threads.
        If set to 0, the number of threads will be equal to the number of logical processors available for the Java Vitual Machine (default).
        NOTE: Under Java Runtime Environment 1.3.1 or older the number of processors cannot be determined. In this case the default number of threads is 16.
        Since:
        JChem 3.0

      • getNumberOfProcessingThreads

        public int getNumberOfProcessingThreads()
        Gets the number of processing threads.
        Returns:
        number of threads executed the database search.

      • setThreadPriority

        public void setThreadPriority​(int priority)
        Sets the priority of the processing threads. Only effective, if setRunMode(int) is set to either RUN_MODE_ASYNCH_COMPLETE or RUN_MODE_ASYNCH_PROGRESSIVE .
        Parameters:
        priority - the priority ranging 1 (Thread.MIN_PRIORITY) to 10 (Thread.MAX_PRIORITY).
        The default and recommended setting is 1 ( Thread.MIN_PRIORITY).
        NOTE: if all other threads are not constantly calculating, a low priority setting will not slow down the search process, and it will help user interfaces to be responsive.
        Since:
        JChem 3.0

      • getResult

        public int getResult​(int index)
        Indexed getter for property results. Returns a cd_id value of the found compound specified by index. If result table is generated, getResult throws NullPointerException.
        Parameters:
        index - Index of the property.
        Returns:
        Value of the property at index.
        See Also:
        setResultTable

      • getResultContext

        public chemaxon.jchem.db.SearchCoreReturnedValue getResultContext()
        For internal use only.
        Returns:
        the result

      • getResults

        public int[] getResults()
        Returns an int array containing the cd_id values of found compounds. If a result table is generated in the database, it returns null.
        Returns:
        an array of cd_ids

      • getExtraInformation

        public List<byte[]> getExtraInformation()
        For internal use only.
        Returns:
        extrainformation for all results

      • cleanResults

        public void cleanResults()
        Cleans stored search results. Can be called to save memory while keeping the JChemSearch object. since JChem 3.0

      • getDissimilarity

        public float getDissimilarity​(int index)
        Indexed getter for property dissimilarity. Returns the calculated dissimilarity value of the found compound specified by index and the query structure. If searching has not been finished yet or if a result table is generated, getDissimilarity throws NullPointerException.
        Parameters:
        index - Index of the property.
        Returns:
        Value of the property at index.
        See Also:
        setResultTable

      • getDissimilarity

        public float[] getDissimilarity()
        Getter for dissimilarity results. Returns the calculated dissimilarity values calculated for the last query strucutre. If searching has not been finished yet or if a result table is generated, getDissimilarity throws NullPointerException.
        Returns:
        the dissimilarity results.
        See Also:
        setResultTable

      • getProgressMessage

        public String getProgressMessage()
        Getter for property progressMessage. It returns a message that shows the state of the search. It can be used for showing the progress of the search.
        Returns:
        Value of property progressMessage.

      • isMaxResultCountReached

        public boolean isMaxResultCountReached()
        Getter for property maxResultCountReached. It returns true if the search was stopped because the number of hits had reached the maximum value, false otherwise.
        Returns:
        Value of property maxResultCountReached.

      • isMaxTimeReached

        public boolean isMaxTimeReached()
        Getter for property maxTimeReached. It returns true if the search stopped because the time that passed since the start of the searched had reached the maximum value, false otherwise.
        Returns:
        Value of property maxTimeReached.

      • getResultCount

        public int getResultCount()
        Getter for property resultCount. It returns the number of hits found by the search.
        Returns:
        Value of property resultCount.

      • isRunning

        public boolean isRunning()
        Getter for property running.
        Returns:
        Value of property running.

      • setRunning

        public void setRunning​(boolean run)
                throws SQLException,
                       IOException,
                       DatabaseSearchException
        Setter for property running. If it is set to true and the search has not been started yet, then searching is unleashed. If it is set to false and a search is running, the the process will be stopped. (Default: false)
        Parameters:
        run - New value of property run.
        Throws:
        IOException - if an io error is encountered
        DatabaseSearchException - if a search error occurs
        SQLException - if an sql exception is encountered

      • getNextHit

        public int getNextHit()
               throws InterruptedException
        Used with run mode = RUN_MODE_ASYNCH_PROGRESSIVE.
        Returns the next available hit. Waits until at least one is available or throws NoSuchElementException, there are no more hits to return.
        Returns:
        the next available hit. Waits until at least one is available or throws NoSuchElementException, there are no more hits to return.
        Throws:
        InterruptedException - if the calling thread was interrupted while waiting for the next available hit.
        Since:
        JChem 5.0

      • getAvailableNewHits

        public int[] getAvailableNewHits​(int minimumHitSize)
                          throws InterruptedException,
                                 DatabaseSearchException
        Used with run mode = RUN_MODE_ASYNCH_PROGRESSIVE.
        Returns all new hits available at the time of return, but at least minimumHitSize new hits.
        Parameters:
        minimumHitSize - the minimum number of hits to return, which will be waited if not yet available.
        Returns:
        all new hits available at the time of return, but at least minimumHitSize new hits.
        Throws:
        InterruptedException - if the calling thread was interrupted while waiting.
        DatabaseSearchException - if there was an error during searching.
        Since:
        JChem 5.0

      • getScreenedCount

        public int getScreenedCount()
        Gets the number of total screened structures.
        Returns:
        the number of total screened structures, or -1 if the screened count was not calculated
        Since:
        JChem 5.6

      • getScreenedCountUnique

        public int getScreenedCountUnique()
        Gets the number of unique screened structures.
        Returns:
        the number of unique screened structures, or -1 if the screened count was not calculated
        Since:
        JChem 5.6

      • getScreenedCountTotal

        public int getScreenedCountTotal()
        Gets the number of total screened structures.
        Returns:
        the number of total screened structures, or -1 if the screened count was not calculated
        Since:
        JChem 5.6

      • getScreenedResults

        public int[] getScreenedResults()
        Gets the screened unique structures' ids.
        Returns:
        the screened structures' ids
        Since:
        JChem 5.6

      • getScreeningTime

        public long getScreeningTime()
        Gets the screening time.
        Returns:
        the screening time in milliseconds

      • getFirstHitTime

        public long getFirstHitTime()
        Gets the first hit's retrieving time (measured from start of screening).
        Returns:
        the retrieving time of first hit in milliseconds

      • getSearchTime

        public long getSearchTime()
        Gets the total search time.
        Returns:
        the search time in milliseconds (includes screening time) If the returned value is -1 then the search time is invalid (e.g search hasn't finished yet).

      • isTargetMarkush

        public boolean isTargetMarkush()
        Gets whether target structure table is a Markush table
        Returns:
        true if target table is a Markush table, false if not

      • getEnumerationCount

        public int getEnumerationCount()
        Gets the number of enumerates used while screening the database
        Returns:
        the number of enumerates for the query

      • isLicensed

        public boolean isLicensed()
        Specified by:
        isLicensed in interface chemaxon.license.Licensable

      • setLicenseEnvironment

        public void setLicenseEnvironment​(String env)
        Specified by:
        setLicenseEnvironment in interface chemaxon.license.Licensable

      • setProgressMessage

        public void setProgressMessage​(String message)

      • getCacheLoadTime

        public long getCacheLoadTime()
                      throws IllegalStateException
        Gets the time spent with cache loading for the target structure table. Returns
        Returns:
        duration for the last successful cache loading in milliseconds
        Throws:
        IllegalStateException - if no cache is loaded yet

      • getCacheSizeEstimate

        public double getCacheSizeEstimate()
                            throws IllegalStateException
        Returns an estimate of the cache size for the target structure table.
        Returns:
        estimated size of the cache for the target structure table in MBs
        Throws:
        IllegalStateException - if no cache is loaded yet

      • getCacheSize

        public double getCacheSize()
                    throws IllegalStateException
        Returns the size of the cache for the target structure table.

        Warning: the calculation performed by this function may be slow and may consume a large amount of memory. Consider to use getCacheSizeEstimate() to obtain an estimation of the cache size much faster.

        Returns:
        the size of the cache for the target structure table in MBs
        Throws:
        IllegalStateException - if no cache is loaded yet

      • getHitsAsMolecules

        public Molecule[] getHitsAsMolecules​(int[] idList,
                                     HitColoringAndAlignmentOptions options,
                                     List<String> dataFieldNames,
                                     List<Object[]> dataFieldValues)
                              throws SQLException,
                                     IOException,
                                     SearchException,
                                     chemaxon.enumeration.supergraph.SupergraphException,
                                     DatabaseSearchException
        Returns hits ready for display. If hit alignment or coloring is needed, the graph search must be repeated for the selected structures to obtain the atom indexes of hits. (Storing this data would consume too much memory for large hit sets) If alignment mode has been set to rotate, and query has 0 dimension, it will be cleaned in 2d. If alignment mode has been set to partial clean, this option will be changed to rotate in this case.
        Parameters:
        idList - the cd_id list of hits to be retrieved.
        options - the options for coloring and alignment. If null the structures will be displayed in their original form.
        dataFieldNames - fields of the jchem table that should be fetched together with the structure or null.
        dataFieldValues - an empty List required or it can be null. The fetched values will be stored in this object as Object[] elements.
        Returns:
        the hits as Molecules, colored and aligned if needed. If coloring is specified in case of SearchConstants.SUPERSTRUCTURE search mode, always the query structure is returned, the target subgraph is colored. If there is no hit for a target then the appropriate element of the result array is null.
        Throws:
        SQLException - if the fetched row is deleted
        IOException - if an io error is encountered
        SearchException - Search failure during getting colored atoms
        chemaxon.enumeration.supergraph.SupergraphException - Search failure during getting colored atoms
        DatabaseSearchException - Search failure during getting colored atoms
        Since:
        JChem 5.0

      • getHitsAsHitDisplayTool

        public HitDisplayTool getHitsAsHitDisplayTool​(int[] idList,
                                              HitColoringAndAlignmentOptions options,
                                              List<String> dataFieldNames,
                                              List<Object[]> dataFieldValues,
                                              List<? super Molecule> molecules,
                                              List<byte[]> sources)
                                       throws SQLException,
                                              IOException,
                                              SearchException,
                                              chemaxon.enumeration.supergraph.SupergraphException,
                                              DatabaseSearchException
        Gets a HitDisplayTool object from which the results can be retrieved. Parameters are similar to getHitsAsMolecules(int[], HitColoringAndAlignmentOptions, List, List) Additional parameters: molecules, sources Example usage: 
         List<Molecule> molecules = new ArrayList<Molecule>();
 List<byte[]> sources = new ArrayList<byte[]>();
 HitDisplayTool colorUtil = getHitsAsHitDisplayTool(idList, options,
         dataFieldNames, dataFieldValues, molecules, sources);
 for (int x = 0, n = molecules.size(); x < n; x++) {
     if (molecules.get(x) == null) { // not found
         continue;
     }
     colorUtil.setMoleculeMarkushSourceTarget(molecules.get(x), sources.get(x));
     // fetch the hits using colorUtil.getNextHit() or colorUtil.getHits(int)
     // ...
 }
        Parameters:
        idList - the cd_id list of hits to be retrieved.
        options - the options for coloring and alignment. If null the structures will be displayed in their original form.
        dataFieldNames - fields of the jchem table that should be fetched together with the structure or null.
        dataFieldValues - an empty List required or it can be null. The fetched values will be stored in this object as Object[] elements.
        molecules - An empty list that will contain the molecules to be set on the hitdisplaytool object. For not found IDs (e.g. deleted) null is set.
        sources - An empty list that will contain the byte array sources to be set on the hitdisplaytool object.
        Returns:
        the hitDisplayTool object
        Throws:
        SQLException - if an sql error encountered
        IOException - if an io exception is encountered
        SearchException - if there was an error during searching.
        chemaxon.enumeration.supergraph.SupergraphException - if there was an error during searching.
        DatabaseSearchException - if there was an error during searching.
        Since:
        version 5.4

      • setTargetCollection

        @Beta
public void setTargetCollection​(chemaxon.jchem.base.storage.search.CurrentTargetCollection targetCollection)
        For internal use only.
        Parameters:
        targetCollection - the targetcollection to use