webservices/compbio/data/msa/MsaWS.java

   1 /* Copyright (c) 2009 Peter Troshin\r
   2  *  \r
   3  *  JAva Bioinformatics Analysis Web Services (JABAWS) @version: 1.0   \r
   4  * \r
   5  *  This library is free software; you can redistribute it and/or modify it under the terms of the\r
   6  *  Apache License version 2 as published by the Apache Software Foundation\r
   7  * \r
   8  *  This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without\r
   9  *  even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Apache \r
  10  *  License for more details.\r
  11  * \r
  12  *  A copy of the license is in apache_license.txt. It is also available here:\r
  13  * @see: http://www.apache.org/licenses/LICENSE-2.0.txt\r
  14  * \r
  15  * Any republication or derived work distributed in source code form\r
  16  * must include this copyright and license notice.\r
  17  */\r
  18 \r
  19 package compbio.data.msa;\r
  20 \r
  21 import java.security.InvalidParameterException;\r
  22 import java.util.List;\r
  23 \r
  24 import javax.jws.WebParam;\r
  25 import javax.jws.WebService;\r
  26 \r
  27 import compbio.data.sequence.Alignment;\r
  28 import compbio.data.sequence.FastaSequence;\r
  29 import compbio.metadata.ChunkHolder;\r
  30 import compbio.metadata.JobStatus;\r
  31 import compbio.metadata.JobSubmissionException;\r
  32 import compbio.metadata.Limit;\r
  33 import compbio.metadata.LimitExceededException;\r
  34 import compbio.metadata.LimitsManager;\r
  35 import compbio.metadata.Option;\r
  36 import compbio.metadata.Preset;\r
  37 import compbio.metadata.PresetManager;\r
  38 import compbio.metadata.ResultNotAvailableException;\r
  39 import compbio.metadata.RunnerConfig;\r
  40 import compbio.metadata.UnsupportedRuntimeException;\r
  41 import compbio.metadata.WrongParameterException;\r
  42 \r
  43 /**\r
  44  * Multiple Sequence Alignment (MSA) Web Services Interface\r
  45  * \r
  46  * @author pvtroshin\r
  47  * \r
  48  *         Date September 2009\r
  49  * \r
  50  * @param <T>\r
  51  *            executable type / web service type\r
  52  */\r
  53 @WebService(targetNamespace = "http://msa.data.compbio/01/01/2010/")\r
  54 public interface MsaWS<T> {\r
  55 \r
  56     /**\r
  57      * Align a list of sequences with default settings.\r
  58      * \r
  59      * Any dataset containing a greater number of sequences or the average\r
  60      * length of the sequences are greater then defined in the default Limit\r
  61      * will not be accepted for an alignment operation and\r
  62      * JobSubmissionException will be thrown.\r
  63      * \r
  64      * @param sequences\r
  65      *            List of FastaSequence objects. The programme does not perform\r
  66      *            any sequence validity checks. Nor does it checks whether the\r
  67      *            sequences names are unique. It is responsibility of the caller\r
  68      *            to validate this information\r
  69      * @return jobId - unique identifier for the job\r
  70      * @throws JobSubmissionException. This\r
  71      *             exception is thrown when the job could not be submitted due\r
  72      *             to the following reasons: 1) The number of sequences in the\r
  73      *             submission or their average length is greater then defined by\r
  74      *             the default Limit. 2) Any problems on the server side e.g. it\r
  75      *             is misconfigured or malfunction, is reported via this\r
  76      *             exception. In the first case the information on the limit\r
  77      *             could be obtained from an exception.\r
  78      * @throws InvalidParameterException\r
  79      *             thrown if input list of fasta sequence is null or empty\r
  80      * @throws UnsupportedRuntimeException\r
  81      *             thrown if server OS does not support native executables for a\r
  82      *             given web service, e.g. JWS2 is deployed on Windows and Mafft\r
  83      *             service is called\r
  84      * @throws LimitExceededException\r
  85      *             is throw if the input sequences number or average length\r
  86      *             exceeds what is defined by the limit\r
  87      */\r
  88     String align(\r
  89             @WebParam(name = "fastaSequences") List<FastaSequence> sequences)\r
  90             throws UnsupportedRuntimeException, LimitExceededException,\r
  91             JobSubmissionException;\r
  92 \r
  93     /**\r
  94      * Align a list of sequences with options.\r
  95      * \r
  96      * @see Option\r
  97      * \r
  98      *      Default Limit is used to decide whether the calculation will be\r
  99      *      permitted or denied\r
 100      * \r
 101      * @param sequences\r
 102      *            List of FastaSequence objects. The programme does not perform\r
 103      *            any sequence validity checks. Nor does it checks whether the\r
 104      *            sequences names are unique. It is responsibility of the caller\r
 105      *            to validate this information\r
 106      * @param options\r
 107      *            A list of Options\r
 108      * @return jobId - unique identifier for the job\r
 109      * @throws JobSubmissionException. This\r
 110      *             exception is thrown when the job could not be submitted due\r
 111      *             to the following reasons: 1) The number of sequences in the\r
 112      *             submission or their average length is greater then defined by\r
 113      *             the default Limit. 2) Any problems on the server side e.g. it\r
 114      *             is misconfigured or malfunction, is reported via this\r
 115      *             exception. In the first case the information on the limit\r
 116      *             could be obtained from an exception.\r
 117      * @throws WrongParameterException\r
 118      *             is throws when 1) One of the Options provided is not\r
 119      *             supported, 2) The value of the option is defined outside the\r
 120      *             boundaries. In both cases exception object contain the\r
 121      *             information on the violating Option.\r
 122      * @throws InvalidParameterException\r
 123      *             thrown if input list of fasta sequence is null or empty\r
 124      * @throws UnsupportedRuntimeException\r
 125      *             thrown if server OS does not support native executables for a\r
 126      *             given web service, e.g. JWS2 is deployed on Windows and Mafft\r
 127      *             service is called\r
 128      * @throws LimitExceededException\r
 129      *             is throw if the input sequences number or average length\r
 130      *             exceeds what is defined by the limit\r
 131      */\r
 132     String customAlign(\r
 133             @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 134             @WebParam(name = "options") List<Option<T>> options)\r
 135             throws UnsupportedRuntimeException, LimitExceededException,\r
 136             JobSubmissionException, WrongParameterException;\r
 137 \r
 138     /**\r
 139      * Align a list of sequences with preset. @see Preset\r
 140      * \r
 141      * Limit for a presetName is used whether the calculation will be permitted\r
 142      * or denied. If no Limit was defined for a presetName, than default limit\r
 143      * is used.\r
 144      * \r
 145      * @param sequences\r
 146      *            List of FastaSequence objects. The programme does not perform\r
 147      *            any sequence validity checks. Nor does it checks whether the\r
 148      *            sequences names are unique. It is responsibility of the caller\r
 149      *            to validate this information\r
 150      * @param preset\r
 151      *            A list of Options\r
 152      * @return String - jobId - unique identifier for the job\r
 153      * @throws JobSubmissionException. This\r
 154      *             exception is thrown when the job could not be submitted due\r
 155      *             to the following reasons: 1) The number of sequences in the\r
 156      *             submission or their average length is greater then defined by\r
 157      *             the default Limit. 2) Any problems on the server side e.g. it\r
 158      *             is misconfigured or malfunction, is reported via this\r
 159      *             exception. In the first case the information on the limit\r
 160      *             could be obtained from an exception.\r
 161      * @throws WrongParameterException\r
 162      *             is throws when 1) One of the Options provided is not\r
 163      *             supported, 2) The value of the option is defined outside the\r
 164      *             boundaries. In both cases exception object contain the\r
 165      *             information on the violating Option.\r
 166      * @throws InvalidParameterException\r
 167      *             thrown if input list of fasta sequence is null or empty\r
 168      * @throws UnsupportedRuntimeException\r
 169      *             thrown if server OS does not support native executables for a\r
 170      *             given web service, e.g. JWS2 is deployed on Windows and Mafft\r
 171      *             service is called\r
 172      * @throws LimitExceededException\r
 173      *             is throw if the input sequences number or average length\r
 174      *             exceeds what is defined by the limit\r
 175      */\r
 176     String presetAlign(\r
 177             @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 178             @WebParam(name = "preset") Preset<T> preset)\r
 179             throws UnsupportedRuntimeException, LimitExceededException,\r
 180             JobSubmissionException, WrongParameterException;\r
 181 \r
 182     /**\r
 183      * Return the result of the job.\r
 184      * \r
 185      * @param jobId\r
 186      *            a unique job identifier\r
 187      * @return Alignment\r
 188      * @throws ResultNotAvailableException\r
 189      *             this exception is throw if the job execution was not\r
 190      *             successful or the result of the execution could not be found.\r
 191      *             (e.g. removed). Exception could also be thrown is dues to the\r
 192      *             lower level problems on the server i.e. IOException,\r
 193      *             FileNotFoundException problems as well as\r
 194      *             UnknownFileFormatException.\r
 195      * @throws InvalidParameterException\r
 196      *             thrown if jobId is empty or cannot be recognised e.g. in\r
 197      *             invalid format\r
 198      */\r
 199     Alignment getResult(@WebParam(name = "jobId") String jobId)\r
 200             throws ResultNotAvailableException;\r
 201 \r
 202     /**\r
 203      * Stop running job but leave its output untouched\r
 204      * \r
 205      * @return true if job was cancelled successfully, false otherwise\r
 206      * @throws InvalidParameterException\r
 207      *             thrown if jobId is empty or cannot be recognised e.g. in\r
 208      *             invalid format\r
 209      */\r
 210     boolean cancelJob(@WebParam(name = "jobId") String jobId);\r
 211 \r
 212     /**\r
 213      * Return the status of the job. @see JobStatus\r
 214      * \r
 215      * @param jobId\r
 216      *            - unique job identifier\r
 217      * @return JobStatus - status of the job\r
 218      * @throws InvalidParameterException\r
 219      *             thrown if jobId is empty or cannot be recognised e.g. in\r
 220      *             invalid format\r
 221      */\r
 222     JobStatus getJobStatus(@WebParam(name = "jobId") String jobId);\r
 223 \r
 224     /**\r
 225      * Reads 1kb chunk from the statistics file which is specific to a given web\r
 226      * service from the position. If in time of a request less then 1kb data is\r
 227      * available from the position to the end of the file, then it returns all\r
 228      * the data available from the position to the end of the file.\r
 229      * \r
 230      * @param jobId\r
 231      *            - unique job identifier\r
 232      * @param position\r
 233      *            - next position within the file to read\r
 234      * @return ChunkHolder - @see ChunkHolder which contains a chuink of data\r
 235      *         and a next position within the file from which no data has been\r
 236      *         read\r
 237      * @throws InvalidParameterException\r
 238      *             thrown if jobId is empty or cannot be recognised e.g. in\r
 239      *             invalid format and also if the position value is negative\r
 240      */\r
 241     ChunkHolder pullExecStatistics(@WebParam(name = "jobId") String jobId,\r
 242             @WebParam(name = "position") long position);\r
 243 \r
 244     /*\r
 245      * TODO\r
 246      * \r
 247      * @param jobId\r
 248      * \r
 249      * @return\r
 250      * \r
 251      * byte getProgress(@WebParam(name = "jobId") String jobId);\r
 252      */\r
 253 \r
 254     /**\r
 255      * Get options supported by a web service\r
 256      * \r
 257      * @return RunnerConfig the list of options and parameters supported by a\r
 258      *         web service.\r
 259      */\r
 260     RunnerConfig<T> getRunnerOptions();\r
 261 \r
 262     /**\r
 263      * Get presets supported by a web service\r
 264      * \r
 265      * @return PresetManager the object contains information about presets\r
 266      *         supported by a web service\r
 267      */\r
 268     PresetManager<T> getPresets();\r
 269 \r
 270     /**\r
 271      * Get a Limit for a preset.\r
 272      * \r
 273      * @param presetName\r
 274      *            the name of the preset. if no name is provided, then the\r
 275      *            default preset is returned. If no limit for a particular\r
 276      *            preset is defined then the default preset is returned\r
 277      * @return Limit\r
 278      */\r
 279     Limit<T> getLimit(@WebParam(name = "presetName") String presetName);\r
 280 \r
 281     /**\r
 282      * List Limits supported by a web service.\r
 283      * \r
 284      * @param presetName\r
 285      *            the name of the preset. if no name is provided, then the\r
 286      *            default preset is returned. If no limit for a particular\r
 287      *            preset is defined then the default preset is returned\r
 288      * @return LimitManager\r
 289      */\r
 290     LimitsManager<T> getLimits();\r
 291 \r
 292 }\r