com.biomatters.geneious.publicapi.databaseservice

Class DatabaseService

java.lang.Object

com.biomatters.geneious.publicapi.plugin.GeneiousService

com.biomatters.geneious.publicapi.databaseservice.DatabaseService

Direct Known Subclasses:

PartiallyWritableDatabaseService, WritableDatabaseService

public abstract class DatabaseService
extends GeneiousService

A Geneious service providing documents in response to a search query. For example the NCBI or Local Documents services in Geneious.

The simplest way to use an instance of an existing service is to call retrieve(String). For example

    DatabaseService service = (DatabaseService)PluginUtilities.getGeneiousService("NCBI_nucleotide_gbc");
    List<AnnotatedPluginDocument> documents = service.retrieve("AF093856");
    for (AnnotatedPluginDocument document : documents) {
        if (DocumentType.isSequence(document)) {
            SequenceDocument sequence = (SequenceDocument) document.getDocument();
            System.out.println("name="+sequence.getName()+" sequence="+sequence.getSequenceString());
        }
    }

 

The simplest way to implement a service is to implement retrieve(Query, RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[]) and inside the implementation call RetrieveCallback.add(com.biomatters.geneious.publicapi.documents.PluginDocument, java.util.Map) For example:

    public void retrieve(Query query, RetrieveCallback callback, URN[] urnsToNotRetrieve) throws DatabaseServiceException {
        callback.add(new DefaultNucleotideSequence("name","GATTACA"),null);
    }
 

For more detailed examples of implementing a DatabaseService, refer to GeneiousService or to ExampleGeneiousService in the API examples folder.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DatabaseService.SequenceSearchQueryType The type of query for a sequence search

Nested classes/interfaces inherited from class com.biomatters.geneious.publicapi.plugin.GeneiousService

GeneiousService.ServiceStatus

Constructor Summary

Constructors

Constructor and Description
DatabaseService()

Method Summary

Methods

