Difference between revisions of "RAP/Protocol"

From Eclipsepedia

< RAP
Jump to: navigation, search
(Operation)
(Operation)
Line 37: Line 37:
 
</source>
 
</source>
  
=== Operation ===
+
=== Operations ===
 +
 
 +
The operations are commands that the peer must execute in the order they appear in the message.
 +
There are different types of operations: create, set, call, listen, and destroy.
 +
Every operation has a target object. In case of a create operation, the target object is to be created, for all other operations, the target object must already exist.
  
There are five different types of operations: create, set, call, listen, and destroy.
 
 
<source lang="javascript">
 
<source lang="javascript">
 
   Operation ::= CreateOperation | SetOperation | CallOperation | ListenOperation | DestroyOperation
 
   Operation ::= CreateOperation | SetOperation | CallOperation | ListenOperation | DestroyOperation
Line 46: Line 49:
 
Operations are processed in the order of their appearance in the message. Unkown operations will be ignored.
 
Operations are processed in the order of their appearance in the message. Unkown operations will be ignored.
  
==== CreateOperation ====
+
==== Create ====
  
 
A create operation advises the peer to create an object of the given type and attach a given id to it.
 
A create operation advises the peer to create an object of the given type and attach a given id to it.
Line 56: Line 59:
 
   "target" : TargetId,
 
   "target" : TargetId,
 
   "type" : TypeName,
 
   "type" : TypeName,
   "properties" : CreateProperties
+
   "properties" : { PropertyName : PropertyValue ( , PropertyName : PropertyValue )* }
 
}
 
}
 
</source>
 
</source>
  
==== SetOperation ====
+
<source lang="javascript">
 +
TargetId ::= <string> // the id of the object to create
 +
TypeName ::= <string> // the fully qualified name of the type
 +
PropertyName ::= <string> // the name of a property to set
 +
PropertyValue ::= <any JSON value> // the initial value for this property
 +
</source>
 +
 
 +
==== Set ====
  
 
A set operation advises the peer to set a number of properties of the given target object.
 
A set operation advises the peer to set a number of properties of the given target object.
Line 68: Line 78:
 
   "action" : "set",
 
   "action" : "set",
 
   "target" : TargetId,
 
   "target" : TargetId,
   "properties" : SetProperties
+
   "properties" : { PropertyName : PropertyValue ( , PropertyName : PropertyValue )* }
 
}
 
}
 
</source>
 
</source>
  
==== CallOperation ====
+
<source lang="javascript">
 +
TargetId ::= <string> // the id of the object to set properties to
 +
PropertyName ::= <string> // the name of a property to set
 +
PropertyValue ::= <any JSON value> // the new value for this property
 +
</source>
 +
 
 +
==== Call ====
  
 
A call operation advises the peer to call a method on the target object.
 
A call operation advises the peer to call a method on the target object.
Line 81: Line 97:
 
   "target" : TargetId,
 
   "target" : TargetId,
 
   "method" : MethodName,
 
   "method" : MethodName,
   "properties" : CallProperties
+
   "properties" : { ParameterName : ParameterValue ( , ParameterName : ParameterValue )* }
 
}
 
}
 
</source>
 
</source>
  
==== ListenOperation ====
+
<source lang="javascript">
 +
TargetId ::= <string> // the id of the object to call a method on
 +
MethodName ::= <string> // the name of the method to call
 +
ParameterName ::= <string> // the name of a method parameter
 +
ParameterValue ::= <any JSON value> // the value for the method parameter
 +
</source>
 +
 
 +
==== Listen ====
  
 
A listen operation advises the peer to listen on certain types of events.
 
A listen operation advises the peer to listen on certain types of events.
  
 
<source lang="javascript">
 
<source lang="javascript">
ListenOperation ::= {  
+
ListenOperation ::= {
 
   "action" : "listen",
 
   "action" : "listen",
 
   "target" : TargetId,
 
   "target" : TargetId,
   "properties" : ListenProperties
+
   "properties" : { EventName : ListenToEvent ( , EventName : ListenToEvent )* }
 
}
 
}
 
</source>
 
</source>
  
 +
<source lang="javascript">
 +
TargetId ::= <string> // the id of the object to set properties to
 +
EventName ::= <string> // the name of an event
 +
ListenToEvent ::= <boolean> // whether to listen to the given event or not
 +
</source>
  
==== DestroyOperation ====
+
==== Destroy ====
  
 
A destroy operation advises the peer to destroy the target object.
 
A destroy operation advises the peer to destroy the target object.
Line 109: Line 137:
 
</source>
 
</source>
  
