Class GeneiousGridDocumentOperation
- java.lang.Object
-
- com.biomatters.geneious.publicapi.plugin.DocumentOperation
-
- com.biomatters.geneious.publicapi.plugin.GeneiousGridDocumentOperation
-
public abstract class GeneiousGridDocumentOperation extends DocumentOperation
A grid-aware version of
DocumentOperation
, containing many convenience features to simplify the task of creating a grid-aware DocumentOperation.While you do not have to extend this class to create a grid-aware document operation, you must extend it if you want your operation to be part of a GeneiousGridWorkflow.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
GeneiousGridDocumentOperation.GridInput
A class describing all the elements needed to run a program on the grid.static interface
GeneiousGridDocumentOperation.LocationChangedListenerProvider
Interface that allowsOperationLocationOptions.LocationChangedListener
s provided by program options to be registered in LocationOptions that are displayed to the user-
Nested classes/interfaces inherited from class com.biomatters.geneious.publicapi.plugin.DocumentOperation
DocumentOperation.OperationCallback, DocumentOperation.Wrapper
-
-
Constructor Summary
Constructors Constructor Description GeneiousGridDocumentOperation()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description boolean
canRunOnLocalGeneious()
abstract java.lang.String
getExecutableName()
Returns the name of (or path to) the executable used for local runs (or null if the DocumentOperation does not support local runs)java.lang.String
getGeneiousServerExecutableName()
If this operation returns true fromDocumentOperation.canRunOnGeneiousServer()
then this method returns the executable name used to run the operation on the server.Options
getGeneralOptions()
Gets some Options that work for this document operation when invoked on any set of input sequences.abstract GeneiousGridDocumentOperation.GridInput
getGridInput(AnnotatedPluginDocument[] documents, Options programOptions, Options fullOptions)
Returns aGeneiousGridDocumentOperation.GridInput
object representing all the files and command-line inputs needed to run a job on the gridjava.lang.String
getHelpForFindingProgram()
Returns an HTML fragment that contains instructions to the user for downloading the program for local runs.java.lang.String
getHTMLSummary(Options options)
Should return a summary of the operation that was run including all parameters sent to the command line application and any other options that the user entered.GeneiousGridImporter
getImporter()
If this method returns a non-null value, then Geneious will use the returnedGeneiousGridImporter
to produce documents from the results returned by the operation.static OperationLocationOptions
getLocationOptions(Options options)
A utility method to get the location options (the options visible at the top of the options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
) ,Options
getOptions(DocumentOperationInput operationInput)
Returns options for running the full grid operation (an almagimation of the options given bygetProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
, and some extra options describing where the job will run.abstract java.lang.String
getProgramName()
Returns the name of the program as given on the grid.abstract Options
getProgramOptions(AnnotatedPluginDocument... documents)
This method returns options for running the programstatic Options
getProgramOptions(Options options)
A utility method to get the program options (equivalent to options taken fromgetProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
, given options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
java.lang.String
getProgramVersion()
Returns the version of the program to run on the grid.static Options
getSelectedServiceOptions(Options options)
A utility method to get the configuration options for the service this operation has been chosen to run on.static boolean
isRemoteRun(Options options)
Returns true if the job represented by the given options (fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
) is a remote run.boolean
isSupportsCustomExecutable()
Indicates whether the operation allows users to specify a custom executable when run locally.void
performOperation(AnnotatedPluginDocument[] documents, jebl.util.ProgressListener progress, Options _options, SequenceSelection sequenceSelection, DocumentOperation.OperationCallback callback)
Do not use.java.util.List<AnnotatedPluginDocument>
runLocally(AnnotatedPluginDocument[] documents, jebl.util.ProgressListener progressListener, Options programOptions, Options fullOptions, java.lang.String executableLocation)
GeneiousGridDocumentOperations that support local runs must implement either this method orrunLocally(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, Options, String, OperationCallback)
void
runLocally(AnnotatedPluginDocument[] documents, jebl.util.ProgressListener progressListener, Options programOptions, Options fullOptions, java.lang.String executableLocation, DocumentOperation.OperationCallback callback)
GeneiousGridDocumentOperations that support local runs must implement either this method orrunLocally(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, Options, String)
java.util.List<AnnotatedPluginDocument>
runLocally(java.util.List<AnnotatedPluginDocument> documents, jebl.util.ProgressListener progressListener, Options programOptions, Options fullOptions, java.lang.String executableLocation)
GeneiousGridDocumentOperations that support local runs should implement this method.-
Methods inherited from class com.biomatters.geneious.publicapi.plugin.DocumentOperation
cacheDocumentsBeforeShowingOptions, canRunOnGeneiousServer, getActionOptions, getFractionOfTimeToSaveResults, getHelp, getLocationOptions, getOptions, getOptions, getOptions, getOptions, getOrderDependentOperationMessage, getSelectionSignatures, getUniqueId, isDocumentGenerator, loadDocumentsBeforeRunningOperation, loadDocumentsBeforeShowingOptions, performOperation, performOperation, performOperation, performOperation
-
-
-
-
Method Detail
-
getExecutableName
public abstract java.lang.String getExecutableName()
Returns the name of (or path to) the executable used for local runs (or null if the DocumentOperation does not support local runs)- Returns:
- the name of (or path to) the executable used for local runs (or null if the DocumentOperation does not support local runs)
-
getProgramName
public abstract java.lang.String getProgramName()
Returns the name of the program as given on the grid. Cannot return null- Returns:
- Returns the name of the program as given on the grid. Cannot return null.
-
getProgramVersion
public java.lang.String getProgramVersion()
Returns the version of the program to run on the grid. May return null to indicate the default version available, or if a version is not applicable.- Returns:
- the version of the program to run on the grid. May return null to indicate the default version available, or if a version is not applicable.
- Since:
- API version 4.610 (Geneious 6.1.0)
-
getHelpForFindingProgram
public java.lang.String getHelpForFindingProgram()
Returns an HTML fragment that contains instructions to the user for downloading the program for local runs.- Returns:
- an HTML fragment, or null if there is no help supplied
-
runLocally
public void runLocally(AnnotatedPluginDocument[] documents, jebl.util.ProgressListener progressListener, Options programOptions, Options fullOptions, java.lang.String executableLocation, DocumentOperation.OperationCallback callback) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
GeneiousGridDocumentOperations that support local runs must implement either this method orrunLocally(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, Options, String)
Performs a local run of the program, and adds any documents that are generated to anDocumentOperation.OperationCallback
.- Parameters:
documents
- The user-selected input documentsprogressListener
- a progress listenerprogramOptions
- the options returned bygetProgramOptions(AnnotatedPluginDocument[])
fullOptions
- the options returned byDocumentOperation.getOptions(AnnotatedPluginDocument[])
executableLocation
- a string representing the location of the program executable on diskcallback
- a callback to add documents to as they are generated- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if something goes wrong- Since:
- API 4.14 (Geneious 5.1)
-
runLocally
public java.util.List<AnnotatedPluginDocument> runLocally(AnnotatedPluginDocument[] documents, jebl.util.ProgressListener progressListener, Options programOptions, Options fullOptions, java.lang.String executableLocation) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
GeneiousGridDocumentOperations that support local runs must implement either this method orrunLocally(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, Options, String, OperationCallback)
Performs a local run of the program, and returns any documents that are generated.- Parameters:
documents
- The user-selected input documentsprogressListener
- a progress listenerprogramOptions
- the options returned bygetProgramOptions(AnnotatedPluginDocument[])
fullOptions
- the options returned byDocumentOperation.getOptions(AnnotatedPluginDocument[])
executableLocation
- a string representing the location of the program executable on disk- Returns:
- A list of documents generated in the run, or null if operation failed or canceled
- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if something goes wrong
-
runLocally
public final java.util.List<AnnotatedPluginDocument> runLocally(java.util.List<AnnotatedPluginDocument> documents, jebl.util.ProgressListener progressListener, Options programOptions, Options fullOptions, java.lang.String executableLocation) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
GeneiousGridDocumentOperations that support local runs should implement this method. Performs a local run of the program, and returns any documents that are generated.- Parameters:
documents
- The user-selected input documentsprogressListener
- a progress listenerprogramOptions
- the options returned bygetProgramOptions(AnnotatedPluginDocument[])
fullOptions
- the options returned byDocumentOperation.getOptions(AnnotatedPluginDocument[])
executableLocation
- a string representing the location of the program executable on disk- Returns:
- A list of documents generated in the runn, or null if operation failed or canceled
- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if something goes wrong
-
getGridInput
public abstract GeneiousGridDocumentOperation.GridInput getGridInput(AnnotatedPluginDocument[] documents, Options programOptions, Options fullOptions) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
Returns aGeneiousGridDocumentOperation.GridInput
object representing all the files and command-line inputs needed to run a job on the grid- Parameters:
documents
- the user-selected documentsprogramOptions
- the options returned bygetProgramOptions(AnnotatedPluginDocument[])
fullOptions
- the options returned byDocumentOperation.getOptions(AnnotatedPluginDocument[])
- Returns:
- A
GeneiousGridDocumentOperation.GridInput
object representing all the files and command-line inputs needed to run a job on the grid - Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if something goes wrong
-
getImporter
public GeneiousGridImporter getImporter()
If this method returns a non-null value, then Geneious will use the returnedGeneiousGridImporter
to produce documents from the results returned by the operation. Geneious will give the importer a folder containing all the files specified ingetGridInput(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], Options, Options)
and also any output files produced by the operation.- Returns:
- an
GeneiousGridImporter
capable of importing results for this operation, or null to import no documents.
-
getHTMLSummary
public java.lang.String getHTMLSummary(Options options)
Should return a summary of the operation that was run including all parameters sent to the command line application and any other options that the user entered. This can be used for keeping a record of analyses run.- Parameters:
options
- the options generated byDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
.- Returns:
- an HTML or plain text summary of the analysis that will be run based on the given options.
-
isRemoteRun
public static boolean isRemoteRun(Options options)
Returns true if the job represented by the given options (fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
) is a remote run.- Parameters:
options
- options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
- Returns:
- true if the options represent a remote run
-
performOperation
public final void performOperation(AnnotatedPluginDocument[] documents, jebl.util.ProgressListener progress, Options _options, SequenceSelection sequenceSelection, DocumentOperation.OperationCallback callback) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
Description copied from class:DocumentOperation
Do not use. This method will be removed and replaced with a more powerful alternative in the next release. More powerful alternative toDocumentOperation.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.- Overrides:
performOperation
in classDocumentOperation
- Parameters:
documents
- the documents to apply the operation to. These must be the same documents as those passed toDocumentOperation.getOptions(AnnotatedPluginDocument[])
.progress
- report progress for slow operations. If the progressListener requests that the operation cancels, the operation may choose to throw aDocumentOperationException.Canceled
_options
- the options returned fromgetOptions
sequenceSelection
- 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 (seeDocumentOperation.OperationCallback
)- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- when something goes wrong.
-
getProgramOptions
public abstract Options getProgramOptions(AnnotatedPluginDocument... documents) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
This method returns options for running the program- Parameters:
documents
- user-selected documents- Returns:
- options for running the program
- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if something goes wrong
-
canRunOnLocalGeneious
public boolean canRunOnLocalGeneious()
- Overrides:
canRunOnLocalGeneious
in classDocumentOperation
- Returns:
- true if this operations supports being run on the current computer.
-
getOptions
public final Options getOptions(DocumentOperationInput operationInput) throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
Returns options for running the full grid operation (an almagimation of the options given bygetProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
, and some extra options describing where the job will run.- Overrides:
getOptions
in classDocumentOperation
- Parameters:
operationInput
- the operation input- Returns:
- options for running the full grid operation
- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if something goes wrong- Since:
- API 4.14 (Geneious 5.1)
- See Also:
DocumentOperation.getOptions(AnnotatedPluginDocument[])
-
getGeneralOptions
public final Options getGeneralOptions() throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
Description copied from class:DocumentOperation
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.- Overrides:
getGeneralOptions
in classDocumentOperation
- 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)
andOptions.valuesFromXML(org.jdom.Element)
- Throws:
com.biomatters.geneious.publicapi.plugin.DocumentOperationException
- if this document operation does not support general options.
-
isSupportsCustomExecutable
public boolean isSupportsCustomExecutable()
Indicates whether the operation allows users to specify a custom executable when run locally.- Returns:
- true iff this operation supports a user-specified executable when run locally
- Since:
- API 4.201923 (Geneious Prime 2019.2.3)
-
getSelectedServiceOptions
public static Options getSelectedServiceOptions(Options options)
A utility method to get the configuration options for the service this operation has been chosen to run on.- Parameters:
options
- options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
- Returns:
- The configuration options specific to the service selected to run the operation on.
-
getProgramOptions
public static Options getProgramOptions(Options options)
A utility method to get the program options (equivalent to options taken fromgetProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
, given options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
- Parameters:
options
- options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
- Returns:
- The program options
-
getLocationOptions
public static OperationLocationOptions getLocationOptions(Options options)
A utility method to get the location options (the options visible at the top of the options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
) ,- Parameters:
options
- options taken fromDocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
- Returns:
- The location options, or null if this operation can only be run locally.
-
getGeneiousServerExecutableName
public java.lang.String getGeneiousServerExecutableName()
If this operation returns true fromDocumentOperation.canRunOnGeneiousServer()
then this method returns the executable name used to run the operation on the server. The executable is then expected to be on the path for Geneious Server. The default implementation of this method returnsgetExecutableName()
.- Returns:
- The executable name to run on GeneiousServer.
- Since:
- API 4.14 (Geneious 5.1)
-
-