Package com.biomatters.geneious.publicapi.databaseservice

Class RetrieveCallback

  • All Implemented Interfaces:
    jebl.util.Cancelable
    Direct Known Subclasses:
    CompositeRetrieveCallback
    public abstract class RetrieveCallback
extends jebl.util.ProgressListener
    A callback that asynchronously reports back the documents resulting from a DatabaseService search. All interaction between retriever and caller during the retrieval operation goes through this callback.

    • Constructor Detail

      • RetrieveCallback

        protected RetrieveCallback​(RetrieveCallback internalCallback)
        Creates a wrapper callback that delegates all non-overriden methods to an internal callback class.
        Parameters:
        internalCallback - the internal callback class to delegate methods to.

      • RetrieveCallback

        protected RetrieveCallback​(jebl.util.ProgressListener progressListener)
        Creates a wrapper callback that delegates all non-overriden ProgressListener methods to an internal ProgressListener.
        Parameters:
        progressListener - the internal ProgressListener to delegate methods to.

      • RetrieveCallback

        protected RetrieveCallback()
        Default constructor.

    • Method Detail

      • _add

        protected abstract void _add​(PluginDocument document,
                             java.util.Map<java.lang.String,​java.lang.Object> searchResultProperties)
        Report back one retrieved document.
        Parameters:
        document - retrieved document; must not be null
        searchResultProperties - properties associated with this document for this particular search. Must not be null, but may be empty if no properties are relevant. This is used in situations such as blast where the evalue returned is not actually a property of the document, but is associated with the document for this given search only. The properties must be valid fields and values returned by setPropertyFields(java.util.List<com.biomatters.geneious.publicapi.documents.DocumentField>, com.biomatters.geneious.publicapi.documents.DocumentField).

        Geneious code can "pause" the operation by delaying the return from add.

      • setPropertyFields

        public void setPropertyFields​(java.util.List<DocumentField> searchResultProperties,
                              DocumentField defaultSortingField)
        Set query specific properties.
        Parameters:
        searchResultProperties - a list of additional fields associated with each document in the search results. This may not be null, but may be an empty list. This is used in situations such as blast where the e-value returned is not actually a property of the document, but is associated with the document for a given search only. The property values will be specified in the searchResultProperties parameter in add() or add()
        defaultSortingField - Every time this database service is searched the results will immediately be sorted on this field.

        Geneious will automatically make this column the leftmost column, and sort on this column as soon as the user initiates a new search.

        Useful for situations such as blast where you wanted to sort based on the e-value returned. Also consider making the DocumentField a temporary document field, which can be specified in DocumentField.create.

      • setSearchResumptionIdentifier

        @Deprecated
