Package com.biomatters.geneious.publicapi.plugin

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 allows OperationLocationOptions.LocationChangedListeners 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

Modifier and Type	Method	Description
boolean	canRunOnLocalGeneious()
abstract 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)
String	getGeneiousServerExecutableName()	If this operation returns true from DocumentOperation.canRunOnGeneiousServer() then this method returns the executable name used to run the operation on the server.
final 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 a GeneiousGridDocumentOperation.GridInput object representing all the files and command-line inputs needed to run a job on the grid
String	getHelpForFindingProgram()	Returns an HTML fragment that contains instructions to the user for downloading the program for local runs.
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 returned GeneiousGridImporter 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 from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]) ) ,
final Options	getOptions(DocumentOperationInput operationInput)	Returns options for running the full grid operation (an almagimation of the options given by getProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]), and some extra options describing where the job will run.
abstract 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 program
static Options	getProgramOptions(Options options)	A utility method to get the program options (equivalent to options taken from getProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]) , given options taken from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])
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 (from DocumentOperation.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.
final void	performOperation(AnnotatedPluginDocument[] documents, ProgressListener progress, Options _options, SequenceSelection sequenceSelection, DocumentOperation.OperationCallback callback)	Do not use.
List<AnnotatedPluginDocument>	runLocally(AnnotatedPluginDocument[] documents, ProgressListener progressListener, Options programOptions, Options fullOptions, String executableLocation)	GeneiousGridDocumentOperations that support local runs must implement either this method or runLocally(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, Options, String, OperationCallback)
void	runLocally(AnnotatedPluginDocument[] documents, ProgressListener progressListener, Options programOptions, Options fullOptions, String executableLocation, DocumentOperation.OperationCallback callback)	GeneiousGridDocumentOperations that support local runs must implement either this method or runLocally(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[], jebl.util.ProgressListener, Options, Options, String)
final List<AnnotatedPluginDocument>	runLocally(List<AnnotatedPluginDocument> documents, ProgressListener progressListener, Options programOptions, Options fullOptions, 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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

GeneiousGridDocumentOperation

public GeneiousGridDocumentOperation()

Method Details

getExecutableName

public abstract 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 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 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 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,
 ProgressListener progressListener,
 Options programOptions,
 Options fullOptions,
 String executableLocation,
 DocumentOperation.OperationCallback callback)
                throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException

GeneiousGridDocumentOperations that support local runs must implement either this method or runLocally(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 an DocumentOperation.OperationCallback.

Parameters:

documents - The user-selected input documents

progressListener - a progress listener

programOptions - the options returned by getProgramOptions(AnnotatedPluginDocument[])

fullOptions - the options returned by DocumentOperation.getOptions(AnnotatedPluginDocument[])

executableLocation - a string representing the location of the program executable on disk

callback - 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 List<AnnotatedPluginDocument> runLocally(AnnotatedPluginDocument[] documents,
 ProgressListener progressListener,
 Options programOptions,
 Options fullOptions,
 String executableLocation)
                                         throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException

GeneiousGridDocumentOperations that support local runs must implement either this method or runLocally(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 documents

progressListener - a progress listener

programOptions - the options returned by getProgramOptions(AnnotatedPluginDocument[])

fullOptions - the options returned by DocumentOperation.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 List<AnnotatedPluginDocument> runLocally(List<AnnotatedPluginDocument> documents,
 ProgressListener progressListener,
 Options programOptions,
 Options fullOptions,
 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 documents

progressListener - a progress listener

programOptions - the options returned by getProgramOptions(AnnotatedPluginDocument[])

fullOptions - the options returned by DocumentOperation.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 a GeneiousGridDocumentOperation.GridInput object representing all the files and command-line inputs needed to run a job on the grid

Parameters:

documents - the user-selected documents

programOptions - the options returned by getProgramOptions(AnnotatedPluginDocument[])

fullOptions - the options returned by DocumentOperation.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 returned GeneiousGridImporter to produce documents from the results returned by the operation. Geneious will give the importer a folder containing all the files specified in getGridInput(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 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 by DocumentOperation.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 (from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])) is a remote run.

Parameters:

options - options taken from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])

Returns:

true if the options represent a remote run

performOperation

public final void performOperation(AnnotatedPluginDocument[] documents,
 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 to DocumentOperation.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 class DocumentOperation

Parameters:

documents - the documents to apply the operation to. These must be the same documents as those passed to DocumentOperation.getOptions(AnnotatedPluginDocument[]).

progress - 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.

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 class DocumentOperation

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 by getProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]), and some extra options describing where the job will run.

Overrides:

getOptions in class DocumentOperation

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 class DocumentOperation

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.

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 from DocumentOperation.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 from getProgramOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]) , given options taken from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])

Parameters:

options - options taken from DocumentOperation.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 from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[]) ) ,

Parameters:

options - options taken from DocumentOperation.getOptions(com.biomatters.geneious.publicapi.documents.AnnotatedPluginDocument[])

Returns:

The location options, or null if this operation can only be run locally.

getGeneiousServerExecutableName

public String getGeneiousServerExecutableName()

If this operation returns true from DocumentOperation.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 returns getExecutableName().

Returns:

The executable name to run on GeneiousServer.

Since:

API 4.14 (Geneious 5.1)