Package com.biomatters.geneious.publicapi.documents

Interface PluginDocument

    • Field Detail

      • FILE_DATA_ATTRIBUTE_NAME

        static final java.lang.String FILE_DATA_ATTRIBUTE_NAME
        A PluginDocument may choose to serialize some or all of its data to a file instead of to in memory XML. If it does it may create a temporary file name and return an XML element with this attribute whose value is the file name. Any WritableDatabaseService that stores such an element for a PluginDocument will store a copy of the contents of this file (or potentially a file system hard link to the temporary file) and when deserializing, provide a reference to a file containing the data. The PluginDocument must therefore never modify the contents of a temporary file it creates after it has provided it to a WritableDatabaseService and it must never modify the contents of a file it is provided with for deserialization purposes. Instead it should create a new file to hold any changes made. A single document may use references to multiple files by adding this attribute to multiple elements.

        For example, a PluginDocument may generate XML such as the following:
        <sequence> <name>My Sequence</name> <sequenceString xmlFileData="C:\temp\sequenceData.txt"/> </sequence>
        And when a document with that XML is saved to a WritableDatabaseService, the WritableDatabaseService will make a copy of the file and give back XML with the file name adjusted to point to its own copy of the file.

        It is recommended that PluginDocument implementations use FileUtilities.createTempFile for temporary file management, which supports automatically deleting temporary files once their names are no longer referenced.

        A PluginDocument may prefer to use DocumentUtilities.pluginDocumentFileDataToXml and DocumentUtilities.pluginDocumentFileDataFromXml instead of using this attribute directly. These methods support detection and gracefully handling the underlying file data being corrupted which is prone to happening on Windows systems that use a network drive for data storage.

        See Also:
        Constant Field Values

      • MAXIMUM_HTML_LENGTH

        static final int MAXIMUM_HTML_LENGTH
        toHTML() should not return a string greater in length to this. The Text view truncates anything that is longer.
        Since:
        API 4.60 (Geneious 5.6.0)
        See Also:
        Constant Field Values

    • Method Detail

      • getDisplayableFields

        java.util.List<DocumentField> getDisplayableFields()
        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 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.

        Returns:
        a list of document fields (or null to indicate no displayable fields)

      • getFieldValue

        java.lang.Object getFieldValue​(java.lang.String fieldCodeName)
        Get the value of a particular field.
        Parameters:
        fieldCodeName - field code. This should be the code of one of the fields returned from 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 from getDisplayableFields().

      • getName

        java.lang.String getName()
        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.

        Returns:
        document name. Cannot be null but may be an empty string.

      • getURN

        URN getURN()
        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.

        Returns:
        the urn, or null if this document doesn't have a unique identifier

      • getDescription

        java.lang.String getDescription()
        A human readable single line of text describing this document, to appear in the description field in the document table.
        Returns:
        a one line simple text description of the document, or null if no description is available.

      • toHTML

        java.lang.String toHTML()
        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>

        Returns:
        an HTML fragment of tag set, or null to have no text view.