public abstract class AnnotatedPluginDocument extends Object implements XMLSerializable
PluginDocument
(such as a SequenceDocument
or SequenceAlignmentDocument
or TreeDocument) 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, use getDocument(). In many situations
(such as inside a DocumentOperation where you
have provided a DocumentSelectionSignature) you can cast the
returned PluginDocument to the expected type (such as a SequenceDocument or SequenceAlignmentDocument
or TreeDocument).
An importer or database service creates a PluginDocument. 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 should never implment this. Instead, call
DocumentUtilities.createAnnotatedPluginDocument(PluginDocument).
Commonly used methods of AnnotatedPluginDocument include
getDocument() to get the wrapped PluginDocument
getName() to get the name of the documentgetDisplayableFields() to get a list of all fields that are displayable to the usergetFieldValue(DocumentField) or getFieldValue(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 with DocumentUtilities.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 itself.save() to save changes made to just the AnnotatedPluginDocument (this does not save the wrapped PluginDocument)| Modifier and Type | Class and Description |
|---|---|
static class |
AnnotatedPluginDocument.ActiveLinkSaveBehaviour
Gives an action to take when
saveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument.ActiveLinkSaveBehaviour, jebl.util.ProgressListener) is called. |
static interface |
AnnotatedPluginDocument.DocumentNotes
Provides access to all the
DocumentNotes on an AnnotatedPluginDocument |
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType| Modifier and Type | Field and Description |
|---|---|
static String |
TEMPORARY_FIELD_KEY_ANNOTATED_DOCUMENT_LOCATION
Used by databases with
setTemporaryFieldValue(String,Object) for
providing the user with information about the location of the AnnotatedPluginDocument. |
static String |
TEMPORARY_FIELD_KEY_PLUGIN_DOCUMENT_LOCATION
Used by databases with
setTemporaryFieldValue(String,Object) for
providing the user with information about the location of the PluginDocument. |
ROOT_ELEMENT_NAME| Constructor and Description |
|---|
AnnotatedPluginDocument() |
| Modifier and Type | Method and 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.
|
abstract void |
changeReferencedDocumentURNs(Map<URN,URN> URNsToChange)
Changes the URNs of any documents that the internal PluginDocument references.
|
abstract String |
confirmDocumentValid()
Confirms this document is valid.
|
abstract void |
documentChanged(org.jdom.Element newElement)
Replaces the contents of this document.
|
abstract Map<String,ElementProvider> |
getAdditionalXml(List<String> keys,
boolean isPerUser,
ProgressListener progressListener)
Get additional data in the form of XML which has been stored associated with this document using
setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener) or setAdditionalXml(String, boolean, org.jdom.Element). |
abstract org.jdom.Element |
getAdditionalXml(String key,
boolean isPerUser)
Get additional data in the form of XML which has been stored associated with this document using
setAdditionalXml(String,boolean,org.jdom.Element). |
abstract 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 List<URN> |
getDescendantOperationRecords() |
abstract 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 Class<? extends PluginDocument> |
getDocumentClass()
Get the class of the underlying document without loading it.
|
abstract DocumentHistory |
getDocumentHistory()
Get the instance of
DocumentHistory for this document. |
abstract AnnotatedPluginDocument.DocumentNotes |
getDocumentNotes(boolean isForEditing)
Changes made to the notes on a document will not be saved to the document
unless
AnnotatedPluginDocument.DocumentNotes.saveNotes() is called after modification. |
abstract PluginDocument |
getDocumentOrCrash()
A convenience method that calls
getDocumentOrThrow(RuntimeException.class). |
abstract PluginDocument |
getDocumentOrNull()
A convenience method that calls
getDocumentOrThrow(true,ProgressListener.EMPTY,...)
but instead of throwing an exception if the document cannot be loaded, returns null. |
abstract <T extends Exception> |
getDocumentOrThrow(boolean warnIfCantLoad,
ProgressListener progressListener,
Class<T> exceptionClass)
Returns the underlying document.
|
abstract <T extends Exception> |
getDocumentOrThrow(Class<T> exceptionClass)
Equivalent to calling
getDocumentOrThrow(true,ProgressListener.EMPTY,exceptionClass) |
abstract List<DocumentField> |
getExtendedDisplayableFields()
Gets a list of all displayable document fields, which includes all those returned by
getDisplayableFields() as well as the document name, description, creation date
and all note fields with DocumentField.getCode()s
of the form "noteCode.fieldCode". |
abstract Object |
getFieldValue(DocumentField field)
Get value of a field - either a displayable field or a hidden field.
|
abstract Object |
getFieldValue(String fieldCode)
Retrieves the value of a displayable or hidden field, given the field's
code. |
Icons |
getIcons() |
abstract String |
getName()
Name of document.
|
abstract URN |
getParentOperationRecord() |
abstract org.jdom.Element |
getPluginDocumentXml(ProgressListener progressListener)
Get the XML of the internal PluginDocument.
|
abstract List<String> |
getPotentialAdditionalXmlKeys(boolean isPerUser)
Get a list of potential keys for additional xml that is associated with this document.
|
abstract 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.
|
Map<DocumentField,List<Object>> |
getSearchableFieldsAndValues()
Equivalent to
getSearchableFieldsAndValues(ProgressListener.EMPTY) |
abstract Map<DocumentField,List<Object>> |
getSearchableFieldsAndValues(ProgressListener progressListener)
Gets a set of fields and associated values that are indexed
for search purposes.
|
abstract Map<DocumentField,List<Object>> |
getSearchableFieldsAndValuesForAnnotatedDocumentOnly()
The same as
getSearchableFieldsAndValues() except that only fields and values for the annotated
document are returned. |
abstract long |
getSize()
Get the uncompressed size in bytes of this document
|
abstract Set<URN> |
getStronglyReferencedDocuments()
Get a set of document URNs strongly referred to by this document.
|
abstract String |
getSummary()
Deprecated.
use
getFieldValue(DocumentField) with DocumentField.DESCRIPTION_FIELD to get the Description for the docment. |
abstract Object |
getTemporaryFieldValue(String fieldName)
This us 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 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 a
WritableDatabaseService 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 |
isReadOnly() |
abstract boolean |
isUnread()
Returns true if document retrieved by agent and not yet seen by user.
|
abstract void |
removeWeakReferenceDocumentListener(DocumentListener listener)
Remove a listener previously added using
addWeakReferenceDocumentListener(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,
ProgressListener progressListener)
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database.
|
boolean |
saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour,
ProgressListener progressListener)
Saves the internal PluginDocument and the AnnotatedPluginDocument to the database.
|
abstract void |
setAdditionalXml(Map<String,ElementProvider> elementsToSave,
boolean isPerUser,
ProgressListener progressListener)
Stores additional data in the form of XML which is directly associated with this document.
|
abstract void |
setAdditionalXml(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 |
setDatabase(DatabaseService location)
Set the database folder that this document was generated from.
|
abstract void |
setFieldValue(DocumentField field,
Object value)
Set the value of field which is visible in the user interface.
|
abstract void |
setHiddenFieldValue(DocumentField field,
Object value)
Set the value of field which is not visible in the user interface.
|
abstract void |
setName(String name)
Set document name.
|
abstract void |
setParentOperationRecord(URN operationRecordUrn)
Sets a record of the operation that generated this document.
|
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
(implements
SummaryDocument)
save() must be called afterwards to save the changes to the database. |
abstract void |
setSummary(String summary)
Deprecated.
|
abstract void |
setTemporaryFieldValue(String fieldName,
Object value)
This us 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 calling
toXMLExcludingInternalPluginDocument(Geneious#getMajorVersion()) |
abstract org.jdom.Element |
toXMLExcludingInternalPluginDocument(Geneious.MajorVersion majorVersion)
converts this AnnotatedPluginDocument to a single XML element.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitfromXML, toXMLpublic static final String TEMPORARY_FIELD_KEY_ANNOTATED_DOCUMENT_LOCATION
setTemporaryFieldValue(String,Object) for
providing the user with information about the location of the AnnotatedPluginDocument.
For example, this might be a file name.public static final String TEMPORARY_FIELD_KEY_PLUGIN_DOCUMENT_LOCATION
setTemporaryFieldValue(String,Object) for
providing the user with information about the location of the PluginDocument.
For example, this might be a file name.public abstract String getName()
public abstract URN getURN()
DocumentUtilities.getDocumentByURN(URN).URNpublic abstract Date getCreationDate()
getDocumentOrNull().creationDate()
or if that returned null, this method will return the date the PluginDocument
was first instantiated.@Deprecated public abstract String getSummary()
getFieldValue(DocumentField) with DocumentField.DESCRIPTION_FIELD to get the Description for the docment.PluginDocument.getDescription()public abstract List<DocumentField> getDisplayableFields()
getFieldValue(java.lang.String) to get the value.getExtendedDisplayableFields()public abstract List<DocumentField> getExtendedDisplayableFields()
getDisplayableFields() as well as the document name, description, creation date
and all note fields with DocumentField.getCode()s
of the form "noteCode.fieldCode".
The values of any fields returned from this method can be retrieved using getFieldValue(String).getDisplayableFields()public abstract Object getFieldValue(String fieldCode)
code.
Can be used to get the value of any field returned from getExtendedDisplayableFields(),
including document note fields.fieldCode - code of the field to access.
A field with this code must either be among the displayable fields,
or must have been assigned a hidden value.public abstract Object getFieldValue(DocumentField field)
getExtendedDisplayableFields(),
including document note fields.field - field as given by getDisplayableFields() or setHiddenFieldValue(DocumentField,Object)public abstract void setHiddenFieldValue(DocumentField field, Object value)
save() must be called afterwards to save the changes to the database.field - to setvalue - of field. The class of value must either implement XMLSerializable 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.public abstract void setFieldValue(DocumentField field, Object value)
getExtendedDisplayableFields(),
including document note fields.
save() must be called afterwards to save the changes to the database.field - to setvalue - of field@Deprecated public abstract void setSummary(String summary)
setFieldValue(DocumentField.DESCRIPTION_FIELD, description) insteadsummary - to setpublic abstract void setName(String name)
save() must be called afterwards to save the changes to the database.name - to setpublic abstract Set<URN> getReferencedDocuments()
getStronglyReferencedDocuments() and getWeaklyReferencedDocuments()
Usually used with sequence alignment documents that point back to the original sequences.getStronglyReferencedDocuments(),
getWeaklyReferencedDocuments()public abstract Set<URN> getStronglyReferencedDocuments()
URN.toXML(String) for a discussion on strong/weak document references.getReferencedDocuments(),
getWeaklyReferencedDocuments()public abstract Set<URN> getWeaklyReferencedDocuments()
URN.toXML(String) for a discussion on strong/weak document references.getReferencedDocuments(),
getStronglyReferencedDocuments()public abstract boolean isUnread()
public abstract boolean setUnread(boolean unread)
save() afterwards (it is done automatically)unread - status to setpublic abstract AnnotatedPluginDocument.DocumentNotes getDocumentNotes(boolean isForEditing)
AnnotatedPluginDocument.DocumentNotes.saveNotes() is called after modification.isForEditing - if any of these notes will be changed using AnnotatedPluginDocument.DocumentNotes.setNote(DocumentNote) , AnnotatedPluginDocument.DocumentNotes.removeNote(String) or AnnotatedPluginDocument.DocumentNotes.saveNotes()public abstract DocumentHistory getDocumentHistory() throws IOException
DocumentHistory for this document.
Most plugins will use this to add a DocumentHistoryEntry to provide details of changes they make to the document.IOException - if history cannot be retrieved for this documentpublic abstract <T extends Exception> PluginDocument getDocumentOrThrow(boolean warnIfCantLoad, ProgressListener progressListener, Class<T> exceptionClass) throws T extends Exception
getDocumentClass()
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.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 type exceptionClass if the document can not be loaded.progressListener - used to report progress while loading the document. Must not be null, but may be ProgressListener.EMPTYexceptionClass - If the document cannot be loaded an exception of this class will be thrown. Must not be null.T - exception of class exceptionClass if the document could not be loadedT extends ExceptiongetDocument(),
getDocumentClass(),
getDocumentOrNull(),
getDocumentOrCrash(),
getDocumentOrThrow(Class)public abstract <T extends Exception> PluginDocument getDocumentOrThrow(Class<T> exceptionClass) throws T extends Exception
getDocumentOrThrow(true,ProgressListener.EMPTY,exceptionClass)exceptionClass - If the document cannot be loaded an exception of this class will be thrown. Must not be null.T - exception of class exceptionClass if the document could not be loadedT extends ExceptiongetDocument(),
getDocumentClass(),
getDocumentOrNull(),
getDocumentOrCrash(),
getDocumentOrThrow(boolean,jebl.util.ProgressListener,Class)public abstract PluginDocument getDocumentOrNull()
getDocumentOrThrow(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 use getDocument() which throws a DocumentOperationException meaning they do not need to worry about document load failures.public abstract PluginDocument getDocument() throws DocumentOperationException
getDocumentClass()
which does not cause loading of the document.
This method is equivalent to getDocumentOrThrow(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.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)getDocumentClass(),
getDocumentOrNull(),
getDocumentOrCrash(),
getDocumentOrThrow(Class),
getDocumentOrThrow(boolean, jebl.util.ProgressListener, Class)public abstract PluginDocument getDocumentOrCrash()
getDocumentOrThrow(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.getDocument(),
getDocumentClass(),
getDocumentOrNull(),
getDocumentOrThrow(Class),
getDocumentOrThrow(boolean,jebl.util.ProgressListener,Class)public abstract Class<? extends PluginDocument> getDocumentClass()
getDocument(),
getDocumentOrNull(),
getDocumentOrCrash(),
getDocumentOrThrow(Class),
getDocumentOrThrow(boolean,jebl.util.ProgressListener,Class)public abstract String confirmDocumentValid()
WritableDatabaseService.addDocumentCopy(AnnotatedPluginDocument, jebl.util.ProgressListener)
and during import.public abstract void saveDocument()
save() instead.
WARNING - AnnotatedPluginDocument only stores a SoftReference to the document returned from getDocument(). 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 as PluginDocument#hashCode() immediately after calling saveDocument()save()public boolean saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour, ProgressListener progressListener)
save() instead.activeLinkSaveBehaviour - the action to undertake if this document has active links to its descendants (see AnnotatedPluginDocument.ActiveLinkSaveBehaviour).progressListener - for reporting progress and allowing the save to be canceled.save()public abstract boolean saveDocument(AnnotatedPluginDocument.ActiveLinkSaveBehaviour activeLinkSaveBehaviour, boolean updateModifiedDate, ProgressListener progressListener)
save() instead.activeLinkSaveBehaviour - the action to undertake if this document has active links to its descendants (see AnnotatedPluginDocument.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.save()public abstract void save()
saveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument.ActiveLinkSaveBehaviour, jebl.util.ProgressListener)saveDocument()public abstract void save(boolean updateModifiedDate)
saveDocument(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument.ActiveLinkSaveBehaviour, jebl.util.ProgressListener)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.saveDocument()public abstract boolean isInLocalRepository()
isDeletedFromWritableDatabaseService()public abstract boolean isDeletedFromWritableDatabaseService()
WritableDatabaseService but has now been deleted. (i.e. originally it returned true from isInLocalRepository() but no longer does now)WritableDatabaseService but has now been deleted.isInLocalRepository()public abstract void setDatabase(DatabaseService location)
WritableDatabaseService 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, then WritableDatabaseService.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.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 databasegetDatabase()public abstract DatabaseService getDatabase()
WritableDatabaseService.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), use
WritableDatabaseService.getDocumentLocation()setDatabase(com.biomatters.geneious.publicapi.databaseservice.DatabaseService)public abstract AnnotatedPluginDocument toSummaryDocument()
public org.jdom.Element toXMLExcludingInternalPluginDocument()
toXMLExcludingInternalPluginDocument(Geneious#getMajorVersion())public abstract org.jdom.Element toXMLExcludingInternalPluginDocument(Geneious.MajorVersion majorVersion)
XMLSerializable.toXML(). This method is primarily for use
with DocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN).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 implement XMLSerializable.OldVersionCompatible
then toXMLExcludingInternalPluginDocument() should be called instead. If it does
then this must be a version returned greater or equal to a version returned from
getVersionSupport(VersionSupportType.OldestVersionSerializableTo)
and must never be greater than the current version (Geneious.getMajorVersion())public Map<DocumentField,List<Object>> getSearchableFieldsAndValues() throws IOException
getSearchableFieldsAndValues(ProgressListener.EMPTY)IOExceptionpublic abstract Map<DocumentField,List<Object>> getSearchableFieldsAndValues(ProgressListener progressListener) throws IOException
DocumentField.ALL field.IOException - if the PluginDocument 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.getSearchableFieldsAndValuesForAnnotatedDocumentOnly()public abstract Map<DocumentField,List<Object>> getSearchableFieldsAndValuesForAnnotatedDocumentOnly() throws IOException
getSearchableFieldsAndValues() 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.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 memorygetSearchableFieldsAndValues()public abstract void setTemporaryFieldValue(String fieldName, Object value)
getTemporaryFieldValue(String) to retrieve the value.fieldName - a unique name of the fieldvalue - the value for this fieldpublic abstract Object getTemporaryFieldValue(String fieldName)
setTemporaryFieldValue(String, Object) to set the value.fieldName - a unique name of the fieldpublic abstract void changeReferencedDocumentURNs(Map<URN,URN> URNsToChange)
getReferencedDocuments() that are keys in URNsToChange
will be changed to the corresponding value in changeURNS.URNsToChange - a map where the key is the old URN and the value is the new URN for that keypublic abstract void addWeakReferenceDocumentListener(DocumentListener listener)
listener - the listener to be notifiedremoveWeakReferenceDocumentListener(DocumentListener)public abstract void removeWeakReferenceDocumentListener(DocumentListener listener)
addWeakReferenceDocumentListener(DocumentListener).
Since the AnnotatedPluginDocument only stores a weak reference to the document listener,
calling this method is often unnecessary.listener - the listener to be notifiedaddWeakReferenceDocumentListener(DocumentListener)public abstract void documentChanged(org.jdom.Element newElement)
DatabaseServices,
to notify Geneious about external changes to a document already returned from the database.
Furthermore it may only be used on AnnotatedPluginDocuments created using
DocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN) (Element, ElementProvider)}
A side effect of calling this method is that any DocumentListeners
will be notified about the changes.newElement - the new XML for the AnnotatedPluginDocument, which must be XML returned from
a previous call to toXMLExcludingInternalPluginDocument(). 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.public abstract void additionalXmlChanged()
DatabaseServices, to notify Geneious about external changes to additional XML retrieved by
calling getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener) or getAdditionalXml(String, boolean) .
Furthermore it may only be used on AnnotatedPluginDocuments created using DocumentUtilities.createAnnotatedPluginDocument(org.jdom.Element, ElementProvider, URN) (Element, ElementProvider)}public abstract int getRevisionNumber()
public abstract void setSourceService(DatabaseService sourceService)
SummaryDocument)
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.sourceService - the DatabaseService from which the full document can be downloaded.public abstract long getSize()
public abstract org.jdom.Element getPluginDocumentXml(ProgressListener progressListener) throws IOException
XMLSerializable.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 calling XMLSerializable.toXML().progressListener - a progress listener to report progress to and to allow cancelling loading of the document's xml.IOException - if the source document cannot be loadedgetDocument()public abstract void setAdditionalXml(String key, boolean isPerUser, org.jdom.Element element) throws IOException
getAdditionalXml(String,boolean) to
recover data stored using this method.
It is not necessary to call save(), the additional XML is immediately saved to the database. However, if
setting this additional XML could change how a DocumentViewer renders the document, then calling save()
is recommended to fire a refresh event on the DocumentViewers.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 if getAdditionalXml(String, boolean) is
called for the same user with true passed in for isPerUser. If false then the XML is stored globally
and it will be returned when the getter is called for ANY user with false for isPerUser. 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.IOException - if there was a problem writing to the databasesetAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener),
getAdditionalXml(String, boolean),
getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)public abstract void setAdditionalXml(Map<String,ElementProvider> elementsToSave, boolean isPerUser, ProgressListener progressListener) throws IOException
setAdditionalXml(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 to setAdditionalXml(String, boolean, org.jdom.Element)elementsToSave - A mapping from a unique key to store the data under to an ElementProvider 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 if getAdditionalXml(String, boolean) is
called for the same user with true passed in for isPerUser. If false then the XML is stored globally
and it will be returned when the getter is called for ANY user with false for isPerUser. 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 given ElementProviders as well as saving to the database. Must not be
null, but may be ProgressListener.EMPTYIOException - if there was a problem writing to the databasesetAdditionalXml(String, boolean, org.jdom.Element),
getAdditionalXml(String, boolean),
getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)public abstract org.jdom.Element getAdditionalXml(String key, boolean isPerUser) throws IOException
setAdditionalXml(String,boolean,org.jdom.Element).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 calling setAdditionalXml(String, boolean, org.jdom.Element)
with true passed in for isPerUser). If false then return the XML which has been stored globally
(by calling the setter with false for isPerUser). This parameter
has no effect when the document is stored in single-user database such as the local database.IOException - if there was a problem retrieving from the databasesetAdditionalXml(String, boolean, org.jdom.Element),
setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener),
getAdditionalXml(java.util.List, boolean, jebl.util.ProgressListener)public abstract Map<String,ElementProvider> getAdditionalXml(List<String> keys, boolean isPerUser, ProgressListener progressListener) throws IOException
setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener) or setAdditionalXml(String, boolean, org.jdom.Element).
This method is similar to getAdditionalXml(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 to getAdditionalXml(String, boolean)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 calling setAdditionalXml(String, boolean, org.jdom.Element)
with true passed in for isPerUser). If false then return the XML which has been stored globally
(by calling the setter with false for isPerUser). 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
be ProgressListener.EMPTYElementProvider 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.IOException - if there was a problem retrieving from the databasesetAdditionalXml(String, boolean, org.jdom.Element),
setAdditionalXml(java.util.Map, boolean, jebl.util.ProgressListener),
getAdditionalXml(String, boolean)public abstract List<String> getPotentialAdditionalXmlKeys(boolean isPerUser) throws IOException
setAdditionalXml(String,boolean,org.jdom.Element)) it may include extra keys which aren't
associated with this document (getAdditionalXml(String,boolean) will return null).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 calling setAdditionalXml(String, boolean, org.jdom.Element)
with true passed in for isPerUser). If false then only return keys which have been used to store XML
globally (by calling the setter with false for isPerUser. This parameter
has no effect when the document is stored in single-user database such as the local database.IOException - if there was a problem writing to the databasepublic abstract void addDescendantOperationRecord(URN operationRecordUrn)
save() shortly afterwards.operationRecordUrn - this must refer to an AnnotatedPluginDocument containing a OperationRecordDocument. Must not be nullgetDescendantOperationRecords(),
getParentOperationRecord(),
setParentOperationRecord(URN)public abstract List<URN> getDescendantOperationRecords()
addDescendantOperationRecord(URN),
getParentOperationRecord(),
setParentOperationRecord(URN)public abstract void setParentOperationRecord(URN operationRecordUrn)
operationRecordUrn - this must refer to an AnnotatedPluginDocument containing a OperationRecordDocument. Must not be nullgetParentOperationRecord(),
addDescendantOperationRecord(URN),
getDescendantOperationRecords()public abstract URN getParentOperationRecord()
setParentOperationRecord(URN),
addDescendantOperationRecord(URN),
getDescendantOperationRecords()public Icons getIcons()
public boolean isReadOnly()
public abstract boolean isFormatExtendedInFutureVersion()
XMLSerializable.VersionSupportType.FormatLastExtended