public abstract class RetrieveCallback extends ProgressListener
DatabaseService search.
All interaction between retriever and caller during the retrieval operation
goes through this callback.ProgressListener.Wrapper| Modifier and Type | Field and Description |
|---|---|
static RetrieveCallback |
EMPTY |
| Modifier | Constructor and Description |
|---|---|
protected |
RetrieveCallback()
Default constructor.
|
protected |
RetrieveCallback(ProgressListener progressListener)
Creates a wrapper callback that delegates all non-overriden ProgressListener methods to an internal
ProgressListener.
|
protected |
RetrieveCallback(RetrieveCallback internalCallback)
Creates a wrapper callback that delegates all non-overriden methods to an internal
callback class.
|
| Modifier and Type | Method and Description |
|---|---|
protected abstract void |
_add(AnnotatedPluginDocument document,
Map<String,Object> searchResultProperties)
Report back one retrieved document.
|
protected abstract void |
_add(PluginDocument document,
Map<String,Object> searchResultProperties)
Report back one retrieved document.
|
protected boolean |
_isCanceled()
The default implementation always returns false.
|
protected void |
_setImage(Image image) |
protected void |
_setIndeterminateProgress() |
protected void |
_setMessage(String message) |
protected void |
_setProgress(double fractionCompleted) |
protected void |
_setStatus(String message,
long totalNumberOfDocuments,
boolean approximated,
long predictedTimeToRetrive,
long numberOfBytesDownloaded,
long totalNumberOfBytesToDownload) |
boolean |
acceptsChangesAfterRetrieveCompletes(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.
|
boolean |
add(AnnotatedPluginDocument document,
Map<String,Object> searchResultProperties)
A wrapper method that forwards its arguments to
_add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map)
only if this retrieval hasn't been canceled. |
boolean |
add(PluginDocument document,
Map<String,Object> searchResultProperties)
A wrapper method that forwards its arguments to
_add(com.biomatters.geneious.publicapi.documents.PluginDocument, java.util.Map)
only if this retrieval hasn't been canceled. |
void |
addFeedbackAction(String label,
SimpleListener listener) |
void |
addFeedbackAction(String label,
String description,
SimpleListener listener) |
void |
addSearchCancelledListener(SimpleListener cancelledListener)
Add a listener to be notified when a search on this database has been cancelled
|
boolean |
isCanceled()
Returns true if this retrieval has been canceled.
|
void |
issueWarning(String message,
String title)
Initiate a message to user from retriever.
|
protected void |
notifyListenersSearchCancelled()
Notifies all listeners registered via addSearchCancelledListener().
|
void |
remove(AnnotatedPluginDocument document)
Remove a document previously added using
add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument,java.util.Map). |
void |
removeFeedbackAction(String label) |
void |
removeSearchCancelledListener(SimpleListener cancelledListener)
Remove a listener to be notified when a search on this database has been cancelled
|
void |
setFinalStatus(String message,
boolean appendToDefaultStatus)
Sets a final status to be displayed to the user in the status bar when the search is finished.
|
void |
setFolderViewDocument(AnnotatedPluginDocument folderViewDocument)
Instead of calling
setPropertyFields(java.util.List, com.biomatters.geneious.publicapi.documents.DocumentField)
this method may be called to provide a document that may be used to provide a document style view on the entire
results of the search. |
void |
setPropertyFields(List<DocumentField> searchResultProperties,
DocumentField defaultSortingField)
Set query specific properties.
|
boolean |
setSearchResumptionIdentifier(String uniqueIdentifier)
Deprecated.
Geneious no longer supports resuming searches
|
boolean |
setStatus(String message,
long totalNumberOfDocuments,
boolean approximated,
long predictedTimeToRetrive,
long numberOfBytesDownloaded,
long totalNumberOfBytesToDownload)
Report download progress back to Geneious.
|
void |
setTitle(String title) |
createSplitProgress, createSplitProgress, forCancelable, getSplitProgress, setImage, setIndeterminateProgress, setMessage, setProgress, setProgress, setProgresspublic static final RetrieveCallback EMPTY
protected RetrieveCallback(RetrieveCallback internalCallback)
internalCallback - the internal callback class to delegate methods to.protected RetrieveCallback(ProgressListener progressListener)
progressListener - the internal ProgressListener to delegate methods to.protected RetrieveCallback()
public final boolean add(PluginDocument document, Map<String,Object> searchResultProperties)
_add(com.biomatters.geneious.publicapi.documents.PluginDocument, java.util.Map)
only if this retrieval hasn't been canceled.document - retrieved document; must not be nullsearchResultProperties - may be null (null will be translated to Collections.emptyMap() before calling
_add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map).canceled.protected abstract void _add(PluginDocument document, Map<String,Object> searchResultProperties)
document - retrieved document; must not be nullsearchResultProperties - 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.public final boolean add(AnnotatedPluginDocument document, Map<String,Object> searchResultProperties)
_add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map)
only if this retrieval hasn't been canceled.document - retrieved annotated document; must not be nullsearchResultProperties - may be null (null will be translated to Collections.emptyMap() before calling
_add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map).canceled.protected abstract void _add(AnnotatedPluginDocument document, Map<String,Object> searchResultProperties)
add(com.biomatters.geneious.publicapi.documents.PluginDocument, java.util.Map) instead.
If the database wishes to a change document after it has been returned, it should call AnnotatedPluginDocument.documentChanged(org.jdom.Element).
If a callback is interested in changes made to a document after it has been returned by the database, it should call AnnotatedPluginDocument.addWeakReferenceDocumentListener(com.biomatters.geneious.publicapi.documents.DocumentListener).document - the plugin document to addsearchResultProperties - 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.public void setPropertyFields(List<DocumentField> searchResultProperties, DocumentField defaultSortingField)
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.public void setFolderViewDocument(AnnotatedPluginDocument folderViewDocument)
setPropertyFields(java.util.List, com.biomatters.geneious.publicapi.documents.DocumentField)
this method may be called to provide a document that may be used to provide a document style view on the entire
results of the search. For example a query centric view of some blast results.
In the case of a batch sequence search (DatabaseService.batchSequenceSearch(java.util.List, String, com.biomatters.geneious.publicapi.plugin.Options, RetrieveCallback)
the name of the folderViewDocument will be used to name the folder for each batch of results.folderViewDocument - a folderViewDocument which must not contain any documents. If the
callback is interested in using this document, it is responsible for adding later documents supplied
to add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, java.util.Map)
to the provider's FolderView. Note that the caller of this method should not further
refer to folderViewDocument after calling this method as the callback may instead choose to
create a copy of this document and add the results to the copy instead. (for example if this document
is added directly to a WritableDatabaseService@Deprecated public boolean setSearchResumptionIdentifier(String uniqueIdentifier)
public final boolean setStatus(String message, long totalNumberOfDocuments, boolean approximated, long predictedTimeToRetrive, long numberOfBytesDownloaded, long totalNumberOfBytesToDownload)
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.message - user message to displaytotalNumberOfDocuments - total number of documents to be retrieved in this session.approximated - true if total number is not known yet and may increase in future callspredictedTimeToRetrive - 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)canceled.protected void _setStatus(String message, long totalNumberOfDocuments, boolean approximated, long predictedTimeToRetrive, long numberOfBytesDownloaded, long totalNumberOfBytesToDownload)
public void issueWarning(String message, String title)
message - explains the reasons.title - of message dialog.public void setFinalStatus(String message, boolean appendToDefaultStatus)
message - a message to be displayed to the user in the status barappendToDefaultStatus - if this is true, then the new message is appended to the default message.
otherwise, the new message replaces the default message.public void addSearchCancelledListener(SimpleListener cancelledListener)
cancelledListener - a SimpleListenerpublic void removeSearchCancelledListener(SimpleListener cancelledListener)
cancelledListener - a SimpleListenerprotected final void notifyListenersSearchCancelled()
public void remove(AnnotatedPluginDocument document)
add(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument,java.util.Map).
This allows a DatabaseService to notify the view of the documents that
the underlying database has removed one of the documents previously
reported to be in the database.
An implementation may only called this method if
acceptsChangesAfterRetrieveCompletes(org.virion.jam.util.SimpleListener)
returned true.
If the database wishes to a change document after it has been returned, it should call
AnnotatedPluginDocument.documentChanged(org.jdom.Element).
If a callback is interested in changes made to a document after it has been returned by the database, it should call
AnnotatedPluginDocument.addWeakReferenceDocumentListener(com.biomatters.geneious.publicapi.documents.DocumentListener).document - the document to be removedpublic boolean acceptsChangesAfterRetrieveCompletes(SimpleListener noLongerWantsChangesListener)
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.
If you are overriding this class, the default implementation does nothing and returns false.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.protected void _setProgress(double fractionCompleted)
_setProgress in class ProgressListenerprotected void _setIndeterminateProgress()
_setIndeterminateProgress in class ProgressListenerprotected void _setMessage(String message)
_setMessage in class ProgressListenerpublic final boolean isCanceled()
isCanceled in interface CancelableisCanceled in class ProgressListenerprotected boolean _isCanceled()
protected void _setImage(Image image)
_setImage in class ProgressListenerpublic void addFeedbackAction(String label, SimpleListener listener)
addFeedbackAction in class ProgressListenerpublic void addFeedbackAction(String label, String description, SimpleListener listener)
addFeedbackAction in class ProgressListenerpublic void removeFeedbackAction(String label)
removeFeedbackAction in class ProgressListenerpublic void setTitle(String title)
setTitle in class ProgressListener