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

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