Class AbstractPluginDocument

    • Constructor Detail

      • AbstractPluginDocument

        public AbstractPluginDocument​(java.util.Date created)
        Construct a new document with a given time of creation.
        Parameters:
        created - the date this document was created, or null to use the current date. The date will be serialized to XML by this document and then restored when the document is deserialized again from XML. See PluginDocument.getCreationDate().
      • AbstractPluginDocument

        public AbstractPluginDocument​(java.util.Date created,
                                      URN urn)
        Construct a new document with a given URN and time of creation.
        Parameters:
        created - the date this document was created, or null to use the current date. The date will be serialized to XML by this document and then restored when the document is deserialized again from XML. See PluginDocument.getCreationDate().
        urn - the urn for this document
      • AbstractPluginDocument

        public AbstractPluginDocument()
        Create a new document with a creation date taken from system clock.
    • Method Detail

      • getBaseElement

        public org.jdom.Element getBaseElement()
        A JDOM element holding document data.
        Returns:
        base element
      • getBaseElementString

        public java.lang.String getBaseElementString()
        Base element as a XML text fragment.
        Returns:
        XML text
      • setBaseElement

        public void setBaseElement​(org.jdom.Element baseElement)
        Set document base element.
        Parameters:
        baseElement - to set
      • createFromBaseElement

        public void createFromBaseElement​(org.jdom.Element element)
        Restore document from base element. Called during construction via fromXML(org.jdom.Element) to let document set any variables or fields from data inside base element. The code in the base class does nothing since the semantics of the base element are not known to it. Meaningful stuff happens only in subclasses which override this method.
        Parameters:
        element - saved base element
      • setFieldValue

        public void setFieldValue​(java.lang.String code,
                                  java.lang.Object value)
        Set value of one data item (field).
        It is important to call 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.
        Parameters:
        code - field code
        value - item value
        Throws:
        java.lang.IllegalArgumentException - if code was the code of DocumentField.CREATED_FIELD, and the associated value was not of type Date.
        See Also:
        setFieldValue(DocumentField, Object)
      • setFieldValue

        public void setFieldValue​(DocumentField field,
                                  java.lang.Object value)
        Set value of one data item (field). If this field is not currently a displayable field on this document, it will be added as a displayable field using addDisplayableField(DocumentField) unless value is null, in which case the displayable field will be removed
        Parameters:
        field - the field
        value - item value
        Since:
        API 4.610 (Geneious 6.1.0)
        See Also:
        setFieldValue(String, Object)
      • setFieldValues

        public void setFieldValues​(java.util.Map<java.lang.String,​java.lang.Object> fieldValues)
        Set all fields in one go. (Overrides any previous sets by setFieldValue and setFieldValues).
        Parameters:
        fieldValues - all values
      • getFieldValueCodes

        public java.util.List<java.lang.String> getFieldValueCodes()
        Gets the code of all fields stored in this document, including non-displayable fields. The codes returned are all codes which can be used to obtain field values via getFieldValue(String)
        Returns:
        the code of all fields stored in this document, including non-displayable fields.
        Since:
        API 4.50 (Geneious 5.5.0)
      • setURN

        protected final void setURN​(URN urn)
        Set document URN. Only needs to be set on initial creation of document. Not required on deserialization (fromXML()).
        Parameters:
        urn - to set
      • setCreated

        protected final void setCreated​(java.util.Date date)
        Set document date of creation.
        Parameters:
        date - to set
      • getURN

        public final URN getURN()
        Description copied from interface: PluginDocument
        A Universal Resource Name.

        Documents from external sources should set this to a unique name inside that service. Documents generated locally (such as from operations) and documents that don't have a unique identifier should return null since Geneious handles URNs for these.

        Specified by:
        getURN in interface PluginDocument
        Returns:
        the urn, or null if this document doesn't have a unique identifier
      • 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
        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.

        See XMLSerializable.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 interface XMLSerializable.OldVersionCompatible
        Parameters:
        version - the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". This must be a version returned greater or equal to a version returned from getVersionSupport(VersionSupportType.OldestVersionSerializableTo) and must never be greater than the current version (Geneious.getMajorVersion())
        progressListener - for reporting progress and cancelling
        Returns:
        object encoded as a JDOM element
      • fromXML

        public void fromXML​(org.jdom.Element root)
                     throws XMLSerializationException
        Description copied from interface: XMLSerializable
        Restore the object from the JDOM Element returned by XMLSerializable.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().

        Specified by:
        fromXML in interface XMLSerializable
        Parameters:
        root - representation from a previous call to XMLSerializable.toXML()
        Throws:
        XMLSerializationException - if the Element can't be converted into this type of object
      • addDisplayableField

        public void addDisplayableField​(DocumentField field)
        adds a displayable field to the document that is stored with the documents. Generally, most classes that subclass this class should implement getDisplayableFields() if they have a fixed list of displayable fields that does not vary with each instance of the document. If the field is already present, this method does nothing. addDisplayableField() should only be used for documents that vary the list of displayable fields with each instance of the document.
        Parameters:
        field - a DocumentField
      • getDisplayableFields

        public java.util.List<DocumentField> getDisplayableFields()
        Description copied from interface: PluginDocument
        A list of columns for display in the main document panel. This function only defines the columns available to display, not the particular values of these columns, which are returned 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
        Returns:
        a list of document fields (or null to indicate no displayable fields)
      • getReferencedDocumentUrns

        public java.util.List<URN> getReferencedDocumentUrns()
        This function can be called to retrieve the list of documents previously remembered using the addReferencedDocumentUrn(URN) function. Note: if the user has deleted one or more of the referenced documents from their local database, then those documents still be available via this function. Documents are not really deleted (just hidden from the user) until all documents that reference it are also deleted.
        Returns:
        the list of referenced documents
      • clearReferencedDocumentUrns

        public void clearReferencedDocumentUrns()
        Clears the list of all referenced docments previously added using addReferencedDocumentUrn(URN).
      • hasProperties

        public boolean hasProperties()
        Returns:
        true if the AbstractPluginDocument part of the implementation of this document stores any properties. If this is false, AbstractPluginDocument.toXML will return an empty element.