webservices/compbio/data/msa/Annotation.java

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