Package com.biomatters.geneious.publicapi.plugin

Class DocumentOperation.OperationCallback

    • Constructor Detail

      • OperationCallback

        public OperationCallback()

    • Method Detail

      • setResumableState

        public void setResumableState​(org.jdom.Element e)
        Sets a resumable state for your operation. You should store all information that you need to resume the operation in the xml you pass in. You do not need to serialise the AnnotatedPluginDocuments, Options or SequenceSelections passed in to your operation - the same ones will be passed in when your operation is resumed.
        Parameters:
        e - all the information necessary to resume the operation, or null to set this operation to be non-resumable.

      • getResumableState

        public org.jdom.Element getResumableState()
        returns the persistent information that was set with the last call to setResumableState(org.jdom.Element) (this call may have been before the operation was paused)
        Returns:
        the persistent information stored in the last call to setResumableState(org.jdom.Element) (this call may have been before the operation was paused), or null if it was never called.

      • setSubFolder

        public void setSubFolder​(java.lang.String name)
                  throws DatabaseServiceException
        Specify the name of a subfolder that the results of the operation should go in. The callback handles creating the folder if necessary. Some callbacks may ignore this, eg. if another plugin is calling performOperation.

        This method can be called more than once.

        The subfolder is created immediately but will be deleted if the operation is canceled and the folder is empty.

        Parameters:
        name - name of the subfolder or null to not put the results in a subfolder. Defaults to null.
        Throws:
        DatabaseServiceException - if failed to create subfolder, in which case the parent folder is used. This exception may be ignored if that is acceptable
        Since:
        API 4.14 (Geneious 5.1)

      • setMarkUnselectedDocumentsUnread

        public void setMarkUnselectedDocumentsUnread​(boolean markUnselectedDocumentsUnread)
        Sets whether or not documents added to the callback that can't be immediately selected are marked as unread. An implementation may choose to ignore this request. The default behaviour is to mark unselectable documents as unread
        Parameters:
        markUnselectedDocumentsUnread -
        Since:
        API 4.710 (Geneious 7.1.0)

      • addDocument

        public final AnnotatedPluginDocument addDocument​(PluginDocument doc,
                                                 boolean dontSelectDocumentWhenComplete,
                                                 jebl.util.ProgressListener progress)
                                          throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        returns a document from the operaiton while the operation is still in progress.
        Parameters:
        doc - a document to return
        dontSelectDocumentWhenComplete - should Geneious select the document when the operation is complete
        Returns:
        an AnnotatedPluginDocument that contains the given PluginDocument
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the document could not be added for some reason.

      • addDocument

        public AnnotatedPluginDocument addDocument​(AnnotatedPluginDocument doc,
                                           boolean dontSelectDocumentWhenComplete,
                                           jebl.util.ProgressListener progress)
                                    throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        returns a document from the operation while the operation is still in progress.
        Parameters:
        doc - a document to return
        dontSelectDocumentWhenComplete - should Geneious select the document when the operation is complete
        Returns:
        either the given AnnotatedPluginDocument or a copy if the document was added to the local database.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the document could not be added for some reason.

      • setRemoteJobId

        public void setRemoteJobId​(GeneiousService service,
                           java.lang.String jobId)
        This method is only provided for core Geneious use when implementing a remote service such as a Geneious Server or a Green Button service. Plugin developers should never need to call or implement it, except when delegating a callback.
        Parameters:
        service - The location the operation is running. Must not be null.
        jobId - A unique identifier for a running operation. This identifier must be unique across all jobs for the service.
        Since:
        API 4.14 (Geneious 5.1)

      • setOptionsForActivelyLinkedDescendants

        public void setOptionsForActivelyLinkedDescendants​(org.jdom.Element optionsElement,
                                                   java.util.List<AnnotatedPluginDocument> inputDocuments,
                                                   java.util.List<AnnotatedPluginDocument> additionalParentDocuments,
                                                   java.lang.String additionalInformation)
                                            throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        This method will only have an effect if isInterestedInParentDescendants() returns true. If not, then this method won't do anything if you try and use it. Furthermore if an operation modifies input documents as part of providing parent/descendant functionality (for example adding invisible annotations) then it must not do that if isInterestedInParentDescendants() returns false.

        Creates an operation record that will include all descendant documents added afterwards using addDocument. These documents can be recreated later using DocumentOperation.getOptions(org.jdom.Element, List, List) in conjunction with a performOperation call. This method may be called multiple times for different sets of output from the operation. For example when batch creating results, each result may be produced as an independent parent/descendant data set that can be recreated later independently of other results.
        Parameters:
        optionsElement - an xml form of the options that, when deserialized, allows this operation to be rerun with exactly the same results as when it was first run in this (and any future) version of Geneious, using DocumentOperation.getOptions(org.jdom.Element, List, List). If the options never change between versions of Geneious, and the operation ignores the Sequence Selection, then this is as simple as calling Options.valuesToXML(String) and using Options.valuesFromXML(org.jdom.Element) in DocumentOperation.getOptions(org.jdom.Element, List, List).

        A robust implementation should ideally store a plugin version number in some form, and additionally should serialize the SequenceSelection if necessary, along with any other relevant information required to completely rerun the operation exactly. For example, call Options.valuesToXML() and then call setAttribute("version","2.3")

        This may be null to indicate that documents generated should not be actively linked.

        inputDocuments - those parent documents that should be supplied to performOperation as parameters for future runs of the operation. Most of the time this should be the input documents to the operation, except when performing a batch operation.

        additionalParentDocuments - those parent documents that shouldn't be supplied directly as parameters to performOperation, but that are supplied via some other mechanism (e.g. DocumentSelectionOption.DocumentChooser)).

        additionalInformation - additional information to show in the operation record (in addition to the operationId and the timeAtWhichOperationWasRun).
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if there is a problem writing to the database
        Since:
        API 4.910 (Geneious 9.1.0)

      • setAdditionalInformation

        public void setAdditionalInformation​(java.lang.String additionalInformation)
        Set additional information that is shown on the operation node in the Lineage tab
        Parameters:
        additionalInformation -
        Since:
        API 4.1011 (Geneious 10.1.1)
        See Also:
        OperationRecordDocument.setAdditionalInformation(String)

      • setOptionsForActivelyLinkedDescendants

        public void setOptionsForActivelyLinkedDescendants​(org.jdom.Element optionsElement,
                                                   java.util.List<AnnotatedPluginDocument> inputDocuments,
                                                   java.util.List<AnnotatedPluginDocument> additionalParentDocuments)
                                            throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        This method will only have an effect if isInterestedInParentDescendants() returns true. If not, then this method won't do anything if you try and use it. Furthermore if an operation modifies input documents as part of providing parent/descendant functionality (for example adding invisible annotations) then it must not do that if isInterestedInParentDescendants() returns false.

        Creates an operation record that will include all descendant documents added afterwards using addDocument. These documents can be recreated later using DocumentOperation.getOptions(org.jdom.Element, List, List) in conjunction with a performOperation call. This method may be called multiple times for different sets of output from the operation. For example when batch creating results, each result may be produced as an independent parent/descendant data set that can be recreated later independently of other results.
        Parameters:
        optionsElement - an xml form of the options that, when deserialized, allows this operation to be rerun with exactly the same results as when it was first run in this (and any future) version of Geneious, using DocumentOperation.getOptions(org.jdom.Element, List, List). If the options never change between versions of Geneious, and the operation ignores the Sequence Selection, then this is as simple as calling Options.valuesToXML(String) and using Options.valuesFromXML(org.jdom.Element) in DocumentOperation.getOptions(org.jdom.Element, List, List).

        A robust implementation should ideally store a plugin version number in some form, and additionally should serialize the SequenceSelection if necessary, along with any other relevant information required to completely rerun the operation exactly. For example, call Options.valuesToXML() and then call setAttribute("version","2.3")

        This may be null to indicate that documents generated should not be actively linked.

        inputDocuments - those parent documents that should be supplied to performOperation as parameters for future runs of the operation. Most of the time this should be the input documents to the operation, except when performing a batch operation.

        additionalParentDocuments - those parent documents that shouldn't be supplied directly as parameters to performOperation, but that are supplied via some other mechanism (e.g. DocumentSelectionOption.DocumentChooser)).
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if there is a problem writing to the database
        Since:
        API 4.60 (Geneious 5.6.0)

      • isInterestedInParentDescendants

        public boolean isInterestedInParentDescendants()
        Returns:
        true if the callback is interested in parent/descendants, and supports setOptionsForActivelyLinkedDescendants. You should diverge your code paths so that, for example, any additional work for parent/descendants you do such as creating invisible annotations on parent documents doesn't get done unnecessarily. If this returns false, then they shouldn't do that or make any other sort of changes to the parent/input documents
        Since:
        API 4.61 (Geneious 5.6.1)

      • stopCreatingOperationRecords

        public void stopCreatingOperationRecords()
                                  throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Stops any operation records from being created for subsequent documents added using addDocument. This can be undone for later documents you wish to add by calling setOptionsForActivelyLinkedDescendants(org.jdom.Element, List, List) - documents added subsequent to that call will then have records created in the manner described in by that method.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if a problem occurs
        Since:
        API 4.60 (Geneious 5.6.0)