Class DefaultSequenceDocument
- java.lang.Object
-
- com.biomatters.geneious.publicapi.documents.AbstractPluginDocument
-
- com.biomatters.geneious.publicapi.implementations.sequence.DefaultSequenceDocument
-
- All Implemented Interfaces:
PluginDocument
,Renamable
,EditableSequenceDocument
,SequenceDocument
,SequenceDocumentWithEditableAnnotations
,XMLSerializable
,XMLSerializable.OldVersionCompatible
,SequenceTrack.Manager.Provider
,SequenceGapInformation.Provider
- Direct Known Subclasses:
DefaultAminoAcidSequence
,DefaultNucleotideSequence
public abstract class DefaultSequenceDocument extends AbstractPluginDocument implements SequenceDocument, EditableSequenceDocument, Renamable, SequenceTrack.Manager.Provider, SequenceGapInformation.Provider, XMLSerializable.OldVersionCompatible
A default implementation of a sequence document.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
DefaultSequenceDocument.Cache
Used for controlling caching of the char sequence and annotations controlled from this class.-
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.sequence.SequenceDocument
SequenceDocument.Alphabet, SequenceDocument.Transformer
-
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.sequence.SequenceDocument
GENOME_SEQUENCE_THRESHOLD
-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
ROOT_ELEMENT_NAME
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
DefaultSequenceDocument()
Construct a DefaultSequenceDocument with no arguments.protected
DefaultSequenceDocument(SequenceDocument sequence, java.util.Date created)
Construct a new DefaultSequenceDocument from an existing SequenceDocument.protected
DefaultSequenceDocument(java.lang.String name, java.lang.String description, java.lang.CharSequence sequence, java.util.Date created)
protected
DefaultSequenceDocument(java.lang.String name, java.lang.String description, java.lang.CharSequence sequence, java.util.Date created, URN urn)
protected
DefaultSequenceDocument(jebl.evolution.sequences.Sequence jeblSequence)
Construct a new DefaultSequenceDocument using a Sequence from JEBL.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addSequenceAnnotation(SequenceAnnotation annotation)
Add a sequence annotation to this document.static java.util.List<SequenceAnnotation>
annotationsFromXML(org.jdom.Element annotationsElement)
Return a List of SequenceAnnotations from a JDOM XML Element.void
copySequenceTracksFrom(SequenceDocument sourceSequence)
Copies allSequenceTracks
(if any) from the source sequence on to this sequence.DefaultSequenceDocument
createCopy()
Creates a copy of this sequenceDefaultSequenceDocument
createCopy(boolean allowReturningNonStandardImplementations)
Creates a copy of this sequencevoid
fromXML(org.jdom.Element root)
Restore the object from the JDOM Element returned byXMLSerializable.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.java.lang.String
getDescription()
A human readable single line of text describing this document, to appear in the description field in the document table.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.lang.String
getName()
A short name (preferably one or two words) for the document.java.util.List<SequenceAnnotation>
getSequenceAnnotations()
Gets sequence annotations which are directly on the sequence.SequenceGapInformation
getSequenceGapInformation()
Gets SequenceGapInformation associated with the char sequence returned fromgetCharSequence()
SequenceGapInformation
getSequenceGapInformation(boolean createIfNull)
Returns a SequenceGapInformation associated with this sequence.int
getSequenceLength()
Returns the length of the sequence.java.lang.String
getSequenceString()
Get the sequence as a string.SequenceTrack.Manager
getTrackManager(boolean mayReturnNullIfNoTracks)
Gets aSequenceTrack.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 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
isBestSerializedToXmlRatherThanBinaryFormat()
Returns true if this sequence would be best serialized usingtoXML()
rather thanwriteObject(java.io.DataOutput, jebl.util.ProgressListener)
.boolean
isCircular()
Is this a circular sequence?boolean
isStandardImplementation()
Returns true if this sequence implementation is eitherDefaultNucleotideSequence
orDefaultAminoAcidSequence
orDefaultNucleotideGraphSequence
.static DefaultSequenceDocument
readObject(GeneiousObjectInputStream in)
Recreates a sequence from a stream previously written to usingwriteObject(com.biomatters.geneious.publicapi.documents.sequence.GeneiousObjectOutputStream , jebl.util.ProgressListener)
static DefaultSequenceDocument
readObject(java.io.DataInput in)
Recreates a sequence from a stream previously written to usingwriteObject(java.io.DataOutput, jebl.util.ProgressListener)
static org.jdom.Element
sequenceAnnotationsToXML(Geneious.MajorVersion version, java.lang.String elementName, java.util.List<SequenceAnnotation> annotations)
Return a list of sequence annotations as XML in the specified version of Geneiousstatic org.jdom.Element
sequenceAnnotationsToXML(java.lang.String elementName, java.util.List<SequenceAnnotation> annotations)
Return a list of sequence annotations as XML.void
setAnnotations(java.util.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 fromgetCharSequence()
andgetSequenceAnnotations()
.void
setCircular(boolean isCircular)
Set whether this sequence is circular.void
setDescription(java.lang.String description)
Sets the description of this sequence.void
setFieldValue(java.lang.String code, java.lang.Object value)
Set value of one data item (field).
It is important to callAbstractPluginDocument.addDisplayableField(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
setModified(boolean modifiedFromOriginal)
Sets whether or not this sequence has been modified from its original.void
setName(java.lang.String name)
Change the name of the sequence.void
setSequenceAndAnnotations(java.lang.CharSequence sequence, java.util.List<SequenceAnnotation> annotations)
Sets the sequence and annotations of this document.java.lang.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, jebl.util.ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.void
writeObject(GeneiousObjectOutputStream out, jebl.util.ProgressListener progressListener)
Writes this sequence to a stream as specified bySerializable
.void
writeObject(Geneious.MajorVersion version, java.io.DataOutput out, jebl.util.ProgressListener progressListener)
Writes this sequence to a stream as specified bySerializable
.void
writeObject(java.io.DataOutput out, jebl.util.ProgressListener progressListener)
Equivalent towriteObject
(Geneious.getMajorVersion(), out, progressListener)-
Methods inherited from class com.biomatters.geneious.publicapi.documents.AbstractPluginDocument
addDisplayableField, addReferencedDocumentUrn, clearReferencedDocumentUrns, createFromBaseElement, getBaseElement, getBaseElementString, getCreationDate, getFieldValueCodes, getReferencedDocumentUrns, getURN, hasProperties, setBaseElement, setCreated, setFieldValue, setFieldValues, setURN
-
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
getCreationDate, getURN
-
-
-
-
Constructor Detail
-
DefaultSequenceDocument
protected DefaultSequenceDocument(java.lang.String name, java.lang.String description, java.lang.CharSequence sequence, java.util.Date created)
- Parameters:
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.
-
DefaultSequenceDocument
protected DefaultSequenceDocument(java.lang.String name, java.lang.String description, java.lang.CharSequence sequence, java.util.Date created, URN urn)
- Parameters:
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.
-
DefaultSequenceDocument
protected DefaultSequenceDocument(SequenceDocument sequence, java.util.Date created)
Construct a new DefaultSequenceDocument from an existing SequenceDocument.- Parameters:
sequence
- an existing SequenceDocumentcreated
- sequence creation time
-
DefaultSequenceDocument
protected DefaultSequenceDocument()
Construct a DefaultSequenceDocument with no arguments.
-
DefaultSequenceDocument
protected DefaultSequenceDocument(jebl.evolution.sequences.Sequence jeblSequence)
Construct a new DefaultSequenceDocument using a Sequence from JEBL.- Parameters:
jeblSequence
- a JEBL Sequence
-
-
Method Detail
-
getSequenceAnnotations
public java.util.List<SequenceAnnotation> getSequenceAnnotations()
Description copied from interface:SequenceDocument
Gets sequence annotations which are directly on the sequence. This does not include annotations onsequence tracks
.
To get all annotations, including those on sequence tracks, useSequenceUtilities.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)
WARNING: this list may not include all SequenceAnnotations represented as annotations in the sequence viewer. One such case is with trim annotations, which should be found usingSequenceUtilities.getSequenceAnnotationsIncludingImmutableSequencesTrims(SequenceDocument)
.
This may also return annotations that are not visible in the sequence viewer, such asSequenceAnnotation.TYPE_EXTRACTED_REGION
.- Specified by:
getSequenceAnnotations
in interfaceSequenceDocument
- Returns:
- a list of SequenceAnnotations; must not return null, but may return an
empty list (e.g.
Collections.emptyList()
). - See Also:
SequenceUtilities.getSequenceAndTrackAnnotations(SequenceDocument)
,SequenceDocumentWithEditableAnnotations.setAnnotations(java.util.List)
-
addSequenceAnnotation
public void addSequenceAnnotation(SequenceAnnotation annotation)
Add a sequence annotation to this document.- Parameters:
annotation
- a SequenceAnnotation
-
getName
public java.lang.String getName()
Description copied from interface:PluginDocument
A short name (preferably one or two words) for the document. If this PluginDocument is wrapped inside anAnnotatedPluginDocument
then this method will be overridden and delegate back toAnnotatedPluginDocument.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.- Specified by:
getName
in interfacePluginDocument
- Returns:
- document name. Cannot be null but may be an empty string.
-
setName
public void setName(java.lang.String name)
Change the name of the sequence. Note that if this sequence is wrapped by anAnnotatedPluginDocument
then a call to this method will not have any effect. This is because AnnotatedPluginDocument overrides calls toPluginDocument.getName()
on the document it wraps. Instead you should callAnnotatedPluginDocument.setName(String)
in most cases.
-
getDescription
public java.lang.String getDescription()
Description copied from interface:PluginDocument
A human readable single line of text describing this document, to appear in the description field in the document table.- Specified by:
getDescription
in interfacePluginDocument
- Returns:
- a one line simple text description of the document, or null if no description is available.
-
setDescription
public void setDescription(java.lang.String description)
Sets the description of this sequence. Note that if this sequence is wrapped by anAnnotatedPluginDocument
then (likesetName
) a call to this method may not have any effect. This is because AnnotatedPluginDocument overrides calls toPluginDocument.getDescription()
on the document it wraps. Instead you should callAnnotatedPluginDocument.setFieldValue
(DocumentField.DESCRIPTION_FIELD
,value) in those cases.- Parameters:
description
- the new description for this document
-
setFieldValue
public void setFieldValue(java.lang.String code, java.lang.Object value)
Description copied from class:AbstractPluginDocument
Set value of one data item (field).
It is important to callAbstractPluginDocument.addDisplayableField(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.- Overrides:
setFieldValue
in classAbstractPluginDocument
- Parameters:
code
- field codevalue
- item value- See Also:
AbstractPluginDocument.setFieldValue(DocumentField, Object)
-
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
- Overrides:
getFieldValue
in classAbstractPluginDocument
- 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()
.
-
getSequenceString
public final java.lang.String getSequenceString()
Description copied from interface:SequenceDocument
Get the sequence as a string. For nucleotide or amino acid sequences, each residue or ambiguity symbol is represented by one uppercase or lowercase character as per the IUPAC recommendations. For nucleotide sequences, any of the following are valid characters "ACGTURYMWSKBDHVN?-acgturymwskbdhvn" For amino acid sequences, any of the following are valid characters "ACDEFGHIKLMNPQRSTVWY*OUBJZX?-acdefghiklmnpqrstvwyoubjzx" Gap characters (-) are only allowed on sequences within aSequenceAlignmentDocument
. Stand-alone sequences may not contain gaps. IfSequenceDocument.getCharSequence()
doesn't call this method, then one possible implementation for this method is the following:return getCharSequence().toString();
WARNING: It is generally a bad idea to use this method on anything but very short sequences. On large sequences (e.g. whole chromosomes) this method may take some time and may use significant amounts of memory. e.g. A String representation of human chr1 requires 500 MB of memory. It is preferable to use
SequenceDocument.getCharSequence()
instead.- Specified by:
getSequenceString
in interfaceSequenceDocument
- Returns:
- the sequence as a string; must not return null.
- See Also:
SequenceDocument.getCharSequence()
-
getSequenceLength
public final int getSequenceLength()
Description copied from interface:SequenceDocument
Returns the length of the sequence. This returns exactly the same asgetCharSequence()
.length()
, but may be more performant on some implementations.- Specified by:
getSequenceLength
in interfaceSequenceDocument
- Returns:
- The length of this document's sequence.
Note that if a class implements both this interface and
NucleotideGraph
, the return value of this method must be consistent with the contracts from both interfaces.
-
getCharSequence
public final SequenceCharSequence getCharSequence()
Description copied from interface:SequenceDocument
Get the sequence as a CharSequence. Used as an alternative toSequenceDocument.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()
andCharSequence.charAt(int)
. If a SequenceDocument is editable and changes are made to it, it is required that the original CharSequence obtained fromSequenceDocument.getCharSequence()
not change. A client of the SequenceDocument is only able to obtain the changes by making a fresh call toSequenceDocument.getCharSequence()
. IfSequenceDocument.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.
- Specified by:
getCharSequence
in interfaceSequenceDocument
- Returns:
- the sequence as a SequenceCharSequence; must not return null.
- See Also:
SequenceDocument.getSequenceString()
-
setCache
public void setCache(DefaultSequenceDocument.Cache cache)
Sets the cache used for caching the vaules returned fromgetCharSequence()
andgetSequenceAnnotations()
. 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.- Parameters:
cache
- the cache to use- Since:
- API 4.50 (Geneious 5.5.0)
-
getSequenceGapInformation
public SequenceGapInformation getSequenceGapInformation()
Gets SequenceGapInformation associated with the char sequence returned fromgetCharSequence()
- Returns:
- SequenceGapInformation associated with the char sequence returned from
getCharSequence()
- Since:
- API 4.50 (Geneious 5.5.0)
-
getSequenceGapInformation
public SequenceGapInformation getSequenceGapInformation(boolean createIfNull)
Description copied from interface:SequenceGapInformation.Provider
Returns a SequenceGapInformation associated with this sequence.- Specified by:
getSequenceGapInformation
in interfaceSequenceGapInformation.Provider
- Parameters:
createIfNull
- 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.- Returns:
- a SequenceGapInformation associated with this sequence or potentially null if createIfNecessary is false
-
setSequenceAndAnnotations
public void setSequenceAndAnnotations(java.lang.CharSequence sequence, java.util.List<SequenceAnnotation> annotations)
Description copied from interface:EditableSequenceDocument
Sets the sequence and annotations of this document. This does not replace annotations onSequenceTracks
If this changes the length of the sequence, this is only allowed if this document is not a NucleotideGraphSequence (because the graph site positions and qualities would have to be updated too by callingEditableNucleotideGraphSequenceDocument.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()); }
- Specified by:
setSequenceAndAnnotations
in interfaceEditableSequenceDocument
- Parameters:
sequence
- new residues; NOTE: This CharSequence must not change its length or characters after it was passed to this method!annotations
- new annotations
-
setAnnotations
public void setAnnotations(java.util.List<SequenceAnnotation> annotations)
Description copied from interface:SequenceDocumentWithEditableAnnotations
Sets new annotations on this document, replacing the existing ones. This does not replace annotations onSequenceTracks
- Specified by:
setAnnotations
in interfaceSequenceDocumentWithEditableAnnotations
- Parameters:
annotations
- New annotations to set on this document.- See Also:
SequenceDocument.getSequenceAnnotations()
-
setModified
public void setModified(boolean modifiedFromOriginal)
Sets whether or not this sequence has been modified from its original. Core Geneious calls this method when necessary so you don't normally need to call it, but you may override it in your own subclass if you want to record the modified state of the sequence. The default implementation does nothing.
As an example, this is used by Genbank documents to display a note in the Text View informing the user if a sequence has been modified since it was downloaded from NCBI.- Parameters:
modifiedFromOriginal
- whether this document is a modified version of the original. May be set to false if changes are made that are not considered as modification or to remove a previously set flag.- Since:
- API 4.910 (Geneious 9.1.0)
-
toHTML
public java.lang.String toHTML()
Description copied from interface:PluginDocument
Provide a textual view of document. The contents should be at most 30K-60K characters. One reason is that this text is rendered using JTextPane, which is horrendously slow when handling large text. The more fundamental reason is that large amounts of text are generally not useful for a user. The whole idea of using a tool such as Geneious is to provide specialized viewers which make the large amount of bioinformatics data perceivable and comprehensible to a human user. Return an HTML body fragment (i.e. a fragment which sits inside a <body></body> tag). (Header,stylesheet and annotations are automatically added by GENEious code). Can optionally return an entire html tag set, as long as the first six characters are<html>
- Specified by:
toHTML
in interfacePluginDocument
- Returns:
- an HTML fragment of tag set, or null to have no text view.
-
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
- Overrides:
getDisplayableFields
in classAbstractPluginDocument
- Returns:
- a list of document fields (or null to indicate no displayable fields)
-
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
- Overrides:
getVersionSupport
in classAbstractPluginDocument
- 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
- Overrides:
toXML
in classAbstractPluginDocument
- 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
- Overrides:
toXML
in classAbstractPluginDocument
- 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
-
getAnnotationsRevisionNumber
public int getAnnotationsRevisionNumber()
Gets a revision number associated with the annotations. The revision number is incremented every time annotations (those returned fromgetSequenceAnnotations()
) are changed on this sequence.- Returns:
- a revision number associated with the annotations
- Since:
- API 4.50 (Geneious 5.5.0)
-
getCharSequenceRevisionNumber
public int getCharSequenceRevisionNumber()
Gets a revision number associated with the char sequence. The revision number is incremented every time char sequence (returned fromgetCharSequence()
is changed on this sequence.- Returns:
- a revision number associated with the char sequence
- Since:
- API 4.50 (Geneious 5.5.0)
-
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
- Overrides:
fromXML
in classAbstractPluginDocument
- Parameters:
root
- representation from a previous call toXMLSerializable.toXML()
- Throws:
XMLSerializationException
- if the Element can't be converted into this type of object
-
sequenceAnnotationsToXML
public static org.jdom.Element sequenceAnnotationsToXML(java.lang.String elementName, java.util.List<SequenceAnnotation> annotations)
Return a list of sequence annotations as XML.- Parameters:
elementName
- the name of the root XML Elementannotations
- a List of SequenceAnnotations- Returns:
- a JDOM XML Element
-
sequenceAnnotationsToXML
public static org.jdom.Element sequenceAnnotationsToXML(Geneious.MajorVersion version, java.lang.String elementName, java.util.List<SequenceAnnotation> annotations)
Return a list of sequence annotations as XML in the specified version of Geneious- Parameters:
version
- the major version of Geneious to ensure the annotations are readable in.elementName
- the name of the root XML Elementannotations
- a List of SequenceAnnotations- Returns:
- a JDOM XML Element
- Since:
- API 4.600 (Geneious 6.0.0)
-
annotationsFromXML
public static java.util.List<SequenceAnnotation> annotationsFromXML(org.jdom.Element annotationsElement) throws XMLSerializationException
Return a List of SequenceAnnotations from a JDOM XML Element.- Parameters:
annotationsElement
- a JDOM XML Element- Returns:
- a List of SequenceAnnotations
- Throws:
XMLSerializationException
- if the annotations cannot be deserialized
-
isCircular
public boolean isCircular()
Is this a circular sequence?- Specified by:
isCircular
in interfaceSequenceDocument
- Returns:
- true if this a circular sequence.
-
setCircular
public void setCircular(boolean isCircular)
Set whether this sequence is circular.- Specified by:
setCircular
in interfaceEditableSequenceDocument
- Parameters:
isCircular
- true if this sequence should be considered circular.- See Also:
SequenceDocument.isCircular()
-
isStandardImplementation
public final boolean isStandardImplementation()
Returns true if this sequence implementation is eitherDefaultNucleotideSequence
orDefaultAminoAcidSequence
orDefaultNucleotideGraphSequence
. Returns false for any implementation that is not one of these and is a sub-class of one of these.- Returns:
- true if this sequence implementation is either
DefaultNucleotideSequence
orDefaultAminoAcidSequence
orDefaultNucleotideGraphSequence
.
-
isBestSerializedToXmlRatherThanBinaryFormat
public final boolean isBestSerializedToXmlRatherThanBinaryFormat()
Returns true if this sequence would be best serialized usingtoXML()
rather thanwriteObject(java.io.DataOutput, jebl.util.ProgressListener)
. This method is mainly intended for core Geneious usage. Plugin developers probably don't need to use it.- Returns:
- true if this sequence would be best serialized using
toXML()
rather thanwriteObject(java.io.DataOutput, jebl.util.ProgressListener)
- Since:
- API 4.50 (Geneious 5.5.0)
-
writeObject
public void writeObject(GeneiousObjectOutputStream out, jebl.util.ProgressListener progressListener) throws java.io.IOException
Writes this sequence to a stream as specified bySerializable
. The object can be deserialized usingreadObject(com.biomatters.geneious.publicapi.documents.sequence.GeneiousObjectInputStream)
This method may only be called ifisStandardImplementation()
returns true. Furthermore, if this document returns a non-empty list fromAbstractPluginDocument.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.- Parameters:
out
- the stream to write to.progressListener
- for reporting progress and allowing the write to be canceled.- Throws:
java.io.IOException
- if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)
-
writeObject
public void writeObject(java.io.DataOutput out, jebl.util.ProgressListener progressListener) throws java.io.IOException
Equivalent towriteObject
(Geneious.getMajorVersion(), out, progressListener)- Parameters:
out
- the stream to write to.progressListener
- for reporting progress and allowing the write to be canceled.- Throws:
java.io.IOException
- if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)- Since:
- API 4.30 (Geneious 5.3.0)
-
writeObject
public void writeObject(Geneious.MajorVersion version, java.io.DataOutput out, jebl.util.ProgressListener progressListener) throws java.io.IOException
Writes this sequence to a stream as specified bySerializable
. The object can be deserialized usingreadObject(java.io.DataInput)
This method may only be called ifisStandardImplementation()
returns true. Furthermore, if this document returns a non-empty list fromAbstractPluginDocument.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.- Parameters:
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.- Throws:
java.io.IOException
- if the write cannot be completed for any reason (including if the progress listener requests the operation be canceled)- Since:
- API 4.600 (Geneious 6.0.0)
-
readObject
public static DefaultSequenceDocument readObject(GeneiousObjectInputStream in) throws XMLSerializationException
Recreates a sequence from a stream previously written to usingwriteObject(com.biomatters.geneious.publicapi.documents.sequence.GeneiousObjectOutputStream , jebl.util.ProgressListener)
- Parameters:
in
- the stream to read from- Returns:
- the deserialized sequence
- Throws:
XMLSerializationException
- if the sequence cannot be deserialized
-
readObject
public static DefaultSequenceDocument readObject(java.io.DataInput in) throws XMLSerializationException
Recreates a sequence from a stream previously written to usingwriteObject(java.io.DataOutput, jebl.util.ProgressListener)
- Parameters:
in
- the stream to read from- Returns:
- the deserialized sequence
- Throws:
XMLSerializationException
- if the sequence cannot be deserialized- Since:
- API 4.30 (Geneious 5.3.0)
-
createCopy
public DefaultSequenceDocument createCopy()
Creates a copy of this sequence- Returns:
- a copy of this sequence
- Since:
- API 4.11 (Geneious 5.0)
-
createCopy
public DefaultSequenceDocument createCopy(boolean allowReturningNonStandardImplementations)
Creates a copy of this sequence- Parameters:
allowReturningNonStandardImplementations
- false to force this method to only return instances for whichisStandardImplementation()
is true. If in doubt, use true.- Returns:
- a copy of this sequence
- Since:
- API 4.801 (Geneious 8.0.1)
-
getTrackManager
public SequenceTrack.Manager getTrackManager(boolean mayReturnNullIfNoTracks)
Description copied from interface:SequenceTrack.Manager.Provider
Gets aSequenceTrack.Manager
associated with this sequence for providing sequence tracks. For detailed information on sequence tracks, seeSequenceTrack
. If this method is called on an alignment, the track manager is for the consensus sequence. Individual sequences in the alignment may also implementSequenceTrack.Manager.Provider
if they provide tracks.- Specified by:
getTrackManager
in interfaceSequenceTrack.Manager.Provider
- Parameters:
mayReturnNullIfNoTracks
- 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 tracks- Returns:
- a track manager or possibly null if mayReturnNullIfNoTracks is true
-
copySequenceTracksFrom
public void copySequenceTracksFrom(SequenceDocument sourceSequence)
Copies allSequenceTracks
(if any) from the source sequence on to this sequence.- Parameters:
sourceSequence
- the source sequence to copy tracks from- Since:
- API 4.50 (Geneious 5.5.0)
-
-