public abstract class DefaultSequenceDocument extends AbstractPluginDocument implements SequenceDocument, EditableSequenceDocument, Renamable, SequenceTrack.Manager.Provider, SequenceGapInformation.Provider, XMLSerializable.OldVersionCompatible
| Modifier and Type | Class and Description |
|---|---|
static class |
DefaultSequenceDocument.Cache
Used for controlling caching of the char sequence and annotations controlled from this class.
|
SequenceDocument.Alphabet, SequenceDocument.TransformerPluginDocument.ReferencedDocumentsAlwaysLoaded, PluginDocument.ReferencedDocumentsNotLoaded, PluginDocument.SizeRequiredToLoadIntoMemoryProviderXMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportTypeGENOME_SEQUENCE_THRESHOLDFILE_DATA_ATTRIBUTE_NAME, MAXIMUM_HTML_LENGTH, MODIFIED_DATE_FIELDROOT_ELEMENT_NAME| Modifier | Constructor and Description |
|---|---|
protected |
DefaultSequenceDocument()
Construct a DefaultSequenceDocument with no arguments.
|
protected |
DefaultSequenceDocument(Sequence jeblSequence)
Construct a new DefaultSequenceDocument using a Sequence from JEBL.
|
protected |
DefaultSequenceDocument(SequenceDocument sequence,
Date created)
Construct a new DefaultSequenceDocument from an existing
SequenceDocument.
|
protected |
DefaultSequenceDocument(String name,
String description,
CharSequence sequence,
Date created) |
protected |
DefaultSequenceDocument(String name,
String description,
CharSequence sequence,
Date created,
URN urn) |
| Modifier and Type | Method and Description |
|---|---|
void |
addSequenceAnnotation(SequenceAnnotation annotation)
Add a sequence annotation to this document.
|
static List<SequenceAnnotation> |
annotationsFromXML(org.jdom.Element annotationsElement)
Return a List of SequenceAnnotations from a JDOM XML Element.
|
void |
copySequenceTracksFrom(SequenceDocument sourceSequence)
Copies all
SequenceTracks (if any) from the source sequence on to this sequence. |
DefaultSequenceDocument |
createCopy()
Creates a copy of this sequence
|
DefaultSequenceDocument |
createCopy(boolean allowReturningNonStandardImplementations)
Creates a copy of this sequence
|
void |
fromXML(org.jdom.Element root)
Restore the object from the JDOM Element returned by
XMLSerializable.toXML(). |
int |
getAnnotationsRevisionNumber()
Gets a revision number associated with the annotations.
|
SequenceCharSequence |
getCharSequence()
Get the sequence as a CharSequence.
|
int |
getCharSequenceRevisionNumber()
Gets a revision number associated with the char sequence.
|
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 code)
Get the value of a particular field.
|
String |
getName()
A short name (preferably one or two words) for the document.
|
List<SequenceAnnotation> |
getSequenceAnnotations()
Gets sequence annotations which are directly on the sequence.
|
SequenceGapInformation |
getSequenceGapInformation()
Gets SequenceGapInformation associated with the char sequence returned from
getCharSequence() |
SequenceGapInformation |
getSequenceGapInformation(boolean createIfNull)
Returns a SequenceGapInformation associated with this sequence.
|
int |
getSequenceLength()
Returns the length of the sequence.
|
String |
getSequenceString()
Get the sequence as a string.
|
SequenceTrack.Manager |
getTrackManager(boolean mayReturnNullIfNoTracks)
Gets a
SequenceTrack.Manager associated with this sequence for providing sequence tracks. |
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 |
isBestSerializedToXmlRatherThanBinaryFormat()
Returns true if this sequence would be best serialized using
toXML() rather than writeObject(java.io.DataOutput, jebl.util.ProgressListener). |
boolean |
isCircular()
Is this a circular sequence?
|
boolean |
isStandardImplementation()
Returns true if this sequence implementation is either
DefaultNucleotideSequence
or DefaultAminoAcidSequence or DefaultNucleotideGraphSequence. |
static DefaultSequenceDocument |
readObject(DataInput in)
Recreates a sequence from a stream previously written to using
writeObject(java.io.DataOutput, jebl.util.ProgressListener) |
static DefaultSequenceDocument |
readObject(GeneiousObjectInputStream in)
Recreates a sequence from a stream previously written to using
writeObject(com.biomatters.geneious.publicapi.documents.sequence.GeneiousObjectOutputStream , jebl.util.ProgressListener) |
static org.jdom.Element |
sequenceAnnotationsToXML(Geneious.MajorVersion version,
String elementName,
List<SequenceAnnotation> annotations)
Return a list of sequence annotations as XML in the specified version of Geneious
|
static org.jdom.Element |
sequenceAnnotationsToXML(String elementName,
List<SequenceAnnotation> annotations)
Return a list of sequence annotations as XML.
|
void |
setAnnotations(List<SequenceAnnotation> annotations)
Sets new annotations on this document, replacing the existing ones.
|
void |
setCache(DefaultSequenceDocument.Cache cache)
Sets the cache used for caching the vaules returned from
getCharSequence() and getSequenceAnnotations(). |
void |
setCircular(boolean isCircular)
Set whether this sequence is circular.
|
void |
setDescription(String description)
Sets the description of this sequence.
|
void |
setFieldValue(String code,
Object value)
Set value of one data item (field).
It is important to call AbstractPluginDocument.addDisplayableField(DocumentField) if this field should be displayable and isn't already on this document.
For non displayable fields, the value must either implement XMLSerializable or be an instance of a simple type that Geneious knows how to serialize (e.g. |
void |
setName(String name)
Change the name of the sequence.
|
void |
setSequenceAndAnnotations(CharSequence sequence,
List<SequenceAnnotation> annotations)
Sets the sequence and annotations of this document.
|
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.
|
void |
writeObject(DataOutput out,
ProgressListener progressListener)
Equivalent to
writeObject(Geneious.getMajorVersion(), out, progressListener) |
void |
writeObject(Geneious.MajorVersion version,
DataOutput out,
ProgressListener progressListener)
Writes this sequence to a stream as specified by
Serializable. |
void |
writeObject(GeneiousObjectOutputStream out,
ProgressListener progressListener)
Writes this sequence to a stream as specified by
Serializable. |
addDisplayableField, addReferencedDocumentUrn, clearReferencedDocumentUrns, createFromBaseElement, getBaseElement, getBaseElementString, getCreationDate, getFieldValueCodes, getReferencedDocumentUrns, getURN, hasProperties, setBaseElement, setCreated, setFieldValue, setFieldValues, setURNclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitgetCreationDate, getURNprotected DefaultSequenceDocument(String name, String description, CharSequence sequence, Date created)
name - name of the document, must not be nulldescription - sequence descriptions (may be null or "")sequence - sequence as a stringcreated - sequence creation date. May be null.protected DefaultSequenceDocument(String name, String description, CharSequence sequence, Date created, URN urn)
name - name of the document, must not be nulldescription - sequence descriptions (may be null or "")sequence - sequence as a stringcreated - sequence creation date. May be null.urn - URN. May be null.protected DefaultSequenceDocument(SequenceDocument sequence, Date created)
sequence - an existing SequenceDocumentcreated - sequence creation timeprotected DefaultSequenceDocument()
protected DefaultSequenceDocument(Sequence jeblSequence)
jeblSequence - a JEBL Sequencepublic List<SequenceAnnotation> getSequenceAnnotations()
SequenceDocumentsequence tracks.
SequenceUtilities.getSequenceAndTrackAnnotations
This method may return an unmodifiable list and must not return the list which is used internally by the SequenceDocument to store the annotations
(ie modifying the returned list should not modify the annotations on the SequenceDocument directly)SequenceUtilities.getSequenceAnnotationsIncludingImmutableSequencesTrims(SequenceDocument).SequenceAnnotation.TYPE_EXTRACTED_REGION.getSequenceAnnotations in interface SequenceDocumentCollections.emptyList()).SequenceUtilities.getSequenceAndTrackAnnotations(SequenceDocument),
SequenceDocumentWithEditableAnnotations.setAnnotations(java.util.List)public void addSequenceAnnotation(SequenceAnnotation annotation)
annotation - a SequenceAnnotationpublic 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 void setName(String name)
AnnotatedPluginDocument
then a call to this method will not have any effect. This is because AnnotatedPluginDocument overrides
calls to PluginDocument.getName() on the document it wraps.
Instead you should call AnnotatedPluginDocument.setName(String)
in most cases.public String getDescription()
PluginDocumentgetDescription in interface PluginDocumentpublic void setDescription(String description)
AnnotatedPluginDocument
then (like setName) a call to this method may not have any effect. This is because AnnotatedPluginDocument overrides
calls to PluginDocument.getDescription() on the document it wraps.
Instead you should call AnnotatedPluginDocument.setFieldValue(DocumentField.DESCRIPTION_FIELD,value)
in those cases.description - the new description for this documentpublic void setFieldValue(String code, Object value)
AbstractPluginDocumentAbstractPluginDocument.addDisplayableField(DocumentField) if this field should be displayable and isn't already on this document.
For non displayable fields, the value must either implement XMLSerializable 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.setFieldValue in class AbstractPluginDocumentcode - field codevalue - item valueAbstractPluginDocument.setFieldValue(DocumentField, Object)public Object getFieldValue(String code)
PluginDocumentgetFieldValue in interface PluginDocumentgetFieldValue in class AbstractPluginDocumentcode - 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 final String getSequenceString()
SequenceDocumentSequenceDocument.getCharSequence() doesn't call this method, then one possible implementation
for this method is the following:
return getCharSequence().toString();
getSequenceString in interface SequenceDocumentSequenceDocument.getCharSequence()public final int getSequenceLength()
SequenceDocumentgetCharSequence().length(),
but may be more performant on some implementations.getSequenceLength in interface SequenceDocumentNucleotideGraph,
the return value of this method must be consistent with the contracts from both
interfaces.public final SequenceCharSequence getCharSequence()
SequenceDocumentSequenceDocument.getSequenceString()
in situations where a String is unnecessary and could potentially
use too much memory, or where we want to efficiently calculate the terminal gap lengths.
The returned CharSequence must always return consistent
values from any of the CharSequence methods
(e.g. CharSequence.length() and CharSequence.charAt(int).
If a SequenceDocument is editable and changes are made to it,
it is required that the original CharSequence obtained from
SequenceDocument.getCharSequence()
not change. A client of the SequenceDocument is only able to obtain
the changes by making a fresh call to SequenceDocument.getCharSequence().
If SequenceDocument.getSequenceString() doesn't call this method, then it is possible to
implement this method as follows:
return SequenceCharSequence.valueOf(getSequenceString());
However, it is recommended that a more memory efficient representation is used
where possible; in that case, SequenceDocument.getSequenceString() can be implemented
based on this method (see its javadoc).
Some implementations of this method may choose to throw a RuntimeException whose cause is an XMLSerializationException if there is insufficient memory to load the sequence. In most situations (e.g. from a DocumentOperation or DocumentFileImporter) catching this exception is unnecessary as core Geneious will have either pre-loaded the sequence or will catch and unwrap this exception itself gracefully.
getCharSequence in interface SequenceDocumentSequenceDocument.getSequenceString()public void setCache(DefaultSequenceDocument.Cache cache)
getCharSequence() and getSequenceAnnotations().
A client may set the same cache on multiple sequences to ensure that only one of them is ever cached in memory at once.
For example sequence list document of multiple chromosomes might use this to ensure they are not all cached in memory at once.cache - the cache to usepublic SequenceGapInformation getSequenceGapInformation()
getCharSequence()getCharSequence()public SequenceGapInformation getSequenceGapInformation(boolean createIfNull)
SequenceGapInformation.ProvidergetSequenceGapInformation in interface SequenceGapInformation.ProvidercreateIfNull - true to create a SequenceGapInformation even if the sequence doesn't already have one cached. The implementation may choose to cache the result it returns.public void setSequenceAndAnnotations(CharSequence sequence, List<SequenceAnnotation> annotations)
EditableSequenceDocumentSequenceTracks
EditableNucleotideGraphSequenceDocument.setSequenceAndAnnotationsAndGraph(CharSequence, java.util.List, NucleotideGraph).
Hence, it is illegal to change the length of the sequence through this method if
this is instanceof NucleotideGraphSequenceDocument;
Therefore, implementations of this method should start with the following code:
if (this instanceof NucleotideGraphSequenceDocument && sequence.length() != getSequenceLength()) {
throw new IllegalArgumentException("Can't change sequence length without updating graph for " + getClass());
}
setSequenceAndAnnotations in interface EditableSequenceDocumentsequence - new residues; NOTE: This CharSequence must not change its length or characters after it was passed to this method!annotations - new annotationspublic void setAnnotations(List<SequenceAnnotation> annotations)
SequenceDocumentWithEditableAnnotationsSequenceTrackssetAnnotations in interface SequenceDocumentWithEditableAnnotationsannotations - New annotations to set on this document.SequenceDocument.getSequenceAnnotations()public String toHTML()
PluginDocument<html>toHTML in interface PluginDocumentpublic 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 PluginDocumentgetDisplayableFields in class AbstractPluginDocumentpublic 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.OldVersionCompatiblegetVersionSupport in class AbstractPluginDocumentversionType - 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 XMLSerializabletoXML in class AbstractPluginDocumentpublic 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.OldVersionCompatibletoXML in class AbstractPluginDocumentversion - 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 int getAnnotationsRevisionNumber()
getSequenceAnnotations()) are changed on this sequence.public int getCharSequenceRevisionNumber()
getCharSequence() is changed on this sequence.public void fromXML(org.jdom.Element root)
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 XMLSerializablefromXML in class AbstractPluginDocumentroot - representation from a previous call to XMLSerializable.toXML()XMLSerializationException - if the Element can't be converted into this type of objectpublic static org.jdom.Element sequenceAnnotationsToXML(String elementName, List<SequenceAnnotation> annotations)
elementName - the name of the root XML Elementannotations - a List of SequenceAnnotationspublic static org.jdom.Element sequenceAnnotationsToXML(Geneious.MajorVersion version, String elementName, List<SequenceAnnotation> annotations)
version - the major version of Geneious to ensure the annotations are readable in.elementName - the name of the root XML Elementannotations - a List of SequenceAnnotationspublic static List<SequenceAnnotation> annotationsFromXML(org.jdom.Element annotationsElement) throws XMLSerializationException
annotationsElement - a JDOM XML ElementXMLSerializationException - if the annotations cannot be deserializedpublic boolean isCircular()
isCircular in interface SequenceDocumentpublic void setCircular(boolean isCircular)
setCircular in interface EditableSequenceDocumentisCircular - true if this sequence should be considered circular.SequenceDocument.isCircular()public final boolean isStandardImplementation()
DefaultNucleotideSequence
or DefaultAminoAcidSequence or DefaultNucleotideGraphSequence.
Returns false for any implementation that is not one of these and is a sub-class of one of these.DefaultNucleotideSequence
or DefaultAminoAcidSequence or DefaultNucleotideGraphSequence.public final boolean isBestSerializedToXmlRatherThanBinaryFormat()
toXML() rather than writeObject(java.io.DataOutput, jebl.util.ProgressListener).
This method is mainly intended for core Geneious usage. Plugin developers probably don't need to use it.toXML() rather than writeObject(java.io.DataOutput, jebl.util.ProgressListener)public void writeObject(GeneiousObjectOutputStream out, ProgressListener progressListener) throws IOException
Serializable.
The object can be deserialized using readObject(com.biomatters.geneious.publicapi.documents.sequence.GeneiousObjectInputStream)
This method may only be called if isStandardImplementation() returns true.
Furthermore, if this document returns a non-empty list from AbstractPluginDocument.getReferencedDocumentUrns(), then the caller
of writeObject is responsible for separately serializing the referenced URNs to XML and reassigning them back
to this sequence after deserialization. This is because core Geneious can only recognize serialized URNs in XML
(but not in binary formats)
and may in some circumstances (e.g. exporting and importing) may need to change the URNs in the serialized XML.out - the stream to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public void writeObject(DataOutput out, ProgressListener progressListener) throws IOException
writeObject(Geneious.getMajorVersion(), out, progressListener)out - the stream to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public void writeObject(Geneious.MajorVersion version, DataOutput out, ProgressListener progressListener) throws IOException
Serializable.
The object can be deserialized using readObject(java.io.DataInput)
This method may only be called if isStandardImplementation() returns true.
Furthermore, if this document returns a non-empty list from AbstractPluginDocument.getReferencedDocumentUrns(), then the caller
of writeObject is responsible for separately serializing the referenced URNs to XML and reassigning them back
to this sequence after deserialization. This is because core Geneious can only recognize serialized URNs in XML
(but not in binary formats)
and may in some circumstances (e.g. exporting and importing) may need to change the URNs in the serialized XML.version - the Geneious version to ensure the data is compatible without - the stream to write to.progressListener - for reporting progress and allowing the write to be canceled.IOException - if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)public static DefaultSequenceDocument readObject(GeneiousObjectInputStream in) throws XMLSerializationException
writeObject(com.biomatters.geneious.publicapi.documents.sequence.GeneiousObjectOutputStream , jebl.util.ProgressListener)in - the stream to read fromXMLSerializationException - if the sequence cannot be deserializedpublic static DefaultSequenceDocument readObject(DataInput in) throws XMLSerializationException
writeObject(java.io.DataOutput, jebl.util.ProgressListener)in - the stream to read fromXMLSerializationException - if the sequence cannot be deserializedpublic DefaultSequenceDocument createCopy()
public DefaultSequenceDocument createCopy(boolean allowReturningNonStandardImplementations)
allowReturningNonStandardImplementations - false to force this method to only return instances for which isStandardImplementation() is true. If in doubt, use true.public SequenceTrack.Manager getTrackManager(boolean mayReturnNullIfNoTracks)
SequenceTrack.Manager.ProviderSequenceTrack.Manager associated with this sequence for providing sequence tracks. For detailed information on sequence tracks, see SequenceTrack.
If this method is called on an alignment, the track manager is for the consensus sequence. Individual sequences in the alignment may also implement SequenceTrack.Manager.Provider if they provide tracks.getTrackManager in interface SequenceTrack.Manager.ProvidermayReturnNullIfNoTracks - to save on memory usage when dealing with lots of small sequences, some implementations may not wish to construct a TrackManager unless necessary. If this parameter is true the implementation may return null rather than an empty track manager if is has no trackspublic void copySequenceTracksFrom(SequenceDocument sourceSequence)
SequenceTracks (if any) from the source sequence on to this sequence.sourceSequence - the source sequence to copy tracks from