Package com.biomatters.geneious.publicapi.plugin

Class PluginUtilities

  • public final class PluginUtilities
extends java.lang.Object
    Provides various functionality to access other installed plug-ins. For example, exporting, importing, performing sequence alignment, and accessing annotation generators.

    • Field Detail

      • SEARCH_RESULTS_SERVICE_UNIQUE_ID

        public static final java.lang.String SEARCH_RESULTS_SERVICE_UNIQUE_ID
        The unique ID of the local database root "Searches" service. Use getGeneiousService(String) to get the service. Note: In Geneious R7 and later, the "Searches" service is no longer used. Search results are now saved in a sub-folder of the query sequence.
        Since:
        API 4.50 (Geneious 5.5.0)
        See Also:
        Constant Field Values

      • LOCAL_DATABASE_SERVICE_UNIQUE_ID

        public static final java.lang.String LOCAL_DATABASE_SERVICE_UNIQUE_ID
        The unique ID of the local database root "Local" service. Use getGeneiousService(String) to get the service.
        Since:
        API 4.50 (Geneious 5.5.0)
        See Also:
        Constant Field Values

    • Method Detail

      • getAssemblers

        public static java.util.List<Assembler> getAssemblers()
        Get a list of all Assemblers provided by all currently installed plugins.
        Returns:
        a list of all Assemblers provided by all currently installed plugins
        Since:
        API 4.14 (Geneious 5.1)

      • getCategoryOperation

        public static DocumentOperation getCategoryOperation​(GeneiousActionOptions.Category category)
        Get the category operation that includes all other operations in this category. e.g. alignment or tree building. This may be null if no such category operation exists.
        Returns:
        the category operation that includes all other operations in this category. e.g. alignment or tree building, or null

      • getDocumentViewerFactories

        public static java.util.List<DocumentViewerFactory> getDocumentViewerFactories​(AnnotatedPluginDocument... documents)
        Get a list of DocumentViewerFactories provided by all currently installed plugins or optionally restrict the returned list to those that can view a given set of documents.

        The returned list will be sorted in order of decreasing viewer precedence.

        Parameters:
        documents - optionally restrict the list of returned factories to only those that can view these documents. Use no documents to get all viewer factories.
        Returns:
        a list of DocumentViewerFactories provided by all currently installed plugins

      • displayDocumentSearchDialog

        public static DocumentSelectionOption.FolderOrDocuments displayDocumentSearchDialog​(java.lang.String preferenceKey,
                                                                                    DocumentSearchCache searchCache,
                                                                                    java.util.Set<DocumentType> documentTypes,
                                                                                    DocumentFilter documentFilter,
                                                                                    java.lang.String documentTypeDescription,
                                                                                    java.util.List<AnnotatedPluginDocument> extraDocuments,
                                                                                    DocumentSelectionOption.FolderOrDocuments initialSelection,
                                                                                    java.util.List<DocumentField> fieldsToDisplay,
                                                                                    boolean allowMultipleSelection,
                                                                                    boolean showUseAllButton,
                                                                                    javax.swing.JComponent owner)
        Display a dialog allowing the user to choose document(s) from their local database (or connected shared databases).
        Parameters:
        preferenceKey - a preferences key used for storing the most recently viewed folder and expanded folders.
        searchCache - the DocumentSearchCache searching the documents the user will choose from. Should be null if it isn't feasible to cache all documents of these types in memory. For example, primers can be cached, but SequenceDocuments should not be.
        documentTypes - the document types the user will choose their documents from. If searchCache!=null, then this must be the types that correspond to the search cache.
        documentFilter - An optional filter to further reject documents even if they are one of the provided documentTypes. May be null to perform no additional filtering
        documentTypeDescription - An optional description of what the documentTypes and documentFilter accept. For example "linear nucleotide sequences". May be null in which case this implementation will choose an reasonable description
        extraDocuments - a list of extra documents (not present in any connected databases) to also display in the dialog
        initialSelection - documents or folder that should be selected initially, may be null
        fieldsToDisplay - a list of DocumentFields which will be displayed in columns in the dialog. If the list is null, then one will be created from the fields present on the documents.
        allowMultipleSelection - true if the user can select multiple documents at once
        showUseAllButton - if true, a "Use All" button will be displayed in the dialog which will cause this method to return an empty list when clicked. If false, this method will never return an empty list
        owner - the owner component for the dialog
        Returns:
        null if the user clicked cancel, the list of documents they selected if they clicked ok
        Since:
        API 4.810 (Geneious 8.1.0)

      • getGeneiousService

        public static GeneiousService getGeneiousService​(java.lang.String uniqueID)
        Get access to any standard GeneiousService or any 3rd party GeneiousService. You can then search these from within your own plugin. The following uniqueIDs are used for standard Geneious services:
        • LocalDocuments
        • LocalDocuments/myfolder1/myfolder2
        • SearchResults
        • UniProt
        • NCBI
        • NCBI_genome
        • NCBI_nucleotide_gbc
        • NCBI_popset_gbc
        • NCBI_protein_gpc
        • NCBI_pubmed
        • NCBI_structure
        • NCBI_BLAST
        • NCBI_blastp
        • NCBI_blastn
        • NCBI_blastx
        • NCBI_tblastn
        • NCBI_tblastx
        • rootService
        • BMCollaboration
        • BMCollaboration_account@domain
        • BMCollaboration_account@domain_contact@domain
        • BMCollaboration_account@domain_contact@domain_folderName
        • BMCollaboration_account@domain_contact@domain_folderName_folderName

        The following code will print a list of all uniqueIDs available:

         for (GeneiousService service : PluginUtilities.getGeneiousServices()) {
    System.out.println(service.getUniqueID());
 }
        >

        If the service with the specified unique ID is currently unavailable (e.g. it has not finished initializing, or it is restricted because there is no active license), this method will return null.

        Parameters:
        uniqueID - a unique ID as described above or the unique ID returned from any GeneiousService.getUniqueID()
        Returns:
        the GeneiousService or null if it's not found (for example, not currently installed) or null if it is unavailable (e.g. it has not finished initializing, or it is restricted because there is no active license) Most GeneiousServices are DatabaseServices, so you can usually cast the return type to that.

      • getDocumentOperation

        public static DocumentOperation getDocumentOperation​(java.lang.String uniqueID)
        get the DocumentOperation with the given unique ID. To view a list of all DocumentOperation unique IDs, you can call DocumentOperation.getUniqueId() on each of the results returned from getDocumentOperations() e.g.
        for (DocumentOperation operation : PluginUtilities.getDocumentOperations())
            System.out.println("Operation: "+operation.getUniqueId());

        A DocumentOperation version of an AlignmentOperation can be retrieved from this method by passing in the unique id prefix (AlignmentOperation.getUniqueIdPrefix()) of the alignment operation with either "_NUCLEOTIDE_" or "_PROTEIN_" on the end depending on which sequence type you wish to align. eg. "Geneious_NUCLEOTIDE_", "Clustal_Alignment_PROTEIN_" or "MUSCLE_PROTEIN_".

        Parameters:
        uniqueID - a unique ID as described above or the unique ID returned from any DocumentOperation.getUniqueId()
        Returns:
        the DocumentOperation or null if it's not found (for example, not currently installed).

      • getAlignmentOperation

        public static DocumentOperation getAlignmentOperation​(java.lang.String uniqueIdPrefix,
                                                      SequenceDocument.Alphabet alphabet)
        Get a DocumentOperation representation of an AlignmentOperation.

        To determine the unique IDs of AlignmentOperations, you can call DocumentOperation.getUniqueId() and look for IDs ending with "with_sequence_type_in_name". The unique ID prefix is the section before "with_sequence_type_in_name" and the alphabet suffix (_NUCLEOTIDE_ or _PROTEIN_).

        Examples for uniqueIdPrefix:

        • Geneious
        • MUSCLE
        • MAFFT (Downloadable plugin)
        Parameters:
        uniqueIdPrefix - the uniqueIdPrefix returned from AlignmentOperation.getUniqueIdPrefix()
        alphabet - alphabet of the sequences that need to be aligned
        Returns:
        a DocumentOperation representation of an AlignmentOperation for aligning the given alphabet. Null if the alignment operation isn't found or if the given alphabet is not supported.
        Since:
        API 4.14 (Geneious 5.1)

      • getDatabaseFolderImporter

        public static DatabaseFolderImporter getDatabaseFolderImporter​(java.lang.String uniqueID)
        get the DatabaseFolderImporter with the given unique ID.
        Parameters:
        uniqueID - a unique ID as described above or the unique ID returned from any DatabaseFolderImporter.getUniqueId()
        Returns:
        the DatabaseFolderImporter or null if it's not found (for example, not currently installed)
        Since:
        API 4.201920 (Geneious Prime 2019.2.0)

      • getGeneiousServices

        public static java.util.List<GeneiousService> getGeneiousServices()
        Returns all installed GeneiousServices. This includes all parent and child services. Alternately you can find a single GeneiousService by ID using getGeneiousService(String). Note, unlike getGeneiousService(String) this method returns services that are currently unavailable (e.g. have not finished initializing or are restricted and there is no active license).
        Returns:
        a list of all installed GeneiousServices

      • getWritableDatabaseServiceRoots

        public static java.util.List<WritableDatabaseService> getWritableDatabaseServiceRoots()
        Returns the root services of all installed WritableDatabaseServices. This includes the local database root folder, the search results root folder, and any shared Database root folders.
        Returns:
        the root services of all installed WritableDatabaseServices. This includes the local database root folder, the search results root folder, and any shared Database root folders.

      • doAlignment

        public static SequenceAlignmentDocument doAlignment​(java.util.List<SequenceDocument> sequences,
                                                    jebl.util.ProgressListener progressListener)
                                             throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Prompts the user to perform an alignment using any of the available alignment plugins. This function will return null if the user aborts, and it must not be run in the dispatch thread.
        Parameters:
        sequences - the sequences to be aligned
        progressListener - Optional. If this is null, the function will create its own progress listener.
        Returns:
        the new alignment.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException

      • importDocuments

        public static java.util.List<AnnotatedPluginDocument> importDocuments​(java.io.File file,
                                                                      java.util.Map<java.lang.String,​java.lang.String> extraOptions,
                                                                      jebl.util.ProgressListener progress)
                                                               throws java.io.IOException,
                                                                      DocumentImportException
        Imports documents from a file into an in memory list.
        Parameters:
        file - the file to import from. This can be any importable file type supported by Geneious or any installed plug-ins.
        extraOptions - The extra options which you want the importer to use. Will attempt to set each option if it's available in the importer identified for the file. Can be null.
        progress - ProgressListener to be notified of import progress. May be null if not interested in progress
        Returns:
        a list of documents, or an empty list if the file contains no documents.
        Throws:
        java.io.IOException - when unable to read the contents of the file for any reason
        DocumentImportException - when unable to generate document(s) from contents of file.
        Since:
        API 4.202200 (Geneious 2022.0.0)
        See Also:
        importDocumentsToDatabase(java.io.File, com.biomatters.geneious.publicapi.databaseservice.WritableDatabaseService, jebl.util.ProgressListener)

      • importDocumentsToDatabase

        public static java.util.List<AnnotatedPluginDocument> importDocumentsToDatabase​(java.io.File file,
                                                                                WritableDatabaseService destination,
                                                                                jebl.util.ProgressListener progress)
                                                                         throws DocumentImportException,
                                                                                java.io.IOException
        Imports documents from a file into a database.
        Parameters:
        file - the file to import from. This can be any importable file type supported by Geneious or any installed plug-ins.
        progress - ProgressListener to be notified of import progress. May be null if not interested in progress
        Returns:
        a list of documents imported, or an empty list if the file contains no documents.
        Throws:
        java.io.IOException - when unable to read the contents of the file for any reason
        DocumentImportException - when unable to generate document(s) from contents of file.
        Since:
        API 4.14 (Geneious 5.1)
        See Also:
        importDocuments(java.io.File, jebl.util.ProgressListener)

      • exportDocumentsInGeneiousFormat

        public static void exportDocumentsInGeneiousFormat​(java.io.File outputFile,
                                                   jebl.util.ProgressListener progressListener,
                                                   AnnotatedPluginDocument... documents)
                                            throws java.io.IOException
        Exports the given documents in Geneious format (zip compressed), to the given file.
        Parameters:
        outputFile - the file to output to. Its extension should be ".geneious".
        progressListener - for reporting exporting progress and allowing the export to be cancelled.
        documents - the documents to export
        Throws:
        java.io.IOException - if the documents cannot be exported or if the progressListener requests the export be canceled.
        Since:
        API 4.40 (Geneious 5.4.0)

      • getDocumentFileImporterForSingleFile

        public static DocumentFileImporter getDocumentFileImporterForSingleFile​(java.io.File file)
                                                                 throws DocumentImportException
        This method returns the document importer that will be used for importing the single file provided. Returns null if no importer could be found. Just because an importer is returned doesn't mean that the file is compatible with geneious or even capable of being imported by the returned importer.
        Parameters:
        file - the file to get the default importer for.
        Returns:
        The document file importer which will be used to import this single file.
        Throws:
        DocumentImportException - if something goes wrong when looking for a compatible DocumentFileImporter
        Since:
        API 4.202120 (Geneious 2021.2.0)

      • exportDocumentsInGeneiousFormat

        public static void exportDocumentsInGeneiousFormat​(java.io.File outputFile,
                                                   jebl.util.ProgressListener progressListener,
                                                   Geneious.MajorVersion minimumVersionToTryToMakeCompatibleWith,
                                                   Geneious.MajorVersion minimumVersionMustBeCompatibleWith,
                                                   Geneious.MajorVersion minimumVersionToNotWarnAboutDataLossWhenImporting,
                                                   java.util.List<AnnotatedPluginDocument> documents)
                                            throws java.io.IOException,
                                                   com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Exports the given documents in Geneious format (zip compressed), to the given file.
        Parameters:
        outputFile - the file to output to. Its extension should be ".geneious".
        progressListener - for reporting exporting progress and allowing the export to be cancelled.
        minimumVersionToTryToMakeCompatibleWith - if this is non=null, then the size of the exported file maybe be increased in order to include versions of documents in legacy formats in addition to the current format. Documents exported are not guaranteed to be compatible with this version if for example this document type was created in a more recent version of Geneious. Use minimumVersionMustBeCompatibleWith to fail if documents cannot be exported to the specified version
        minimumVersionMustBeCompatibleWith - if this is non-null, specifies the minimum version that these documents must be able to be imported in. If they can't be exported to this version, this method will throw a DocumentOperationException
        minimumVersionToNotWarnAboutDataLossWhenImporting - normally Geneious warns when importing a file which was exported in a future version because there may be data that is ignored by the older version. If this parameter is non-null the user won't be warned about potential data loss when importing into this version or later. If they can't be exported to this version, this method will throw a DocumentOperationException
        documents - the documents to export
        Throws:
        java.io.IOException - if the documents cannot be exported or if the progressListener requests the export be canceled.
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the documents cannot be exported in a format compatible with the requested version number
        Since:
        API 4.201900 (Geneious 2019.0.0)

      • exportDocumentsInGeneiousFormat

        public static void exportDocumentsInGeneiousFormat​(java.io.OutputStream outputStream,
                                                   jebl.util.ProgressListener progressListener,
                                                   AnnotatedPluginDocument... documents)
                                            throws java.io.IOException
        Exports the given documents in Geneious format (zip compressed), to the given output stream.
        Parameters:
        outputStream - the stream to output to. If streaming to a file its extension should be ".geneious".
        progressListener - for reporting exporting progress and allowing the export to be cancelled.
        documents - the documents to export
        Throws:
        java.io.IOException - if the documents cannot be exported or if the progressListener requests the export be canceled.
        Since:
        API 4.44 (Geneious 5.4.4)

      • getClass

        public static java.lang.Class getClass​(java.lang.String className)
                                throws java.lang.ClassNotFoundException
        Find a class by name in Geneious or in any installed plugin.

        For certain classes where the absolute class name has changed between versions of Geneious, this method automatically re-maps old class names to new class names.

        This method will find classes in any installed plugin. If multiple plugins define a class with the same name it is undefined which class will be returned. Therefore plugins should always use fully qualified class names to ensure they are unique.

        This method is useful because Class.forName(String) will not find classes from other plugins due to them being defined in a different class loader from the calling code.

        Parameters:
        className - the name of the class to find.
        Returns:
        a Class object
        Throws:
        java.lang.ClassNotFoundException - if the class name is not found in Geneious or in any plugin

      • exportDocuments

        public static void exportDocuments​(java.io.File file,
                                   AnnotatedPluginDocument... documentsToExport)
                            throws java.io.IOException,
                                   java.lang.UnsupportedOperationException
        Exports these documents to this file in a format suitable for the given file's extension.

        If multiple DocumentFileExporter plugins support exporting these documents to a format the uses the given file extension then the first plugin found will be used.

        Note: If the exporter has any options (see DocumentFileExporter.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]), this method uses the default option values. If you want to change option values, use getDocumentFileExporters() to get the required exporter.

        Parameters:
        file - the file to export to. The file name extension of this file is used to determine the exporter to use.
        documentsToExport - the documents to export.
        Throws:
        java.io.IOException - if the exporter encounters problems exporting to the file.
        java.lang.UnsupportedOperationException - if no plugin exists that can export these documents to a format with the given file extension.

      • getActiveGeneiousPlugins

        public static java.util.List<GeneiousPlugin> getActiveGeneiousPlugins()
        Returns:
        a list of the currently enabled plugins in Geneious. Plugins that have been disabled by the user will not appear in this list even if they have been installed.
        Since:
        API 4.14 (Geneious 5.1)

      • getPluginForAssembler

        public static GeneiousPlugin getPluginForAssembler​(Assembler assembler)
        Get the GeneiousPlugin that provides a given Assembler via GeneiousPlugin.getAssemblers()
        Parameters:
        assembler - The Assembler to get the plugin for
        Returns:
        The GeneiousPlugin that provides the specified Assembler or null if there was no plugin found that provides the assembler
        Since:
        API 4.14 (Geneious 5.1)

      • isRunningFromScript

        public static boolean isRunningFromScript()
        Returns:
        true if the current thread is running from a script or workflow. If so, then dialogs should not be displayed. Choose a reasonable default or have it as an option. Furthermore, document operations should not modify input documents. Instead they should create copies to modify and output those.
        Since:
        API 4.700 (Geneious 7.0.0)
        See Also:
        setRunningFromScript(boolean), isConfiguringScript()

      • setRunningFromScript

        public static void setRunningFromScript​(boolean runningFromScript)
        Sets whether or not the current thread is running from a script. For a discussion of what this means, see isRunningFromScript().

        Any code that calls setRunningFromScript() with a value of true must make a matching call with a value of false. For example 
         try {
     PluginUtilities.setRunningFromScript(true);
     ...
 } finally {
     PluginUtilities.setRunningFromScript(false);
 }
        Calls to setRunningFromScript from a script may be nested. isRunningFromScript() only returns false if there has been a matching call with "false" for each call made with "true".
        Parameters:
        runningFromScript - whether or not to flag the current thread as running from a script
        Since:
        API 4.1000 (Geneious 10.0.0)
        See Also:
        isRunningFromScript()

      • isConfiguringScript

        public static boolean isConfiguringScript()
        Returns:
        true if the current thread is configuring a script or workflow. If so, then some dialogs should not be displayed. Choose a reasonable default or have it as an option.
        Since:
        API 4.1011 (Geneious 10.1.1)
        See Also:
        isRunningFromScript(), setConfiguringScript(boolean)

      • setConfiguringScript

        public static void setConfiguringScript​(boolean configuringScript)
        Sets whether or not the current thread is configuring a script. For a discussion of what this means, see isConfiguringScript().

        Any code that calls setConfiguringScript() with a value of true must make a matching call with a value of false. For example 
         try {
     PluginUtilities.setConfiguringScript(true);
     ...
 } finally {
     PluginUtilities.setConfiguringScript(false);
 }
        Calls to setConfiguringScript from a script may be nested. isConfiguringScript() only returns false if there has been a matching call with "false" for each call made with "true".
        Parameters:
        configuringScript - whether or not to flag the current thread is currently configuring a script
        Since:
        API 4.1011 (Geneious 10.1.1)
        See Also:
        isConfiguringScript()

      • installPluginSilently

        public static void installPluginSilently​(java.io.File pluginFile)
                                  throws java.io.IOException
        Installs and activates a plugin without providing any feedback to the user
        Parameters:
        pluginFile - the gplugin file to be installed
        Throws:
        java.io.IOException - if the plugin can't be installed, or if it requires a restart to complete the installation (in which case the exception message will begin with the word restart)
        Since:
        API 4.1021 (Geneious 10.2.1)