public boolean setSearchResumptionIdentifier​(java.lang.String uniqueIdentifier)
        Deprecated.
        Geneious no longer supports resuming searches
        /**

      • setStatus

        public final boolean setStatus​(java.lang.String message,
                               long totalNumberOfDocuments,
                               boolean approximated,
                               long predictedTimeToRetrive,
                               long numberOfBytesDownloaded,
                               long totalNumberOfBytesToDownload)
        Report download progress back to Geneious. There two ways to report progress, one of which is this method, the other of which is the ProgressListener that this class extends using ProgressListener.setMessage(String) and ProgressListener.setProgress(double). It is recommended that new implementations use the ProgressListener methods and may optionally use this method as well.
        Parameters:
        message - user message to display
        totalNumberOfDocuments - total number of documents to be retrieved in this session.
        approximated - true if total number is not known yet and may increase in future calls
        predictedTimeToRetrive - time to end of download. -1 for unknown. There is no need to predict based on actual retrieval performance, since geneious will do that automatically when passed -1.
        numberOfBytesDownloaded - total number of bytes downloaded so far (for all documents).
        totalNumberOfBytesToDownload - total number of bytes still to be downloaded (if not known, return -1)
        Returns:
        true if this retrieval has been canceled.

      • _setStatus

        protected void _setStatus​(java.lang.String message,
                          long totalNumberOfDocuments,
                          boolean approximated,
                          long predictedTimeToRetrive,
                          long numberOfBytesDownloaded,
                          long totalNumberOfBytesToDownload)

      • issueWarning

        public void issueWarning​(java.lang.String message,
                         java.lang.String title)
        Initiate a message to user from retriever.
        Parameters:
        message - explains the reasons.
        title - of message dialog.

      • setFinalStatus

        public void setFinalStatus​(java.lang.String message,
                           boolean appendToDefaultStatus)
        Sets a final status to be displayed to the user in the status bar when the search is finished. If this function is not called, then a default message is generated.
        Parameters:
        message - a message to be displayed to the user in the status bar
        appendToDefaultStatus - if this is true, then the new message is appended to the default message. otherwise, the new message replaces the default message.

      • addSearchCancelledListener

        public void addSearchCancelledListener​(org.virion.jam.util.SimpleListener cancelledListener)
        Add a listener to be notified when a search on this database has been cancelled
        Parameters:
        cancelledListener - a SimpleListener

      • removeSearchCancelledListener

        public void removeSearchCancelledListener​(org.virion.jam.util.SimpleListener cancelledListener)
        Remove a listener to be notified when a search on this database has been cancelled
        Parameters:
        cancelledListener - a SimpleListener

      • notifyListenersSearchCancelled

        protected final void notifyListenersSearchCancelled()
        Notifies all listeners registered via addSearchCancelledListener(). Descendant classes can invoke this method when they realise that the search is cancelled. Alternatively, descendant classes can override addSearchCancelledListener and removeSearchCancelledListener to provide their own listener handling, but this is discouraged.

      • acceptsChangesAfterRetrieveCompletes

        public boolean acceptsChangesAfterRetrieveCompletes​(org.virion.jam.util.SimpleListener noLongerWantsChangesListener)
        If a database service wishes to make changes to the result of a retrieve after the retrieve method has returned then it should call this method first.

        If this method returns true then the database service may hold a reference to the callback and make changes after returning from retrieve (by calling add for example). If false is returned then the database service must not make any changes after returning from retrieve.

        The database service should pass in a listener that will be notified if the callback will no longer accept changes. When this happens, the database service should discard the reference to the callback and make no more changes.

        An example situation where this is used as for the Local DatabaseService which wants to display any newly added documents to the browse results and hide deleted and moved documents.

        A typical DatabaseService implementation may call this method in a manner such as this after calling the callback method on all existing results but before returning from the retrieve method: 

        
    SimpleListener noLongerWantsChangesListener = new SimpleListener() {
        public void objectChanged() {
            callback = null; // The callback is no longer interested in changes, so discard our reference to it.
        }
    };
    if (!callback.acceptsChangesAfterRetrieveCompletes(noLongerWantsChangesListener)) {
        callback = null; // The callback does not want changes that occur later, so we can discard our reference to it now.
    }
        And at any time later when a document is added or removed from the database, if callback!= null, it may call the appropriate callback method. This callback may be made from any thread, and potentially multiple threads may make callbacks simultaneously. It is up to the callback to ensure it is thread safe.

        If you are overriding this class, the default implementation does nothing and returns false.

        Parameters:
        noLongerWantsChangesListener - a listener to be notified when this RetrieveCallbacks is no longer interested in changes that may occur in future. When this listener is invoked, the retrieve implementation should discard all references to this RetrieveCallback so that it may be garbage collected.
        Returns:
        true if this RetrieveCallback wants to be notified about changes that may occur in future.

      • _setProgress

        protected void _setProgress​(double fractionCompleted)
        Specified by:
        _setProgress in class jebl.util.ProgressListener

      • _setIndeterminateProgress

        protected void _setIndeterminateProgress()
        Specified by:
        _setIndeterminateProgress in class jebl.util.ProgressListener

      • _setMessage

        protected void _setMessage​(java.lang.String message)
        Specified by:
        _setMessage in class jebl.util.ProgressListener

      • isCanceled

        public final boolean isCanceled()
        Returns true if this retrieval has been canceled.
        Specified by:
        isCanceled in interface jebl.util.Cancelable
        Specified by:
        isCanceled in class jebl.util.ProgressListener
        Returns:
        true if this retrieval has been canceled.

      • _isCanceled

        protected boolean _isCanceled()
        The default implementation always returns false. Subclasses can override this method to implement a RetrieveCallback that can be canceled although it doesn't wrap another RetrieveCallback
        Returns:
        true if this retrieval has been canceled.

      • _setImage

        protected void _setImage​(java.awt.Image image)
        Overrides:
        _setImage in class jebl.util.ProgressListener

      • addFeedbackAction

        public void addFeedbackAction​(java.lang.String label,
                              org.virion.jam.util.SimpleListener listener)
        Overrides:
        addFeedbackAction in class jebl.util.ProgressListener

      • addFeedbackAction

        public void addFeedbackAction​(java.lang.String label,
                              java.lang.String description,
                              org.virion.jam.util.SimpleListener listener)
        Overrides:
        addFeedbackAction in class jebl.util.ProgressListener

      • removeFeedbackAction

        public void removeFeedbackAction​(java.lang.String label)
        Overrides:
        removeFeedbackAction in class jebl.util.ProgressListener

      • setTitle

        public void setTitle​(java.lang.String title)
        Overrides:
        setTitle in class jebl.util.ProgressListener

      • getResultsDescription

        protected java.lang.String getResultsDescription()
        Only core Geneious should implement and call this method. Returns a description of what this search is for (e.g. "contents of folder 'sample documents'" or "primer search cache") for displaying to the user if there is insufficient free memory to continue. Additionally, if this returns a non-null value the the free memory threshold under which the search is automatically cancelled is lower.
        Returns:
        a description of the results or null for a generic description
        Since:
        API 4.900 (Geneious 9.0.0)