Package com.biomatters.geneious.publicapi.databaseservice

Class 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.

    • Constructor Detail

      • DatabaseService

        public DatabaseService()

    • Method Detail

      • getSearchFields

        @MustReturnPromptly
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

        @MayReturnSlowly
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.
        java.lang.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

        @MayReturnSlowly
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

        @MustReturnPromptly
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

        @MustReturnPromptly
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

      • isBrowsable

        @MustReturnPromptly
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

        @MustReturnPromptly
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

        @MayReturnSlowly
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.

        If a document with any of these URNs is not in this database, this method should return without throwing an exception.

        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 due to a problem with connecting to the database. May also throw this if the callback requests the retrieve to be cancelled.

      • getSequenceSearchPrograms

        @MustReturnPromptly
public java.util.Map<java.lang.String,​java.lang.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

        @MustReturnPromptly
public Options getSequenceSearchOptions​(java.lang.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.

      • getOpenInWebUrlForDocuments

        @MustReturnPromptly
public java.lang.String getOpenInWebUrlForDocuments​(java.util.List<AnnotatedPluginDocument> documents)
        Returns a String which will be used by core Geneious to open the selected documents in a web browser. Return null to indicate that the selected documents cannot be opened in a web browser, or that the database service does not support this behavior. This method will be invoked on only the database service of the first selected document.
        Parameters:
        documents - The documents currently selected, these may be from different Database Services, beware!
        Returns:
        A string url or null.
        Since:
        API 4.202520 (Geneious 2025.2.0)

      • getDocumentTypesForSequenceSearch

        @MustReturnPromptly
public DocumentSelectionSignature[] getDocumentTypesForSequenceSearch​(DatabaseService.SequenceSearchQueryType queryType,
                                                                      java.lang.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.

      • retrieve

        @MayReturnSlowly
public final java.util.List<AnnotatedPluginDocument> retrieve​(java.lang.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

        @MayReturnSlowly
public final java.util.List<AnnotatedPluginDocument> retrieve​(java.util.List<AnnotatedPluginDocument> summaryDocuments,
                                                              jebl.util.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.

      • showAdvancedSearchByDefault

        @MustReturnPromptly
public boolean showAdvancedSearchByDefault()
        Override this to have the advanced search options shown by default in Geneious (instead of the basic search). Method returns false unless overridden.

        Note that the search panel won't be showing at all by default if isBrowsable() returns true. If the user clicks the "Search" button, then this method will take effect to determine whether advanced or basic is shown at that point.

        Returns:
        true if advanced search panel should be shown by default, false if basic should be shown by default.
        Since:
        API 4.1021 (Geneious 10.2.1)

      • isDocumentUnreadStatusEnabled

        @MustReturnPromptly
public boolean isDocumentUnreadStatusEnabled()
        Indicates whether documents inside this database service are allowed to be marked "unread". This is true by default. If this returns false, Geneious Prime will consider all documents in this database as "read" and not allow users to modify this.
        Returns:
        true if the database service supports document unread status.
        Since:
        API 4.202310 (Geneious 2023.1.0)