Package com.biomatters.geneious.publicapi.documents

Class DocumentHistory

  • public abstract class DocumentHistory
extends java.lang.Object
    The document history for an AnnotatedPluginDocument is made up of a list of entries. Each entry represents a single change made to the document. Plugins should add entries using addHistoryEntry(entry), or addHistoryEntry(entry, true) if they have created an AnnotatedPluginDocument.

    Example of adding document history for an edit: 

    
  try {
    DocumentHistory documentHistory = annotatedPluginDocument.getDocumentHistory();
    DocumentHistoryEntry documentHistoryEntry = documentHistory.createDocumentHistoryEntry();
    documentHistoryEntry.addField(DocumentHistoryEntryField.DESCRIPTION_CODE, "Edited", "replaced bases");
    documentHistoryEntry.addField(this.getClass().getCanonicalName() + ".exampleFieldCode", "Example field name", "example field value");
    documentHistory.addHistoryEntry(documentHistoryEntry);
  }
  catch (IOException e) {
    e.printStackTrace();
    // there's not much you can do if there's an IO exception while retrieving the history. This probably means the document itself won't save either.
  }
    Note that save() does not need to be called from within the plugin, Geneious saves entries automatically when the document is saved.

    Example of adding document history for creation of an AnnotatedPluginDocument, including referenced documents: 

    
  try {
    DocumentHistory documentHistory = annotatedPluginDocument.getDocumentHistory();
    DocumentHistoryEntry documentHistoryEntry = documentHistory.createDocumentHistoryEntry();
    documentHistoryEntry.setReferencedAnnotatedDocuments("Documents used in the creation of this document", annotatedPluginDocuments);
    documentHistoryEntry.addField(DocumentHistoryEntryField.DESCRIPTION_CODE, "Created a Document", "using some other documents");
    documentHistory.addHistoryEntry(documentHistoryEntry, true);
  }
  catch (IOException e) {
    e.printStackTrace();
    // there's not much you can do if there's an IO exception while retrieving the history. This probably means the document itself won't save either.
  }

    Plugin writers should not extend this class.

    Since:
    API 4.11 (Geneious 5.0)

    • Method Detail

      • getHistoryEntries

        public abstract java.util.List<DocumentHistoryEntry> getHistoryEntries()
        Gets the list of entries. NB this is an unmodifiable copy of the actual list and is not backed by the actual list, so changes (eg new entries added) will not be reflected in this list.
        Returns:
        unmodifiable list of all DocumentHistoryEntries in order (oldest first)

      • addHistoryEntry

        public abstract void addHistoryEntry​(DocumentHistoryEntry entry,
                                     boolean attemptToSetAsCreationEntry)
        Adds a DocumentHistoryEntry to the history of this document.

        NB If history is turned off (via 'Preferences' -> 'Appearance and Behaviour' -> 'Store history when...' checkbox) this will silently discard the entry.

        Parameters:
        entry - the entry to add
        attemptToSetAsCreationEntry - if true will attempt to replace the initial entry that Geneious has auto-generated for the document with this entry. If this cannot occur (eg because another plugin has already set a non-auto-generated entry) this entry will appended to the list of entries.

      • createDocumentHistoryEntry

        public abstract DocumentHistoryEntry createDocumentHistoryEntry()
        Create a historyEntry which can then have entryFields added to it before it is passed to one of the addHistoryEntry methods in this class.
        Returns:
        a newly generated concrete instance of DocumentHistoryEntry,

      • save

        public abstract void save()
        Saves the document history. This is for internal Geneious use only and does not need to be called by plugins. Geneious automatically saves all entries added using the add methods in this interface when the document is saved.

      • getUserName

        public static java.lang.String getUserName()
        Get the name that should be used when recording that the user created or modified data. Defaults to System.getProperty("user.name") and can be overridden by the user editable (advanced) preference "History.username".
        Since:
        API 4.1011 (Geneious 10.1.1)

      • setUserName

        public static void setUserName​(java.lang.String userName)
        Set the name to return from getUserName()
        Parameters:
        userName - the name to return from getUserName()
        Since:
        API 4.1101 (Geneious 11.0.1)