public abstract class DocumentOperation extends Object
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 panel that we returned in the getOptionsPanel() 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, hopefuly 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;
}
}
| Modifier and Type | Class and Description |
|---|---|
static class |
DocumentOperation.OperationCallback
Provides a callback facility to DocumentOperations.
|
static class |
DocumentOperation.Wrapper
Provides a wrapper DocumentOperation that delegates all methods (except
getUniqueId()) to the wrapped operation. |
| Constructor and Description |
|---|
DocumentOperation() |
| Modifier and Type | Method and Description |
|---|---|
boolean |
canRunOnGeneiousServer()
Returns true if this operation supports being run on a GeneiousServer.
|
boolean |
canRunOnLocalGeneious() |
abstract GeneiousActionOptions |
getActionOptions()
GeneiousActionOptions contains all the important status information including
name, description, icon, where the action is displayed in the interface etc.
|
double |
getFractionOfTimeToSaveResults()
Returns an approximate fraction of the total operation time which will probably be required to save the generated document(s).
|
Options |
getGeneralOptions()
Gets some Options that work for this document operation when invoked on any set of input sequences.
|
abstract String |
getHelp()
Help for this operation in the form of HTML or plain text.
|
OperationLocationOptions |
getLocationOptions(AnnotatedPluginDocument... documents)
Returns
Options that can be used to set the location where this operation is run. |
Options |
getOptions(AnnotatedPluginDocument... documents)
Provides some options applicable to this document operation to the user.
|
Options |
getOptions(DocumentOperationInput operationInput)
More powerful alternative to
getOptions(com.biomatters.geneious.publicapi.documents.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. |
Options |
getOptions(org.jdom.Element optionsElement,
List<AnnotatedPluginDocument> inputDocuments,
List<AnnotatedPluginDocument> additionalParentDocuments)
Recreates some options for rerunning an earlier operation to recreate descendant documents.
|
Options |
getOptions(List<AnnotatedPluginDocument> documents)
A convenience method for calling
getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
This method may be invoked from either the swing thread or a non-swing thread. |
Options |
getOptions(SequenceSelection sequenceSelection,
AnnotatedPluginDocument... documents)
More powerful alternative to
getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
which may provide the currently selected region of any sequence in the documents. |
String |
getOrderDependentOperationMessage()
Support for operations caring about the order of similarily typed documents.
|
abstract DocumentSelectionSignature[] |
getSelectionSignatures()
Specifies the type of documents this operation accepts as input.
|
String |
getUniqueId()
Get a unique identifier for this DocumentOperation.
|
boolean |
isDocumentGenerator()
Does this DocumentOperation generate documents? (i.e.
|
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. |
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. |
List<AnnotatedPluginDocument> |
performOperation(AnnotatedPluginDocument[] annotatedDocuments,
ProgressListener progressListener,
Options options)
Create document(s) from a set of documents.
|
List<AnnotatedPluginDocument> |
performOperation(AnnotatedPluginDocument[] annotatedDocuments,
ProgressListener progressListener,
Options options,
SequenceSelection sequenceSelection)
|
void |
performOperation(AnnotatedPluginDocument[] annotatedDocuments,
ProgressListener progressListener,
Options options,
SequenceSelection sequenceSelection,
DocumentOperation.OperationCallback callback)
Do not use.
|
List<AnnotatedPluginDocument> |
performOperation(List<AnnotatedPluginDocument> documents,
ProgressListener progressListener,
Options options)
A convenience method for calling
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options) |
List<AnnotatedPluginDocument> |
performOperation(ProgressListener progressListener,
Options options,
AnnotatedPluginDocument... documents)
A convenience method for calling
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options) |
public abstract GeneiousActionOptions getActionOptions()
public abstract String getHelp()
Options.getOptionsHelp()
on the Options returned from getOptionsOptions.getOptionsHelp()public abstract DocumentSelectionSignature[] getSelectionSignatures()
return new DocumentSelectionSignature[] {new DocumentSelectionSignature(NucleotideSequenceDocument.class,1,2)}}
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.public Options getOptions(AnnotatedPluginDocument... documents) throws DocumentOperationException
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.documents - the currently selected documents so that the panel can contain different
options depending on these. This can be ignored in most cases.DocumentOperationException - if obtaining the options for this operation is unsuccessful for any reasonpublic Options getOptions(SequenceSelection sequenceSelection, AnnotatedPluginDocument... documents) throws DocumentOperationException
getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
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.
This method may be invoked from either the swing thread or a non-swing thread.sequenceSelection - the currently selected region of any sequence in the documents, never null but may be an empty selectiondocuments - the currently selected documents so that the panel can contain different
options depending on these. This can be ignored in most cases.DocumentOperationException - if the obtaining the options for this operation is unsuccessful for any reasongetOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])public Options getOptions(DocumentOperationInput operationInput) throws DocumentOperationException
getOptions(com.biomatters.geneious.publicapi.documents.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.operationInput - the data being used as input to the operation. This contains information such as the selected documents.DocumentOperationException - if the obtaining the options for this operation is unsuccessful for any reasongetOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])public Options getGeneralOptions() throws DocumentOperationException
Options.valuesToXML(String) and Options.valuesFromXML(org.jdom.Element)DocumentOperationException - if this document operation does not support general options.public final Options getOptions(List<AnnotatedPluginDocument> documents) throws DocumentOperationException
getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
This method may be invoked from either the swing thread or a non-swing thread.documents - the documents to apply the operation toDocumentOperationException - if the obtaining the options for this operation is unsuccessful for any reasonpublic String getOrderDependentOperationMessage()
public List<AnnotatedPluginDocument> performOperation(AnnotatedPluginDocument[] annotatedDocuments, ProgressListener progressListener, Options options) throws DocumentOperationException
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.annotatedDocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]).progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceledoptions - the options returned from getOptionsDocumentUtilities.createAnnotatedPluginDocument(com.biomatters.geneious.publicapi.documents.PluginDocument)DocumentOperationException - when something goes wrong.public void performOperation(AnnotatedPluginDocument[] annotatedDocuments, ProgressListener progressListener, Options options, SequenceSelection sequenceSelection, DocumentOperation.OperationCallback callback) throws DocumentOperationException
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.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.annotatedDocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]).progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceledoptions - the options returned from getOptionssequenceSelection - the currently selected region of any sequence in the documents, never null but may be an empty selectioncallback - 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)DocumentOperationException - when something goes wrong.public List<AnnotatedPluginDocument> performOperation(AnnotatedPluginDocument[] annotatedDocuments, ProgressListener progressListener, Options options, SequenceSelection sequenceSelection) throws DocumentOperationException
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, SequenceSelection, com.biomatters.geneious.publicapi.plugin.DocumentOperation.OperationCallback) . Does not return intermediate documents.annotatedDocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]).progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceledoptions - the options returned from getOptionssequenceSelection - the currently selected region of any sequence in the documents, never null but may be an empty selectionperformOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, SequenceSelection, com.biomatters.geneious.publicapi.plugin.DocumentOperation.OperationCallback).DocumentOperationException - if something goes wrongpublic Options getOptions(org.jdom.Element optionsElement, List<AnnotatedPluginDocument> inputDocuments, List<AnnotatedPluginDocument> additionalParentDocuments) throws DocumentOperationException
DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.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 workoptionsElement - some options XML previously specified in DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List)inputDocuments - the input documents to the operation (the parent documents specified in DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List))additionalParentDocuments - any additional parent documents that shouldn't be passed into the performOperation directly, but that are still needed by the operation.UnsupportedOperationException - for operations that don't support this (those that don't use DocumentOperation.OperationCallback.setOptionsForActivelyLinkedDescendants(org.jdom.Element, java.util.List, java.util.List))DocumentOperationException - if obtaining the options for this operation is unsuccessful for any reasonpublic final List<AnnotatedPluginDocument> performOperation(List<AnnotatedPluginDocument> documents, ProgressListener progressListener, Options options) throws DocumentOperationException
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options)documents - the documents to apply the operation to. These must be the same documents as those passed to getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]).progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceledoptions - the options returned from getOptionsDocumentOperationException - if the operation fails for any reason.public final List<AnnotatedPluginDocument> performOperation(ProgressListener progressListener, Options options, AnnotatedPluginDocument... documents) throws DocumentOperationException
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options)progressListener - report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw a DocumentOperationException.Canceledoptions - the options returned from getOptionsdocuments - the documents to apply the operation to. These must be the same documents as those passed to getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]).DocumentOperationException - if the operation fails for any reason.public boolean isDocumentGenerator()
performOperation(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.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.public String getUniqueId()
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.public boolean loadDocumentsBeforeShowingOptions()
PluginDocuments of all input
AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments
into memory before invoking getOptions.
The default implementation returns false.PluginDocuments of all input
AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments
into memory before invoking the getOptions.loadDocumentsBeforeRunningOperation()public boolean loadDocumentsBeforeRunningOperation()
PluginDocuments of all input
AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments
into memory before invoking performOperation.
The default implementation returns true.PluginDocuments of all input
AnnotatedPluginDocuments and the PluginDocuments of all referenced AnnotatedPluginDocuments
into memory before invoking performOperation.loadDocumentsBeforeShowingOptions()public double getFractionOfTimeToSaveResults()
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.public boolean canRunOnLocalGeneious()
public boolean canRunOnGeneiousServer()
Options.valuesFromXML(org.jdom.Element) with the element obtained from Options.valuesToXML(String).DocumentOperation.OperationCallback
or as an element in the return list.GeneiousServices directly.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.public final OperationLocationOptions getLocationOptions(AnnotatedPluginDocument... documents)
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 thedocuments - The documents the operation is going to be run on.