]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.databoard/src/org/simantics/databoard/method/MethodInterface.java
Improve Databoard's dynamically typed data capabilities.
[simantics/platform.git] / bundles / org.simantics.databoard / src / org / simantics / databoard / method / MethodInterface.java
1 /*******************************************************************************\r
2  *  Copyright (c) 2010 Association for Decentralized Information Management in\r
3  *  Industry THTH ry.\r
4  *  All rights reserved. This program and the accompanying materials\r
5  *  are made available under the terms of the Eclipse Public License v1.0\r
6  *  which accompanies this distribution, and is available at\r
7  *  http://www.eclipse.org/legal/epl-v10.html\r
8  *\r
9  *  Contributors:\r
10  *      VTT Technical Research Centre of Finland - initial API and implementation\r
11  *******************************************************************************/\r
12 package org.simantics.databoard.method;
13
14 import java.util.concurrent.TimeUnit;\r
15 \r
16 import org.simantics.databoard.Datatypes;\r
17
18 /**\r
19  * MethodInterface is an interface for invoking methods.<p> 
20  *\r
21  * If MethodInterface is executed on TCP/IP socket, the current\r
22  * Connection can be acquired with Connection#getCurrentConnection().\r
23  * You can attach close listener this way.<p>\r
24  * \r
25  * MethodInterface may be used from multiple-threads simultaneously.
26  * 
27  * @see Server puts a MethodInterface in a server socket 
28  * @see Client creates a MethodInterface from a socket connection
29  * @see Datatypes to create MethodInterface from an interface  
30  * @see Datatypes to create MethodInterface implementation from an object
31  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
32  * @author Hannu Niemisto
33  */
34 public interface MethodInterface {
35         
36         /**
37          * Get method descriptions
38          * 
39          * @return method descriptions
40          */
41         Interface getInterface();
42
43         /**
44          * Get an access to the implementation of a method. The binding is suggested by the producer. 
45          * 
46          * @param description method description
47          * @return method access
48          * @throws MethodNotSupportedException
49          */
50         Method getMethod(MethodTypeDefinition description)
51         throws MethodNotSupportedException;
52         
53         /**
54          * Get an access to the implementation of a method. The binding is suggested by the consumer.
55          * 
56          * @param binding binding to use
57          * @return method access
58          * @throws MethodNotSupportedException
59          */
60         Method getMethod(MethodTypeBinding binding)
61         throws MethodNotSupportedException;
62         
63         /**
64          * Access to the implementation of a method.
65          */
66         public interface Method {
67                 AsyncResult invoke(Object request);
68                 MethodTypeBinding getMethodBinding();
69         }
70         
71         public interface AsyncResult {
72                 
73                 /**
74                  * Add a listener. It will be notified immediately if the response is
75                  * available. 
76                  *  
77                  * @param listener (listener may not block) or null to remove listener
78                  */
79                 void setListener(InvokeListener listener);
80                 
81                 /**
82                  * 
83                  * @return response or null
84                  */
85                 Object getResponse();
86                 
87                 Object getExecutionError(); 
88                 
89                 InvokeException getInvokeException(); 
90                 
91                 AsyncRequestStatus getStatus(); 
92                 
93                 /**
94                  * 
95                  * @return response
96                  * @throws InterruptedException block was canceled
97                  * @throws InvokeException network error, e.g. IOException of MethodNotSupportedException
98                  * @throws ExecutionError error that occured while executing the method 
99                  */
100                 Object waitForResponse() 
101                 throws InvokeException, ExecutionError, InterruptedException;
102                 
103                 /**
104                  * 
105                  * @return response
106                  * @throws InterruptedException 
107                  * @throws InvokeException network error, e.g. IOException of MethodNotSupportedException
108                  * @throws ExecutionError error that occured while executing the method 
109                  */
110                 Object waitForResponse(long timeout, TimeUnit unit)
111                 throws InvokeException, ExecutionError, InterruptedException;
112                 
113         }
114         
115         enum AsyncRequestStatus {Waiting, Succeed, Failed}
116         
117         public interface InvokeListener {
118                 void onCompleted(Object result);
119                 void onExecutionError(Object error);
120                 void onException(Exception cause);
121         }
122         
123         /**
124          * A wrapper to an error that occured in the execution of the method.
125          */
126         public static class ExecutionError extends Exception {
127                 private static final long serialVersionUID = 1L;
128                 Object error;
129                 public ExecutionError(Object error) {
130                         this.error = error;
131                 }
132                 public Object getError() {
133                         return error;
134                 }
135         }
136                 
137 }
138