Package com.biomatters.geneious.publicapi.plugin

Class DocumentOperation

java.lang.Object
com.biomatters.geneious.publicapi.plugin.DocumentOperation
Direct Known Subclasses:
DocumentOperation.Wrapper, GeneiousGridDocumentOperation
public abstract class DocumentOperation extends Object
A DocumentOperation creates a new document from a set of existing documents (or from no documents).
The DocumentOperation displays an optional OptionsPanel (a JPanel), and then performs an operation on the set of documents that the user has selected. The document(s) that the operation creates are stored in the currently selected repository.
You can control what document types, and number of documents are allowed to be acted upon by the action by returning a series of DocumentSelectionSignature objects in the getSelectionSignatures() method.

A plugin may provide a set of document operations via GeneiousPlugin.getDocumentOperations().

The following example shows how to create a documentOperation that creates a new sequence based on user input as an anonymous inner class. 


 new DocumentOperation(){

       //This method is so this DocumentOperation can be returned by PluginUtilities.getDocumentOperation(String id);
       public String getUniqueId() {
           return "New_Sequence";
       }


       //GeneiousActionOptions specify how the action is going to be displayed within Geneious.
       //in this case it is going to be displayed on the toolbar with the label "New Sequence", and the pencil icon.
       public GeneiousActionOptions getActionOptions(){
           return new GeneiousActionOptions("New Sequence").setInMainToolbar(true);
       }

       public String getHelp(){
           return "This operation creates a <b>New Sequence</b>";
       }

       //DocumentSelection signatures define what types of documents (and numbers of documents) the operation can take.
       //in this case we do not need to take documents, so we can just return an empty set.
       public DocumentSelectionSignature[] getSelectionSignatures(){
           return new DocumentSelectionSignature[0];
       }

       //Geneious will display the Options returned from this method as a panel before calling performOperation().
       public Options getOptions(AnnotatedPluginDocument[] docs){
           Options options = new Options(this.getClass());
           //Genieous will identify this option by the "nameinvalid input: '&quot' parameter we pass in.
           //We can get this value later in the performOperation method by referring to this name.
           Options.MultipleLineStringOption stringOption = options.addMultipleLineStringOption("residues", "", "",5,true);
           return options;
       }

       //This is the method that does all the work.  Geneious passes a list of the documents that were selected when the user
       //started the operation, a progressListener, and the options that we returned in the getOptions() method above.
       public List performOperation(AnnotatedPluginDocument[] docs, ProgressListener progress, Options options){
           //lets create the list that we're going to return...
           ArrayList sequenceList = new ArrayList();

           //The options that we created in the getOptions() method above has been passed to us, hopefully the user has filled in their sequence.
           //We get the option we added by using its name.  MultiLineStringOption has a String ValueType, so we can safely cast to a String object.
           String residues = (String)options.getValue("residues");

           //lets construct a new sequence document from the residues that the user entered
           AminoAcidSequenceDocument sequence = new DefaultAminoAcidSequence("New Sequence","A new Sequence",residues,new Date());

           //and add it to the list
           sequenceList.add(DocumentUtilities.createAnnotatedPluginDocument(sequence));

           //normaly we would set the progress incrimentaly as we went, but this operation is quick so we just set it to finished when we're done.
           progress.setProgress(1.0);

           //return the list containing the sequence we just created, and we're done!
           return sequenceList;
      }
   }

  • Constructor Details

    • DocumentOperation

      public DocumentOperation()

  • Method Details

    • getActionOptions

      public abstract GeneiousActionOptions getActionOptions()
      GeneiousActionOptions contains all the important status information including name, description, icon, where the action is displayed in the interface etc.
      Returns:
      options for action; must not be null

    • getHelp

      public abstract String getHelp()
      Help for this operation in the form of HTML or plain text. This should give a brief description of any selection signatures this operation can act on and what the effect is. See some of the standard operations in Geneious for examples (eg. Alignment).

      This text is displayed when the user tries to perform the operation on documents which do not match the selection signature or if the user clicks the help button in the operation's options panel.

      May return null.

      An operation that wants to provide more detailed help on how to use it should implement Options.getOptionsHelp() on the Options returned from getOptions

      Returns:
      the help
      See Also:

    • getSelectionSignatures

      public abstract DocumentSelectionSignature[] getSelectionSignatures()
      Specifies the type of documents this operation accepts as input. When documents that match at least one of the selection signatures are selected in the document table, the operation will be enabled.

      For example an operation that accepts 1 or 2 nucleotide sequences could use
      return new DocumentSelectionSignature[] {new DocumentSelectionSignature(NucleotideSequenceDocument.class,1,2)}}
      However, NucleotideSequenceDocuments are a special case and it is recommended to use DocumentSelectionSignature.forNucleotideSequences(int, int, boolean) instead when the operation may accept either stand-alone sequences or SequenceListDocuments as input.

      If an operation accepts no documents as input, it should return an empty array and the operation will always be enabled but won't be passed any documents as input.

      Returns:
      all supported signatures, at least one of which must match the selected documents for the operation to be enabled. Cannot be null but may be an empty array.

    • getOptions

      public Options getOptions(AnnotatedPluginDocument... documents) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      Provides some options applicable to this document operation to the user. This is guaranteed to be called before any of the performOperation methods. The user can click "Cancel" at this point and performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, com.biomatters.geneious.publicapi.plugin.Options) will not be called The same Options object will be passed to performOperation if the user clicks "Ok". The necessary values can then be extracted from it.

      Example 1: Use Options class directly.

       public Options getOptions(final AnnotatedPluginDocument[] documents) throws DocumentOperationException {
     Options options = new Options(getClass());
     options.addBooleanOption("optionName", "text displayed the user", true);
     return options;
 }

 public List<AnnotatedPluginDocument> performOperation(AnnotatedPluginDocument[] documentListx,
          ProgressListener progressListener, Options options) throws DocumentOperationException {
      boolean checkboxSelected=(Boolean)options.getValue("optionName");
      ...
 }
      Example 2: Subclass Options. Useful for more complicated options where you want to improve code separation and avoid referring to options via their String names.
      
 private static class MyOptions extends Options {
     private BooleanOption sampleOption;

     public MyOptions() {
         sampleOption=addBooleanOption("sampleOption", "text displayed the user", true);
     }

     public boolean isSampleOption() {
         return sampleOption.getValue();
     }
 }

 public Options getOptions(final AnnotatedPluginDocument[] documents) throws DocumentOperationException {
     return new MyOptions();
 }

 public List<AnnotatedPluginDocument> performOperation(AnnotatedPluginDocument[] documentList, ProgressListener progressListener, Options options) throws DocumentOperationException {
     MyOptions myOptions= (MyOptions) options; // Since an instance of MyOptions is always returned from getOptions, this cast is always valid.
     boolean sampleOptionSelected = myOptions.isSampleOption();
      ...
 }
      For more information, see Options.

      This method may be invoked from either the swing thread or a non-swing thread.

      Parameters:
      documents - the currently selected documents so that the panel can contain different options depending on these. This can be ignored in most cases.
      Returns:
      options that can be displayed to the user or null if this operation has no options. The default implementation returns null.
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if obtaining the options for this operation is unsuccessful for any reason

    • getOptions

      public Options getOptions(SequenceSelection sequenceSelection, AnnotatedPluginDocument... documents) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      More powerful alternative to getOptions(AnnotatedPluginDocument[]) which may provide the currently selected region of any sequence in the documents. eg. if a region of a sequence is selected in the Sequence View then the selection will be passed in.

      This method may be invoked from either the swing thread or a non-swing thread.

      Parameters:
      sequenceSelection - the currently selected region of any sequence in the documents, never null but may be an empty selection
      documents - the currently selected documents so that the panel can contain different options depending on these. This can be ignored in most cases.
      Returns:
      options that can be displayed to the user or null if this operation has no options. The default implementation returns null.
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the obtaining the options for this operation is unsuccessful for any reason
      See Also:

    • getOptions

      public Options getOptions(DocumentOperationInput operationInput) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      More powerful alternative to getOptions(AnnotatedPluginDocument[]) which may provide additional values such as the location the operation is run and the currently selected region of any sequence in the documents. eg. if a region of a sequence is selected in the Sequence View then the selection will be passed in.

      Operations that have Options that need to change state depending on which GeneiousService the operation is run on should implement this method and register a listener on the results of DocumentOperationInput.getLocationOptions() by calling OperationLocationOptions.addLocationChangedListener(com.biomatters.geneious.publicapi.plugin.OperationLocationOptions.LocationChangedListener)

      This method may be invoked from either the swing thread or a non-swing thread.

      Parameters:
      operationInput - the data being used as input to the operation. This contains information such as the selected documents.
      Returns:
      options that can be displayed to the user or null if this operation has no options. The default implementation returns null.
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the obtaining the options for this operation is unsuccessful for any reason
      Since:
      API 4.14 (Geneious 5.1)
      See Also:

    • getGeneralOptions

      public Options getGeneralOptions() throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      Gets some Options that work for this document operation when invoked on any set of input sequences. Document operations should implement getGeneralOptions in order for them to be configurable from Workflows.
      Returns:
      some Options suitable for running on any supported set of input documents. This options will never be passed directly to a performOperation call. Instead, getOptions will be called at runtime and any applicable option values will be copied from the general options to the specific options using Options.valuesToXML(String) and Options.valuesFromXML(org.jdom.Element)
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if this document operation does not support general options.
      Since:
      API 4.700 (Geneious 7.0.0)

    • getOptions

      public final Options getOptions(List<AnnotatedPluginDocument> documents) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      A convenience method for calling getOptions(AnnotatedPluginDocument[])

      This method may be invoked from either the swing thread or a non-swing thread.

      Parameters:
      documents - the documents to apply the operation to
      Returns:
      options that can be displayed to the user or null if this operation has no options.
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the obtaining the options for this operation is unsuccessful for any reason

    • getOrderDependentOperationMessage

      public String getOrderDependentOperationMessage()
      Support for operations caring about the order of similarily typed documents.

      A document operation may return a non null message so that a user will be prompted to choose the ordering of the documents before they are passed to the operation. Message text is shown to the user in the ordering dialog.

      Returns:
      message text

    • performOperation

      public List<AnnotatedPluginDocument> performOperation(AnnotatedPluginDocument[] annotatedDocuments, ProgressListener progressListener, Options options) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      Create document(s) from a set of documents.

      The document may use the URNs of documents in documents to save a handle for the constructing set.

      Note: The operation will be run in a non AWT thread. If you need to perform user interface interaction in addition to the options provided in the optionsPanel (for example prompting for user input) then you need to place this inside a ThreadUtilities.invokeAndWait() function call.

      WARNING: Geneious may call this function multiple times simultaneously. Therefore, any implementation should not store its internal state within instance fields.

      Parameters:
      annotatedDocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(AnnotatedPluginDocument[]).
      progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceled
      options - the options returned from getOptions
      Returns:
      a list of new annotated documents, or null in case of failure or cancel. Many plugins will generate PluginDocuments instead of AnnotatedPluginDocuments which is what this function must return. You can create an AnnotatedPluginDocument from a PluginDocument using DocumentUtilities.createAnnotatedPluginDocument(PluginDocument)
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - when something goes wrong.

    • performOperation

      @Deprecated public void performOperation(AnnotatedPluginDocument[] annotatedDocuments, ProgressListener progressListener, Options options, SequenceSelection sequenceSelection, DocumentOperation.OperationCallback callback) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      Deprecated.
      As the callback parameter is not fully supported anymore.
      Do not use. This method will be removed and replaced with a more powerful alternative in the next release. More powerful alternative to performOperation(AnnotatedPluginDocument[], ProgressListener, Options) which may provide the currently selected region of any sequence in the documents. eg. if a region of a sequence is slected in the Sequence View then the selection will be passed in. It also provides a callback which allows you to specify points from which this operation can be resumed, and to return documents while the operation is in progress.

      Parameters:
      annotatedDocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(AnnotatedPluginDocument[]).
      progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceled
      options - the options returned from getOptions
      sequenceSelection - the currently selected region of any sequence in the documents, never null but may be an empty selection
      callback - provides a mechanism to specify persistent data so that the operation can be resumed, and also a mechanism to return documents while the operation is in progress (see DocumentOperation.OperationCallback)
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - when something goes wrong.

    • performOperation

      public List<AnnotatedPluginDocument> performOperation(AnnotatedPluginDocument[] annotatedDocuments, ProgressListener progressListener, Options options, SequenceSelection sequenceSelection) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      A convenience method to call performOperation(AnnotatedPluginDocument[], ProgressListener, Options, SequenceSelection, com.biomatters.geneious.publicapi.plugin.DocumentOperation.OperationCallback) . Does not return intermediate documents.
      Parameters:
      annotatedDocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(AnnotatedPluginDocument[]).
      progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceled
      options - the options returned from getOptions
      sequenceSelection - the currently selected region of any sequence in the documents, never null but may be an empty selection
      Returns:
      A list of all non-intermediate documents returned by the callback of performOperation(AnnotatedPluginDocument[], ProgressListener, Options, SequenceSelection, com.biomatters.geneious.publicapi.plugin.DocumentOperation.OperationCallback).
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if something goes wrong

    • getOptions

      public Options getOptions(org.jdom.Element optionsElement, List<AnnotatedPluginDocument> inputDocuments, List<AnnotatedPluginDocument> additionalParentDocuments) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      Recreates some options for rerunning an earlier operation to recreate descendant documents. This method only needs to be implemented for operations that use DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, List, List)

      An operation that is rerun must generate the same number of documents and those documents must be in the same order to ensure actively links correctly work

      Parameters:
      optionsElement - some options XML previously specified in DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, List, List)
      inputDocuments - the input documents to the operation (the parent documents specified in DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, List, List))
      additionalParentDocuments - any additional parent documents that shouldn't be passed into the performOperation directly, but that are still needed by the operation.
      Returns:
      an Options form of optionsElement. These options must exactly recreate the behaviour of the original options even if they are from earlier versions of Geneious
      Throws:
      UnsupportedOperationException - for operations that don't support this (those that don't use DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, List, List))
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if obtaining the options for this operation is unsuccessful for any reason
      Since:
      API 4.60 (Geneious 5.6.0)

    • performOperation

      public final List<AnnotatedPluginDocument> performOperation(List<AnnotatedPluginDocument> documents, ProgressListener progressListener, Options options) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      A convenience method for calling performOperation(AnnotatedPluginDocument[], ProgressListener, Options)
      Parameters:
      documents - the documents to apply the operation to. These must be the same documents as those passed to getOptions(AnnotatedPluginDocument[]).
      progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceled
      options - the options returned from getOptions
      Returns:
      a list of new annotated documents, or null if cancelled.
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the operation fails for any reason.

    • performOperation

      public final List<AnnotatedPluginDocument> performOperation(ProgressListener progressListener, Options options, AnnotatedPluginDocument... documents) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
      A convenience method for calling performOperation(AnnotatedPluginDocument[], ProgressListener, Options)
      Parameters:
      progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceled
      options - the options returned from getOptions
      documents - the documents to apply the operation to. These must be the same documents as those passed to getOptions(AnnotatedPluginDocument[]).
      Returns:
      a list of new annotated documents, or null if cancelled.
      Throws:
      com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if the operation fails for any reason.

    • isDocumentGenerator

      public boolean isDocumentGenerator()
      Does this DocumentOperation generate documents? (i.e. return a list that is not empty from performOperation(AnnotatedPluginDocument[], ProgressListener, Options). This is used so that Geneious knows whether to prompt the user for a destination for the documents that may be generated before starting the operation.

      If this DocumentOperation sometimes generates documents, then this method should return true.

      The default implementation returns true.

      Returns:
      true if this DocumentOperation generates documents

    • getUniqueId

      public String getUniqueId()
      Get a unique identifier for this DocumentOperation. This is so that PluginUtilities.getDocumentOperation(String) can be used to find this DocumentOperation. A unique identifier may consist of any valid Java indentifier characters (see Character.isJavaIdentifierPart(char) as well as to the space character.
      Returns:
      a unique identifier for this DocumentOperation. The default implementation returns the className.

    • loadDocumentsBeforeShowingOptions

      public boolean loadDocumentsBeforeShowingOptions()
      Returns true if this operation requires that the caller load the PluginDocuments of all input AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments into memory before invoking getOptions.

      The default implementation returns false.

      Returns:
      true if this operation requires that the caller load the PluginDocuments of all input AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments into memory before invoking the getOptions.
      See Also:

    • cacheDocumentsBeforeShowingOptions

      public boolean cacheDocumentsBeforeShowingOptions()
      If this method returns true then the caller should call cachePluginDocumentXmlAndAdditionalXmlLocallyForDocumentsInAnyDatabase before invoking getOptions to avoid impacting user experience.

      loadDocumentsBeforeShowingOptions() will take precedence over this option if it returns true. The default implementation returns false.

      Since:
      API 4.202230 (Geneious 2022.3.0)
      See Also:

    • loadDocumentsBeforeRunningOperation

      public boolean loadDocumentsBeforeRunningOperation()
      Returns true if this operation requires that the caller load the PluginDocuments of all input AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments into memory before invoking performOperation.

      The default implementation returns true.

      Returns:
      true if this operation requires that the caller load the PluginDocuments of all input AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments into memory before invoking performOperation.
      See Also:

    • getFractionOfTimeToSaveResults

      public double getFractionOfTimeToSaveResults()
      Returns an approximate fraction of the total operation time which will probably be required to save the generated document(s).

      The default implementation returns 0.05 which means that the progress returned from performOperation will take the progress bar up to 95% and then Geneious will fill in the remaining 5% as the document is saved to the user's local database.

      Returns:
      an approximate fraction of the total operation time which will probably be required to save the generated document(s).

    • canRunOnLocalGeneious

      public boolean canRunOnLocalGeneious()
      Returns:
      true if this operations supports being run on the current computer.
      Since:
      API 4.14 (Geneious 5.1)

    • canRunOnGeneiousServer

      public boolean canRunOnGeneiousServer()
      Returns true if this operation supports being run on a GeneiousServer. If this returns true then the user is presented with the option of running the operation on their local computer or on a connected GeneiousServer.

      Operations should only return true if the following is true, otherwise undesired behavior may occur.

      Operations that allow users to set an external executable, should check Geneious.isServer() when the operation is being run to see if it is running on the a Geneious Server. If running on Geneious Server then the path of the bundled executable should always be used rather than a path specified by the user.
      Returns:
      true if the operation can be run on a remote GeneiousServer
      Since:
      API 4.14 (Geneious 5.1)

    • getLocationOptions

      public final OperationLocationOptions getLocationOptions(AnnotatedPluginDocument... documents)
      Returns Options that can be used to set the location where this operation is run. Will be null if the operation can only be run locally. May also include child options used for configuration of the remote operation if they are provided by GeneiousService implementations. Options that care about the location they are run on should be registered with the
      Parameters:
      documents - The documents the operation is going to be run on.
      Returns:
      the location options for this operation, or null if the operation can only be run locally (because there are no services installed that support it)
      Since:
      API 4.14 (Geneious 5.1)