Package com.biomatters.geneious.publicapi.implementations.sequence

Class DefaultSequenceDocument

    • 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 null
        description - sequence descriptions (may be null or "")
        sequence - sequence as a string
        created - 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 null
        description - sequence descriptions (may be null or "")
        sequence - sequence as a string
        created - 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 SequenceDocument
        created - 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

      • 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 an AnnotatedPluginDocument 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.

        Specified by:
        getName in interface PluginDocument
        Returns:
        document name. Cannot be null but may be an empty string.

      • 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 interface PluginDocument
        Returns:
        a one line simple text description of the document, or null if no description is available.

      • 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 a SequenceAlignmentDocument. Stand-alone sequences may not contain gaps.

        If SequenceDocument.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 interface SequenceDocument
        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 as getCharSequence().length(), but may be more performant on some implementations.
        Specified by:
        getSequenceLength in interface SequenceDocument
        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 to SequenceDocument.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.

        Specified by:
        getCharSequence in interface SequenceDocument
        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 from 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.
        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 from getCharSequence()
        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 interface SequenceGapInformation.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 on SequenceTracks

        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 calling 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());
 }
        Specified by:
        setSequenceAndAnnotations in interface EditableSequenceDocument
        Parameters:
        sequence - new residues; NOTE: This CharSequence must not change its length or characters after it was passed to this method!
        annotations - new annotations

      • 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 interface PluginDocument
        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 by PluginDocument.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.

        Specified by:
        getDisplayableFields in interface PluginDocument
        Overrides:
        getDisplayableFields in class AbstractPluginDocument
        Returns:
        a list of document fields (or null to indicate no displayable fields)

      • toXML

        public org.jdom.Element toXML()
        Description copied from interface: XMLSerializable
        Convert object to a JDOM element. The representation should be complete so that XMLSerializable.fromXML(org.jdom.Element) can completely restore the object's 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.

        Specified by:
        toXML in interface XMLSerializable
        Overrides:
        toXML in class AbstractPluginDocument
        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 from getSequenceAnnotations()) 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 from getCharSequence() is changed on this sequence.
        Returns:
        a revision number associated with the char sequence
        Since:
        API 4.50 (Geneious 5.5.0)

      • 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 Element
        annotations - 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 Element
        annotations - 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 interface SequenceDocument
        Returns:
        true if this a circular sequence.

      • writeObject

        public void writeObject​(GeneiousObjectOutputStream out,
                        jebl.util.ProgressListener progressListener)
                 throws java.io.IOException
        Writes this sequence to a stream as specified by 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.

        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 to writeObject(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 by 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.

        Parameters:
        version - the Geneious version to ensure the data is compatible with
        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.600 (Geneious 6.0.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 which isStandardImplementation() 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 a SequenceTrack.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.
        Specified by:
        getTrackManager in interface SequenceTrack.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 all SequenceTracks (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)