Modifier and Type	Method and Description
void	addDatabaseServiceListener(DatabaseServiceListener listener) DatabaseServiceListener has several methods for the database service to notify the program of changes.
void	addWeakDatabaseServiceListener(DatabaseServiceListener listener) Like addWeakDatabaseServiceListener(DatabaseServiceListener) but adds a weakly referenced listener instead.
void	batchSequenceSearch(List<AnnotatedPluginDocument> querySequences, String program, Options options, RetrieveCallback callback) If this is a Sequence Database (ie.
protected List<DatabaseServiceListener>	getDatabaseServiceListeners() The default implementations of addDatabaseServiceListener(DatabaseServiceListener) and removeDatabaseServiceListener(DatabaseServiceListener) store the listeners in a list that is available for subclasses using this method.
DocumentSelectionSignature[]	getDocumentTypesForSequenceSearch(DatabaseService.SequenceSearchQueryType queryType, String program, Options searchOptions, boolean summaryDocumentTypes) Return DocumentSelectionSignatures describing all possible types of documents that can be returned from a sequence search on this service.
ExtendedSearchOption[]	getExtendedSearchOptions(boolean isAdvancedSearch) Provide a list of extended options to be displayed the in the search panel.
abstract QueryField[]	getSearchFields() Gives the set of fields that can be used for searching this repository/database.
Options	getSequenceSearchOptions(String program) Optionally override to provide options which will be displayed at the bottom of the options in the Sequence Search interface when this database is selected and the given program is selected.
Map<String,String>	getSequenceSearchPrograms(DatabaseService.SequenceSearchQueryType queryType) This method can be optionally overridden if this database provides sequence similarity searching and should be available through the Sequence Search interface in Geneious.
boolean	isBrowsable() A Database Service is browsable if its documents are viewed when it is selected in the service tree.
int	locateSummaryDocument(AnnotatedPluginDocument actualDocument, AnnotatedPluginDocument[] summaryDocuments) Locate summary document of fully downloaded documents.
void	removeDatabaseServiceListener(DatabaseServiceListener listener) Remove a listener which was added using addDatabaseServiceListener(DatabaseServiceListener) or addWeakDatabaseServiceListener(DatabaseServiceListener) .
void	resumeSearch(String uniqueIdentifier, RetrieveCallback callback) Deprecated. Geneious no longer supports resuming searches
void	retrieve(AnnotatedPluginDocument[] summaryDocuments, RetrieveCallback callback, URN[] urnsToNotRetrieve) Retrieves full documents corresponding to the given summary documents from the database.
List<AnnotatedPluginDocument>	retrieve(List<AnnotatedPluginDocument> summaryDocuments, ProgressListener progressListener) Convenience method to be used instead of the standard retrieve method to avoid dealing with a callback method when downloading full documents given summary documents.
List<AnnotatedPluginDocument>	retrieve(Query query, ProgressListener progressListener) Convenience method to be used instead of the standard retrieve(Query, RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[]) method to avoid dealing with a callback method.
abstract void	retrieve(Query query, RetrieveCallback callback, URN[] urnsToNotRetrieve) Get documents by searching a database.
List<AnnotatedPluginDocument>	retrieve(String searchText) Convenience method to be used instead of the standard retrieve method when doing a standard textbased search and ignoring failure (by returning an empty list) and ignoring search properties (such as e-values).
void	retrieve(URN[] urnsToRetrieve, RetrieveCallback callback) Retrieve documents with the specified URNs.
void	sequenceSearch(AnnotatedPluginDocument querySequence, String program, Options options, RetrieveCallback callback) If this is a Sequence Database (ie.

Methods inherited from class com.biomatters.geneious.publicapi.plugin.GeneiousService

_shutdown, addGeneiousServiceListener, addWeakGeneiousServiceListener, canShutdown, getActionsAlwaysEnabled, getActionsEnabledWhenServiceSelected, getChildServices, getDescription, getFullPath, getGeneiousServiceListener, getHelp, getIcons, getName, getParentService, getPreferences, getServiceTreeLabel, getStatus, getUniqueID, hasShutdownOrStartedShuttingDown, initialize, initializeService, isProOnly, removeGeneiousServiceListener, showInServiceTree, shutdown, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DatabaseService

public DatabaseService()

Method Detail

getSearchFields

public abstract QueryField[] getSearchFields()

Gives the set of fields that can be used for searching this repository/database.

The database must respond quickly from this method and must not wait on network IO. If it is unable to return a list of search fields quickly, it should return an empty list and fire DatabaseServiceListener.fieldsChanged() when the fields are available.

Returns:

an array of fields or null.

retrieve

public abstract void retrieve(Query query,
            RetrieveCallback callback,
            URN[] urnsToNotRetrieve)
                       throws DatabaseServiceException

Get documents by searching a database.

The database should not return from this function until it has called callback.addDocument() for all results. None of the arguments may be null, but it is not guaranteed that a NullPointerException will be thrown if a client violates this requirement.

Parameters:

query - the query specifying what we are searching this DatabaseService for; must not be null.

callback - The RetrieveCallback to which to report search results (documents and progress reports); must not be null.

urnsToNotRetrieve - a set of document URN's to ignore. retrievers can save bandwidth/disk access by not downloading documents with the same URN. Must not be null. Most implementations can ignore this method.

Throws:

DatabaseServiceException - if retrieval fails for any reason. May also throw this if the callback requests the retrieve to be cancelled.

NullPointerException - A subclass may, but isn't obliged to, throw a NullPointerException if any of the arguments (query, callback or urnsToNotRetrieve) is null. A client shouldn't pass in null for either of this value, but a client should also not depend for its correctness on a NullPointerException to be thrown.

retrieve

public void retrieve(AnnotatedPluginDocument[] summaryDocuments,
            RetrieveCallback callback,
            URN[] urnsToNotRetrieve)
              throws DatabaseServiceException

Retrieves full documents corresponding to the given summary documents from the database.

If this DatabaseService returns SummaryDocuments then this method must be implemented to allow the full documents to be downloaded.

Parameters:

summaryDocuments - A list of summary documents.

callback - Full documents should be passed on to this callback's add method as they are being retrieved from the database. It is an error to call any methods on the callback after retrieve() has returned, or after callback.setFinalStatus() has been called.

urnsToNotRetrieve - a set of document URN's to ignore. Documents matching one of these URNs must not be passed to the callback, and to save bandwidth, the DatabaseService should not download them from the database.

Throws:

DatabaseServiceException - if retrieval fails for any reason. May also throw this if the callback requests the retrieve to be cancelled.

locateSummaryDocument

public int locateSummaryDocument(AnnotatedPluginDocument actualDocument,
                        AnnotatedPluginDocument[] summaryDocuments)

Locate summary document of fully downloaded documents.

If this DatabaseService returns SummaryDocuments then this method must be implemented.

Locate the summary document whose download resulted in this actual document. This is so the SummaryDocument can be removed from the document table once the full document has been downloaded and placed there.

Parameters:

actualDocument - document downloaded for that summary

summaryDocuments - list of all summary documents

Returns:

Index of the summary document inside summaryDocuments from which actualDocument was generated. Return -1 if not found.

addDatabaseServiceListener

public void addDatabaseServiceListener(DatabaseServiceListener listener)

DatabaseServiceListener has several methods for the database service to notify the program of changes. Store a list of listeners added through this method and call the required functions as necessary on all of the listeners.

This method can be ignored if none of the listener methods are required.

. The default implementation stores the listeners in a list that can be accessed by subclasses using getDatabaseServiceListeners().

Parameters:

listener - the DatabaseServiceListener

addWeakDatabaseServiceListener

public void addWeakDatabaseServiceListener(DatabaseServiceListener listener)

Like addWeakDatabaseServiceListener(DatabaseServiceListener) but adds a weakly referenced listener instead.

Parameters:

listener - the DatabaseServiceListener

Since:

API 4.600 (Geneious 6.0.0)

removeDatabaseServiceListener

public void removeDatabaseServiceListener(DatabaseServiceListener listener)

Remove a listener which was added using addDatabaseServiceListener(DatabaseServiceListener) or addWeakDatabaseServiceListener(DatabaseServiceListener)

. The default implementation removes the listeners from a list that can be accessed by subclasses using getDatabaseServiceListeners().

Parameters:

listener - the DatabaseServiceListener

getDatabaseServiceListeners

protected List<DatabaseServiceListener> getDatabaseServiceListeners()

The default implementations of addDatabaseServiceListener(DatabaseServiceListener) and removeDatabaseServiceListener(DatabaseServiceListener) store the listeners in a list that is available for subclasses using this method.

Returns:

a list of DatabaseServiceListeners.

isBrowsable

public boolean isBrowsable()

A Database Service is browsable if its documents are viewed when it is selected in the service tree. Otherwise documents are available only via an explicit search.

Returns:

true if this DatabaseService is browsable

getExtendedSearchOptions

public ExtendedSearchOption[] getExtendedSearchOptions(boolean isAdvancedSearch)

Provide a list of extended options to be displayed the in the search panel.

Parameters:

isAdvancedSearch - specifies if the options returned are going be attached to the advanced or basic search panel. This method will be called twice with true and false. Disregard this if the extended options are to be on both basic and advanced.

Returns:

array of options or empty array if none. Cannot be null.

retrieve

public void retrieve(URN[] urnsToRetrieve,
            RetrieveCallback callback)
              throws DatabaseServiceException

Retrieve documents with the specified URNs. A DatabaseService only needs to implement this function if it generates AnnotatedPluginDocuments that reference other documents. Geneious will then use this function to obtain those referenced documents.

Parameters:

urnsToRetrieve - URNs which must be the URNS of documents referenced by a previous document returned from this DatabaseService

callback - Used to notify when a document has been retrieved.

Throws:

DatabaseServiceException - if retrieval fails for any reason. May also throw this if the callback requests the retrieve to be cancelled.

sequenceSearch

public void sequenceSearch(AnnotatedPluginDocument querySequence,
                  String program,
                  Options options,
                  RetrieveCallback callback)
                    throws DatabaseServiceException

If this is a Sequence Database (ie. getSequenceSearchPrograms(com.biomatters.geneious.publicapi.databaseservice.DatabaseService.SequenceSearchQueryType) returns a non-empty list) then this method must be overridden because it will be called when the user initiates a sequence search. If this is not a sequence database then it is not necessary to override this method.

When returning results from a search, the database service must quickly (i.e. without waiting on network I/O) either call RetrieveCallback.setPropertyFields(java.util.List, com.biomatters.geneious.publicapi.documents.DocumentField) or call RetrieveCallback.setFolderViewDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument)

Parameters:

querySequence - the query sequence, should be used as a referenced document in any results if possible.

program - the program selected by the user to use for the search (see getSequenceSearchPrograms(com.biomatters.geneious.publicapi.databaseservice.DatabaseService.SequenceSearchQueryType)

options - the options returned from getSequenceSearchOptions(String) after they have been displayed to the user.

callback - Used to notify when a document has been retrieved.

Throws:

DatabaseServiceException

batchSequenceSearch

public void batchSequenceSearch(List<AnnotatedPluginDocument> querySequences,
                       String program,
                       Options options,
                       RetrieveCallback callback)
                         throws DatabaseServiceException

If this is a Sequence Database (ie. getSequenceSearchPrograms(com.biomatters.geneious.publicapi.databaseservice.DatabaseService.SequenceSearchQueryType) returns a non-empty list) then this method may be overridden to allow efficient batch sequence searching.

When returning results from a search, each result set in the batch must be preceeded by a call to either RetrieveCallback.setFolderViewDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument) or RetrieveCallback.setPropertyFields(java.util.List, com.biomatters.geneious.publicapi.documents.DocumentField). If RetrieveCallback.setPropertyFields(java.util.List, com.biomatters.geneious.publicapi.documents.DocumentField) is being used then calls to setPropertyFields must be made in the same order as the query sequences because folder names are generated from the query sequences. If RetrieveCallback.setFolderViewDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument) is being used then the calls may be made in any order because the folder names will be the obtained by calling PluginDocument.getName(). There must be exactly querySequences.size() calls to one of these methods before this method returns (unless it is cancelled or an exception is throws).

