Class AnnotatedPluginDocument

    • Field Detail

      • TEMPORARY_FIELD_KEY_ANNOTATED_DOCUMENT_LOCATION

        public static final java.lang.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. 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 with setTemporaryFieldValue(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
    • Constructor Detail

      • AnnotatedPluginDocument

        public AnnotatedPluginDocument()
    • 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 as DocumentUtilities.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 as getDocumentOrNull().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.
      • getDisplayableFields

        public abstract java.util.List<DocumentField> getDisplayableFields()
        Get a list of all displayable fields available on the PluginDocument contained within this AnnotatedPluginDocument.

        Call getFieldValue(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 by 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).

        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's code. Can be used to get the value of any field returned from getExtendedDisplayableFields(), including document note fields.
        Parameters:
        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.
        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 set
        value - 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.
      • 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 from getExtendedDisplayableFields(), including document note fields.

        save() must be called afterwards to save the changes to the database.

        Use setHiddenFieldValue(DocumentField, Object) if the field should not be visible to the user

        Parameters:
        field - to set
        value - of field
      • 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 (see getStronglyReferencedDocuments() and getWeaklyReferencedDocuments() 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. See URN.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 (see getParentOperationRecord())
        Returns:
        URNs of referenced documents
        Since:
        API 4.60 (Geneious 5.6.0)
        See Also:
        getReferencedDocuments(), getWeaklyReferencedDocuments()
      • 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 call save() afterwards (it is done automatically)
        Parameters:
        unread - status to set
        Returns:
        true if unread status has changed, false otherwise.
      • getDocumentHistory

        public abstract DocumentHistory getDocumentHistory()
                                                    throws java.io.IOException
        Get the instance of DocumentHistory for this document. Most plugins will use this to add a DocumentHistoryEntry 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 use 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.

        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 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.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 class exceptionClass if the document could not be loaded
        T extends java.lang.Exception
        See Also:
        getDocument(), getDocumentClass(), getDocumentOrNull(), getDocumentOrCrash(), getDocumentOrThrow(Class)
      • getDocumentOrNull

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

        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.

        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)
      • 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.
        Plugin writers don't normally need to call this, it is done automatically in 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, use 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()

        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, use save() instead.

        Parameters:
        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.
        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, use save() instead.

        Parameters:
        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.
        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()
      • 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 a WritableDatabaseService but has now been deleted. (i.e. originally it returned true from isInLocalRepository() 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 by 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.

        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 (see 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()
        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
      • 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 the DocumentField.ALL field.
        Returns:
        a set fields and associated values to be indexed for search purposes.
        Throws:
        java.io.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.
        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 as 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.
        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. Use getTemporaryFieldValue(String) to retrieve the value.
        Parameters:
        fieldName - a unique name of the field
        value - 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. Use setTemporaryFieldValue(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 in getReferencedDocuments() that are keys in URNsToChange will be changed to the corresponding value in changeURNS.
        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)
      • documentChanged

        public abstract void documentChanged​(org.jdom.Element newElement)
        Replaces the contents of this document. This method may only be used internally by 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.
        Parameters:
        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.
      • 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, use getInternalPluginDocumentRevisionNumber() 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 (implements 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.

        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 calling 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().
        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. Use 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.

        Parameters:
        key - a unique key to store the data under
        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.
        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 to 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)

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

        @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. See getAdditionalXml(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 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.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
        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 using setAdditionalXml(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 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.
        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
      • 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
      • 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, unlike getDocument() 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 from getDescendantOperationRecords().

        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 using DocumentUtilities.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 of WritableDatabaseService.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 using DocumentUtilities.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 calling save(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, a DocumentHistoryEntry 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, use ProgressListener.EMPTY.
        Since:
        API 4.202230 (Geneious 2022.3.0)