Migrated source code from Simantics SVN

[simantics/platform.git] / bundles / org.simantics.databoard / src / org / simantics / databoard / channel / AsyncRequest.java

diff --git a/bundles/org.simantics.databoard/src/org/simantics/databoard/channel/AsyncRequest.java b/bundles/org.simantics.databoard/src/org/simantics/databoard/channel/AsyncRequest.java
new file mode 100644 (file)
index 0000000..65bcd68
--- /dev/null
+++ b/bundles/org.simantics.databoard/src/org/simantics/databoard/channel/AsyncRequest.java
@@ -0,0 +1,108 @@
+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