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.JobSubmissionException;\r
  30 import compbio.metadata.LimitExceededException;\r
  31 import compbio.metadata.Option;\r
  32 import compbio.metadata.Preset;\r
  33 import compbio.metadata.ResultNotAvailableException;\r
  34 import compbio.metadata.UnsupportedRuntimeException;\r
  35 import compbio.metadata.WrongParameterException;\r
  36 \r
  37 /**\r
  38  * Multiple Sequence Alignment (MSA) Web Services Interface\r
  39  * \r
  40  * @author pvtroshin\r
  41  * \r
  42  *         Date November 2010\r
  43  * \r
  44  * @param <T>\r
  45  *            executable type / web service type\r
  46  */\r
  47 @WebService(targetNamespace = "http://msa.data.compbio/01/01/2010/")\r
  48 public interface MsaWS<T> extends JABAService, JManagement, Metadata<T> {\r
  49 \r
  50         /**\r
  51          * Align a list of sequences with default settings.\r
  52          * \r
  53          * Any dataset containing a greater number of sequences or when the average\r
  54          * length of the sequences are greater then defined in the default Limit,\r
  55          * will not be accepted for an alignment operation and\r
  56          * JobSubmissionException will be thrown.\r
  57          * \r
  58          * @param sequences\r
  59          *            List of FastaSequence objects. The programme does not perform\r
  60          *            any sequence validity checks. Nor does it checks whether the\r
  61          *            sequences names are unique. It is responsibility of the caller\r
  62          *            to make sure of this\r
  63          * @return jobId - unique identifier for the job\r
  64          * @throws JobSubmissionException\r
  65          *             is thrown when the job could not be submitted due to the\r
  66          *             following reasons: 1) The number of sequences in the\r
  67          *             submission or their average length is greater then defined by\r
  68          *             the default Limit. 2) Any problems on the server side e.g. it\r
  69          *             is misconfigured or malfunction, is reported via this\r
  70          *             exception. In the first case the information on the limit\r
  71          *             could be obtained from an exception.\r
  72          * @throws InvalidParameterException\r
  73          *             thrown if input list of FASTA sequences is null or empty\r
  74          * @throws UnsupportedRuntimeException\r
  75          *             thrown if server OS does not support native executables for a\r
  76          *             given web service, e.g. JABAWS is deployed on Windows and\r
  77          *             Mafft service is called\r
  78          * @throws LimitExceededException\r
  79          *             is throw if the input sequences number or their average\r
  80          *             length exceeds what is defined by the limit\r
  81          */\r
  82         String align(\r
  83                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences)\r
  84                         throws UnsupportedRuntimeException, LimitExceededException,\r
  85                         JobSubmissionException;\r
  86 \r
  87         /**\r
  88          * Align a list of sequences with options.\r
  89          * \r
  90          * @see Option\r
  91          * \r
  92          *      Default Limit is used to decide whether the calculation will be\r
  93          *      permitted or denied\r
  94          * \r
  95          * @param sequences\r
  96          *            List of FastaSequence objects. The programme does not perform\r
  97          *            any sequence validity checks. Nor does it checks whether the\r
  98          *            sequences names are unique. It is responsibility of the caller\r
  99          *            to validate this information\r
 100          * @param options\r
 101          *            A list of Options\r
 102          * @return jobId - unique identifier for the job\r
 103          * @throws JobSubmissionException\r
 104          *             is thrown when the job could not be submitted due to the\r
 105          *             following reasons: 1) The number of sequences in the\r
 106          *             submission or their average length is greater then defined by\r
 107          *             the default Limit. 2) Any problems on the server side e.g. it\r
 108          *             is misconfigured or malfunction, is reported via this\r
 109          *             exception. In the first case the information on the limit\r
 110          *             could be obtained from an exception.\r
 111          * @throws WrongParameterException\r
 112          *             is throws when 1) One of the Options provided is not\r
 113          *             supported, 2) The value of the option is defined outside the\r
 114          *             boundaries. In both cases exception object contain the\r
 115          *             information on the violating Option.\r
 116          * @throws InvalidParameterException\r
 117          *             thrown if input list of FASTA sequence is null or empty\r
 118          * @throws UnsupportedRuntimeException\r
 119          *             thrown if server OS does not support native executables for a\r
 120          *             given web service, e.g. JABAWS is deployed on Windows and\r
 121          *             Mafft service is called\r
 122          * @throws LimitExceededException\r
 123          *             is throw if the input sequences number or their average\r
 124          *             length exceeds what is defined by the limit\r
 125          */\r
 126         String customAlign(\r
 127                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 128                         @WebParam(name = "options") List<Option<T>> options)\r
 129                         throws UnsupportedRuntimeException, LimitExceededException,\r
 130                         JobSubmissionException, WrongParameterException;\r
 131 \r
 132         /**\r
 133          * Align a list of sequences with preset.\r
 134          * \r
 135          * Limit for a presetName is used whether the calculation will be permitted\r
 136          * or denied. If no Limit was defined for a presetName, than default limit\r
 137          * is used.\r
 138          * \r
 139          * @param sequences\r
 140          *            List of FastaSequence objects. The programme does not perform\r
 141          *            any sequence validity checks. Nor does it checks whether the\r
 142          *            sequences names are unique. It is responsibility of the caller\r
 143          *            to validate this information\r
 144          * @param preset\r
 145          *            A list of Options\r
 146          * @return String - jobId - unique identifier for the job\r
 147          * @throws JobSubmissionException\r
 148          *             is thrown when the job could not be submitted due to the\r
 149          *             following reasons: 1) The number of sequences in the\r
 150          *             submission or their average length is greater then defined by\r
 151          *             the default Limit. 2) Any problems on the server side e.g. it\r
 152          *             is misconfigured or malfunction, is reported via this\r
 153          *             exception. In the first case the information on the limit\r
 154          *             could be obtained from an exception.\r
 155          * @throws WrongParameterException\r
 156          *             is throws when 1) One of the Options provided is not\r
 157          *             supported, 2) The value of the option is defined outside the\r
 158          *             boundaries. In both cases exception object contain the\r
 159          *             information on the violating Option.\r
 160          * @throws InvalidParameterException\r
 161          *             thrown if input list of FASTA sequence is null or empty\r
 162          * @throws UnsupportedRuntimeException\r
 163          *             thrown if server OS does not support native executables for a\r
 164          *             given web service, e.g. JABAWS is deployed on Windows and\r
 165          *             Mafft service is called\r
 166          * @throws LimitExceededException\r
 167          *             is throw if the input sequences number or average length\r
 168          *             exceeds what is defined by the limit\r
 169          * @see Preset\r
 170          */\r
 171         String presetAlign(\r
 172                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 173                         @WebParam(name = "preset") Preset<T> preset)\r
 174                         throws UnsupportedRuntimeException, LimitExceededException,\r
 175                         JobSubmissionException, WrongParameterException;\r
 176 \r
 177         /**\r
 178          * Return the result of the job. This method waits for the job\r
 179          * <code>jobId</code> to complete before return.\r
 180          * \r
 181          * @param jobId\r
 182          *            a unique job identifier\r
 183          * @return Alignment\r
 184          * @throws ResultNotAvailableException\r
 185          *             this exception is throw if the job execution was not\r
 186          *             successful or the result of the execution could not be found.\r
 187          *             (e.g. removed). Exception could also be thrown due to the\r
 188          *             lower level problems on the server i.e. IOException,\r
 189          *             FileNotFoundException problems as well as\r
 190          *             UnknownFileFormatException.\r
 191          * @throws InvalidParameterException\r
 192          *             thrown if jobId is empty or is not recognised e.g. in invalid\r
 193          *             format\r
 194          */\r
 195         Alignment getResult(@WebParam(name = "jobId") String jobId)\r
 196                         throws ResultNotAvailableException;\r
 197 \r
 198 }\r