bundles/org.simantics.databoard/src/org/simantics/databoard/channel/AsyncRequest.java

   1 package org.simantics.databoard.channel;\r
   2 \r
   3 import java.io.IOException;\r
   4 import java.util.concurrent.Executor;\r
   5 import java.util.concurrent.TimeUnit;\r
   6 import java.util.concurrent.TimeoutException;\r
   7 \r
   8 import org.simantics.databoard.binding.Binding;\r
   9 \r
  10 /**\r
  11  * Delayed response object. The result or error may be or become available to\r
  12  * this object at any given time.    \r
  13  * \r
  14  * This interface is intended to be used by clients that make service requests\r
  15  * over command channel. \r
  16  *\r
  17  * @author Toni Kalajainen <toni.kalajainen@iki.fi>\r
  18  */\r
  19 public interface AsyncRequest {\r
  20 \r
  21         /**\r
  22          * Get the current request status. <p>\r
  23          *  \r
  24          * If Succeeded or Failed, then result or error is available and can be read \r
  25          * without wait. <p>\r
  26          * \r
  27          * Succeeded and Failed statuses are final. <p>\r
  28          */\r
  29         enum Status {Waiting, Succeed, Failed} Status getStatus();                      \r
  30         \r
  31         /**\r
  32          * Get result if available. \r
  33          * \r
  34          * @param binding\r
  35          * @return result or <tt>null</tt>\r
  36          * @throws RequestException\r
  37          */\r
  38         Object getResult(Binding binding) throws RequestException;\r
  39         \r
  40         /**\r
  41          * Get error if available.\r
  42          * \r
  43          * Cause is (typically) one of these:\r
  44          *  o Communication problems {@link IOException}\r
  45          *  o Timeout {@link TimeoutException}\r
  46          *  o Service(handler) problem {@link ServiceException}\r
  47          * \r
  48          * @return error or <tt>null</tt>\r
  49          */\r
  50         Exception getError();   \r
  51         \r
  52         /**\r
  53          * Synchronous wait for result until default timeout. \r
  54          * Default timeout is configured to the channel. \r
  55          * If timeout occurs TimeoutException is thrown wrapped in RequestException.\r
  56          * \r
  57          * @param binding the format for the result\r
  58          * @return the result object\r
  59          * @throws RequestException\r
  60          */\r
  61         Object waitForResult(Binding binding) throws RequestException;\r
  62         \r
  63         /**\r
  64          * Wait for result or break after until timeout. \r
  65          * If timeout occurs TimeoutException is thrown wrapped in RequestException.\r
  66          * \r
  67          * @param binding\r
  68          * @param timeout\r
  69          * @param unit\r
  70          * @return result\r
  71          * @throws RequestException\r
  72          */\r
  73         Object waitForResult(Binding binding, long timeout, TimeUnit unit) throws RequestException;\r
  74 \r
  75         /**\r
  76          * Set a listener. If the result is already available, the event\r
  77          * schedueled immediately.\r
  78          * \r
  79          * @param listener (listener may not block) or null to remove listener\r
  80          */\r
  81         void setListener(RequestListener listener);\r
  82         \r
  83         interface RequestListener {\r
  84                 \r
  85                 /**\r
  86                  * Get thread where the listening is to be processed\r
  87                  *   \r
  88                  * @return thread to run listener events\r
  89                  */\r
  90                 Executor getThread();\r
  91                 \r
  92                 /**\r
  93                  * Request completed, the result is available\r
  94                  * \r
  95                  * @param result the result \r
  96                  */\r
  97                 void onCompleted(Object result);\r
  98                 \r
  99                 /**\r
 100                  * There was an error in processing the request\r
 101                  * \r
 102                  * @param error the error\r
 103                  */\r
 104                 void onError(ServiceException error);\r
 105                 \r
 106         }\r
 107         \r
 108 }\r