bundles/org.simantics.databoard/src-isv/spec/Remote Procedure Call.mediawiki

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