com.biomatters.geneious.publicapi.documents

Class DocumentUtilities

java.lang.Object

com.biomatters.geneious.publicapi.documents.DocumentUtilities

public final class DocumentUtilities
extends Object

Some core functionality provided by Geneious for adding and managing documents.

Method Summary

Methods

Modifier and Type	Method and Description
static List<AnnotatedPluginDocument>	addAndReturnGeneratedDocuments(List<AnnotatedPluginDocument> documents, boolean selectDocumentsImmediately, List<AnnotatedPluginDocument> additionalDocumentsToSelect) Adds a list of documents that have just been generated to Geneious so that appear in the users local database and returns the newly added documents.
static List<AnnotatedPluginDocument>	addAndReturnGeneratedDocuments(List<AnnotatedPluginDocument> documents, boolean selectDocumentsImmediately, List<AnnotatedPluginDocument> additionalDocumentsToSelect, WritableDatabaseService destination) Adds a list of documents that have just been generated to Geneious so that appear in the users local database and so that they become visible in the document table.
static void	addGeneratedDocument(AnnotatedPluginDocument document, boolean selectDocumentImmediately) Adds a newly generated document that will appear in the users local database.
static void	addGeneratedDocuments(List<AnnotatedPluginDocument> documents, boolean selectDocumentsImmediately) Adds newly generated documents that will appear in the users local database.
static void	addGeneratedDocuments(List<AnnotatedPluginDocument> documents, boolean selectDocumentsImmediately, List<AnnotatedPluginDocument> additionalDocumentsToSelect) Adds a list of documents that have just been generated to Geneious so that appear in the users local database and so that they become visible in the document table.
static void	addGeneratedDocuments(List<AnnotatedPluginDocument> documents, boolean selectDocumentsImmediately, List<AnnotatedPluginDocument> additionalDocumentsToSelect, WritableDatabaseService destination) Adds a list of documents that have just been generated to Geneious so that appear in the users 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 users local database.
static void	addGeneratedPluginDocuments(List<PluginDocument> documents, boolean selectDocumentsImmediately) Adds newly generated documents that will appear in the users local database.
static AnnotatedPluginDocument	createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, boolean assignNewURN) Deprecated. use createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, boolean) instead, where the final parameter of null is equivalent to assignNewURN==false or URN.generateUniqueLocalURN() for assignNewURN==true
static AnnotatedPluginDocument	createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, String assignerForUrn) Deprecated. use createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN) instead.
static AnnotatedPluginDocument	createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement, ElementProvider pluginDocumentElementProvider, URN urnForNewDocument) Creates an AnnotatedPluginDocument without the internal PluginDocument included.
static AnnotatedPluginDocument	createAnnotatedPluginDocument(PluginDocument document) Equivalent to createAnnotatedPluginDocument(document,ProgressListener.EMPTY)
static AnnotatedPluginDocument	createAnnotatedPluginDocument(PluginDocument document, ProgressListener progressListener) Creates an AnnotatedPluginDocument from a PluginDocument.
static List<AnnotatedPluginDocument>	createAnnotatedPluginDocuments(List<? extends PluginDocument> documents) Creates a list of AnnotatedPluginDocuments from a list of PluginDocuments.
static List<AnnotatedPluginDocument>	createAnnotatedPluginDocuments(PluginDocument document) creates a list of AnnotatedPluginDocuments from a single of PluginDocument.
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 List<DocumentField>	getAllDisplayableFields() Gets a list of all the displayable fields on any document in the user's database
static 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 List<AnnotatedPluginDocument>	getSelectedDocuments() Gets the currently selected documents in the Geneious document table.
static String	getUniqueNameForDocument(String baseDocumentName) Deprecated. use getUniqueNameForDocument(String, WritableDatabaseService, Collection)
static String	getUniqueNameForDocument(String baseDocumentName, boolean reserveName) Deprecated. use getUniqueNameForDocument(String, WritableDatabaseService, Collection)
static String	getUniqueNameForDocument(String baseDocumentName, WritableDatabaseService mustBeUniqueIn) Generate a document name that is unique to the given folder, based on the original name passed in.
static String	getUniqueNameForDocument(String baseDocumentName, WritableDatabaseService mustBeUniqueIn, Collection<String> mustNotBe) Generate a document name that is unique to the given folder, based on the original name passed in.
static void	openDocumentsInNewWindow(List<AnnotatedPluginDocument> documents) Opens a new Geneious window and displays these documents in all available document viewers that match these documents.
static File	pluginDocumentFileDataFromXml(org.jdom.Element element, boolean mayReturnNullIfNoFileData, boolean fileMayBeZeroBytesInSize) Deserializes the name of a file serialized using pluginDocumentFileDataToXml(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, 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(List<URN> urns) Changes the currently selected documents in the Geneious document table.
static boolean	selectDocuments(List<URN> urns, SequenceSelection sequenceSelection) Changes the currently selected documents in the Geneious document table and selects a region within them.
static boolean	showSaveAsDialog(JComponent viewerComponent) Shows the "Save As" dialog (i.e.
static void	unselectDocuments() Unselects any documents currently selected in Geneious.
static boolean	wouldDocumentNameBeUnique(String baseDocumentName) Deprecated.

Methods inherited from class java.lang.Object

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

Method Detail

createAnnotatedPluginDocument

public static AnnotatedPluginDocument createAnnotatedPluginDocument(PluginDocument document)

Equivalent to createAnnotatedPluginDocument(document,ProgressListener.EMPTY)

Parameters:

document - the underlying PluginDocument

Returns:

the newly created AnnotatedPluginDocument

createAnnotatedPluginDocument

public static AnnotatedPluginDocument createAnnotatedPluginDocument(PluginDocument document,
                                                    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.

createAnnotatedPluginDocuments

public static List<AnnotatedPluginDocument> createAnnotatedPluginDocuments(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

createAnnotatedPluginDocuments

public static List<AnnotatedPluginDocument> createAnnotatedPluginDocuments(PluginDocument document)

creates a list of AnnotatedPluginDocuments from a single of PluginDocument. See createAnnotatedPluginDocument(PluginDocument) for further details

Parameters:

document - the underlying PluginDocument

Returns:

the newly created AnnotatedPluginDocuments

addGeneratedDocuments

public static void addGeneratedDocuments(List<AnnotatedPluginDocument> documents,
                         boolean selectDocumentsImmediately)

Adds newly generated documents that will appear in the users local database. 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 - 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(List<AnnotatedPluginDocument> documents,
                         boolean selectDocumentsImmediately,
                         List<AnnotatedPluginDocument> additionalDocumentsToSelect)

Adds a list of documents that have just been generated to Geneious so that appear in the users 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.

See Also:

addAndReturnGeneratedDocuments(java.util.List, boolean, java.util.List)

addGeneratedDocuments

public static void addGeneratedDocuments(List<AnnotatedPluginDocument> documents,
                         boolean selectDocumentsImmediately,
                         List<AnnotatedPluginDocument> additionalDocumentsToSelect,
                         WritableDatabaseService destination)

Adds a list of documents that have just been generated to Geneious so that appear in the users 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)

addAndReturnGeneratedDocuments

public static List<AnnotatedPluginDocument> addAndReturnGeneratedDocuments(List<AnnotatedPluginDocument> documents,
                                                           boolean selectDocumentsImmediately,
                                                           List<AnnotatedPluginDocument> additionalDocumentsToSelect,
                                                           WritableDatabaseService destination)

Adds a list of documents that have just been generated to Geneious so that appear in the users 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()

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 List<AnnotatedPluginDocument> addAndReturnGeneratedDocuments(List<AnnotatedPluginDocument> documents,
                                                           boolean selectDocumentsImmediately,
                                                           List<AnnotatedPluginDocument> additionalDocumentsToSelect)

Adds a list of documents that have just been generated to Geneious so that appear in the users 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(List<PluginDocument> documents,
                               boolean selectDocumentsImmediately)

Adds newly generated documents that will appear in the users 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 users 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 users 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

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 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:

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

public static boolean wouldDocumentNameBeUnique(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

public static String getUniqueNameForDocument(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

public static String getUniqueNameForDocument(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 String getUniqueNameForDocument(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 String getUniqueNameForDocument(String baseDocumentName,
                              WritableDatabaseService mustBeUniqueIn,
                              Collection<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(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(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()

Unselects any documents currently selected in Geneious. This method must be called from the Swing thread.

getSelectedDocuments

public static 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. use createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, boolean) instead, where the final parameter of null is equivalent to assignNewURN==false or URN.generateUniqueLocalURN() for assignNewURN==true

Throws:

XMLSerializationException

createAnnotatedPluginDocument

@Deprecated
public static AnnotatedPluginDocument createAnnotatedPluginDocument(org.jdom.Element annotatedDocumentElement,
                                                               ElementProvider pluginDocumentElementProvider,
                                                               String assignerForUrn)
                                                             throws XMLSerializationException

Deprecated. use createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN) instead.

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

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. Generally a WritableDatabaseService will use null here when loading documents and a non-null value 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(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:

NullPointerException - if pluginDocument is null.

Since:

API 4.14 (Geneious 5.1)

showSaveAsDialog

public static boolean showSaveAsDialog(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 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,
                               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

pluginDocumentFileDataFromXml

public static File pluginDocumentFileDataFromXml(org.jdom.Element element,
                                 boolean mayReturnNullIfNoFileData,
                                 boolean fileMayBeZeroBytesInSize)
                                          throws XMLSerializationException

Deserializes the name of a file serialized using pluginDocumentFileDataToXml(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 called PluginDocument.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 to pluginDocumentFileDataToXml(org.jdom.Element, java.io.File, boolean)

fileMayBeZeroBytesInSize - for serialization performed using pluginDocumentFileDataToXml(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 Geneious

mayReturnNullIfNoFileData - 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