]> gerrit.simantics Code Review - simantics/platform.git/blob - bundles/org.simantics.databoard/src-isv/spec/Remote Procedure Call.mediawiki
Support dependency embedding in generic model export/import
[simantics/platform.git] / bundles / org.simantics.databoard / src-isv / spec / Remote Procedure Call.mediawiki
1 =Remote Procedure Call=
2 Databoard RPC is a method call interface. 
3 Server is an object that handles service requests. 
4 The server publishes an [[#Interfaces]] that contains a list of callable methods.
5
6 ===Network Protocol===
7 The protocol is very simple. There are two conversing peers, one is ''the client'' and the other ''the server''.
8 Both parties introduce callable ''network interface''. Typically, the server's has plenty of procedures, and client's 
9 has some callbacks. 
10 The connection starts with handshake and is then followed by repeating conversation of writing ''Requests'' and reading ''Responses''.
11
12 In handshake, boths peers write their ''InterfaceDescription'' and message size limits. 
13 (See [[#Definitions|Definitions]]).
14 Then both parties make a decision to whether accept or reject the other's interface.
15
16 =Interfaces=
17 ''A function type'' can be constructed as <tt>D -> R</tt>, where <tt>D</tt> is the domain and <tt>R</tt> the range of the function.
18 If the function can throw exceptions, it is denoted as <tt>D -> R throws E<sub>1</sub>, ..., E<sub>k</sub></tt>, where
19 <tt>E<sub>i</sub></tt> is a datatype for an exception. Multi-parameter types can be defined using the tuple notation:
20     Double -> Double
21     () -> String
22     (Integer,Integer) -> Integer
23     Integer -> Integer throws IndexOutOfRange
24
25 ''A method definition'' is a combination of name and method type. 
26 The format is following, <tt>method M : T</tt>, where <tt>M</tt> is the name and <tt>T</tt> the type of the method. 
27 <tt>T</tt> has to be a function type. 
28     method getSamples : TimeSegment -> Sample[],
29     method read : ReadRequest -> Sample,
30     method getValueBounds : TimeSegment -> Sample[2]
31
32 ''Interface'' is a specification of fields and methods the interface has to have. 
33 The interface is defined as a record that contains fields and methods definitions in the curly braces.
34     interface HistoryRecord = {
35              records : TimeSeries,
36  
37              method getSamples : TimeSegment -> Sample[],
38              method read : ReadRequest -> Sample,
39              method getValueBounds : TimeSegment -> Sample[2]
40          }
41
42 Interfaces may extend other interfaces. This is denoted as <tt>interface I extends B<sub>1</sub>, ..., B<sub>k</sub> { ... }</tt>.
43     interface MutableHistoryRecord extends HistoryRecord = {
44              method write : Sample[] -> {},
45              method clear : {} -> {}
46          }
47
48 ====Request====
49 Client sends RequestHeader, followed by a serialization of the message's request argument.
50 The datatype and thus serialization format of the request argument was defined in MethodType which was informed by the server in the handshake. 
51
52 The server processes the procedure request.
53 * On procedure success, ResponseHeader is sent, followed by a serialization of ResponseType. ResponseType serialization format was declared in MethodType.
54 * On procedure failure, ExecutionError_ is sent, followed by a serialization of ErrorType. ErrorType format was declared in MethodType.
55 * On unexpected error, Exception_ is sent
56 * On invalid method number, InvalidMethodError is sent
57 * On request or response message size exceeded, ResponseTooLargeError is sent
58
59
60 ==Definitions==
61   type Interface = {
62          methodDefinitions : Map(MethodTypeDefinition, {})
63        }
64   
65   type InterfaceDefinition = {
66          name : String,
67          type : Interface
68        }
69   
70   type MethodType = {
71          requestType : DataType,
72          responseType : DataType,
73          errorType : UnionType
74        }
75    
76   type MethodTypeDefinition = {
77          name : String,
78          type : MethodType
79        }
80
81   type Handshake = | Version0
82   
83   type Version0 = {
84          recvMsgLimit : Integer,
85          sendMsgLimit : Integer,
86          methods : MethodTypeDefinition[]
87        }
88   
89   type Message = | RequestHeader RequestHeader 
90                  | ResponseHeader ResponseHeader
91                  | ExecutionError_ ExecutionError_
92                  | Exception_ Exception_
93                  | InvalidMethodError InvalidMethodError
94                  | ResponseTooLarge ResponseTooLarge
95   
96   type RequestHeader = {
97          requestId : Integer,
98          methodId : Integer
99        }
100   
101   type ResponseHeader = {
102          requestId : Integer
103        }
104   
105   type ExecutionError_ = {
106          requestId : Integer
107        }
108   
109   type InvalidMethodError = {
110          requestId : Integer
111        }
112   
113   type Exception_ = {
114          requestId : Integer,         
115          message : String
116        }
117   
118   type ResponseTooLarge = {
119          requestId : Integer    
120        }