==== TargetId ====
+
<source lang="javascript">
 
+
TargetId ::= <string> // the id of the object to destroy
The id of the target object as string
+
</source>
 
+
==== TypeName ====
+
 
+
The name of the type to create
+
 
+
==== MethodName ====
+
 
+
The name of the method to call
+
  
 
== Data Type Reference ==
 
== Data Type Reference ==

Revision as of 17:22, 20 January 2012

Contents

Introduction

NOTE: All information within this document is subject to change until further notice.

The RAP Protocol is the JSON-based format used within the HTTP-Requests from a RAP-client to a RAP-server. Compared with the previously used JavaScript and HTTP-fields based communication it will provide a number of advantages:

  • It allowes to move all client-specific code from the server to the client.
  • It produces human readable messages, easing debugging.
  • It allowes the client to create more informative error messages.
  • It allowes to replace either ends as long as they process and create valid RAP-protocol messages.
  • It allowes to add client-independent client-side scripting.

The protocol is currently beeing developed in CVS HEAD. Server-to-Client communication is completed for all RWT-Widgets and will be part of the 1.5 release. Client-to-Server communication will possibly be implemented after 1.5.

Protocol Format

The protocol is based on the JSON fromat as described here: [ http://www.json.org/ ]

Message

There is exactly one message in a response. A message contains of a meta part and a list of operations.

{
  "meta" : Meta,
  "operations" : [ Operation* ]
}

Meta

{
  "requestCounter" : <integer number>
}

Operations

The operations are commands that the peer must execute in the order they appear in the message. There are different types of operations: create, set, call, listen, and destroy. Every operation has a target object. In case of a create operation, the target object is to be created, for all other operations, the target object must already exist.

  Operation ::= CreateOperation | SetOperation | CallOperation | ListenOperation | DestroyOperation

Operations are processed in the order of their appearance in the message. Unkown operations will be ignored.

Create

A create operation advises the peer to create an object of the given type and attach a given id to it. The CreateProperties contain properties that should be initially set on the created objects.

CreateOperation ::= {
  "action" : "create",
  "target" : TargetId,
  "type" : TypeName,
  "properties" : { PropertyName : PropertyValue ( , PropertyName : PropertyValue )* }
}
TargetId ::= <string> // the id of the object to create
TypeName ::= <string> // the fully qualified name of the type
PropertyName ::= <string> // the name of a property to set
PropertyValue ::= <any JSON value> // the initial value for this property

Set

A set operation advises the peer to set a number of properties of the given target object.

SetOperation ::= {
  "action" : "set",
  "target" : TargetId,
  "properties" : { PropertyName : PropertyValue ( , PropertyName : PropertyValue )* }
}
TargetId ::= <string> // the id of the object to set properties to
PropertyName ::= <string> // the name of a property to set
PropertyValue ::= <any JSON value> // the new value for this property

Call

A call operation advises the peer to call a method on the target object.

CallOperation ::= { 
  "action" : "call",
  "target" : TargetId,
  "method" : MethodName,
  "properties" : { ParameterName : ParameterValue ( , ParameterName : ParameterValue )* }
}
TargetId ::= <string> // the id of the object to call a method on
MethodName ::= <string> // the name of the method to call
ParameterName ::= <string> // the name of a method parameter
ParameterValue ::= <any JSON value> // the value for the method parameter

Listen

A listen operation advises the peer to listen on certain types of events.

ListenOperation ::= {
  "action" : "listen",
  "target" : TargetId,
  "properties" : { EventName : ListenToEvent ( , EventName : ListenToEvent )* }
}
TargetId ::= <string> // the id of the object to set properties to
EventName ::= <string> // the name of an event
ListenToEvent ::= <boolean> // whether to listen to the given event or not

Destroy

A destroy operation advises the peer to destroy the target object.

DestroyOperation ::= { 
  "action" : "destroy",
  "target" : TargetId
}
TargetId ::= <string> // the id of the object to destroy

Data Type Reference

In addition to the datatypes recognized by JSON itself, the RAP protocol also uses these composed types:

Bounds

[ int left, int top, int witdh, int height ]

Note that left and top may be negative. No value may be null.

Color

[ int red, int green, int blue, int alpha ]

All values are to be between 0 and 255. The alpha value may be ignored by the client unless its 0.

Image

[ String url, int width, int height ] | null

Gradient

[ Color[] colors, int[] stops, boolean verticalFlag ] | null

The number of colors must match the number of stops. Each stop is a value between 0 and 1, and has to be equal or higher then the previous stop.

Object Type Reference

Server and JavaScript-Client API