The default implementation calls sequenceSearch(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument, String, com.biomatters.geneious.publicapi.plugin.Options, RetrieveCallback) for each query sequence.

Parameters:

querySequences - the query sequences, should be used as a referenced documents in any results if possible.

program - the program selected by the user to use for the search (see getSequenceSearchPrograms(com.biomatters.geneious.publicapi.databaseservice.DatabaseService.SequenceSearchQueryType)

options - the options returned from getSequenceSearchOptions(String) after they have been displayed to the user.

callback - Used to notify when a document has been retrieved.

Throws:

DatabaseServiceException

getSequenceSearchPrograms

public Map<String,String> getSequenceSearchPrograms(DatabaseService.SequenceSearchQueryType queryType)

This method can be optionally overridden if this database provides sequence similarity searching and should be available through the Sequence Search interface in Geneious.

Return a map of the programs supported by this database with the given query type where the key is a unique code used to identify the program and the value is a human readable name for the database.

eg. "blastn" -> "Nucleotide to nucleotide BLAST (blastn)"

If this returns and empty map then the database will not be available in the Sequence Search interface.

Parameters:

queryType - the DatabaseService.SequenceSearchQueryType of the query sequene.

Returns:

a map of the supported programs or an empty map if this doesn't support the query type. Must not be null.

getSequenceSearchOptions

public Options getSequenceSearchOptions(String program)

Optionally override to provide options which will be displayed at the bottom of the options in the Sequence Search interface when this database is selected and the given program is selected. Eg. a checkbox for "Include subfolders"

Important: if more than one database service in a plugin supports the given program then Geneious will share one instance of the options between the database services that support that program (so that any options that the user selects can be maintained across databases). This means the database services that support the same program should return the same type of options from this method for that program.

Basic options are dislayed just under the program combo in the initial dialog, advanced options are displayed in the More Options section.

Parameters:

program - the program selected by the user to use for the search (see getSequenceSearchPrograms(com.biomatters.geneious.publicapi.databaseservice.DatabaseService.SequenceSearchQueryType)

Returns:

options or null for none.

getDocumentTypesForSequenceSearch

public DocumentSelectionSignature[] getDocumentTypesForSequenceSearch(DatabaseService.SequenceSearchQueryType queryType,
                                                             String program,
                                                             Options searchOptions,
                                                             boolean summaryDocumentTypes)

Return DocumentSelectionSignatures describing all possible types of documents that can be returned from a sequence search on this service. If summaryDocumentTypes is false then this must be the classes of the full documents after the user downloads any summary documents. If it is true then only the classes of summary documents (if any) should be returned. If the search only returns full documents then this method should return an empty selection signature if summaryDocumentTypes is true.

Sequence searchable services should override this. Default implementation returns a signature matching any type of document if summaryDocumentTypes is false or an empty selection signature if it is true.

Parameters:

queryType - the DatabaseService.SequenceSearchQueryType of the query sequene.

program - the program selected by the user to use for the search (see getSequenceSearchPrograms(com.biomatters.geneious.publicapi.databaseservice.DatabaseService.SequenceSearchQueryType)

searchOptions - the options returned from getSequenceSearchOptions(String) after they have been displayed to the user.

summaryDocumentTypes - If false then return the classes of the full documents after the user downloads any summary documents. If true then return the classes of summary documents (if any).

Returns:

DocumentSelectionSignatures describing all types of documents that can be returned from a sequence search on this service.

resumeSearch

@Deprecated
public void resumeSearch(String uniqueIdentifier,
                           RetrieveCallback callback)
                  throws DatabaseServiceException

Deprecated. Geneious no longer supports resuming searches

Throws:

DatabaseServiceException

retrieve

public final List<AnnotatedPluginDocument> retrieve(String searchText)

Convenience method to be used instead of the standard retrieve method when doing a standard textbased search and ignoring failure (by returning an empty list) and ignoring search properties (such as e-values).

Parameters:

searchText - the text to search for.

Returns:

unmodifiable list of matching documents

retrieve

public final List<AnnotatedPluginDocument> retrieve(Query query,
                                     ProgressListener progressListener)
                                             throws DatabaseServiceException

Convenience method to be used instead of the standard retrieve(Query, RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[]) method to avoid dealing with a callback method. This means that search properties (such as e-values) are discarded.

Parameters:

query - the query to search for

progressListener - to notify about progress and to handle cancelling.

Returns:

unmodifiable list of matching documents

Throws:

DatabaseServiceException - if anything goes wrong or the retrieval is canceled

retrieve

public final List<AnnotatedPluginDocument> retrieve(List<AnnotatedPluginDocument> summaryDocuments,
                                     ProgressListener progressListener)
                                             throws DatabaseServiceException

Convenience method to be used instead of the standard retrieve method to avoid dealing with a callback method when downloading full documents given summary documents.

This method is only applicable for databases that return summary documents.

For example, when dealing with the NCBI blast database that returns summary documents, you might do this:

     DatabaseService blastService = (DatabaseService) PluginUtilities.getGeneiousService("NCBI_blastn");

     Map<String, Object> blastOptions = new HashMap<String, Object>();
     blastOptions.put("blastDatabase", "nr"); // The database to blast
     blastOptions.put("EXPECT", 0.01); // Maximum e-value to match
     blastOptions.put("maxHits", 10); // Maximum number of hits returned

     String queryString = "ATGGCATATCCCATACAACTAGGATT";
     Query query = Query.Factory.createExtendedQuery(queryString, blastOptions);

     List<AnnotatedPluginDocument> summaryDocuments = blastService.retrieve(query, ProgressListener.EMPTY);
     List<AnnotatedPluginDocument> fullDocuments = blastService.retrieve(summaryDocuments, ProgressListener.EMPTY);
 

Note: To print a list of blast options available use this:

     for (ExtendedSearchOption option : blastService.getExtendedSearchOptions(true)) {
        System.out.println(option);
     }
 

Parameters:

summaryDocuments - a list of summary documents returned from a previous retrieve(Query, RetrieveCallback, com.biomatters.geneious.publicapi.documents.URN[]) call.

progressListener - to notify about progress and to handle cancelling.

Returns:

a list full documents of the same length and in the same order as the summary documents.

Throws:

DatabaseServiceException - if any of the full documents can not be retrieved.