engine/compbio/engine/AsyncExecutor.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.engine;\r
  20 \r
  21 import compbio.engine.client.ConfiguredExecutable;\r
  22 import compbio.metadata.JobStatus;\r
  23 import compbio.metadata.JobSubmissionException;\r
  24 import compbio.metadata.ResultNotAvailableException;\r
  25 \r
  26 /**\r
  27  * An asynchronous executor engine, capable of running, cancelling, \r
  28  * obtaining results calculated by a native executable wrapper in Executable interface. \r
  29  * Implementation agnostic. Executables can be run either locally to the JVM or on the cluster. \r
  30  *    \r
  31  * @author pvtroshin\r
  32  *              Date October 2009\r
  33  */\r
  34 public interface AsyncExecutor {\r
  35 \r
  36         /**\r
  37          * Submits job for the execution\r
  38          * Immediate execution is not guaranteed, this method puts the job in the queue. \r
  39          * All it guarantees that the job will be eventually executed. \r
  40          * The start of execution will depend on the number of jobs in the queue.\r
  41          *  \r
  42          * @return unique job identifier\r
  43          * @throws JobSubmissionException\r
  44          *             if submission fails. This usually happens due to the problem on a server side. \r
  45          */\r
  46         String submitJob(ConfiguredExecutable<?> executable)\r
  47                         throws JobSubmissionException;\r
  48 \r
  49         /**\r
  50          * Retrieve the results of the job. Please not that current implementations of this method \r
  51          * blocks if the task is running until the end of the calculation.  \r
  52          * \r
  53          * @param jobId job identifier obtained at the job submission \r
  54          * @return ConfiguredExecutable object from which result can be obtained\r
  55          * @throws ResultNotAvailableException if the result is not available for whatever reason. \r
  56          * Could be due to execution failure, or due to the results being removed from the server at \r
  57          * the time of request.  \r
  58          */\r
  59         ConfiguredExecutable<?> getResults(String jobId)\r
  60                         throws ResultNotAvailableException;\r
  61 \r
  62         /**\r
  63          * \r
  64          * @param jobId unique job identifier \r
  65          * @return task working directory\r
  66          */\r
  67         String getWorkDirectory(String jobId);\r
  68 \r
  69         /**\r
  70          * Remove all files and a job directory for a jobid. \r
  71          * @param jobId\r
  72          * @return true if job directory was successfully removed, false otherwise.  \r
  73          */\r
  74         boolean cleanup(String jobId);\r
  75 \r
  76         /**\r
  77          * Stop running job. Please not that this method does not guarantee to remove the job directory and files in it.  \r
  78          * \r
  79          * @return true if job was cancelled successfully, false otherwise\r
  80          */\r
  81         boolean cancelJob(String jobId);\r
  82 \r
  83         /**\r
  84          *  Query the status of the job \r
  85          * @param String\r
  86          *            jobId - unique job identifier\r
  87          * @return The JobStatus object representing the status of the job\r
  88          * @see JobStatus\r
  89          */\r
  90         JobStatus getJobStatus(String jobId);\r
  91 \r
  92 }\r