Package com.biomatters.geneious.publicapi.plugin

Class DocumentOperation

  • Direct Known Subclasses:
    DocumentOperation.Wrapper, GeneiousGridDocumentOperation
    public abstract class DocumentOperation
extends java.lang.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 "name" 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 Detail

      • DocumentOperation

        public DocumentOperation()

    • Method Detail

      • 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 java.lang.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:
        Options.getOptionsHelp()

      • 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(AnnotatedPluginDocument[])

      • 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​(java.util.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 java.lang.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 java.util.List<AnnotatedPluginDocument> performOperation​(AnnotatedPluginDocument[] annotatedDocuments,
                                                                jebl.util.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

        public void performOperation​(AnnotatedPluginDocument[] annotatedDocuments,
                             jebl.util.ProgressListener progressListener,
                             Options options,
                             SequenceSelection sequenceSelection,
                             DocumentOperation.OperationCallback callback)
                      throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        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 final java.util.List<AnnotatedPluginDocument> performOperation​(java.util.List<AnnotatedPluginDocument> documents,
                                                                      jebl.util.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 java.util.List<AnnotatedPluginDocument> performOperation​(jebl.util.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 java.lang.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.

      • 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)