X-Git-Url: https://gerrit.simantics.org/r/gitweb?a=blobdiff_plain;f=bundles%2Forg.simantics.databoard%2Fsrc%2Forg%2Fsimantics%2Fdataboard%2Fchannel%2FAsyncRequest.java;fp=bundles%2Forg.simantics.databoard%2Fsrc%2Forg%2Fsimantics%2Fdataboard%2Fchannel%2FAsyncRequest.java;h=65bcd68cf43742a8ad8d458409a7ebcc5bdf4641;hb=969bd23cab98a79ca9101af33334000879fb60c5;hp=0000000000000000000000000000000000000000;hpb=866dba5cd5a3929bbeae85991796acb212338a08;p=simantics%2Fplatform.git

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