Class DocumentUtilities


  • public final class DocumentUtilities
    extends java.lang.Object
    Some core functionality provided by Geneious for adding and managing documents.
    • Method Detail

      • createAnnotatedPluginDocument

        public static AnnotatedPluginDocument createAnnotatedPluginDocument​(PluginDocument document,
                                                                            jebl.util.ProgressListener progressListener)
        Creates an AnnotatedPluginDocument from a PluginDocument. The AnnotatedPluginDocument may hold a reference to the given PluginDocument and cache properties of the PluginDocument. Therefore the PluginDocument must not be modified after the creation of the AnnotatedPluginDocument.

        Note - if AnnotatedPluginDocument.getDocument() is called on the returned AnnotatedPluginDocument it will not be the same PluginDocument instance as the one passed to this method. See AnnotatedPluginDocument.getDocument() for further information.

        Parameters:
        document - the underlying PluginDocument
        progressListener - since creating annotated plugin documents wrapping huge plugin documents can take a short but noticeable amount of time, this reports the progress and provides the ability to cancel the creation.
        Returns:
        the newly created AnnotatedPluginDocument or null if the progressListener requests the creation be cancelled.
      • createAnnotatedPluginDocument

        public static AnnotatedPluginDocument createAnnotatedPluginDocument​(PluginDocument document,
                                                                            URN urn,
                                                                            jebl.util.ProgressListener progressListener)
        Creates an AnnotatedPluginDocument from a PluginDocument with a specific URN. In almost all cases you should use createAnnotatedPluginDocument(PluginDocument, ProgressListener) instead.
        Parameters:
        document - the underlying PluginDocument
        urn - the URN for the new document.
        progressListener - since creating annotated plugin documents wrapping huge plugin documents can take a short but noticeable amount of time, this reports the progress and provides the ability to cancel the creation.
        Returns:
        the newly created AnnotatedPluginDocument or null if the progressListener requests the creation be cancelled.
        Since:
        API 4.201900 (Geneious 2019.0.0)
      • createAnnotatedPluginDocuments

        public static java.util.List<AnnotatedPluginDocument> createAnnotatedPluginDocuments​(java.util.List<? extends PluginDocument> documents)
        Creates a list of AnnotatedPluginDocuments from a list of PluginDocuments. See createAnnotatedPluginDocument(PluginDocument) for further details
        Parameters:
        documents - the list of underlying PluginDocuments
        Returns:
        the newly created AnnotatedPluginDocuments
      • addGeneratedDocuments

        public static void addGeneratedDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                                 boolean selectDocumentsImmediately)
        Adds newly generated documents that will appear in the user's local database. The documents themselves are not added to the local database, but instead copies are added.

        It is recommended that this method not be called from the AWT thread with waitForResults = true as it could potentially take some time.

        Consider using addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List) instead if you need to reference the newly added document copies.

        Parameters:
        documents - the list of generated AnnotatedPluginDocuments (this list doesn't need to be modifiable)
        selectDocumentsImmediately - set focus to newly added documents if true
      • addGeneratedDocuments

        public static void addGeneratedDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                                 boolean selectDocumentsImmediately,
                                                 java.util.List<AnnotatedPluginDocument> additionalDocumentsToSelect)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and so that they become visible in the document table. The documents themselves are not added to the local database, but instead copies are added.

        It is recommended that this method not be called from the AWT thread with waitForResults = true as it could potentially take some time.

        Consider using addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List) instead if you need to reference the newly added document copies.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        additionalDocumentsToSelect - Optional list of additional documents to select. May not be null, but may be empty (e.g. Collections.emptyList()). If this list is nonempty and selectDocumentImmediately is true, then both these documents and the generated ones will be selected.
        See Also:
        addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List)
      • addGeneratedDocuments

        public static void addGeneratedDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                                 boolean selectDocumentsImmediately,
                                                 java.util.List<AnnotatedPluginDocument> additionalDocumentsToSelect,
                                                 WritableDatabaseService destination)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and so that they become visible in the document table. The documents themselves are not added to the local database, but instead copies are added.

        Consider using addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List) instead if you need to reference the newly added document copies.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        additionalDocumentsToSelect - Optional list of additional documents to select. May not be null, but may be empty (e.g. Collections.emptyList()). If this list is nonempty and selectDocumentImmediately is true, then both these documents and the generated ones will be selected.
        destination - destination folder to add the documents to. May be null to use the default location (prompting the user if necessary). An appropriate destination can be obtained using ServiceUtilities.getResultsDestination()
        Since:
        API 4.51 (Geneious 5.5.1)
        See Also:
        addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List)
      • addGeneratedDocumentsWithLineage

        public static java.util.List<AnnotatedPluginDocument> addGeneratedDocumentsWithLineage​(java.util.List<AnnotatedPluginDocument> documents,
                                                                                               boolean selectDocumentsImmediately,
                                                                                               WritableDatabaseService destination,
                                                                                               java.lang.String operationUniqueId,
                                                                                               java.util.List<AnnotatedPluginDocument> parentDocuments,
                                                                                               jebl.util.ProgressListener progress)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and so that they become visible in the document table. Adds lineage information to both parent and generated descendant documents.

        The documents themselves are not added to the local database, but instead copies are added: It is essential to use the returned documents rather than the passed in parameters if you wish to store a reference to the newly added documents using their URN.

        It is recommended that this method not be called from the AWT thread as it could potentially take some time.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        destination - destination folder to add the documents to. May be null to use the default location (prompting the user if necessary). An appropriate destination can be obtained using ServiceUtilities.getResultsDestination()
        operationUniqueId - Identifier for the operation (DocumentOperation.getUniqueId() or annotation generator (SequenceAnnotationGenerator.getUniqueId()used to generate the documents to add
        parentDocuments - List of parent documents to use to generate lineage information
        progress - A progress listener
        Returns:
        The documents successfully added to the user's database. In some cases the user may need to be prompted for the location to store the documents. In this case, if the user chooses cancel, the documents will not be added and this method will return an empty list. Additionally, if an error is encountered saving a document or lineage information, a message will be displayed to the user and an empty list will be returned.
        Since:
        API 4.1000 (Geneious 10.0.0)
      • addGeneratedDocumentsWithLineage

        public static java.util.List<AnnotatedPluginDocument> addGeneratedDocumentsWithLineage​(java.util.List<AnnotatedPluginDocument> documents,
                                                                                               boolean selectDocumentsImmediately,
                                                                                               WritableDatabaseService destination,
                                                                                               java.lang.String operationUniqueId,
                                                                                               java.util.List<AnnotatedPluginDocument> parentDocuments,
                                                                                               boolean giveResultsUniqueNames,
                                                                                               jebl.util.ProgressListener progress)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and so that they become visible in the document table. Adds lineage information to both parent and generated descendant documents.

        The documents themselves are not added to the local database, but instead copies are added: It is essential to use the returned documents rather than the passed in parameters if you wish to store a reference to the newly added documents using their URN.

        It is recommended that this method not be called from the AWT thread with waitForResults = true as it could potentially take some time.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        destination - destination folder to add the documents to. May be null to use the default location (prompting the user if necessary). An appropriate destination can be obtained using ServiceUtilities.getResultsDestination()
        operationUniqueId - Identifier for the operation (DocumentOperation.getUniqueId() or annotation generator (SequenceAnnotationGenerator.getUniqueId()used to generate the documents to add
        parentDocuments - List of parent documents to use to generate lineage information
        giveResultsUniqueNames - If true, the generated documents will be renamed if a document already exists in the same folder with the input name
        progress - A progress listener
        Returns:
        The documents successfully added to the user's database. In some cases the user may need to be prompted for the location to store the documents. In this case, if the user chooses cancel, the documents will not be added and this method will return an empty list. Additionally, if an error is encountered saving a document or lineage information, a message will be displayed to the user and an empty list will be returned.
        Since:
        API 4.202010 (Geneious Prime 2020.1.0)
      • addAndReturnGeneratedDocuments

        public static java.util.List<AnnotatedPluginDocument> addAndReturnGeneratedDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                                                                             boolean selectDocumentsImmediately,
                                                                                             java.util.List<AnnotatedPluginDocument> additionalDocumentsToSelect,
                                                                                             WritableDatabaseService destination)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and so that they become visible in the document table, and returns the newly added documents

        The documents themselves are not added to the local database, but instead copies are added: it is essential to use the returned documents rather than the passed in parameters if you wish to store a reference to the newly added documents using their URN.

        It is recommended that this method not be called from the AWT thread as it could potentially take some time.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        additionalDocumentsToSelect - Optional list of additional documents to select. May not be null, but may be empty (e.g. Collections.emptyList()). If this list is nonempty and selectDocumentImmediately is true, then both these documents and the generated ones will be selected.
        destination - destination folder to add the documents to. May be null to use the default location (prompting the user if necessary). An appropriate destination can be obtained using ServiceUtilities.getResultsDestination()
        Returns:
        The documents successfully added to the user's database. In some cases the user may need to be prompted for the location to store the documents. In this case, if the user chooses cancel, the documents will not be added and this method will return an empty list. Additionally, if an error is encountered saving a document, a message will be displayed to the user and the document will not be included in the returned list.
        Since:
        API 4.60 (Geneious 5.6.0)
        See Also:
        addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List)
      • addAndReturnGeneratedDocuments

        public static java.util.List<AnnotatedPluginDocument> addAndReturnGeneratedDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                                                                             boolean selectDocumentsImmediately,
                                                                                             java.util.List<AnnotatedPluginDocument> additionalDocumentsToSelect,
                                                                                             boolean giveResultsUniqueNames,
                                                                                             WritableDatabaseService destination)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and so that they become visible in the document table, and returns the newly added documents

        The documents themselves are not added to the local database, but instead copies are added: it is essential to use the returned documents rather than the passed in parameters if you wish to store a reference to the newly added documents using their URN.

        It is recommended that this method not be called from the AWT thread as it could potentially take some time.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        additionalDocumentsToSelect - Optional list of additional documents to select. May not be null, but may be empty (e.g. Collections.emptyList()). If this list is nonempty and selectDocumentImmediately is true, then both these documents and the generated ones will be selected.
        giveResultsUniqueNames - If true, the generated documents will be renamed if a document already exists in the same folder with the input name
        destination - destination folder to add the documents to. May be null to use the default location (prompting the user if necessary). An appropriate destination can be obtained using ServiceUtilities.getResultsDestination()
        Returns:
        The documents successfully added to the user's database. In some cases the user may need to be prompted for the location to store the documents. In this case, if the user chooses cancel, the documents will not be added and this method will return an empty list. Additionally, if an error is encountered saving a document, a message will be displayed to the user and the document will not be included in the returned list.
        Since:
        API 4.202010 (Geneious Prime 2020.1.0)
        See Also:
        addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List)
      • addAndReturnGeneratedDocuments

        public static java.util.List<AnnotatedPluginDocument> addAndReturnGeneratedDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                                                                             boolean selectDocumentsImmediately,
                                                                                             java.util.List<AnnotatedPluginDocument> additionalDocumentsToSelect)
        Adds a list of documents that have just been generated to Geneious so that they appear in the user's local database and returns the newly added documents.

        It is essential to use the returned documents rather than the passed in parameters if you wish to store a reference to the newly added documents using their URN.

        It is recommended that this method not be called from the AWT thread as it could potentially take some time.

        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
        additionalDocumentsToSelect - Optional list of additional documents to select. May not be null, but may be empty (e.g. Collections.emptyList()). If this list is nonempty and selectDocumentImmediately is true, then both these documents and the generated ones will be selected.
        Returns:
        The documents successfully added to the user's database. In some cases the user may need to be prompted for the location to store the documents. In this case, if the user chooses cancel, the documents will not be added and this method will return an empty list. Additionally, if an error is encountered saving a document, a message will be displayed to the user and the document will not be included in the returned list.
      • addGeneratedPluginDocuments

        public static void addGeneratedPluginDocuments​(java.util.List<PluginDocument> documents,
                                                       boolean selectDocumentsImmediately)
        Adds newly generated documents that will appear in the user's local database.
        Parameters:
        documents - List of documents to add; this list doesn't have to be modifiable
        selectDocumentsImmediately - If true, the generated documents will be immediately selected in the document table
      • addGeneratedDocument

        public static void addGeneratedDocument​(AnnotatedPluginDocument document,
                                                boolean selectDocumentImmediately)
        Adds a newly generated document that will appear in the user's local database.
        Parameters:
        document - the document to add
        selectDocumentImmediately - set focus to newly added document if true
      • addGeneratedPluginDocument

        public static void addGeneratedPluginDocument​(PluginDocument document,
                                                      boolean selectDocumentImmediately)
        Adds a newly generated document that will appear in the user's local database.
        Parameters:
        document - the document to add
        selectDocumentImmediately - set focus to newly added document if true
      • getDocumentByURN

        public static AnnotatedPluginDocument getDocumentByURN​(URN urn)
        Fetches the specified document from either in memory or from the local or a shared database.

        if the document is not available locally, this method may obtain the document directly from its source over a network connection. If the document cannot be found then this method will return null.

        Documents are cached so if something else already holds a reference to the AnnotatedPluginDocument, this method will return promptly. However, if the document doesn't exist or if the document is not already in memory, this method will generally be slow because each database needs to be queried.

        Since results from non-WritableDatabaseService databases (e.g. NCBI) are held in memory, this method will also find those results.

        Parameters:
        urn - location of document. If this is null, null will be returned.
        Returns:
        the document specified by the given URN or null if it isn't found
        See Also:
        getDocumentsByURN(List, boolean), AnnotatedPluginDocument.getURN()
      • getDocumentByURNThrowingExceptionOnDatabaseError

        public static AnnotatedPluginDocument getDocumentByURNThrowingExceptionOnDatabaseError​(URN urn)
                                                                                        throws DatabaseServiceException
        Similar to getDocumentByURN(URN) except if a database reports an exception while requesting this document, this this method will throw that exception.
        Parameters:
        urn - location of document. If this is null, null will be returned.
        Returns:
        the document, or null if no connected database contains this document.
        Throws:
        DatabaseServiceException - if there is a problem (e.g. network IO) obtaining a document or checking if a database contains this document
        Since:
        API 4.202111 (Geneious 2021.1.1)
      • getDocumentsByURN

        public static java.util.List<AnnotatedPluginDocument> getDocumentsByURN​(java.util.List<URN> urns,
                                                                                boolean failIfDocumentCannotBeFound)
                                                                         throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Fetches the specified documents from either in memory or from the local or a shared database.

        If a document is not available locally, this method may obtain the document directly from its source over a network connection. If the document cannot be found then this method will optionally either fail or skip the document.

        Documents are cached so if something else already holds a reference to the AnnotatedPluginDocument, this method will return promptly. However, if the document doesn't exist or if the document is not already in memory, this method will generally be slow because each database needs to be queried.

        Since results from non-WritableDatabaseService databases (e.g. NCBI) are held in memory, this method will also find those results.

        Parameters:
        urns - list of locations of documents.
        failIfDocumentCannotBeFound - if true throw a DocumentOperationException if any document cannot be found, else ignore it
        Returns:
        a list with one entry per specified URN, either the document that was found or null if the document could not be found
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if failIfDocumentCannotBeFound is true and any document cannot be found
        Since:
        API 4.1000 (Geneious 10.0.0)
        See Also:
        getDocumentByURN(URN), AnnotatedPluginDocument.getURN()
      • unloadDocuments

        public static void unloadDocuments​(java.util.function.Predicate<URN> urnFilter)
        Deprecated.
        Under no circumstances should this method be used! Core Geneious is responsible for managing the strong references (and by extension, the lifespan) of all AnnotatedPluginDocument in memory, even in the event of document-supplying services being removed (i.e. a network database logout event). Unloading documents from plugin code can cause serious data integrity issues within Geneious. For an in-depth explanation of document lifespan behaviour, see AnnotatedPluginDocument's javadoc.
        Unloads a series of documents from memory based on the specified URN filter pattern, allowing AnnotatedPluginDocument that is no longer strongly referenced to be garbage collected.
        Parameters:
        urnFilter - a filter matching the URNs of the documents to remove from memory
        Since:
        API 4.201904 (Geneious 2019.0.4)
      • duplicateDocument

        public static AnnotatedPluginDocument duplicateDocument​(AnnotatedPluginDocument document,
                                                                boolean duplicateReferencedDocuments)
        Create a duplicate of document. The new document is identical to the source except the URN.
        Parameters:
        document - source
        duplicateReferencedDocuments - also duplicate any other documents referenced by this document if true
        Returns:
        The new document or null if the document cannot be duplicated. A document may fail to be duplicated if there is an IOException loading the document's internal PluginDocument. In this case, a dialog will have been displayed to the user informing them about the failure to load the document.
        See Also:
        duplicateDocumentThrowingDocumentOperationExceptionOnFailure(AnnotatedPluginDocument, boolean)
      • duplicateDocumentThrowingDocumentOperationExceptionOnFailure

        public static AnnotatedPluginDocument duplicateDocumentThrowingDocumentOperationExceptionOnFailure​(AnnotatedPluginDocument document,
                                                                                                           boolean duplicateReferencedDocuments)
                                                                                                    throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Create a duplicate of document. The new document is identical to the source except the URN.
        Parameters:
        document - source
        duplicateReferencedDocuments - also duplicate any other documents referenced by this document if true
        Returns:
        The new document. Will not be null.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the document cannot be duplicated, for example because the original document throws an IOException loading the document's internal PluginDocument.
        Since:
        API 4.60 (Geneious 5.6.0)
        See Also:
        duplicateDocument(AnnotatedPluginDocument, boolean)
      • wouldDocumentNameBeUnique

        @Deprecated
        public static boolean wouldDocumentNameBeUnique​(java.lang.String baseDocumentName)
        Deprecated.
        Checks to see if the document name would be unique if constructed with the given base document name.
        Parameters:
        baseDocumentName - the base document name
        Returns:
        true if the document name would be unique
      • getUniqueNameForDocument

        @Deprecated
        public static java.lang.String getUniqueNameForDocument​(java.lang.String baseDocumentName)
        Deprecated.
        use getUniqueNameForDocument(String, WritableDatabaseService, Collection)
        Generate a unique document name based on the original name passed in. A name is considered to be unique if it was never returned by previous calls to this method with the same value for baseDocumentName.
        Parameters:
        baseDocumentName - the original document name
        Returns:
        a unique document name based on the name passed in
      • getUniqueNameForDocument

        @Deprecated
        public static java.lang.String getUniqueNameForDocument​(java.lang.String baseDocumentName,
                                                                boolean reserveName)
        Deprecated.
        use getUniqueNameForDocument(String, WritableDatabaseService, Collection)
        Generate a unique document name based on the original name passed in. A name is considered to be unique if it was never returned by previous calls to this method with the same value for baseDocumentName and reserveName == true. This method does not check for uses of this name created independently of the use of this method.
        Parameters:
        baseDocumentName - the original document name
        reserveName - whether to "reserve" the returned name so that it cannot be returned by future calls to this method with the same baseDocumentName.
        Returns:
        a unique document name based on the name passed in
      • getUniqueNameForDocument

        public static java.lang.String getUniqueNameForDocument​(java.lang.String baseDocumentName,
                                                                WritableDatabaseService mustBeUniqueIn)
                                                         throws DatabaseServiceException
        Generate a document name that is unique to the given folder, based on the original name passed in. Subfolders are not considered

        This method must not be called in the dispatch (swing) thread because it may have to wait on network I/O.
        Parameters:
        baseDocumentName - the original document name
        mustBeUniqueIn - the folder in which the name must be unique.
        Returns:
        a unique document name based on the name passed in
        Throws:
        DatabaseServiceException - if there is an error checking the folder's documents
        Since:
        API 4.51 (Geneious 5.5.1)
      • getUniqueNameForDocument

        public static java.lang.String getUniqueNameForDocument​(java.lang.String baseDocumentName,
                                                                WritableDatabaseService mustBeUniqueIn,
                                                                java.util.Collection<java.lang.String> mustNotBe)
                                                         throws DatabaseServiceException
        Generate a document name that is unique to the given folder, based on the original name passed in. Subfolders are not considered

        This method must not be called in the dispatch (swing) thread because it may have to wait on network I/O.
        Parameters:
        baseDocumentName - the original document name
        mustBeUniqueIn - the folder in which the name must be unique.
        mustNotBe - any additional names which must not be used
        Returns:
        a unique document name based on the name passed in
        Throws:
        DatabaseServiceException - if there is an error checking the folder's documents
        Since:
        API 4.51 (Geneious 5.5.1)
      • selectDocument

        public static boolean selectDocument​(URN urn)
        Changes the currently selected document in the Geneious document table.
        Parameters:
        urn - the URN of the document to be selected
        Returns:
        true if the document is found and selected.
      • selectDocuments

        public static boolean selectDocuments​(java.util.List<URN> urns)
        Changes the currently selected documents in the Geneious document table. If these documents are not all in the same folder, Geneious will not be able to select them.
        Parameters:
        urns - the URNs of the documents to be selected
        Returns:
        true if the documents are found and selected.
        See Also:
        selectDocuments(java.util.List, com.biomatters.geneious.publicapi.plugin.SequenceSelection)
      • selectDocuments

        public static boolean selectDocuments​(java.util.List<URN> urns,
                                              SequenceSelection sequenceSelection)
        Changes the currently selected documents in the Geneious document table and selects a region within them. If these documents are not all in the same folder, Geneious will not be able to select them.
        Parameters:
        urns - the URNs of the documents to be selected
        sequenceSelection - the selection to apply within these documents. May be null to leave the selection as it currently is.
        Returns:
        true if the documents are found and selected.
      • unselectDocuments

        public static void unselectDocuments​(boolean onlyIfNoUnsavedChanges)
        Unselects any documents currently selected in Geneious. This method must be called from the Swing thread.
        Parameters:
        onlyIfNoUnsavedChanges - if this is true and there are currently unsaved changes, then the selection will not be changed. If this is false and there are currently unsaved changes, the user will be prompted whether or not to save them.
        Since:
        API 4.1000 (Geneious 10.0.0)
      • getSelectedDocuments

        public static java.util.List<AnnotatedPluginDocument> getSelectedDocuments()
        Gets the currently selected documents in the Geneious document table.
        Returns:
        the currently selected documents in the Geneious document table. May return an empty list, but never returns null.
        Since:
        API 4.30 (Geneious 5.3.0)
      • createAnnotatedPluginDocument

        public static AnnotatedPluginDocument createAnnotatedPluginDocument​(org.jdom.Element annotatedDocumentElement,
                                                                            ElementProvider pluginDocumentElementProvider,
                                                                            URN urnForNewDocument)
                                                                     throws XMLSerializationException
        Creates an AnnotatedPluginDocument without the internal PluginDocument included. An ElementProvider will load the PluginDocument when it is required. Generally this method should only used by WritableDatabaseService implementations.

        The database implementation should maintain a SoftReference cache of all documents it creates using this method and reuse previously created documents that refer to the same document URN. Furthermore, the database may make calls to AnnotatedPluginDocument.documentChanged(org.jdom.Element) on any of the documents it stores in this cache.

        Finally, the database implementation must call AnnotatedPluginDocument.setDatabase(DatabaseService) on the document before providing it back in response to database retrieve methods. A document create via this method which has not has setDatabase called may not behave correctly in response to changes to the document.

        Parameters:
        annotatedDocumentElement - some XML returned from a previous call to AnnotatedPluginDocument.toXMLExcludingInternalPluginDocument()
        pluginDocumentElementProvider - an ElementProvider that will load the PluginDocument when it is required
        urnForNewDocument - the returned document will be assigned this URN, or if this is null the document will use the existing URN defined in its XML. A database must use null here when loading existing documents and a non-null value only when creating document copies in WritableDatabaseService.addDocumentCopy(AnnotatedPluginDocument, jebl.util.ProgressListener)
        Returns:
        an AnnotatedPluginDocument
        Throws:
        XMLSerializationException - if the annotatedDocumentElement is not a valid AnnotatedPluginDocument
        Since:
        API 4.60 (Geneious 5.6.0)
      • openDocumentsInNewWindow

        public static void openDocumentsInNewWindow​(java.util.List<AnnotatedPluginDocument> documents)
        Opens a new Geneious window and displays these documents in all available document viewers that match these documents.
        Parameters:
        documents - the documents to display.
      • getAnnotatedPluginDocumentThatContains

        public static AnnotatedPluginDocument getAnnotatedPluginDocumentThatContains​(PluginDocument pluginDocument)
        Gets the AnnotatedPluginDocument that contains the given PluginDocument. This only works with the PluginDocument returned from AnnotatedPluginDocument.getDocument() or any other getDocument* methods in AnnotatedPluginDocument. Since PluginDocument passed to createAnnotatedPluginDocument(PluginDocument) is not the same as the document instance returned from getDocument(), the PluginDocument passed to createAnnotatedPluginDocument is not considered to be contained in the AnnotatedPluginDocument returned from createAnnotatedPluginDocument.
        Parameters:
        pluginDocument - the plugin document to get the associated AnnotatedPluginDocument for.
        Returns:
        the AnnotatedPluginDocument or null if this PluginDocument is not wrapped in an AnnotatedPluginDocument.
        Throws:
        java.lang.NullPointerException - if pluginDocument is null.
        Since:
        API 4.14 (Geneious 5.1)
      • showSaveAsDialog

        public static boolean showSaveAsDialog​(javax.swing.JComponent viewerComponent)
        Shows the "Save As" dialog (i.e. what would happen if the user selected "Save As" from the file menu. This only works if a single document is selected
        Parameters:
        viewerComponent - the component from the currently active document viewer, or null to use the currently focused component.
        Returns:
        true if the save as succeeded. false if it failed, either because multiple documents are selected or the user chose to cancel.
        Since:
        API 4.60 (Geneious 5.6.0)
      • getAllDisplayableFields

        public static java.util.List<DocumentField> getAllDisplayableFields()
        Gets a list of all the displayable fields on any document in the user's database
        Returns:
        a list of all the displayable fields on any document in the users's database
        Since:
        API 4.601 (Geneious 6.0.1)
      • pluginDocumentFileDataToXml

        public static void pluginDocumentFileDataToXml​(org.jdom.Element element,
                                                       java.io.File file,
                                                       boolean fileMayBeZeroBytesInSize)
        Provides a system for storing a reference to an arbitrary immutable file from within a PluginDocument. This is a convenience method that uses PluginDocument.FILE_DATA_ATTRIBUTE_NAME but has additional safety checks to fail gracefully on deserialization when the underlying file is corrupted which is prone to happening on Windows systems where the users data is stored on a network drive. Typically the type of corruption seen are files being truncated, often to 0 bytes in size, and files just disappearing.

        In addition to using PluginDocument.FILE_DATA_ATTRIBUTE_NAME the implementation also adds an attribute called "fileSize" to element

        Parameters:
        element - an element to add appropriate attributes to recording the file name and file size
        file - the file to add a reference to in the XML
        fileMayBeZeroBytesInSize - true if the size of the file may be zero bytes. If this is false then this method throws an IllegalStateException if the file size is 0 bytes.
        Since:
        API 4.60 (Geneious 5.6.0)
        See Also:
        pluginDocumentFileDataFromXml(org.jdom.Element, boolean, boolean), PluginDocument.FILE_DATA_ATTRIBUTE_NAME