001    /*
002     * Copyright (c) 1998-2014 ChemAxon Ltd. All Rights Reserved.
003     *
004     * This software is the confidential and proprietary information of
005     * ChemAxon. You shall not disclose such Confidential Information
006     * and shall use it only in accordance with the terms of the agreements
007     * you entered into with ChemAxon.
008     *
009     */
010    package com.chemaxon.overlap;
011    
012    import com.chemaxon.calculations.common.SubProgressObserver;
013    import com.chemaxon.descriptors.common.Descriptor;
014    import com.google.common.collect.ImmutableList;
015    import com.google.common.util.concurrent.MoreExecutors;
016    import java.util.concurrent.ExecutorService;
017    
018    /**
019     * Query interface for the similarity subsystem.
020     *
021     * <p>Note that this interface is not used currently.</p> 
022     *
023     * <p>A general contract of {@link com.chemaxon.descriptors} API regarding comparison is that only those descriptors can
024     * be compared which are generated using the same {@link com.chemaxon.descriptors.common.DescriptorGenerator} instance.
025     * This contract applies to queries executed.</p>
026     *
027     * @param <D>   Underlying descriptor type
028     *
029     * TODO: implement blocking multithreaded entry point - add ExecutorService?
030     * TODO: dissimilarity histogram query
031     *
032     * @author Gabor Imre
033     */
034    public interface Similarity<D extends Descriptor> {
035    
036        /**
037         * Look up the most similar node.
038         *
039         * @param query     Query descriptor
040         * @param po        Observer to track progress
041         * @return          The most similar node. If multiple nodes share the best dissimilarity, one of them is choosen
042         *                  arbitrarily.
043         */
044        SimilarityResultNode findMostSimilar(D query, SubProgressObserver po);
045    
046        /**
047         * Look up the most similar nodes.
048         *
049         * @param query     Query descriptor
050         * @param po        Observer to track progress
051         * @param maxCount  Max return count. If the underlying similarity space contains fewer structures then all of them
052         *                  will be returned.
053         * @return          List of most similar nodes, in increasing similarity order.
054         */
055        ImmutableList<SimilarityResultNode> findMostSimilars(D query, SubProgressObserver po, int maxCount);
056    
057        /**
058         * Look up the most similar node.
059         *
060         * @param query     Query descriptor
061         * @param po        Observer to track progress
062         * @param executors Executors to use for executing the search. When {@link MoreExecutors#sameThreadExecutor()} is
063         *                  passed then the method will block until the final result is found.
064         * @return          Wrapper for the most similar node. If multiple nodes share the best dissimilarity, one of them
065         *                  is choosen arbitrarily.
066         */
067        AsyncResult<SimilarityResultNode> findMostSimilar(D query, SubProgressObserver po, ExecutorService executors);
068    
069        /**
070         * Look up the most similar nodes.
071         *
072         * @param query     Query descriptor
073         * @param po        Observer to track progress.
074         * @param maxCount  Max return count. If the underlying similarity space contains fewer structures then all of them
075         *                  will be returned.
076         * @param executors Executors to use for executing the search. When {@link MoreExecutors#sameThreadExecutor()} is
077         *                  passed then the method will block until the final result is found.
078         * @return          Wrapper for List of most similar nodes, in increasing similarity order.
079         *
080         */
081        AsyncResult<ImmutableList<SimilarityResultNode>> findMostSimilars(
082                D query, SubProgressObserver po, int maxCount, ExecutorService executors);
083    }