+package org.simantics.databoard.channel;\r
+\r
+import java.io.IOException;\r
+import java.util.concurrent.Executor;\r
+import java.util.concurrent.TimeUnit;\r
+import java.util.concurrent.TimeoutException;\r
+\r
+import org.simantics.databoard.binding.Binding;\r
+\r
+/**\r
+ * Delayed response object. The result or error may be or become available to\r
+ * this object at any given time. \r
+ * \r
+ * This interface is intended to be used by clients that make service requests\r
+ * over command channel. \r
+ *\r
+ * @author Toni Kalajainen <toni.kalajainen@iki.fi>\r
+ */\r
+public interface AsyncRequest {\r
+\r
+ /**\r
+ * Get the current request status. <p>\r
+ * \r
+ * If Succeeded or Failed, then result or error is available and can be read \r
+ * without wait. <p>\r
+ * \r
+ * Succeeded and Failed statuses are final. <p>\r
+ */\r
+ enum Status {Waiting, Succeed, Failed} Status getStatus(); \r
+ \r
+ /**\r
+ * Get result if available. \r
+ * \r
+ * @param binding\r
+ * @return result or <tt>null</tt>\r
+ * @throws RequestException\r
+ */\r
+ Object getResult(Binding binding) throws RequestException;\r
+ \r
+ /**\r
+ * Get error if available.\r
+ * \r
+ * Cause is (typically) one of these:\r
+ * o Communication problems {@link IOException}\r
+ * o Timeout {@link TimeoutException}\r
+ * o Service(handler) problem {@link ServiceException}\r
+ * \r
+ * @return error or <tt>null</tt>\r
+ */\r
+ Exception getError(); \r
+ \r
+ /**\r
+ * Synchronous wait for result until default timeout. \r
+ * Default timeout is configured to the channel. \r
+ * If timeout occurs TimeoutException is thrown wrapped in RequestException.\r
+ * \r
+ * @param binding the format for the result\r
+ * @return the result object\r
+ * @throws RequestException\r
+ */\r
+ Object waitForResult(Binding binding) throws RequestException;\r
+ \r
+ /**\r
+ * Wait for result or break after until timeout. \r
+ * If timeout occurs TimeoutException is thrown wrapped in RequestException.\r
+ * \r
+ * @param binding\r
+ * @param timeout\r
+ * @param unit\r
+ * @return result\r
+ * @throws RequestException\r
+ */\r
+ Object waitForResult(Binding binding, long timeout, TimeUnit unit) throws RequestException;\r
+\r
+ /**\r
+ * Set a listener. If the result is already available, the event\r
+ * schedueled immediately.\r
+ * \r
+ * @param listener (listener may not block) or null to remove listener\r
+ */\r
+ void setListener(RequestListener listener);\r
+ \r
+ interface RequestListener {\r
+ \r
+ /**\r
+ * Get thread where the listening is to be processed\r
+ * \r
+ * @return thread to run listener events\r
+ */\r
+ Executor getThread();\r
+ \r
+ /**\r
+ * Request completed, the result is available\r
+ * \r
+ * @param result the result \r
+ */\r
+ void onCompleted(Object result);\r
+ \r
+ /**\r
+ * There was an error in processing the request\r
+ * \r
+ * @param error the error\r
+ */\r
+ void onError(ServiceException error);\r
+ \r
+ }\r
+ \r
+}\r