compbio.data.msa
Interface MsaWS<T>

Type Parameters:

T - executable type / web service type

public interface MsaWS<T>

Multiple Sequence Alignment (MSA) Web Services Interface

Version:

1.0 September 2009

Author:

pvtroshin

Method Summary

String	align(List<FastaSequence> sequences) Align a list of sequences with default settings.
boolean	cancelJob(String jobId) Stop running the job jobId but leave its output untouched
String	customAlign(List<FastaSequence> sequences, List<Option<T>> options) Align a list of sequences with options.
JobStatus	getJobStatus(String jobId) Return the status of the job.
Limit<T>	getLimit(String presetName) Get a Limit for a preset.
LimitsManager<T>	getLimits() List Limits supported by a web service.
PresetManager<T>	getPresets() Get presets supported by a web service
Alignment	getResult(String jobId) Return the result of the job.
RunnerConfig<T>	getRunnerOptions() Get options supported by a web service
String	presetAlign(List<FastaSequence> sequences, Preset<T> preset) Align a list of sequences with preset.
ChunkHolder	pullExecStatistics(String jobId, long position) Reads 1kb chunk from the statistics file which is specific to a given web service from the position.

Method Detail

align

String align(List<FastaSequence> sequences)
             throws UnsupportedRuntimeException,
                    LimitExceededException,
                    JobSubmissionException

Align a list of sequences with default settings. Any dataset containing a greater number of sequences or when the average length of the sequences are greater then defined in the default Limit, will not be accepted for an alignment operation and JobSubmissionException will be thrown.

Parameters:

sequences - List of FastaSequence objects. The programme does not perform any sequence validity checks. Nor does it checks whether the sequences names are unique. It is responsibility of the caller to make sure of this

Returns:

jobId - unique identifier for the job

Throws:

JobSubmissionException - is thrown when the job could not be submitted due to the following reasons: 1) The number of sequences in the submission or their average length is greater then defined by the default Limit. 2) Any problems on the server side e.g. it is misconfigured or malfunction, is reported via this exception. In the first case the information on the limit could be obtained from an exception.

InvalidParameterException - thrown if input list of FASTA sequences is null or empty

UnsupportedRuntimeException - thrown if server OS does not support native executables for a given web service, e.g. JABAWS is deployed on Windows and Mafft service is called

LimitExceededException - is throw if the input sequences number or their average length exceeds what is defined by the limit

customAlign

String customAlign(List<FastaSequence> sequences,
                   List<Option<T>> options)
                   throws UnsupportedRuntimeException,
                          LimitExceededException,
                          JobSubmissionException,
                          WrongParameterException

Align a list of sequences with options.

Parameters:

sequences - List of FastaSequence objects. The programme does not perform any sequence validity checks. Nor does it checks whether the sequences names are unique. It is responsibility of the caller to validate this information

options - A list of Options

Returns:

jobId - unique identifier for the job

Throws:

JobSubmissionException - is thrown when the job could not be submitted due to the following reasons: 1) The number of sequences in the submission or their average length is greater then defined by the default Limit. 2) Any problems on the server side e.g. it is misconfigured or malfunction, is reported via this exception. In the first case the information on the limit could be obtained from an exception.

WrongParameterException - is throws when 1) One of the Options provided is not supported, 2) The value of the option is defined outside the boundaries. In both cases exception object contain the information on the violating Option.

InvalidParameterException - thrown if input list of FASTA sequence is null or empty

UnsupportedRuntimeException - thrown if server OS does not support native executables for a given web service, e.g. JABAWS is deployed on Windows and Mafft service is called

LimitExceededException - is throw if the input sequences number or their average length exceeds what is defined by the limit

See Also:

Default Limit is used to decide whether the calculation will be permitted or denied

presetAlign

String presetAlign(List<FastaSequence> sequences,
                   Preset<T> preset)
                   throws UnsupportedRuntimeException,
                          LimitExceededException,
                          JobSubmissionException,
                          WrongParameterException

Align a list of sequences with preset. Limit for a presetName is used whether the calculation will be permitted or denied. If no Limit was defined for a presetName, than default limit is used.

Parameters:

sequences - List of FastaSequence objects. The programme does not perform any sequence validity checks. Nor does it checks whether the sequences names are unique. It is responsibility of the caller to validate this information

preset - A list of Options

Returns:

String - jobId - unique identifier for the job

Throws:

JobSubmissionException - is thrown when the job could not be submitted due to the following reasons: 1) The number of sequences in the submission or their average length is greater then defined by the default Limit. 2) Any problems on the server side e.g. it is misconfigured or malfunction, is reported via this exception. In the first case the information on the limit could be obtained from an exception.

WrongParameterException - is throws when 1) One of the Options provided is not supported, 2) The value of the option is defined outside the boundaries. In both cases exception object contain the information on the violating Option.

InvalidParameterException - thrown if input list of FASTA sequence is null or empty

UnsupportedRuntimeException - thrown if server OS does not support native executables for a given web service, e.g. JABAWS is deployed on Windows and Mafft service is called

LimitExceededException - is throw if the input sequences number or average length exceeds what is defined by the limit

See Also:

Preset

getResult

Alignment getResult(String jobId)
                    throws ResultNotAvailableException

Return the result of the job. This method waits for the job jobId to complete before return.

Parameters:

jobId - a unique job identifier

Returns:

Alignment

Throws:

ResultNotAvailableException - this exception is throw if the job execution was not successful or the result of the execution could not be found. (e.g. removed). Exception could also be thrown due to the lower level problems on the server i.e. IOException, FileNotFoundException problems as well as UnknownFileFormatException.

InvalidParameterException - thrown if jobId is empty or is not recognised e.g. in invalid format

cancelJob

boolean cancelJob(String jobId)

Stop running the job jobId but leave its output untouched

Returns:

true if job was cancelled successfully, false otherwise

Throws:

InvalidParameterException - is thrown if jobId is empty or cannot be recognised e.g. in invalid format

getJobStatus

JobStatus getJobStatus(String jobId)

Return the status of the job.

Parameters:

jobId - - unique job identifier

Returns:

JobStatus - status of the job

Throws:

InvalidParameterException - is thrown if jobId is empty or cannot be recognised e.g. in invalid format

See Also:

JobStatus

pullExecStatistics

ChunkHolder pullExecStatistics(String jobId,
                               long position)

Reads 1kb chunk from the statistics file which is specific to a given web service from the position. If in time of a request less then 1kb data is available from the position to the end of the file, then it returns all the data available from the position to the end of the file.

Parameters:

jobId - - unique job identifier

position - - next position within the file to read

Returns:

ChunkHolder - which contains a chunk of data and a next position within the file from which no data has been read

Throws:

InvalidParameterException - thrown if jobId is empty or cannot be recognised e.g. in invalid format and also if the position value is negative

See Also:

ChunkHolder

getRunnerOptions

RunnerConfig<T> getRunnerOptions()

Get options supported by a web service

Returns:

RunnerConfig the list of options and parameters supported by a web service.

getPresets

PresetManager<T> getPresets()

Get presets supported by a web service

Returns:

PresetManager the object contains information about presets supported by a web service

getLimit

Limit<T> getLimit(String presetName)

Get a Limit for a preset.

Parameters:

presetName - the name of the preset. if no name is provided, then the default preset is returned. If no limit for a particular preset is defined then the default preset is returned

Returns:

Limit

getLimits

LimitsManager<T> getLimits()

List Limits supported by a web service.

Returns:

LimitManager