webservices/compbio/data/msa/Annotation.java

   1 package compbio.data.msa;\r
   2 \r
   3 import java.security.InvalidParameterException;\r
   4 import java.util.List;\r
   5 \r
   6 import javax.jws.WebParam;\r
   7 import javax.jws.WebService;\r
   8 \r
   9 import compbio.data.sequence.FastaSequence;\r
  10 import compbio.metadata.JobSubmissionException;\r
  11 import compbio.metadata.LimitExceededException;\r
  12 import compbio.metadata.Option;\r
  13 import compbio.metadata.Preset;\r
  14 import compbio.metadata.ResultNotAvailableException;\r
  15 import compbio.metadata.UnsupportedRuntimeException;\r
  16 import compbio.metadata.WrongParameterException;\r
  17 \r
  18 /**\r
  19  * Interface for tools that results to one or more annotation to sequence(s)\r
  20  * \r
  21  * @author pvtroshin\r
  22  * \r
  23  *         Date November 2010\r
  24  * \r
  25  * @param <T>\r
  26  *            executable type / web service type\r
  27  */\r
  28 @WebService(targetNamespace = "http://msa.data.compbio/01/12/2010/")\r
  29 public interface Annotation<T> extends JManagement, Metadata<T> {\r
  30 \r
  31         /**\r
  32          * \r
  33          * Any dataset containing a greater number of sequences or the average\r
  34          * length of the sequences are greater then defined in the default Limit\r
  35          * will not be accepted for an alignment operation and\r
  36          * JobSubmissionException will be thrown.\r
  37          * \r
  38          * @param sequences\r
  39          *            List of FastaSequence objects. The programme does not perform\r
  40          *            any sequence validity checks. Nor does it checks whether the\r
  41          *            sequences names are unique. It is responsibility of the caller\r
  42          *            to validate this information\r
  43          * @return jobId - unique identifier for the job\r
  44          * @throws JobSubmissionException\r
  45          *             is thrown when the job could not be submitted due to the\r
  46          *             following reasons: 1) The number of sequences in the\r
  47          *             submission or their average length is greater then defined by\r
  48          *             the default Limit. 2) Any problems on the server side e.g. it\r
  49          *             is misconfigured or malfunction, is reported via this\r
  50          *             exception. In the first case the information on the limit\r
  51          *             could be obtained from an exception.\r
  52          * @throws InvalidParameterException\r
  53          *             thrown if input list of fasta sequence is null or empty\r
  54          * @throws UnsupportedRuntimeException\r
  55          *             thrown if server OS does not support native executables for a\r
  56          *             given web service, e.g. JWS2 is deployed on Windows and Mafft\r
  57          *             service is called\r
  58          * @throws LimitExceededException\r
  59          *             is throw if the input sequences number or average length\r
  60          *             exceeds what is defined by the limit\r
  61          */\r
  62         String analize(\r
  63                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences)\r
  64                         throws UnsupportedRuntimeException, LimitExceededException,\r
  65                         JobSubmissionException;\r
  66 \r
  67         /**\r
  68          * \r
  69          * @see Option\r
  70          * \r
  71          *      Default Limit is used to decide whether the calculation will be\r
  72          *      permitted or denied\r
  73          * \r
  74          * @param sequences\r
  75          *            List of FastaSequence objects. The programme does not perform\r
  76          *            any sequence validity checks. Nor does it checks whether the\r
  77          *            sequences names are unique. It is responsibility of the caller\r
  78          *            to validate this information\r
  79          * @param options\r
  80          *            A list of Options\r
  81          * @return jobId - unique identifier for the job\r
  82          * @throws JobSubmissionException. This\r
  83          *             exception is thrown when the job could not be submitted due\r
  84          *             to the following reasons: 1) The number of sequences in the\r
  85          *             submission or their average length is greater then defined by\r
  86          *             the default Limit. 2) Any problems on the server side e.g. it\r
  87          *             is misconfigured or malfunction, is reported via this\r
  88          *             exception. In the first case the information on the limit\r
  89          *             could be obtained from an exception.\r
  90          * @throws WrongParameterException\r
  91          *             is throws when 1) One of the Options provided is not\r
  92          *             supported, 2) The value of the option is defined outside the\r
  93          *             boundaries. In both cases exception object contain the\r
  94          *             information on the violating Option.\r
  95          * @throws InvalidParameterException\r
  96          *             thrown if input list of fasta sequence is null or empty\r
  97          * @throws UnsupportedRuntimeException\r
  98          *             thrown if server OS does not support native executables for a\r
  99          *             given web service, e.g. JWS2 is deployed on Windows and Mafft\r
 100          *             service is called\r
 101          * @throws LimitExceededException\r
 102          *             is throw if the input sequences number or average length\r
 103          *             exceeds what is defined by the limit\r
 104          */\r
 105         String customAnalize(\r
 106                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 107                         @WebParam(name = "options") List<Option<T>> options)\r
 108                         throws UnsupportedRuntimeException, LimitExceededException,\r
 109                         JobSubmissionException, WrongParameterException;\r
 110 \r
 111         /**\r
 112          * \r
 113          * \r
 114          * Limit for a presetName is used whether the calculation will be permitted\r
 115          * or denied. If no Limit was defined for a presetName, than default limit\r
 116          * is used.\r
 117          * \r
 118          * @param sequences\r
 119          *            List of FastaSequence objects. The programme does not perform\r
 120          *            any sequence validity checks. Nor does it checks whether the\r
 121          *            sequences names are unique. It is responsibility of the caller\r
 122          *            to validate this information\r
 123          * @param preset\r
 124          *            A list of Options\r
 125          * @return String - jobId - unique identifier for the job\r
 126          * @throws JobSubmissionException. This\r
 127          *             exception is thrown when the job could not be submitted due\r
 128          *             to the following reasons: 1) The number of sequences in the\r
 129          *             submission or their average length is greater then defined by\r
 130          *             the default Limit. 2) Any problems on the server side e.g. it\r
 131          *             is misconfigured or malfunction, is reported via this\r
 132          *             exception. In the first case the information on the limit\r
 133          *             could be obtained from an exception.\r
 134          * @throws WrongParameterException\r
 135          *             is throws when 1) One of the Options provided is not\r
 136          *             supported, 2) The value of the option is defined outside the\r
 137          *             boundaries. In both cases exception object contain the\r
 138          *             information on the violating Option.\r
 139          * @throws InvalidParameterException\r
 140          *             thrown if input list of fasta sequence is null or empty\r
 141          * @throws UnsupportedRuntimeException\r
 142          *             thrown if server OS does not support native executables for a\r
 143          *             given web service, e.g. JWS2 is deployed on Windows and Mafft\r
 144          *             service is called\r
 145          * @throws LimitExceededException\r
 146          *             is throw if the input sequences number or average length\r
 147          *             exceeds what is defined by the limit\r
 148          */\r
 149         String presetAnalize(\r
 150                         @WebParam(name = "fastaSequences") List<FastaSequence> sequences,\r
 151                         @WebParam(name = "preset") Preset<T> preset)\r
 152                         throws UnsupportedRuntimeException, LimitExceededException,\r
 153                         JobSubmissionException, WrongParameterException;\r
 154 \r
 155         /**\r
 156          * Return the result of the job.\r
 157          * \r
 158          * @param jobId\r
 159          *            a unique job identifier\r
 160          * @return\r
 161          * @throws ResultNotAvailableException\r
 162          *             this exception is throw if the job execution was not\r
 163          *             successful or the result of the execution could not be found.\r
 164          *             (e.g. removed). Exception could also be thrown is dues to the\r
 165          *             lower level problems on the server i.e. IOException,\r
 166          *             FileNotFoundException problems as well as\r
 167          *             UnknownFileFormatException.\r
 168          * @throws InvalidParameterException\r
 169          *             thrown if jobId is empty or cannot be recognised e.g. in\r
 170          *             invalid format\r
 171          */\r
 172         String getResult(@WebParam(name = "jobId") String jobId)\r
 173                         throws ResultNotAvailableException;\r
 174 }\r