Class DocumentUtilities
- java.lang.Object
-
- com.biomatters.geneious.publicapi.documents.DocumentUtilities
-
public final class DocumentUtilities extends java.lang.Object
Some core functionality provided by Geneious for adding and managing documents.
-
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description 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.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 documentsstatic 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 documentsstatic void
addGeneratedDocument(AnnotatedPluginDocument document, boolean selectDocumentImmediately)
Adds a newly generated document that will appear in the user's local database.static void
addGeneratedDocuments(java.util.List<AnnotatedPluginDocument> documents, boolean selectDocumentsImmediately)
Adds newly generated documents that will appear in the user's local database.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.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.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.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.static void
addGeneratedPluginDocument(PluginDocument document, boolean selectDocumentImmediately)
Adds a newly generated document that will appear in the user's local database.static void
addGeneratedPluginDocuments(java.util.List<PluginDocument> documents, boolean selectDocumentsImmediately)
Adds newly generated documents that will appear in the user's local database.static AnnotatedPluginDocument
createAnnotatedPluginDocument(PluginDocument document)
static AnnotatedPluginDocument
createAnnotatedPluginDocument(PluginDocument document, URN urn, jebl.util.ProgressListener progressListener)
Creates an AnnotatedPluginDocument from a PluginDocument with a specific URN.static AnnotatedPluginDocument
createAnnotatedPluginDocument(PluginDocument document, jebl.util.ProgressListener progressListener)
Creates an AnnotatedPluginDocument from a PluginDocument.static AnnotatedPluginDocument
createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, boolean assignNewURN)
Deprecated.usecreateAnnotatedPluginDocument(org.jdom.Element, ElementProvider, boolean)
instead, where the final parameter of null is equivalent to assignNewURN==false orURN.generateUniqueLocalURN()
for assignNewURN==truestatic AnnotatedPluginDocument
createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, URN urnForNewDocument)
Creates an AnnotatedPluginDocument without the internal PluginDocument included.static AnnotatedPluginDocument
createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, java.lang.String assignerForUrn)
Deprecated.static java.util.List<AnnotatedPluginDocument>
createAnnotatedPluginDocuments(PluginDocument document)
creates a list of AnnotatedPluginDocuments from a single of PluginDocument.static java.util.List<AnnotatedPluginDocument>
createAnnotatedPluginDocuments(java.util.List<? extends PluginDocument> documents)
Creates a list of AnnotatedPluginDocuments from a list of PluginDocuments.static AnnotatedPluginDocument
duplicateDocument(AnnotatedPluginDocument document, boolean duplicateReferencedDocuments)
Create a duplicate of document.static AnnotatedPluginDocument
duplicateDocumentThrowingDocumentOperationExceptionOnFailure(AnnotatedPluginDocument document, boolean duplicateReferencedDocuments)
Create a duplicate of document.static java.util.List<DocumentField>
getAllDisplayableFields()
Gets a list of all the displayable fields on any document in the user's databasestatic AnnotatedPluginDocument
getAnnotatedPluginDocumentThatContains(PluginDocument pluginDocument)
Gets the AnnotatedPluginDocument that contains the given PluginDocument.static AnnotatedPluginDocument
getDocumentByURN(URN urn)
Fetches the specified document from either in memory or from the local or a shared database.static AnnotatedPluginDocument
getDocumentByURNThrowingExceptionOnDatabaseError(URN urn)
Similar togetDocumentByURN(URN)
except if a database reports an exception while requesting this document, this this method will throw that exception.static AnnotatedPluginDocument
getDocumentFromMemoryByURN(URN urn)
Returns a reference to the specified document if it is currently in memory.static java.util.List<AnnotatedPluginDocument>
getDocumentsByURN(java.util.List<URN> urns, boolean failIfDocumentCannotBeFound)
Fetches the specified documents from either in memory or from the local or a shared database.static java.util.List<AnnotatedPluginDocument>
getSelectedDocuments()
Gets the currently selected documents in the Geneious document table.static java.lang.String
getUniqueNameForDocument(java.lang.String baseDocumentName)
Deprecated.use getUniqueNameForDocument(String, WritableDatabaseService, Collection)static java.lang.String
getUniqueNameForDocument(java.lang.String baseDocumentName, boolean reserveName)
Deprecated.use getUniqueNameForDocument(String, WritableDatabaseService, Collection)static java.lang.String
getUniqueNameForDocument(java.lang.String baseDocumentName, WritableDatabaseService mustBeUniqueIn)
Generate a document name that is unique to the given folder, based on the original name passed in.static java.lang.String
getUniqueNameForDocument(java.lang.String baseDocumentName, WritableDatabaseService mustBeUniqueIn, java.util.Collection<java.lang.String> mustNotBe)
Generate a document name that is unique to the given folder, based on the original name passed in.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.static java.io.File
pluginDocumentFileDataFromXml(org.jdom.Element element, boolean mayReturnNullIfNoFileData, boolean fileMayBeZeroBytesInSize)
Deserializes the name of a file serialized usingpluginDocumentFileDataToXml(org.jdom.Element, java.io.File, boolean)
checking for corruption such as the file disappearing, changing in size or reducing to 0 bytes in size.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.static boolean
selectDocument(URN urn)
Changes the currently selected document in the Geneious document table.static boolean
selectDocuments(java.util.List<URN> urns)
Changes the currently selected documents in the Geneious document table.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.static boolean
showSaveAsDialog(javax.swing.JComponent viewerComponent)
Shows the "Save As" dialog (i.e.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 allAnnotatedPluginDocument
in memory, even in the event of document-supplying services being removed (i.e.static void
unselectDocuments()
Equivalent tounselectDocuments(false)
static void
unselectDocuments(boolean onlyIfNoUnsavedChanges)
Unselects any documents currently selected in Geneious.static boolean
wouldDocumentNameBeUnique(java.lang.String baseDocumentName)
Deprecated.
-
-
-
Method Detail
-
createAnnotatedPluginDocument
public static AnnotatedPluginDocument createAnnotatedPluginDocument(PluginDocument document)
- Parameters:
document
- the underlying PluginDocument- Returns:
- the newly created AnnotatedPluginDocument
-
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 - ifAnnotatedPluginDocument.getDocument()
is called on the returned AnnotatedPluginDocument it will not be the same PluginDocument instance as the one passed to this method. SeeAnnotatedPluginDocument.getDocument()
for further information.- Parameters:
document
- the underlying PluginDocumentprogressListener
- 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 usecreateAnnotatedPluginDocument(PluginDocument, ProgressListener)
instead.- Parameters:
document
- the underlying PluginDocumenturn
- 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. SeecreateAnnotatedPluginDocument(PluginDocument)
for further details- Parameters:
documents
- the list of underlying PluginDocuments- Returns:
- the newly created AnnotatedPluginDocuments
-
createAnnotatedPluginDocuments
public static java.util.List<AnnotatedPluginDocument> createAnnotatedPluginDocuments(PluginDocument document)
creates a list of AnnotatedPluginDocuments from a single of PluginDocument. SeecreateAnnotatedPluginDocument(PluginDocument)
for further details- Parameters:
document
- the underlying PluginDocument- 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 withwaitForResults = true
as it could potentially take some time. Consider usingaddAndReturnGeneratedDocuments(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 withwaitForResults = true
as it could potentially take some time. Consider usingaddAndReturnGeneratedDocuments(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 modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tableadditionalDocumentsToSelect
- 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 usingaddAndReturnGeneratedDocuments(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 modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tableadditionalDocumentsToSelect
- 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 usingServiceUtilities.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 modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tabledestination
- 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 usingServiceUtilities.getResultsDestination()
operationUniqueId
- Identifier for the operation (DocumentOperation.getUniqueId()
or annotation generator (SequenceAnnotationGenerator.getUniqueId()
used to generate the documents to addparentDocuments
- List of parent documents to use to generate lineage informationprogress
- 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 withwaitForResults = true
as it could potentially take some time.- Parameters:
documents
- List of documents to add; this list doesn't have to be modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tabledestination
- 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 usingServiceUtilities.getResultsDestination()
operationUniqueId
- Identifier for the operation (DocumentOperation.getUniqueId()
or annotation generator (SequenceAnnotationGenerator.getUniqueId()
used to generate the documents to addparentDocuments
- List of parent documents to use to generate lineage informationgiveResultsUniqueNames
- If true, the generated documents will be renamed if a document already exists in the same folder with the input nameprogress
- 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 modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tableadditionalDocumentsToSelect
- 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 usingServiceUtilities.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 modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tableadditionalDocumentsToSelect
- 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 namedestination
- 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 usingServiceUtilities.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 modifiableselectDocumentsImmediately
- If true, the generated documents will be immediately selected in the document tableadditionalDocumentsToSelect
- 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 modifiableselectDocumentsImmediately
- 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 addselectDocumentImmediately
- 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 addselectDocumentImmediately
- 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()
-
getDocumentFromMemoryByURN
public static AnnotatedPluginDocument getDocumentFromMemoryByURN(URN urn)
Returns a reference to the specified document if it is currently in memory. This may include deleted documents, which can be checked for usingAnnotatedPluginDocument.isDeletedFromWritableDatabaseService()
. To get a document either from memory, or load it from a database if it is not already in memory, usegetDocumentByURN(URN)
- Parameters:
urn
- a urn such as that returned fromAnnotatedPluginDocument.getURN()
- Returns:
- the document with this URN if it is currently in memory, or null if it is not currently in memory.
- Since:
- API 4.202210 (Geneious 2022.1.0)
- See Also:
getDocumentByURN(URN)
-
getDocumentByURNThrowingExceptionOnDatabaseError
public static AnnotatedPluginDocument getDocumentByURNThrowingExceptionOnDatabaseError(URN urn) throws DatabaseServiceException
Similar togetDocumentByURN(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 allAnnotatedPluginDocument
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, seeAnnotatedPluginDocument's javadoc
.Unloads a series of documents from memory based on the specified URN filter pattern, allowingAnnotatedPluginDocument
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
- sourceduplicateReferencedDocuments
- 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
- sourceduplicateReferencedDocuments
- 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 namereserveName
- 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 namemustBeUniqueIn
- 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 namemustBeUniqueIn
- 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 selectedsequenceSelection
- 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()
Equivalent tounselectDocuments(false)
-
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
@Deprecated public static AnnotatedPluginDocument createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, boolean assignNewURN) throws XMLSerializationException
Deprecated.usecreateAnnotatedPluginDocument(org.jdom.Element, ElementProvider, boolean)
instead, where the final parameter of null is equivalent to assignNewURN==false orURN.generateUniqueLocalURN()
for assignNewURN==true- Throws:
XMLSerializationException
-
createAnnotatedPluginDocument
@Deprecated public static AnnotatedPluginDocument createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, java.lang.String assignerForUrn) throws XMLSerializationException
Deprecated.- Throws:
XMLSerializationException
- Since:
- API 4.14 (Geneious 5.1)
-
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 byWritableDatabaseService
implementations. The database implementation should maintain aSoftReference
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 toAnnotatedPluginDocument.documentChanged(org.jdom.Element)
on any of the documents it stores in this cache. Finally, the database implementation must callAnnotatedPluginDocument.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 toAnnotatedPluginDocument.toXMLExcludingInternalPluginDocument()
pluginDocumentElementProvider
- an ElementProvider that will load the PluginDocument when it is requiredurnForNewDocument
- 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 inWritableDatabaseService.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 fromAnnotatedPluginDocument.getDocument()
or any other getDocument* methods in AnnotatedPluginDocument. Since PluginDocument passed tocreateAnnotatedPluginDocument(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 usesPluginDocument.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 usingPluginDocument.FILE_DATA_ATTRIBUTE_NAME
the implementation also adds an attribute called "fileSize" toelement
- Parameters:
element
- an element to add appropriate attributes to recording the file name and file sizefile
- the file to add a reference to in the XMLfileMayBeZeroBytesInSize
- 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
-
pluginDocumentFileDataFromXml
public static java.io.File pluginDocumentFileDataFromXml(org.jdom.Element element, boolean mayReturnNullIfNoFileData, boolean fileMayBeZeroBytesInSize) throws XMLSerializationException
Deserializes the name of a file serialized usingpluginDocumentFileDataToXml(org.jdom.Element, java.io.File, boolean)
checking for corruption such as the file disappearing, changing in size or reducing to 0 bytes in size. This may also be used on elements that contain an attribute calledPluginDocument.FILE_DATA_ATTRIBUTE_NAME
in which case it will be unable to detect files that have changed in size.- Parameters:
element
- the element that contains the file attributes. This should be the same element in the XML hierarchy as that passed topluginDocumentFileDataToXml(org.jdom.Element, java.io.File, boolean)
fileMayBeZeroBytesInSize
- for serialization performed usingpluginDocumentFileDataToXml(org.jdom.Element, java.io.File, boolean)
this parameter is ignored since the file size was stored then. This parameter is intended for use with files serialized in earlier versions of GeneiousmayReturnNullIfNoFileData
- true if this method may return null if the element does not contain a PluginDocument.FILE_DATA_ATTRIBUTE_NAME attribute. If this is false and the attribute isn't present, then an XMLSerializationException will be thrown- Returns:
- the file or null if mayReturnNullIfNoFileData is true and the element does not have an
PluginDocument.FILE_DATA_ATTRIBUTE_NAME
attribute. - Throws:
XMLSerializationException
- if the file referred to has become corrupt.- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
pluginDocumentFileDataFromXml(org.jdom.Element, boolean, boolean)
,PluginDocument.FILE_DATA_ATTRIBUTE_NAME
-
-