webservices/compbio/data/msa/SequenceAnnotation.java

   1 /* Copyright (c) 2011 Peter Troshin\r
   2  *  \r
   3  *  JAva Bioinformatics Analysis Web Services (JABAWS) @version: 2.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 package compbio.data.msa;\r
  19 \r
  20 import java.security.InvalidParameterException;\r
  21 import java.util.List;\r
  22 \r
  23 import javax.jws.WebMethod;\r
  24 import javax.jws.WebParam;\r
  25 import javax.jws.WebService;\r
  26 \r
  27 import compbio.data.sequence.FastaSequence;\r
  28 import compbio.data.sequence.ScoreManager;\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  * Interface for tools that results to one or more annotation to sequence(s)\r
  39  * \r
  40  * Single, multiple sequences their groups or alignments can be annotated\r
  41  * \r
  42  * @author Peter Troshin\r
  43  * \r
  44  * @param <T>\r
  45  *            executable type / web service type\r
  46  * \r
  47  * @version 1.0 November 2010\r
  48  */\r
  49 @WebService(targetNamespace = JABAService.V2_SERVICE_NAMESPACE)\r
  50 public interface SequenceAnnotation<T>\r
  51                 extends\r
  52                         JABAService,\r
  53                         JManagement,\r
  54                         Metadata<T> {\r
  55 \r
  56         /**\r
  57          * \r
  58          * Analyse the sequences. The actual analysis algorithm is defined by the\r
  59          * type T.\r
  60          * \r
  61          * Any dataset containing a greater number of sequences or the average\r
  62          * length of the sequences are greater then defined in the default Limit\r
  63          * will not be accepted for an alignment operation and\r
  64          * JobSubmissionException will be thrown.\r
  65          * \r
  66          * @param sequences\r
  67          *            List of FastaSequence objects. The programme does not perform\r
  68          *            any sequence validity checks. Nor does it checks whether the\r
  69          *            sequences names are unique. It is responsibility of the caller\r
  70          *            to validate this information\r
  71          * @return jobId - unique identifier for the job\r
  72          * @throws JobSubmissionException\r
  73          *             is thrown when the job could not be submitted due to the\r
  74          *             following reasons: 1) The number of sequences in the\r
  75          *             submission or their average length is greater then defined by\r
  76          *             the default Limit. 2) Any problems on the server side e.g. it\r
  77          *             is misconfigured or malfunction, is reported via this\r
  78          *             exception. In the first case the information on the limit\r
  79          *             could be obtained from an exception.\r
  80          * @throws InvalidParameterException\r
  81          *             thrown if input list of fasta sequence is null or empty\r
  82          * @throws UnsupportedRuntimeException\r
  83          *             thrown if server OS does not support native executables for a\r
  84          *             given web service, e.g. JABAWS is deployed on Windows and\r
  85          *             Mafft service is called\r
  86          * @throws LimitExceededException\r
  87          *             is throw if the input sequences number or average length\r
  88          *             exceeds what is defined by the limit\r
  89          */\r
  90         @WebMethod\r
  91         String analize(\r
  92                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences)\r
  93                         throws UnsupportedRuntimeException, LimitExceededException,\r
  94                         JobSubmissionException;\r
  95 \r
  96         /**\r
  97          * Analyse the sequences according to custom settings defined in options\r
  98          * list. The actual analysis algorithm is defined by the type T. Default\r
  99          * Limit is used to decide whether the calculation will be permitted or\r
 100          * denied\r
 101          * \r
 102          * @param sequences\r
 103          *            List of FastaSequence objects. The programme does not perform\r
 104          *            any sequence validity checks. Nor does it checks whether the\r
 105          *            sequences names are unique. It is responsibility of the caller\r
 106          *            to validate this information\r
 107          * @param options\r
 108          *            A list of Options\r
 109          * @return jobId - unique identifier for the job\r
 110          * @throws JobSubmissionException\r
 111          *             is thrown when the job could not be submitted due to the\r
 112          *             following reasons: 1) The number of sequences in the\r
 113          *             submission or their average length is greater then defined by\r
 114          *             the default Limit. 2) Any problems on the server side e.g. it\r
 115          *             is misconfigured or malfunction, is reported via this\r
 116          *             exception. In the first case the information on the limit\r
 117          *             could be obtained from an exception.\r
 118          * @throws WrongParameterException\r
 119          *             is throws when 1) One of the Options provided is not\r
 120          *             supported, 2) The value of the option is defined outside the\r
 121          *             boundaries. In both cases exception object contain the\r
 122          *             information on the violating Option.\r
 123          * @throws InvalidParameterException\r
 124          *             thrown if input list of fasta sequence is null or empty\r
 125          * @throws UnsupportedRuntimeException\r
 126          *             thrown if server OS does not support native executables for a\r
 127          *             given web service, e.g. JABAWS is deployed on Windows and\r
 128          *             Mafft service is called\r
 129          * @throws LimitExceededException\r
 130          *             is throw if the input sequences number or average length\r
 131          *             exceeds what is defined by the limit\r
 132          * @see Option\r
 133          */\r
 134         @WebMethod\r
 135         String customAnalize(\r
 136                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 137                         @WebParam(name = "options") List<Option<T>> options)\r
 138                         throws UnsupportedRuntimeException, LimitExceededException,\r
 139                         JobSubmissionException, WrongParameterException;\r
 140 \r
 141         /**\r
 142          * Analyse the sequences according to the preset settings. The actual\r
 143          * analysis algorithm is defined by the type T.\r
 144          * \r
 145          * Limit for a presetName is used whether the calculation will be permitted\r
 146          * or denied. If no Limit was defined for a presetName, than default limit\r
 147          * is used.\r
 148          * \r
 149          * @param sequences\r
 150          *            List of FastaSequence objects. The programme does not perform\r
 151          *            any sequence validity checks. Nor does it checks whether the\r
 152          *            sequences names are unique. It is responsibility of the caller\r
 153          *            to validate this information\r
 154          * @param preset\r
 155          *            A list of Options\r
 156          * @return String - jobId - unique identifier for the job\r
 157          * @throws JobSubmissionException\r
 158          *             is thrown when the job could not be submitted due to the\r
 159          *             following reasons: 1) The number of sequences in the\r
 160          *             submission or their average length is greater then defined by\r
 161          *             the default Limit. 2) Any problems on the server side e.g. it\r
 162          *             is misconfigured or malfunction, is reported via this\r
 163          *             exception. In the first case the information on the limit\r
 164          *             could be obtained from an exception.\r
 165          * @throws WrongParameterException\r
 166          *             is throws when 1) One of the Options provided is not\r
 167          *             supported, 2) The value of the option is defined outside the\r
 168          *             boundaries. In both cases exception object contain the\r
 169          *             information on the violating Option.\r
 170          * @throws InvalidParameterException\r
 171          *             thrown if input list of fasta sequence is null or empty\r
 172          * @throws UnsupportedRuntimeException\r
 173          *             thrown if server OS does not support native executables for a\r
 174          *             given web service, e.g. JABAWS is deployed on Windows and\r
 175          *             Mafft service is called\r
 176          * @throws LimitExceededException\r
 177          *             is throw if the input sequences number or average length\r
 178          *             exceeds what is defined by the limit\r
 179          */\r
 180         @WebMethod\r
 181         String presetAnalize(\r
 182                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 183                         @WebParam(name = "preset") Preset<T> preset)\r
 184                         throws UnsupportedRuntimeException, LimitExceededException,\r
 185                         JobSubmissionException, WrongParameterException;\r
 186 \r
 187         /**\r
 188          * Return the result of the job.\r
 189          * \r
 190          * @param jobId\r
 191          *            a unique job identifier\r
 192          * @return the Map with the sequence names, sequence group names or the word\r
 193          *         'Alignment' in case of alignments and values the represented by a\r
 194          *         Set of Score objects. The alignment can be represented in as\r
 195          *         little as one key->value pair in this map, the list of sequences\r
 196          *         will be represented by multiple key->value mappings. If multiple\r
 197          *         annotations were calculated, then they are represented as a Set\r
 198          *         of Scores.\r
 199          * @throws ResultNotAvailableException\r
 200          *             this exception is throw if the job execution was not\r
 201          *             successful or the result of the execution could not be found.\r
 202          *             (e.g. removed). Exception could also be thrown is dues to the\r
 203          *             lower level problems on the server i.e. IOException,\r
 204          *             FileNotFoundException problems as well as\r
 205          *             UnknownFileFormatException.\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          */\r
 211         @WebMethod\r
 212         ScoreManager getAnnotation(@WebParam(name = "jobId") String jobId)\r
 213                         throws ResultNotAvailableException;\r
 214         /*\r
 215          * The method should really return Map and Set, but unfortunately JAXB\r
 216          * cannot serialize interfaces, has a concrete implementation is used Could\r
 217          * also specify the generic Set e.g. ? extends Set. But this would require\r
 218          * the client cast or operate with generic Set. Keep it simple for now.\r
 219          */\r
 220 }\r