Class AbstractPluginDocument
- java.lang.Object
-
- com.biomatters.geneious.publicapi.documents.AbstractPluginDocument
-
- All Implemented Interfaces:
PluginDocument
,XMLSerializable
,XMLSerializable.OldVersionCompatible
- Direct Known Subclasses:
DefaultMolecularStructureDocument
,DefaultSequenceDocument
,DefaultSequenceListDocument
,DocumentCollection
public abstract class AbstractPluginDocument extends java.lang.Object implements PluginDocument, XMLSerializable.OldVersionCompatible
This class provides a "Field based" implementation of a Plugin documents. A class derived from AbstractPluginDocument does most of its setup in the constructor, where it,- sets URN and creation date by calls to
setURN(com.biomatters.geneious.publicapi.documents.URN)
and setCreated. - sets all displayable columns via calls to
setFieldValue(java.lang.String, java.lang.Object)
. - optionally specifies a "base document", a JDOM element which gets saved with the document. Typically this would be an XML document fetched from an external source, but it may be any additional content document needs to keep on top of items stored in fields.
PluginDocument.getDescription()
andPluginDocument.toHTML()
.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument
PluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProvider
-
Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType
-
-
Field Summary
-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument
FILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELD
-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
ROOT_ELEMENT_NAME
-
-
Constructor Summary
Constructors Constructor Description AbstractPluginDocument()
Create a new document with a creation date taken from system clock.AbstractPluginDocument(java.util.Date created)
Construct a new document with a given time of creation.AbstractPluginDocument(java.util.Date created, URN urn)
Construct a new document with a given URN and time of creation.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addDisplayableField(DocumentField field)
adds a displayable field to the document that is stored with the documents.void
addReferencedDocumentUrn(URN documentUrn)
Adds the given document URN to a list of documents to be referenced.void
clearReferencedDocumentUrns()
Clears the list of all referenced docments previously added usingaddReferencedDocumentUrn(URN)
.void
createFromBaseElement(org.jdom.Element element)
Restore document from base element.void
fromXML(org.jdom.Element root)
Restore the object from the JDOM Element returned byXMLSerializable.toXML()
.org.jdom.Element
getBaseElement()
A JDOM element holding document data.java.lang.String
getBaseElementString()
Base element as a XML text fragment.java.util.Date
getCreationDate()
Get the date this document was created.java.util.List<DocumentField>
getDisplayableFields()
A list of columns for display in the main document panel.java.lang.Object
getFieldValue(java.lang.String code)
Get the value of a particular field.java.util.List<java.lang.String>
getFieldValueCodes()
Gets the code of all fields stored in this document, including non-displayable fields.java.util.List<URN>
getReferencedDocumentUrns()
This function can be called to retrieve the list of documents previously remembered using theaddReferencedDocumentUrn(URN)
function.URN
getURN()
A Universal Resource Name.Geneious.MajorVersion
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Gets either the latest version this class can serialize to viaXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
or the most recent version in which the XML returned fromXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
last changed.boolean
hasProperties()
void
setBaseElement(org.jdom.Element baseElement)
Set document base element.protected void
setCreated(java.util.Date date)
Set document date of creation.void
setFieldValue(DocumentField field, java.lang.Object value)
Set value of one data item (field).void
setFieldValue(java.lang.String code, java.lang.Object value)
Set value of one data item (field).
It is important to calladdDisplayableField(DocumentField)
if this field should be displayable and isn't already on this document. For non displayable fields, the value must either implementXMLSerializable
or be an instance of a simple type that Geneious knows how to serialize (e.g.void
setFieldValues(java.util.Map<java.lang.String,java.lang.Object> fieldValues)
Set all fields in one go.protected void
setURN(URN urn)
Set document URN.org.jdom.Element
toXML()
Convert object to a JDOM element.org.jdom.Element
toXML(Geneious.MajorVersion version, jebl.util.ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface com.biomatters.geneious.publicapi.documents.PluginDocument
getDescription, getName, toHTML
-
-
-
-
Constructor Detail
-
AbstractPluginDocument
public AbstractPluginDocument(java.util.Date created)
Construct a new document with a given time of creation.- Parameters:
created
- the date this document was created, or null to use the current date. The date will be serialized to XML by this document and then restored when the document is deserialized again from XML. SeePluginDocument.getCreationDate()
.
-
AbstractPluginDocument
public AbstractPluginDocument(java.util.Date created, URN urn)
Construct a new document with a given URN and time of creation.- Parameters:
created
- the date this document was created, or null to use the current date. The date will be serialized to XML by this document and then restored when the document is deserialized again from XML. SeePluginDocument.getCreationDate()
.urn
- the urn for this document
-
AbstractPluginDocument
public AbstractPluginDocument()
Create a new document with a creation date taken from system clock.
-
-
Method Detail
-
getBaseElement
public org.jdom.Element getBaseElement()
A JDOM element holding document data.- Returns:
- base element
-
getBaseElementString
public java.lang.String getBaseElementString()
Base element as a XML text fragment.- Returns:
- XML text
-
setBaseElement
public void setBaseElement(org.jdom.Element baseElement)
Set document base element.- Parameters:
baseElement
- to set
-
createFromBaseElement
public void createFromBaseElement(org.jdom.Element element)
Restore document from base element. Called during construction viafromXML(org.jdom.Element)
to let document set any variables or fields from data inside base element. The code in the base class does nothing since the semantics of the base element are not known to it. Meaningful stuff happens only in subclasses which override this method.- Parameters:
element
- saved base element
-
getFieldValue
public java.lang.Object getFieldValue(java.lang.String code)
Description copied from interface:PluginDocument
Get the value of a particular field.- Specified by:
getFieldValue
in interfacePluginDocument
- Parameters:
code
- field code. This should be thecode
of one of the fields returned fromPluginDocument.getDisplayableFields()
.- Returns:
- value for a field or null if this document does not have a field with the given field code.
The class of the returned value must be the
DocumentField.getValueType()
(or a subclass) of the corresponding DocumentField returned fromPluginDocument.getDisplayableFields()
.
-
setFieldValue
public void setFieldValue(java.lang.String code, java.lang.Object value)
Set value of one data item (field).
It is important to calladdDisplayableField(DocumentField)
if this field should be displayable and isn't already on this document. For non displayable fields, the value must either implementXMLSerializable
or be an instance of 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.- Parameters:
code
- field codevalue
- item value- Throws:
java.lang.IllegalArgumentException
- if code was the code ofDocumentField.CREATED_FIELD
, and the associated value was not of typeDate
.- See Also:
setFieldValue(DocumentField, Object)
-
setFieldValue
public void setFieldValue(DocumentField field, java.lang.Object value)
Set value of one data item (field). If this field is not currently a displayable field on this document, it will be added as a displayable field usingaddDisplayableField(DocumentField)
unless value is null, in which case the displayable field will be removed- Parameters:
field
- the fieldvalue
- item value- Since:
- API 4.610 (Geneious 6.1.0)
- See Also:
setFieldValue(String, Object)
-
setFieldValues
public void setFieldValues(java.util.Map<java.lang.String,java.lang.Object> fieldValues)
Set all fields in one go. (Overrides any previous sets by setFieldValue and setFieldValues).- Parameters:
fieldValues
- all values
-
getFieldValueCodes
public java.util.List<java.lang.String> getFieldValueCodes()
Gets the code of all fields stored in this document, including non-displayable fields. The codes returned are all codes which can be used to obtain field values viagetFieldValue(String)
- Returns:
- the code of all fields stored in this document, including non-displayable fields.
- Since:
- API 4.50 (Geneious 5.5.0)
-
setURN
protected final void setURN(URN urn)
Set document URN. Only needs to be set on initial creation of document. Not required on deserialization (fromXML()).- Parameters:
urn
- to set
-
setCreated
protected final void setCreated(java.util.Date date)
Set document date of creation.- Parameters:
date
- to set
-
getURN
public final URN getURN()
Description copied from interface:PluginDocument
A Universal Resource Name. Documents from external sources should set this to a unique name inside that service. Documents generated locally (such as from operations) and documents that don't have a unique identifier should return null since Geneious handles URNs for these.- Specified by:
getURN
in interfacePluginDocument
- Returns:
- the urn, or null if this document doesn't have a unique identifier
-
getCreationDate
public final java.util.Date getCreationDate()
Description copied from interface:PluginDocument
Get the date this document was created. This method may return null. Generally clients should useAnnotatedPluginDocument.getCreationDate()
instead as that will return either the date returned fromPluginDocument.getCreationDate()
or if that returned null,AnnotatedPluginDocument.getCreationDate()
will return the date the document was first instantiated.- Specified by:
getCreationDate
in interfacePluginDocument
- Returns:
- the date this document was created or null to use the date the document was first instantiated.
- See Also:
PluginDocument.MODIFIED_DATE_FIELD
-
getVersionSupport
public Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
Description copied from interface:XMLSerializable.OldVersionCompatible
Gets either the latest version this class can serialize to viaXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
or the most recent version in which the XML returned fromXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
last changed. Example implementation:switch (versionType) { case FormatLastExtended: //added a new tag to xml in 10.0 that can be safely ignored by older versions return Geneious.MajorVersion.Version10_0; case FormatLastChanged: //renamed a tag in 9.1 meaning that older versions can no longer read the xml from 9.1 return Geneious.MajorVersion.Version9_1; case OldestVersionSerializableTo: //this document class can export xml that is compatible with 9.0 return Geneious.MajorVersion.Version9_0; default: throw new IllegalArgumentException("Unrecognized VersionSupportType"); }
- Specified by:
getVersionSupport
in interfaceXMLSerializable.OldVersionCompatible
- Parameters:
versionType
- specifies which version property to return- Returns:
- the major version of Geneious corresponding to the versionType for this classes toXML method.
-
toXML
public org.jdom.Element toXML()
Description copied from interface:XMLSerializable
Convert object to a JDOM element. The representation should be complete so thatXMLSerializable.fromXML(org.jdom.Element)
can completely restore the object's representation. It is recommended that the returned element useXMLSerializable.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 callXMLSerializer.classToXML(String, XMLSerializable)
which calls this method internally. PluginDocument implementations of this method may choose to throw anXMLSerializationException
, enclosed in aRuntimeException
.- Specified by:
toXML
in interfaceXMLSerializable
- Returns:
- object encoded as a JDOM element
-
toXML
public org.jdom.Element toXML(Geneious.MajorVersion version, jebl.util.ProgressListener progressListener)
Description copied from interface:XMLSerializable.OldVersionCompatible
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious. It is acceptable for the XML to include unnecessary tags that will be ignored by the earlier version. For example if the implementation has only extended the XML since the earlier version, then the XML returned may be identical to the XML returned for the current version. SeeXMLSerializable.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.- Specified by:
toXML
in interfaceXMLSerializable.OldVersionCompatible
- Parameters:
version
- 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 fromgetVersionSupport
(VersionSupportType.OldestVersionSerializableTo
) and must never be greater than the current version (Geneious.getMajorVersion())progressListener
- for reporting progress and cancelling- Returns:
- object encoded as a JDOM element
-
fromXML
public void fromXML(org.jdom.Element root) throws XMLSerializationException
Description copied from interface:XMLSerializable
Restore the object from the JDOM Element returned byXMLSerializable.toXML()
. This method generally should not be called directly. Instead, you should usually callXMLSerializer.classFromXML(org.jdom.Element)
orXMLSerializer.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 singleElement
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 withElement.clone()
.- Specified by:
fromXML
in interfaceXMLSerializable
- Parameters:
root
- representation from a previous call toXMLSerializable.toXML()
- Throws:
XMLSerializationException
- if the Element can't be converted into this type of object
-
addDisplayableField
public void addDisplayableField(DocumentField field)
adds a displayable field to the document that is stored with the documents. Generally, most classes that subclass this class should implement getDisplayableFields() if they have a fixed list of displayable fields that does not vary with each instance of the document. If the field is already present, this method does nothing. addDisplayableField() should only be used for documents that vary the list of displayable fields with each instance of the document.- Parameters:
field
- a DocumentField
-
getDisplayableFields
public java.util.List<DocumentField> getDisplayableFields()
Description copied from interface:PluginDocument
A list of columns for display in the main document panel. This function only defines the columns available to display, not the particular values of these columns, which are returned byPluginDocument.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 toXMLSerializable.fromXML(org.jdom.Element)
The returned list need not and should not be modifiable.- Specified by:
getDisplayableFields
in interfacePluginDocument
- Returns:
- a list of document fields (or null to indicate no displayable fields)
-
addReferencedDocumentUrn
public void addReferencedDocumentUrn(URN documentUrn)
Adds the given document URN to a list of documents to be referenced. This means that the referenced document will remain in the database until all documents referencing it are deleted. To add aPluginDocument
as a reference, first callDocumentUtilities.createAnnotatedPluginDocument(PluginDocument)
or similar then callAnnotatedPluginDocument.getURN()
to get a URN. The reference document will be available later viagetReferencedDocumentUrns()
.- Parameters:
documentUrn
-
-
getReferencedDocumentUrns
public java.util.List<URN> getReferencedDocumentUrns()
This function can be called to retrieve the list of documents previously remembered using theaddReferencedDocumentUrn(URN)
function. Note: if the user has deleted one or more of the referenced documents from their local database, then those documents still be available via this function. Documents are not really deleted (just hidden from the user) until all documents that reference it are also deleted.- Returns:
- the list of referenced documents
-
clearReferencedDocumentUrns
public void clearReferencedDocumentUrns()
Clears the list of all referenced docments previously added usingaddReferencedDocumentUrn(URN)
.
-
hasProperties
public boolean hasProperties()
- Returns:
- true if the AbstractPluginDocument part of the implementation of this document stores any properties. If this is false,
AbstractPluginDocument.toXML
will return an empty element.
-
-