public class OperationRecordDocument extends Object implements PluginDocument, XMLSerializable.OldVersionCompatible
DocumentOperation.
May additionally specify the operation and its parameters
to enable the descendants to be reproduced, in which case it is referred to as an "active link".
Geneious automatically creates an OperationRecordDocument with inactive links for every DocumentOperation that is run. OperationRecordDocuments are stored wrapped in AnnotatedPluginDocuments in
a hidden area of the user's database.
To obtain the URNs of hidden AnnotatedPluginDocuments containing OperationRecordDocuments use
AnnotatedPluginDocument.getParentOperationRecord
or AnnotatedPluginDocument.getDescendantOperationRecords. DocumentUtilities.getDocumentByURN(URN) can then be used to get hold of the document.
If the DocumentOperation wants to create active links, it should use OperationCallback.setOptionsForActivelyLinkedDescendants
and implement DocumentOperation.qgetOptions.
Alternatively, if non-DocumentOperation code wants to create linked documents, it should construct a new OperationRecordDocument and then call linkDocumentsInDatabase(jebl.util.ProgressListener)PluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProviderXMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportTypeFILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELDROOT_ELEMENT_NAME| Constructor and Description |
|---|
OperationRecordDocument()
PluginDocument deserialization constructor.
|
OperationRecordDocument(List<URN> inputDocuments,
List<URN> additionalParentDocuments,
String operationId,
long timeAtWhichOperationWasRun,
org.jdom.Element optionsForRecreatingDescendants)
Creates an operation record whose documents added later using
addOutputDocument(URN) will be actively linked (see hasAnyActiveLinks()) |
OperationRecordDocument(List<URN> inputDocuments,
String operationId,
long timeAtWhichOperationWasRun)
Creates an operation record whose documents added later using
addOutputDocument(URN) will be inactively linked (see hasAnyActiveLinks()) |
| Modifier and Type | Method and Description |
|---|---|
void |
addOutputDocument(URN outputDocument)
adds an output document that this operation produced.
|
void |
fromXML(org.jdom.Element element)
Restore the object from the JDOM Element returned by
XMLSerializable.toXML(). |
List<URN> |
getActiveOutputDocuments() |
List<URN> |
getAdditionalParentDocuments() |
Date |
getCreationDate()
Get the date this document was created.
|
String |
getDescription()
A human readable single line of text describing this document,
to appear in the description field in the document table.
|
List<DocumentField> |
getDisplayableFields()
A list of columns for display in the main document panel.
|
Object |
getFieldValue(String fieldCodeName)
Get the value of a particular field.
|
List<URN> |
getInputDocuments() |
String |
getName()
A short name (preferably one or two words) for the document.
|
String |
getOperationId() |
org.jdom.Element |
getOptionsForRecreatingDescendants() |
List<URN> |
getOutputDocuments() |
List<URN> |
getParentDocuments() |
long |
getTimeAtWhichOperationWasRun() |
URN |
getURN()
A Universal Resource Name.
|
Geneious.MajorVersion |
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Gets either the latest version this class can serialize to via
XMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener)
or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener) last changed. |
boolean |
hasAnyActiveLinks() |
boolean |
isFinishedAddingOutputDocuments() |
void |
linkDocumentsInDatabase(ProgressListener progressListener)
Links the documents in this record together.
|
void |
removeOutputDocument(URN outputDocument)
Removes an output document from the record.
|
boolean |
replaceInputDocument(URN originalUrn,
URN newUrn)
Replaces the URN of an output document with a new one.
|
boolean |
replaceOutputDocument(URN originalUrn,
URN newUrn)
Replaces the URN of an output document with a new one.
|
void |
rerunOperation(ProgressListener progressListener)
Reruns an operation, replacing all output documents of the operation with their corresponding new document
|
void |
setAllOutputDocumentsActive(boolean active)
Equivalent to calling
setOutputDocumentActive(URN, boolean) on each document returned from getOutputDocuments() |
void |
setFinishedAddingOutputDocuments()
tells this Operation Record that we're done adding documents via
addOutputDocument(URN). |
boolean |
setOutputDocumentActive(URN urn,
boolean active)
Sets whether or not the output document with this URN is active.
|
String |
toHTML()
Provide a textual view of document.
|
org.jdom.Element |
toXML()
Convert object to a JDOM element.
|
org.jdom.Element |
toXML(Geneious.MajorVersion version,
ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.
|
public OperationRecordDocument()
public OperationRecordDocument(List<URN> inputDocuments, String operationId, long timeAtWhichOperationWasRun)
addOutputDocument(URN) will be inactively linked (see hasAnyActiveLinks())inputDocuments - the input documents to the operation.operationId - the id of the operation returned from getUniqueId(). This may be an invisible DocumentOperation (one that returns NotPresent from DocumentOperation.getActionOptions().GeneiousActionOptions.getMainMenuLocation()timeAtWhichOperationWasRun - the start time of the operation - get from System.currentTimeMillis().public OperationRecordDocument(List<URN> inputDocuments, List<URN> additionalParentDocuments, String operationId, long timeAtWhichOperationWasRun, org.jdom.Element optionsForRecreatingDescendants)
addOutputDocument(URN) will be actively linked (see hasAnyActiveLinks())inputDocuments - the input documents. See DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List).additionalParentDocuments - the additional parent input documents. See DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List).operationId - the id of the operation returned from getUniqueId(). This may be an invisible DocumentOperation (one that returns NotPresent from DocumentOperation.getActionOptions().GeneiousActionOptions.getMainMenuLocation()timeAtWhichOperationWasRun - the start time of the operation - get from System.currentTimeMillis().optionsForRecreatingDescendants - information necessary to rerun the operation. See DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List).public void addOutputDocument(URN outputDocument)
setFinishedAddingOutputDocuments() when all output documents have been added.outputDocument - an output document that this operation producedpublic void removeOutputDocument(URN outputDocument)
setOutputDocumentActive(URN, boolean) is preferable so that the user still has a record of what happened.
At the time of writing, the only situation in which this should be used is when
duplicating an operation record as a result of a copy/paste or import operation.outputDocument - the URN of an existing output document. Its entry in the list
of output documents will be replaced with null.public void setFinishedAddingOutputDocuments()
addOutputDocument(URN).isFinishedAddingOutputDocuments()public boolean isFinishedAddingOutputDocuments()
setFinishedAddingOutputDocuments()public boolean hasAnyActiveLinks()
public List<URN> getInputDocuments()
DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List).
These are not necessarily all the parent documents, see getAdditionalParentDocuments(). The list will not be null, but individual elements in the list may (or maybe not) be null if documents have been deleted.getAdditionalParentDocuments(),
getParentDocuments()public List<URN> getAdditionalParentDocuments()
DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List). The list will not be null, but individual elements in the list may (or maybe not) be null if documents have been deleted.getInputDocuments(),
getParentDocuments()public final List<URN> getParentDocuments()
getInputDocuments() and getAdditionalParentDocuments(). The list will not be null, but individual elements in the list may (or maybe not) be null if documents have been deleted.getInputDocuments(),
getAdditionalParentDocuments()public List<URN> getOutputDocuments()
getActiveOutputDocuments()public List<URN> getActiveOutputDocuments()
getOutputDocuments() except that additional elements in the
list may be null if the link between this operation and that output document is inactive.getOutputDocuments()public String getOperationId()
getUniqueId())public long getTimeAtWhichOperationWasRun()
System.currentTimeMillis().public org.jdom.Element getOptionsForRecreatingDescendants()
DocumentOperation.getOptions(org.jdom.Element, java.util.List, List). See DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, List).public List<DocumentField> getDisplayableFields()
PluginDocumentPluginDocument.getFieldValue(String).
Each column is specified by a Field. The fields should be obtained from a call to the appropriate
Field.createXXXXField, where XXXX is the appropriate type.
While it is not required, it is recommended that a PluginDocument
handle returning a complete list of its displayable fields before
the document has been properly constructed via a call to XMLSerializable.fromXML(org.jdom.Element)
The returned list need not and should not be modifiable.getDisplayableFields in interface PluginDocumentpublic Object getFieldValue(String fieldCodeName)
PluginDocumentgetFieldValue in interface PluginDocumentfieldCodeName - field code. This should be the
code of one of the fields
returned from PluginDocument.getDisplayableFields().DocumentField.getValueType() (or a subclass) of the corresponding DocumentField returned from PluginDocument.getDisplayableFields().public String getName()
PluginDocumentAnnotatedPluginDocument then this method
will be overridden and delegate back to AnnotatedPluginDocument.getName(). One way to look at it is
that when you call PluginDocument.getName() you will get the current name of the document. If you are implementing PluginDocument.getName() then you are
returning the default name for the document.getName in interface PluginDocumentpublic URN getURN()
PluginDocumentgetURN in interface PluginDocumentpublic Date getCreationDate()
PluginDocumentAnnotatedPluginDocument.getCreationDate()
instead as that will return either the date returned from
PluginDocument.getCreationDate() or if that returned null,
AnnotatedPluginDocument.getCreationDate() will return the date the
document was first instantiated.getCreationDate in interface PluginDocumentPluginDocument.MODIFIED_DATE_FIELDpublic String getDescription()
PluginDocumentgetDescription in interface PluginDocumentpublic String toHTML()
PluginDocument<html>toHTML in interface PluginDocumentpublic Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
XMLSerializable.OldVersionCompatibleXMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener)
or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(com.biomatters.geneious.publicapi.plugin.Geneious.MajorVersion, jebl.util.ProgressListener) last changed.getVersionSupport in interface XMLSerializable.OldVersionCompatibleversionType - specifies which version property to returnpublic org.jdom.Element toXML()
XMLSerializableXMLSerializable.fromXML(org.jdom.Element) can completely
restore the objects representation.
It is recommended that the returned element use XMLSerializable.ROOT_ELEMENT_NAME as its name,
in which case it must not define an attribute called "type". In this case,
fromXML, will be called with an element whose name may differ from the element
return from this function. This recommendation allows a more compact representation
of the XML can be stored.
This method generally should not be called directly. Instead, you should usually call
XMLSerializer.classToXML(String, XMLSerializable)
which calls this method internally.
PluginDocument implementations of this method may choose to throw an XMLSerializationException,
enclosed in a RuntimeException.toXML in interface XMLSerializablepublic org.jdom.Element toXML(Geneious.MajorVersion version, ProgressListener progressListener)
XMLSerializable.OldVersionCompatibleXMLSerializable.toXML() for a more
detailed description of what it means to serialize to XML.
All classes that implement this method must also implement XMLSerializable.toXML() and should delegate back to
this method using Geneious.getMajorVersion() and ProgressListener.EMPTY as parameters.toXML in interface XMLSerializable.OldVersionCompatibleversion - the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". 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())progressListener - for reporting progress and cancellingpublic void fromXML(org.jdom.Element element)
throws XMLSerializationException
XMLSerializableXMLSerializable.toXML().
This method generally should not be called directly. Instead, you should usually call
XMLSerializer.classFromXML(org.jdom.Element)
or XMLSerializer.classFromXML(org.jdom.Element, Class)
which calls this method internally.
It is optional to implement this method. Instead of implementing an empty constructor and implementing
this method properly, the implementation may instead
throw an UnsupportedOperationException and implement a constructor
that takes a single Element as a parameter.
This allows for cleaner code such as support for final fields in the XMLSerializable class.
The element parameter should not be modified since it may be reused. If you need a modified version of it,
take a copy with Element.clone().fromXML in interface XMLSerializableelement - representation from a previous call to XMLSerializable.toXML()XMLSerializationException - if the Element can't be converted into this type of objectpublic void linkDocumentsInDatabase(ProgressListener progressListener) throws DocumentOperationException
WritableDatabaseService.getDatabaseRoot().
This OperationRecord will be added to the database, linking to the parent and output documents. The parent and output documents will also be linked to the newly added operation record.
DocumentOperation.OperationCallback#setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List)progressListener - for reporting progress and cancellingDocumentOperationException - if there is a problem applying these changes (e.g. can't save to database)DocumentOperationException.Canceled - if the progress listener requests the operation be cancelled.IllegalStateException - if setFinishedAddingOutputDocuments() has already been called on this document.public boolean setOutputDocumentActive(URN urn, boolean active)
urn - the urn of the document, which must be a value returned from getOutputDocuments()active - whether or not this output document should be actively linked.public void setAllOutputDocumentsActive(boolean active)
setOutputDocumentActive(URN, boolean) on each document returned from getOutputDocuments()active - whether or not all the output documents should be actively linked.public boolean replaceOutputDocument(URN originalUrn, URN newUrn)
originalUrn - the original URNnewUrn - the new URN to use instead of the original URNpublic boolean replaceInputDocument(URN originalUrn, URN newUrn)
originalUrn - the original URNnewUrn - the new URN to use instead of the original URNpublic void rerunOperation(ProgressListener progressListener) throws DocumentOperationException
progressListener - a ProgressListenerDocumentOperationException - if an exception occurred during the rerunning of the operation