Class AnnotatedPluginDocument
- java.lang.Object
-
- com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument
-
- All Implemented Interfaces:
XMLSerializable
public abstract class AnnotatedPluginDocument extends java.lang.Object implements XMLSerializable
An AnnotatedPluginDocument is a wrapper document that wraps anyPluginDocument
(such as aSequenceDocument
orSequenceAlignmentDocument
orTreeDocument
) and adds extra information and provides extra functionality that the underlying PluginDocument need not concern itself with, such as allowing the user to rename the document or edit any fields displayed in the document table. To access the wrapped PluginDocument, usegetDocument()
. In many situations (such as inside aDocumentOperation
where you have provided aDocumentSelectionSignature
) you can cast the returned PluginDocument to the expected type (such as a SequenceDocument or SequenceAlignmentDocument or TreeDocument). An importer or database service creates aPluginDocument
. The core geneious system adds generic extra value on top of it such as user annotations, editable fields and URN handling. Those features are accessed via an AnnotatedPluginDocument. Plugin classes must never implement this. Instead, callDocumentUtilities.createAnnotatedPluginDocument(PluginDocument)
. Commonly used methods of AnnotatedPluginDocument includegetDocument()
to get the wrapped PluginDocumentgetName()
to get the name of the documentgetDisplayableFields()
to get a list of all fields that are displayable to the usergetFieldValue(DocumentField)
orgetFieldValue(String)
to get field values associated with this document, including field values cached from the wrapped PluginDocument without needing to load the PluginDocumentgetURN()
to get the unique identifier for this document that is useful in conjunction withDocumentUtilities.getDocumentByURN(URN)
getDatabase()
to get the database folder the document is insaveDocument()
to save changes made to the wrapped PluginDocument. This also saves changes made to the AnnotatedPluginDocument itselfsave()
to save changes made to just the AnnotatedPluginDocument (this does not save the wrapped PluginDocument)batchSave(Collection, boolean, ProgressListener)
to save changes to a number of documents in bulk
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
AnnotatedPluginDocument.ActiveLinkSaveBehaviour
Gives an action to take whensaveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument.ActiveLinkSaveBehaviour, jebl.util.ProgressListener)
is called.static interface
AnnotatedPluginDocument.DocumentNotes
Provides access to all theDocumentNote
s on anAnnotatedPluginDocument
-
Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
TEMPORARY_FIELD_KEY_ANNOTATED_DOCUMENT_LOCATION
Used by databases withsetTemporaryFieldValue(String,Object)
for providing the user with information about the location of the AnnotatedPluginDocument.static java.lang.String
TEMPORARY_FIELD_KEY_PLUGIN_DOCUMENT_LOCATION
Used by databases withsetTemporaryFieldValue(String,Object)
for providing the user with information about the location of the PluginDocument.-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
ROOT_ELEMENT_NAME
-
-
Constructor Summary
Constructors Constructor Description AnnotatedPluginDocument()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description abstract void
addDescendantOperationRecord(URN operationRecordUrn)
Adds a record of an operation where this document was an input document to the operation.abstract void
additionalXmlChanged()
Notifies the document that additional XML retrieved already may have changed.abstract void
addWeakReferenceDocumentListener(DocumentListener listener)
Add a listener to be notified when the document changes.static void
batchSave(java.util.Collection<AnnotatedPluginDocument> documentsToSave, boolean updateModifiedDate, jebl.util.ProgressListener progressListener)
Saves the summary information for a number of documents.abstract void
changeReferencedDocumentURNs(java.util.Map<URN,URN> URNsToChange)
Changes the URNs of any documents that the internal PluginDocument references.void
clearInternalDocumentCache()
Clears the internal plugin document cache.abstract java.lang.String
confirmDocumentValid()
Confirms this document is valid.abstract void
documentChanged(org.jdom.Element newElement)
Replaces the contents of this document.abstract java.util.Map<java.lang.String,ElementProvider>
getAdditionalXml(boolean isPerUser, jebl.util.ProgressListener progressListener)
Get all additional XML for this document for every key.abstract org.jdom.Element
getAdditionalXml(java.lang.String key, boolean isPerUser)
Get additional data in the form of XML which has been stored associated with this document usingsetAdditionalXml(String,boolean,org.jdom.Element)
.abstract java.util.Map<java.lang.String,ElementProvider>
getAdditionalXml(java.util.List<java.lang.String> keys, boolean isPerUser, jebl.util.ProgressListener progressListener)
Get additional data in the form of XML which has been stored associated with this document usingsetAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener)
orsetAdditionalXml(String, boolean, org.jdom.Element)
.abstract java.util.Date
getCreationDate()
Get the date this document was created.abstract DatabaseService
getDatabase()
Get the database folder this document is in, or null if it is not in a database.abstract java.util.List<URN>
getDescendantOperationRecords()
abstract java.util.List<DocumentField>
getDisplayableFields()
Get a list of all displayable fields available on the PluginDocument contained within this AnnotatedPluginDocument.abstract PluginDocument
getDocument()
Returns the underlying document which is wrapped inside this AnnotatedPluginDocument.abstract java.lang.Class<? extends PluginDocument>
getDocumentClass()
Get the class of the underlying document without loading it.abstract DocumentHistory
getDocumentHistory()
Get the instance ofDocumentHistory
for this document.abstract AnnotatedPluginDocument.DocumentNotes
getDocumentNotes(boolean isForEditing)
Changes made to the notes on a document will not be saved to the document unlessAnnotatedPluginDocument.DocumentNotes.saveNotes()
is called after modification.abstract PluginDocument
getDocumentOrCrash()
A convenience method that callsgetDocumentOrThrow(RuntimeException.class)
.abstract PluginDocument
getDocumentOrNull()
A convenience method that callsgetDocumentOrThrow(true,ProgressListener.EMPTY,...)
but instead of throwing an exception if the document cannot be loaded, returns null.abstract <T extends java.lang.Exception>
PluginDocumentgetDocumentOrThrow(boolean warnIfCantLoad, jebl.util.ProgressListener progressListener, java.lang.Class<T> exceptionClass)
Returns the underlying document.abstract <T extends java.lang.Exception>
PluginDocumentgetDocumentOrThrow(java.lang.Class<T> exceptionClass)
Equivalent to callinggetDocumentOrThrow(true,ProgressListener.EMPTY,exceptionClass)
abstract DocumentType
getDocumentType()
abstract java.util.List<DocumentField>
getExtendedDisplayableFields()
Gets a list of all displayable document fields, which includes all those returned bygetDisplayableFields()
as well as the document name, description, creation date and all note fields withDocumentField.getCode()
s of the form "noteCode.fieldCode".abstract java.lang.Object
getFieldValue(DocumentField field)
Get value of a field - either a displayable field or a hidden field.abstract java.lang.Object
getFieldValue(java.lang.String fieldCode)
Retrieves the value of a displayable or hidden field, given the field'scode
.Icons
getIcons()
abstract int
getInternalPluginDocumentRevisionNumber()
Get a revision number associated with the internal PluginDocument.abstract java.lang.String
getName()
Name of document.abstract URN
getParentOperationRecord()
abstract org.jdom.Element
getPluginDocumentXml(jebl.util.ProgressListener progressListener)
Get the XML of the internal PluginDocument.abstract java.util.List<java.lang.String>
getPotentialAdditionalXmlKeys(boolean isPerUser)
abstract java.util.Set<URN>
getReferencedDocuments()
Get a set of document URNs referred to by this document.abstract int
getRevisionNumber()
Get a revision number associated with this document.java.util.Map<DocumentField,java.util.List<java.lang.Object>>
getSearchableFieldsAndValues()
Equivalent togetSearchableFieldsAndValues(ProgressListener.EMPTY)
abstract java.util.Map<DocumentField,java.util.List<java.lang.Object>>
getSearchableFieldsAndValues(jebl.util.ProgressListener progressListener)
Gets a set of fields and associated values that are indexed for search purposes.abstract java.util.Map<DocumentField,java.util.List<java.lang.Object>>
getSearchableFieldsAndValuesForAnnotatedDocumentOnly()
The same asgetSearchableFieldsAndValues()
except that only fields and values for the annotated document are returned.abstract long
getSize()
Get the uncompressed size in bytes of this documentabstract java.util.Set<URN>
getStronglyReferencedDocuments()
Get a set of document URNs strongly referred to by this document.abstract java.lang.String
getSummary()
Deprecated.usegetFieldValue(DocumentField)
withDocumentField.DESCRIPTION_FIELD
to get the Description for the document.abstract java.lang.Object
getTemporaryFieldValue(java.lang.String fieldName)
This is used for retrieving temporary in memory only information about this document.abstract URN
getURN()
A unique URN which serves as a primary database key for this document.abstract UrnWithRevisionNumber
getUrnWithInternalPluginDocumentRevisionNumber()
abstract UrnWithRevisionNumber
getUrnWithRevisionNumber()
abstract java.util.Set<URN>
getWeaklyReferencedDocuments()
Get a set of document URNs weakly referred to by this document.abstract boolean
isDeletedFromWritableDatabaseService()
Returns true if this document was originally in aWritableDatabaseService
but has now been deleted.abstract boolean
isFormatExtendedInFutureVersion()
abstract boolean
isInLocalRepository()
Returns true if this document is in the user's persistent storage repository (a WritableDatabaseService - either a local or shared database) or false if it is an in memory only document.boolean
isPluginDocumentInstanceOf(java.lang.Class<? extends PluginDocument> cl)
boolean
isReadOnly()
abstract boolean
isUnread()
Returns true if document retrieved by agent and not yet seen by user.abstract boolean
removeDescendantOperationRecord(URN operationRecordUrn)
Removes a descendant operation record returned fromgetDescendantOperationRecords()
.abstract void
removeWeakReferenceDocumentListener(DocumentListener listener)
Remove a listener previously added usingaddWeakReferenceDocumentListener(DocumentListener)
.abstract void
save()
Saves the document summary to the database.abstract void
save(boolean updateModifiedDate)
Saves the document summary to the database.abstract void
saveDocument()
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database.abstract boolean
saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour, boolean updateModifiedDate, jebl.util.ProgressListener progressListener)
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database.boolean
saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour, jebl.util.ProgressListener progressListener)
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database.abstract void
setAdditionalXml(java.lang.String key, boolean isPerUser, org.jdom.Element element)
Stores additional data in the form of XML which is directly associated with this document.abstract void
setAdditionalXml(java.util.Map<java.lang.String,ElementProvider> elementsToSave, boolean isPerUser, jebl.util.ProgressListener progressListener)
Stores additional data in the form of XML which is directly associated with this document.abstract void
setDatabase(DatabaseService location)
Set the database folder that this document was generated from.abstract void
setFieldValue(DocumentField field, java.lang.Object value)
Set the value of field which is visible in the user interface.abstract void
setHiddenFieldValue(DocumentField field, java.lang.Object value)
Set the value of field which is not visible in the user interface.abstract void
setName(java.lang.String name)
Set document name.abstract void
setParentOperationRecord(URN operationRecordUrn)
Sets a record of the operation that generated this document.void
setPluginDocumentElementProvider(ElementProvider elementProvider, boolean checkAvailableMemoryBeforeLoadingElement)
For a document created usingDocumentUtilities.createAnnotatedPluginDocument(Element, ElementProvider, URN)
, allows changing the ElementProvider used to load the PluginDocument XML.abstract void
setSourceService(DatabaseService sourceService)
Add an annotation to the document which tells the program which service to download the full document from if the PluginDocument is a summary (implementsSummaryDocument
)abstract void
setSummary(java.lang.String summary)
Deprecated.abstract void
setTemporaryFieldValue(java.lang.String fieldName, java.lang.Object value)
This is used for storing temporary in memory only information about this document.abstract boolean
setUnread(boolean unread)
Set read/unread (false/true) status.abstract AnnotatedPluginDocument
toSummaryDocument()
Generates a new AnnotatedPluginDocument that is identical to this document, except that the internal PluginDocument to a lightweight AnySummaryDocument.org.jdom.Element
toXMLExcludingInternalPluginDocument()
Equivalent to callingtoXMLExcludingInternalPluginDocument(Geneious#getMajorVersion())
abstract org.jdom.Element
toXMLExcludingInternalPluginDocument(Geneious.MajorVersion majorVersion)
converts this AnnotatedPluginDocument to a single XML element.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
fromXML, toXML
-
-
-
-
Field Detail
-
TEMPORARY_FIELD_KEY_ANNOTATED_DOCUMENT_LOCATION
public static final java.lang.String TEMPORARY_FIELD_KEY_ANNOTATED_DOCUMENT_LOCATION
Used by databases withsetTemporaryFieldValue(String,Object)
for providing the user with information about the location of the AnnotatedPluginDocument. For example, this might be a file name.- See Also:
- Constant Field Values
-
TEMPORARY_FIELD_KEY_PLUGIN_DOCUMENT_LOCATION
public static final java.lang.String TEMPORARY_FIELD_KEY_PLUGIN_DOCUMENT_LOCATION
Used by databases withsetTemporaryFieldValue(String,Object)
for providing the user with information about the location of the PluginDocument. For example, this might be a file name.- See Also:
- Constant Field Values
-
-
Method Detail
-
getName
public abstract java.lang.String getName()
Name of document. The one given by the user (when she specifies one), or the one assigned by the service. may be empty (null).- Returns:
- Name of document.
-
getURN
public abstract URN getURN()
A unique URN which serves as a primary database key for this document. This can be used to store a reference to this document, so it can be retrieved later using methods such asDocumentUtilities.getDocumentByURN(URN)
.- Returns:
- unique URN for this document, never null
- See Also:
URN
-
getCreationDate
public abstract java.util.Date getCreationDate()
Get the date this document was created. This will either be the same asgetDocumentOrNull()
.creationDate()
or if that returned null, this method will return the date the PluginDocument was first instantiated.- Returns:
- Date this document was created. Will not be null.
-
getSummary
@Deprecated public abstract java.lang.String getSummary()
Deprecated.usegetFieldValue(DocumentField)
withDocumentField.DESCRIPTION_FIELD
to get the Description for the document.- Returns:
- A short summary of the document.
- See Also:
PluginDocument.getDescription()
-
getDisplayableFields
public abstract java.util.List<DocumentField> getDisplayableFields()
Get a list of all displayable fields available on the PluginDocument contained within this AnnotatedPluginDocument. CallgetFieldValue(java.lang.String)
to get the value.- Returns:
- a list of all displayable fields available on the PluginDocument contained within this AnnotatedPluginDocument.
- See Also:
getExtendedDisplayableFields()
-
getExtendedDisplayableFields
public abstract java.util.List<DocumentField> getExtendedDisplayableFields()
Gets a list of all displayable document fields, which includes all those returned bygetDisplayableFields()
as well as the document name, description, creation date and all note fields withDocumentField.getCode()
s of the form "noteCode.fieldCode". The values of any fields returned from this method can be retrieved usinggetFieldValue(String)
.- Returns:
- a list of all displayable document fields
- See Also:
getDisplayableFields()
-
getFieldValue
public abstract java.lang.Object getFieldValue(java.lang.String fieldCode)
Retrieves the value of a displayable or hidden field, given the field'scode
. Can be used to get the value of any field returned fromgetExtendedDisplayableFields()
, including document note fields.- Parameters:
fieldCode
-code
of the field to access. A field with this code must either be among thedisplayable fields
, or must have been assigned ahidden
value.- Returns:
- value of the specified field or null if the field does not exist.
-
getFieldValue
public abstract java.lang.Object getFieldValue(DocumentField field)
Get value of a field - either a displayable field or a hidden field. Can be used to get the value of any field returned fromgetExtendedDisplayableFields()
, including document note fields.- Parameters:
field
- field as given bygetDisplayableFields()
orsetHiddenFieldValue(DocumentField,Object)
- Returns:
- value of the specified field or null if the field does not exist.
-
setHiddenFieldValue
public abstract void setHiddenFieldValue(DocumentField field, java.lang.Object value)
Set the value of field which is not visible in the user interface. This will add the field if not already existing (by code) or replace an existing one.save()
must be called afterwards to save the changes to the database.- Parameters:
field
- to setvalue
- of field. The class of value must either implementXMLSerializable
or be a simple type that Geneious knows how to serialize (e.g. Integer, Double, Date, String) or a List or Map of any of these types.
-
setFieldValue
public abstract void setFieldValue(DocumentField field, java.lang.Object value)
Set the value of field which is visible in the user interface. This will add the field if not already existing (by code) or replace an existing one. Can be used to set the value of any field returned fromgetExtendedDisplayableFields()
, including document note fields.save()
must be called afterwards to save the changes to the database. UsesetHiddenFieldValue(DocumentField, Object)
if the field should not be visible to the user- Parameters:
field
- to setvalue
- of field
-
setSummary
@Deprecated public abstract void setSummary(java.lang.String summary)
Deprecated.Set document summary- Parameters:
summary
- to set
-
setName
public abstract void setName(java.lang.String name)
Set document name.save()
must be called afterwards to save the changes to the database.- Parameters:
name
- to set
-
getReferencedDocuments
public abstract java.util.Set<URN> getReferencedDocuments()
Get a set of document URNs referred to by this document. This includes both weakly and strongly referenced documents (seegetStronglyReferencedDocuments()
andgetWeaklyReferencedDocuments()
Usually used with sequence alignment documents that point back to the original sequences. Also used with parent and descendant operation records. Documents may have references to each other, but strong references are always in a single direction so that there will never by a cycle of strong references. For example an operation record weakly references both it's parent and descendant documents. The parent document weakly references the operation record. The child documents strongly reference the operation record.- Returns:
- URNs of referenced documents
- See Also:
getStronglyReferencedDocuments()
,getWeaklyReferencedDocuments()
-
getStronglyReferencedDocuments
public abstract java.util.Set<URN> getStronglyReferencedDocuments()
Get a set of document URNs strongly referred to by this document. SeeURN.toXML(String)
for a discussion on strong/weak document references. The set of strongly referenced documents includes a document's parent operation record if any (seegetParentOperationRecord()
)- Returns:
- URNs of referenced documents
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getReferencedDocuments()
,getWeaklyReferencedDocuments()
-
getWeaklyReferencedDocuments
public abstract java.util.Set<URN> getWeaklyReferencedDocuments()
Get a set of document URNs weakly referred to by this document. SeeURN.toXML(String)
for a discussion on strong/weak document references. The set of weakly referenced documents includes all the document's descendant operation records if any (seegetDescendantOperationRecords()
)- Returns:
- URNs of referenced documents
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getReferencedDocuments()
,getStronglyReferencedDocuments()
-
isUnread
public abstract boolean isUnread()
Returns true if document retrieved by agent and not yet seen by user.- Returns:
- true if document retrieved by agent and not yet seen by user
-
setUnread
public abstract boolean setUnread(boolean unread)
Set read/unread (false/true) status. A document may be unread if retrieved by agent and not yet seen by user, or generated and not immediately viewed. It is not necessary to callsave()
afterwards (it is done automatically)- Parameters:
unread
- status to set- Returns:
- true if unread status has changed, false otherwise.
-
getDocumentType
public abstract DocumentType getDocumentType()
- Returns:
- the type of document this
AnnotatedPluginDocument
contains. - Since:
- API 4.1000 (Geneious 10.0.0)
-
getDocumentNotes
public abstract AnnotatedPluginDocument.DocumentNotes getDocumentNotes(boolean isForEditing)
Changes made to the notes on a document will not be saved to the document unlessAnnotatedPluginDocument.DocumentNotes.saveNotes()
is called after modification.- Parameters:
isForEditing
- if any of these notes will be changed usingAnnotatedPluginDocument.DocumentNotes.setNote(DocumentNote)
,AnnotatedPluginDocument.DocumentNotes.removeNote(String)
orAnnotatedPluginDocument.DocumentNotes.saveNotes()
- Returns:
- all notes on this document
-
getDocumentHistory
public abstract DocumentHistory getDocumentHistory() throws java.io.IOException
Get the instance ofDocumentHistory
for this document. Most plugins will use this to add aDocumentHistoryEntry
to provide details of changes they make to the document.- Returns:
- history for this document
- Throws:
java.io.IOException
- if history cannot be retrieved for this document
-
getDocumentOrThrow
public abstract <T extends java.lang.Exception> PluginDocument getDocumentOrThrow(boolean warnIfCantLoad, jebl.util.ProgressListener progressListener, java.lang.Class<T> exceptionClass) throws T extends java.lang.Exception
Returns the underlying document. Calling this will cause the entire document to be loaded from disk into memory if it is not already loaded. This can be very time-consuming for large documents or large numbers of documents. If you just wish to check the class of the document then usegetDocumentClass()
which does not cause loading of the document. Note: The returned document will not be the class of the actual underlying document this AnnotatedPluginDocument wraps. Instead, it will be a proxy class which extends the original underlying document in order to override the getName() method.- Parameters:
warnIfCantLoad
- True so that if the document can not be loaded (for example due to an IOException), then the user will also be notified the document could not be loaded. False means the user will not be notified. In both cases this method will throw an exception of typeexceptionClass
if the document can not be loaded.progressListener
- used to report progress while loading the document. Must not be null, but may beProgressListener.EMPTY
exceptionClass
- If the document cannot be loaded an exception of this class will be thrown. Must not be null.- Returns:
- the underlying document. Will not be null.
- Throws:
T
- exception of classexceptionClass
if the document could not be loadedT extends java.lang.Exception
- See Also:
getDocument()
,getDocumentClass()
,getDocumentOrNull()
,getDocumentOrCrash()
,getDocumentOrThrow(Class)
-
getDocumentOrThrow
public abstract <T extends java.lang.Exception> PluginDocument getDocumentOrThrow(java.lang.Class<T> exceptionClass) throws T extends java.lang.Exception
Equivalent to callinggetDocumentOrThrow(true,ProgressListener.EMPTY,exceptionClass)
- Parameters:
exceptionClass
- If the document cannot be loaded an exception of this class will be thrown. Must not be null.- Returns:
- the underlying document. Will not be null.
- Throws:
T
- exception of classexceptionClass
if the document could not be loadedT extends java.lang.Exception
- See Also:
getDocument()
,getDocumentClass()
,getDocumentOrNull()
,getDocumentOrCrash()
,getDocumentOrThrow(boolean,jebl.util.ProgressListener,Class)
-
getDocumentOrNull
public abstract PluginDocument getDocumentOrNull()
A convenience method that callsgetDocumentOrThrow(true,ProgressListener.EMPTY,...)
but instead of throwing an exception if the document cannot be loaded, returns null. DocumentViewerFactories can safely assume this method will not return null as Geneious loads the documents prior to displaying them in a viewer, so they do not need to worry about document load failures. DocumentOperations should instead usegetDocument()
which throws a DocumentOperationException meaning they do not need to worry about document load failures.- Returns:
- the underlying document or null if the document can not be loaded (for example due to an IOException or there is insufficient free memory - the user will also be notified the document could not be loaded)
-
getDocument
public abstract PluginDocument getDocument() throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
Returns the underlying document which is wrapped inside this AnnotatedPluginDocument. Calling this will cause the entire document to be loaded from disk into memory if it is not already loaded. This can be very time-consuming for large documents or large numbers of documents. If you just wish to check the class of the document then usegetDocumentClass()
orisPluginDocumentInstanceOf(Class)
which do not cause loading of the document. This method is equivalent togetDocumentOrThrow(true, ProgressListener.EMPTY, DocumentOperationException.class
Note: The returned document will not be the class of the actual underlying document this AnnotatedPluginDocument wraps. Instead it will be a proxy class which extends the original underlying document in order to override the getName() method.- Returns:
- the underlying document. Will not be null.
- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if the document cannot be loaded (for example an IOException reading from disk or loading over a network or there is insufficient free memory)- See Also:
getDocumentClass()
,getDocumentOrNull()
,getDocumentOrCrash()
,getDocumentOrThrow(Class)
,getDocumentOrThrow(boolean, jebl.util.ProgressListener, Class)
,isPluginDocumentInstanceOf(Class)
-
getDocumentOrCrash
public abstract PluginDocument getDocumentOrCrash()
A convenience method that callsgetDocumentOrThrow(RuntimeException.class)
. i.e. loads the document or crashes the program if it cannot be loaded. This should only be used in situations where we know the document is already loaded into memory. For example in a document viewer where Geneious loads all internal documents before invoking the document viewer.- Returns:
- the underlying document. Will not be null.
- See Also:
getDocument()
,getDocumentClass()
,getDocumentOrNull()
,getDocumentOrThrow(Class)
,getDocumentOrThrow(boolean,jebl.util.ProgressListener,Class)
-
getDocumentClass
public abstract java.lang.Class<? extends PluginDocument> getDocumentClass()
Get the class of the underlying document without loading it.- Returns:
- the class of the underlying document
- See Also:
getDocument()
,getDocumentOrNull()
,getDocumentOrCrash()
,getDocumentOrThrow(Class)
,getDocumentOrThrow(boolean,jebl.util.ProgressListener,Class)
,isPluginDocumentInstanceOf(Class)
-
confirmDocumentValid
public abstract java.lang.String confirmDocumentValid()
Confirms this document is valid. Checks consist of:- That a sequence document contains valid residues.
- That an alignment has sequences of identical lengths and valid residues.
- That SameTaxaTreesDocuments have trees with the same taxa.
WritableDatabaseService.addDocumentCopy(AnnotatedPluginDocument, jebl.util.ProgressListener)
and during import.- Returns:
- a message describing the reason the document is invalid or null if the document is fine.
- Since:
- API 4.14 (Geneious 5.1)
-
saveDocument
public abstract void saveDocument()
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database. It is not necessary to call this method when the document is first created. Rather, it should only be used when the internal PluginDocument has been changed at a later date. To save only changes to the AnnotatedPluginDocument, usesave()
instead. WARNING - AnnotatedPluginDocument only stores aSoftReference
to the document returned fromgetDocument()
. Therefore if you modify a PluginDocument and call saveDocument() without further referencing the PluginDocument it could be garbage collected prior to the save and the changes lost. To prevent this happening, you should do something such asPluginDocument#hashCode()
immediately after calling saveDocument()- See Also:
save()
-
saveDocument
public boolean saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour, jebl.util.ProgressListener progressListener)
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database. It is not necessary to call this method when the document is first created. Rather, it should only be used when the internal PluginDocument has been changed at a later date. To save only changes to the AnnotatedPluginDocument, usesave()
instead.- Parameters:
activeLinkSaveBehaviour
- the action to undertake if this document has active links to its descendants (seeAnnotatedPluginDocument.ActiveLinkSaveBehaviour
).progressListener
- for reporting progress and allowing the save to be canceled.- Returns:
- true if the document was successfully saved. If this returns false, then the user will already have been notified with a dialog indicating the reason the save failed.
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
save()
-
saveDocument
public abstract boolean saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour, boolean updateModifiedDate, jebl.util.ProgressListener progressListener)
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database. It is not necessary to call this method when the document is first created. Rather, it should only be used when the internal PluginDocument has been changed at a later date. To save only changes to the AnnotatedPluginDocument, usesave()
instead.- Parameters:
activeLinkSaveBehaviour
- the action to undertake if this document has active links to its descendants (seeAnnotatedPluginDocument.ActiveLinkSaveBehaviour
).progressListener
- for reporting progress and allowing the save to be canceled.updateModifiedDate
- true to set the document's modified date to now, false to leave the modified date as is.- Returns:
- true if the document was successfully saved. If this returns false, then the user will already have been notified with a dialog indicating the reason the save failed.
- Since:
- API 4.800 (Geneious 8.0.0)
- See Also:
save()
-
save
public abstract void save()
Saves the document summary to the database. Does not save changes to the internal PluginDocument. Rather, this method just saves summary information such as the information displayed in the document table. It is not necessary to call this method when the document is first created. Rather, it should only be used when the document has been changed To save the internal PluginDocument too, instead callsaveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument.ActiveLinkSaveBehaviour, jebl.util.ProgressListener)
If this method needs to be called across multiple documents in succession, consider using batchSave(Collection, boolean, ProgressListener) instead, as it may offer performance benefits for saving documents in bulk.
-
save
public abstract void save(boolean updateModifiedDate)
Saves the document summary to the database. Does not save changes to the internal PluginDocument. Rather, this method just saves summary information such as the information displayed in the document table. It is not necessary to call this method when the document is first created. Rather, it should only be used when the document has been changed To save the internal PluginDocument too, instead callsaveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument.ActiveLinkSaveBehaviour, jebl.util.ProgressListener)
If this method needs to be called across multiple documents in succession, consider using batchSave(Collection, boolean, ProgressListener) instead, as it may offer performance benefits for saving documents in bulk.- Parameters:
updateModifiedDate
- true to set the document's modified date to now, false to leave the modified date as is. Furthermore, if this is false, an automatic history entry will not be added.- Since:
- API 4.600 (Geneious 6.0.0)
- See Also:
saveDocument()
,batchSave(Collection, boolean, ProgressListener)
-
isInLocalRepository
public abstract boolean isInLocalRepository()
Returns true if this document is in the user's persistent storage repository (a WritableDatabaseService - either a local or shared database) or false if it is an in memory only document.- Returns:
- true if this document is in the user's repository
- See Also:
isDeletedFromWritableDatabaseService()
-
isDeletedFromWritableDatabaseService
public abstract boolean isDeletedFromWritableDatabaseService()
Returns true if this document was originally in aWritableDatabaseService
but has now been deleted. (i.e. originally it returned true fromisInLocalRepository()
but no longer does now).Note that documents which have become referenced only due to strong references during removal are not considered to be deleted and so will return false from this method.
- Returns:
- true if this document was originally in a
WritableDatabaseService
but has now been permanently deleted. - Since:
- API 4.40 (Geneious 5.4.0)
- See Also:
isInLocalRepository()
-
setDatabase
public abstract void setDatabase(DatabaseService location)
Set the database folder that this document was generated from. This method should only be (and must be) called byWritableDatabaseService
implementations whenever they create documents. When a document had been removed from their database, either to set the database to null, or to the root database if the document has been moved to the referenced only documents location. If the location is set to a WritableDatabaseService, and the document version has changed (i.e. the document was previously created using an old version of Geneious which used a different document format) and is being loaded for the first time since upgrading, thenWritableDatabaseService.saveDocument(AnnotatedPluginDocument, boolean, jebl.util.ProgressListener)
may be invoked as part of the setDatabase call. Therefore to avoid potential problems, a WritableDatabaseService implementation must finish any other internal requirements when loading a document before calling setDatabase.- Parameters:
location
- the DatabaseService that created this document or null if this document is no longer in a database (for example it has been removed from a database) or the root database if this document is in a hidden folder in the database- See Also:
getDatabase()
-
getDatabase
public abstract DatabaseService getDatabase()
Get the database folder this document is in, or null if it is not in a database. In the case of databases that are not a WritableDatabaseService, this may or may not be null depending on whether the database set the location on the document. For WritableDatabaseServices, the database is automatically set, so this method will always return a non-null value for documents in a WritableDatabaseService. If the document is in a hidden folder in the database, this method will return the database root (seeWritableDatabaseService.getDatabaseRoot()
). To determine whether a document is in a hidden folder or not (i.e. a document that is only referenced by other documents but not in any user visible folder), useWritableDatabaseService.getDocumentLocation()
- Returns:
- the database containing this document or null.
- See Also:
setDatabase(com.biomatters.geneious.publicapi.databaseservice.DatabaseService)
-
toSummaryDocument
public abstract AnnotatedPluginDocument toSummaryDocument()
Generates a new AnnotatedPluginDocument that is identical to this document, except that the internal PluginDocument to a lightweight AnySummaryDocument.- Returns:
- the newly generated AnnotatedPluginDocument
-
toXMLExcludingInternalPluginDocument
public org.jdom.Element toXMLExcludingInternalPluginDocument()
Equivalent to callingtoXMLExcludingInternalPluginDocument(Geneious#getMajorVersion())
-
toXMLExcludingInternalPluginDocument
public abstract org.jdom.Element toXMLExcludingInternalPluginDocument(Geneious.MajorVersion majorVersion)
converts this AnnotatedPluginDocument to a single XML element. Does not include the internal PluginDocument. If you want to include the internal PluginDocument, useXMLSerializable.toXML()
. This method is primarily for use withDocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN)
.- Parameters:
majorVersion
- the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". If the implementation of this class does not implementXMLSerializable.OldVersionCompatible
thentoXMLExcludingInternalPluginDocument()
should be called instead. If it does then this must be a version returned greater or equal to a version returned fromgetVersionSupport
(VersionSupportType.OldestVersionSerializableTo
) and must never be greater than the current version (Geneious.getMajorVersion()
)- Returns:
- the XML element
- Since:
- API 4.810 (Geneious 8.1.0)
-
getSearchableFieldsAndValues
public java.util.Map<DocumentField,java.util.List<java.lang.Object>> getSearchableFieldsAndValues() throws java.io.IOException
Equivalent togetSearchableFieldsAndValues(ProgressListener.EMPTY)
- Throws:
java.io.IOException
-
getSearchableFieldsAndValues
public abstract java.util.Map<DocumentField,java.util.List<java.lang.Object>> getSearchableFieldsAndValues(jebl.util.ProgressListener progressListener) throws java.io.IOException
Gets a set of fields and associated values that are indexed for search purposes. For each DocumentField, there may be multiple independent values that are indexed for that field which is why each DocumentField is associated with a list. In addition to searching for the fields returned from this method, the database must also support matching all the returned values when searching in theDocumentField.ALL
field.- Returns:
- a set fields and associated values to be indexed for search purposes.
- Throws:
java.io.IOException
- if thePluginDocument
could not be loaded or if there is a problem storing the searchable field data in a temporary file on disk in the case of a document too large to fit in memory or if the progressListener cancels.- Since:
- API 4.800 (Geneious 8.0.0)
- See Also:
getSearchableFieldsAndValuesForAnnotatedDocumentOnly()
-
getSearchableFieldsAndValuesForAnnotatedDocumentOnly
public abstract java.util.Map<DocumentField,java.util.List<java.lang.Object>> getSearchableFieldsAndValuesForAnnotatedDocumentOnly() throws java.io.IOException
The same asgetSearchableFieldsAndValues()
except that only fields and values for the annotated document are returned. Useful when the search index needs to be updated due to a change to the document and only the annotated document has been changed.- Returns:
- a set fields and associated values to be indexed for search purposes.
- Throws:
java.io.IOException
- if there is a problem storing the searchable field data in a temporary file on disk in the case of a document too large to fit in memory- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getSearchableFieldsAndValues()
-
setTemporaryFieldValue
public abstract void setTemporaryFieldValue(java.lang.String fieldName, java.lang.Object value)
This is used for storing temporary in memory only information about this document. UsegetTemporaryFieldValue(String)
to retrieve the value.- Parameters:
fieldName
- a unique name of the fieldvalue
- the value for this field
-
getTemporaryFieldValue
public abstract java.lang.Object getTemporaryFieldValue(java.lang.String fieldName)
This is used for retrieving temporary in memory only information about this document. UsesetTemporaryFieldValue(String, Object)
to set the value.- Parameters:
fieldName
- a unique name of the field- Returns:
- value the value for this field
-
changeReferencedDocumentURNs
public abstract void changeReferencedDocumentURNs(java.util.Map<URN,URN> URNsToChange)
Changes the URNs of any documents that the internal PluginDocument references. This method is generally only for core Geneious use. Any URNs ingetReferencedDocuments()
that are keys inURNsToChange
will be changed to the corresponding value inchangeURNS
.- Parameters:
URNsToChange
- a map where the key is the old URN and the value is the new URN for that key
-
addWeakReferenceDocumentListener
public abstract void addWeakReferenceDocumentListener(DocumentListener listener)
Add a listener to be notified when the document changes. The AnnotatedPluginDocument only stores a weak reference to the document listener. This means that when nothing else other than the AnnotatedPluginDocument holds a reference to the listener, then the listener will be removed. The reason that weak references are used is that it is often the case that something such as a view on the document adds the listener. When the view is closed, it is sometimes difficult (or easy to forget) to remove the listener, which results in the view being unable to be garbage collected for as long as the document exists.- Parameters:
listener
- the listener to be notified- See Also:
removeWeakReferenceDocumentListener(DocumentListener)
-
removeWeakReferenceDocumentListener
public abstract void removeWeakReferenceDocumentListener(DocumentListener listener)
Remove a listener previously added usingaddWeakReferenceDocumentListener(DocumentListener)
. Since the AnnotatedPluginDocument only stores a weak reference to the document listener, calling this method is often unnecessary.- Parameters:
listener
- the listener to be notified- See Also:
addWeakReferenceDocumentListener(DocumentListener)
-
documentChanged
public abstract void documentChanged(org.jdom.Element newElement)
Replaces the contents of this document. This method may only be used internally byDatabaseService
s, to notify Geneious about external changes to a document already returned from the database. Furthermore it may only be used on AnnotatedPluginDocuments created usingDocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN)
(Element, ElementProvider)} A side effect of calling this method is that anyDocumentListener
s will be notified about the changes.- Parameters:
newElement
- the new XML for the AnnotatedPluginDocument, which must be XML returned from a previous call totoXMLExcludingInternalPluginDocument()
. The internal cache of the PluginDocument will be cleared and it will be reloaded when necessary using the ElementProvider used when the document was originally created.
-
additionalXmlChanged
public abstract void additionalXmlChanged()
Notifies the document that additional XML retrieved already may have changed. This method may only be used internally byDatabaseService
s, to notify Geneious about external changes to additional XML retrieved by callinggetAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)
orgetAdditionalXml(String, boolean)
. Furthermore it may only be used on AnnotatedPluginDocuments created usingDocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN)
(Element, ElementProvider)}- Since:
- API 4.61 (Geneious 5.6.1)
-
getRevisionNumber
public abstract int getRevisionNumber()
Get a revision number associated with this document. Every time either the AnnotatedPluginDocument or the internal PluginDocument is saved, the revision number is incremented. If you are just interested in when the internal PluginDocument changes, but not changes to the wrapper AnnotatedPluginDocument, usegetInternalPluginDocumentRevisionNumber()
instead.- Returns:
- the current revision number for this document.
- See Also:
getInternalPluginDocumentRevisionNumber()
-
getInternalPluginDocumentRevisionNumber
public abstract int getInternalPluginDocumentRevisionNumber()
Get a revision number associated with the internal PluginDocument. Every time the PluginDocument is changed, the revision number is incremented.- Returns:
- the current revision number for the internal PluginDocument. This is 0 if the PluginDocument has not been changed since this AnnotatedPluginDocument was first created.
- Since:
- API 4.900 (Geneious 9.0.0)
- See Also:
getRevisionNumber()
-
setSourceService
public abstract void setSourceService(DatabaseService sourceService)
Add an annotation to the document which tells the program which service to download the full document from if the PluginDocument is a summary (implementsSummaryDocument
)save()
must be called afterwards to save the changes to the database. Normally core Geneious code will automatically call this method on summary documents, but if you are writing code that directly calls database service methods then you may need to explicity call setSourceService on the summary documents so that Geneious knows where to download the full document from.- Parameters:
sourceService
- the DatabaseService from which the full document can be downloaded.
-
getSize
public abstract long getSize()
Get the uncompressed size in bytes of this document- Returns:
- the uncompressed size in bytes of this document or zero if unknown.
-
getPluginDocumentXml
public abstract org.jdom.Element getPluginDocumentXml(jebl.util.ProgressListener progressListener) throws java.io.IOException
Get the XML of the internal PluginDocument. If this is an in memory document that is not saved anywhere to persistent storage, then this is the XML obtained by callingXMLSerializable.toXML()
. If this document is stored in persistent storage or created via collaboration, this is the XML obtained from persistent storage. If the PluginDocument has been changed but not yet saved or if Geneious has been upgraded, then the XML obtained from persistent storage may be different to that obtained by callingXMLSerializable.toXML()
.- Parameters:
progressListener
- a progress listener to report progress to and to allow cancelling loading of the document's xml.- Returns:
- the XML of the internal PluginDocument.
- Throws:
java.io.IOException
- if the source document cannot be loaded- See Also:
getDocument()
-
setAdditionalXml
public abstract void setAdditionalXml(java.lang.String key, boolean isPerUser, org.jdom.Element element) throws java.io.IOException
Stores additional data in the form of XML which is directly associated with this document. The data is persisted to the database but is stored separately to avoid impacting performance. UsegetAdditionalXml(String,boolean)
to recover data stored using this method. It is not necessary to callsave()
, the additional XML is immediately saved to the database. However, if setting this additional XML could change how a DocumentViewer renders the document, then callingsave()
is recommended to fire a refresh event on the DocumentViewers.- Parameters:
key
- a unique key to store the data underisPerUser
- if true and this document is in a multi-user database (eg. shared database) then the XML will only be stored for the current user and will only be returned ifgetAdditionalXml(String, boolean)
is called for the same user with true passed in forisPerUser
. If false then the XML is stored globally and it will be returned when the getter is called for ANY user with false forisPerUser
. This parameter has no effect when the document is stored in single-user database such as the local database.element
- the additional XML data to store for this document. This may be null to delete the additional xml associated with the given key.- Throws:
java.io.IOException
- if there was a problem writing to the database- See Also:
setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener)
,getAdditionalXml(String, boolean)
,getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)
-
setAdditionalXml
public abstract void setAdditionalXml(java.util.Map<java.lang.String,ElementProvider> elementsToSave, boolean isPerUser, jebl.util.ProgressListener progressListener) throws java.io.IOException
Stores additional data in the form of XML which is directly associated with this document. This method is similar tosetAdditionalXml(String, boolean, org.jdom.Element)
except that this method allows setting multiple additional XML entries with a single method invocation, potentially allowing the database to handle it more efficiently than multiple calls tosetAdditionalXml(String, boolean, org.jdom.Element)
- Parameters:
elementsToSave
- A mapping from a unique key to store the data under to anElementProvider
that can be used to retrieve the XML element to store. If a null value is specified in the map then the element corresponding to the specified key will be deleted from the database.isPerUser
- if true and this document is in a multi-user database (eg. shared Database) then the XML will only be stored for the current user and will only be returned ifgetAdditionalXml(String, boolean)
is called for the same user with true passed in forisPerUser
. If false then the XML is stored globally and it will be returned when the getter is called for ANY user with false forisPerUser
. This parameter has no effect when the document is stored in single-user database such as the local database.progressListener
- used to report progress while saving the XML to the database. Progress must include retrieving the elements from the givenElementProvider
s as well as saving to the database. Must not be null, but may beProgressListener.EMPTY
- Throws:
java.io.IOException
- if there was a problem writing to the database- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
setAdditionalXml(String, boolean, org.jdom.Element)
,getAdditionalXml(String, boolean)
,getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)
-
getAdditionalXml
public abstract org.jdom.Element getAdditionalXml(java.lang.String key, boolean isPerUser) throws java.io.IOException
Get additional data in the form of XML which has been stored associated with this document usingsetAdditionalXml(String,boolean,org.jdom.Element)
.- Parameters:
key
- the unique key that the data has been stored underisPerUser
- if true and this document is in a multi-user database (eg. shared Database) then only return the XML which has been stored for the current user (by callingsetAdditionalXml(String, boolean, org.jdom.Element)
with true passed in forisPerUser
). If false then return the XML which has been stored globally (by calling the setter with false forisPerUser
). This parameter has no effect when the document is stored in single-user database such as the local database.- Returns:
- the XML data associated with this document and the given key or null if doesn't exist
- Throws:
java.io.IOException
- if there was a problem retrieving from the database- See Also:
setAdditionalXml(String, boolean, org.jdom.Element)
,setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener)
,getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)
-
getAdditionalXml
public abstract java.util.Map<java.lang.String,ElementProvider> getAdditionalXml(java.util.List<java.lang.String> keys, boolean isPerUser, jebl.util.ProgressListener progressListener) throws java.io.IOException
Get additional data in the form of XML which has been stored associated with this document usingsetAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener)
orsetAdditionalXml(String, boolean, org.jdom.Element)
. This method is similar togetAdditionalXml(String, boolean)
except that this method allows retrieving multiple additional XML entries with a single method invocation, potentially allowing the database to handle it more efficiently than multiple calls togetAdditionalXml(String, boolean)
- Parameters:
keys
- A list of unique keys that the elements have been stored underisPerUser
- if true and this document is in a multi-user database (eg. shared Database) then only return the XML which has been stored for the current user (by callingsetAdditionalXml(String, boolean, org.jdom.Element)
with true passed in forisPerUser
). If false then return the XML which has been stored globally (by calling the setter with false forisPerUser
). This parameter has no effect when the document is stored in single-user database such as the local database.progressListener
- used to report progress while retrieving from the database. Must not be null, but may beProgressListener.EMPTY
- Returns:
- A mapping from unique key to an
ElementProvider
that can be used to retrieve the XML data associated with this document for any elements that were found in the database. If there was no element associated with a key in the provided list, then there will be no entry in the resulting map. - Throws:
java.io.IOException
- if there was a problem retrieving from the database- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
setAdditionalXml(String, boolean, org.jdom.Element)
,setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener)
,getAdditionalXml(String, boolean)
-
getAdditionalXml
@MayReturnSlowly public abstract java.util.Map<java.lang.String,ElementProvider> getAdditionalXml(boolean isPerUser, jebl.util.ProgressListener progressListener) throws java.io.IOException
Get all additional XML for this document for every key. SeegetAdditionalXml(List, boolean, ProgressListener)
for full details.- Parameters:
isPerUser
- if true and this document is in a multi-user database (eg. shared Database) then only return the XML which has been stored for the current user (by callingsetAdditionalXml(String, boolean, org.jdom.Element)
with true passed in forisPerUser
). If false then return the XML which has been stored globally (by calling the setter with false forisPerUser
). This parameter has no effect when the document is stored in single-user database such as the local database.progressListener
- used to report progress while retrieving from the database. Must not be null, but may beProgressListener.EMPTY
- Returns:
- A mapping from unique key to an
ElementProvider
that can be used to retrieve the XML data associated with this document for any elements that were found in the database. - Throws:
java.io.IOException
- if there was a problem retrieving from the database- Since:
- API 4.202210 (Geneious 2022.1.0)
- See Also:
WritableDatabaseService.cachePluginDocumentXmlAndAdditionalXmlLocally(List, ProgressListener)
-
getPotentialAdditionalXmlKeys
@Deprecated public abstract java.util.List<java.lang.String> getPotentialAdditionalXmlKeys(boolean isPerUser) throws java.io.IOException
Deprecated.Get a list of potential keys for additional xml that is associated with this document. The list is 'potential' because although it will always include all of the keys for the additional xml associated with this document (added usingsetAdditionalXml(String,boolean,org.jdom.Element)
) it may include extra keys which aren't associated with this document (getAdditionalXml(String,boolean)
will return null).- Parameters:
isPerUser
- if true and this document is in a multi-user database (eg. shared Database) then only return the keys which have been used to store XML for the current user (by callingsetAdditionalXml(String, boolean, org.jdom.Element)
with true passed in forisPerUser
). If false then only return keys which have been used to store XML globally (by calling the setter with false forisPerUser
. This parameter has no effect when the document is stored in single-user database such as the local database.- Returns:
- a list of potential keys for additional xml that is associated with this document
- Throws:
java.io.IOException
- if there was a problem writing to the database
-
addDescendantOperationRecord
public abstract void addDescendantOperationRecord(URN operationRecordUrn)
Adds a record of an operation where this document was an input document to the operation. The calling code must callsave()
shortly afterwards.- Parameters:
operationRecordUrn
- this must refer to an AnnotatedPluginDocument containing aOperationRecordDocument
. Must not be null- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getDescendantOperationRecords()
,getParentOperationRecord()
,setParentOperationRecord(URN)
-
getDescendantOperationRecords
public abstract java.util.List<URN> getDescendantOperationRecords()
- Returns:
- all operations run where this document was an input document to the operation
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
addDescendantOperationRecord(URN)
,getParentOperationRecord()
,setParentOperationRecord(URN)
-
setParentOperationRecord
public abstract void setParentOperationRecord(URN operationRecordUrn)
Sets a record of the operation that generated this document. This method should be called before the document is added to a database.- Parameters:
operationRecordUrn
- this must refer to an AnnotatedPluginDocument containing aOperationRecordDocument
. May be null to delete the reference to the existing parent operation record.- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getParentOperationRecord()
,addDescendantOperationRecord(URN)
,getDescendantOperationRecords()
-
getParentOperationRecord
public abstract URN getParentOperationRecord()
- Returns:
- then urn of the document operation record that generated this document or null if no record is available.
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
setParentOperationRecord(URN)
,addDescendantOperationRecord(URN)
,getDescendantOperationRecords()
-
getIcons
public Icons getIcons()
- Returns:
- an Icons which manages the icon for this document, or null if it doesn't specify any.
- Since:
- API 4.60 (Geneious 5.6.0)
-
isReadOnly
public boolean isReadOnly()
- Returns:
- true if this document is read only. This may be because it is in a read only database.
- Since:
- API 4.600 (Geneious 6.0.0)
-
isFormatExtendedInFutureVersion
public abstract boolean isFormatExtendedInFutureVersion()
- Returns:
- true if the format this document has been saved in has been extended in a future version.
- Since:
- API 4.811 (Geneious 8.1.1), API 4.718 (Geneious 7.1.8)
- See Also:
XMLSerializable.VersionSupportType.FormatLastExtended
-
getUrnWithRevisionNumber
public abstract UrnWithRevisionNumber getUrnWithRevisionNumber()
- Returns:
- the urn and revision number of this document (i.e. a combination of
getURN()
andgetRevisionNumber()
) - Since:
- API 4.201900 (Geneious 2019.0.0)
- See Also:
getUrnWithInternalPluginDocumentRevisionNumber()
-
getUrnWithInternalPluginDocumentRevisionNumber
public abstract UrnWithRevisionNumber getUrnWithInternalPluginDocumentRevisionNumber()
- Returns:
- the urn and internal plugin document revision number of this document (i.e. a combination of
getURN()
andgetInternalPluginDocumentRevisionNumber()
) - Since:
- API 4.201910 (Geneious 2019.1.0)
- See Also:
getUrnWithRevisionNumber()
-
isPluginDocumentInstanceOf
public boolean isPluginDocumentInstanceOf(java.lang.Class<? extends PluginDocument> cl)
- Returns:
- true if the class returned from
getDocument()
is an instance cl. This method is fast, unlikegetDocument()
which may need to load the internal document from a database. - Since:
- API 4.202100 (Geneious 2021.0.0)
- See Also:
getDocumentClass()
,getDocument()
-
removeDescendantOperationRecord
public abstract boolean removeDescendantOperationRecord(URN operationRecordUrn)
Removes a descendant operation record returned fromgetDescendantOperationRecords()
. Note: This method is intended for core Geneious use only. Plugins should never need to use this.- Parameters:
operationRecordUrn
-- Returns:
- true if there was a descendant operation record with this URN to remove
- Since:
- API 4.202210 (Geneious 2022.1.0)
-
clearInternalDocumentCache
public void clearInternalDocumentCache()
Clears the internal plugin document cache. Only core Geneious and database implementations should ever need to use this.- Since:
- API 4.202210 (Geneious 2022.1.0)
-
setPluginDocumentElementProvider
public void setPluginDocumentElementProvider(ElementProvider elementProvider, boolean checkAvailableMemoryBeforeLoadingElement)
For a document created usingDocumentUtilities.createAnnotatedPluginDocument(Element, ElementProvider, URN)
, allows changing the ElementProvider used to load the PluginDocument XML. Note: This method is intended for core Geneious use, or implementations ofWritableDatabaseService.addDocumentsImplementation(List, ProgressListener)
only. Other plugins should never need to use this.- Parameters:
elementProvider
- the new ElementProvider to replace the one provided to the createAnnotatedPluginDocument. Must not be null.checkAvailableMemoryBeforeLoadingElement
- indicate that Geneious should check available memory and fail gracefully if insufficient memory is available to load an Element into memory of the previously recorded size. This should normally be true, but may be false in rare situations where the Element has already been loaded into memory.- Throws:
java.lang.IllegalStateException
- if this method is called on a document which was not created usingDocumentUtilities.createAnnotatedPluginDocument(Element, ElementProvider, URN)
- Since:
- API 4.202210 (Geneious 2022.1.0)
-
batchSave
public static void batchSave(java.util.Collection<AnnotatedPluginDocument> documentsToSave, boolean updateModifiedDate, jebl.util.ProgressListener progressListener)
Saves the summary information for a number of documents. This method is functionally equivalent to callingsave(boolean)
on the supplied documents. Always prefer using this method over saving single documents iteratively because the document database may have optimisations in place for saving documents in bulk. It is not guaranteed that all documents will be successfully saved when calling this method, but a best attempt will be made. For example, if the document database operates in a network environment, transient failures may cause some documents to not be saved. If at least one document was not saved successfully, or could not be known to have saved successfully, a user-friendly dialog will be displayed as part of this operation so the user may wish to retry the operation.- Parameters:
documentsToSave
- Collection of documents to be saved.updateModifiedDate
- true to set the document's modified date to now, false to leave the modified date as is. If this is true, aDocumentHistoryEntry
for this save will be automatically appended to the document.progressListener
- Progress listener for this operation, also can be used as a cancellation token. If not applicable, useProgressListener.EMPTY
.- Since:
- API 4.202230 (Geneious 2022.3.0)
-
-