Skip to main content
Jump to: navigation, search


Revision as of 10:07, 21 January 2012 by (Talk | contribs) (Data Type Reference)

NOTE: The protocol is still under development. Some details described in this document may still change until the Eclipse Juno release.


The term RAP Protocol describes the JSON-based message format used in the HTTP communication between a RAP client and a RAP server. This protocol will be introduced in RAP 1.5 to replace the plain JavaScript responses that have been used in previous releases. After 1.5, the protocol will be extended to be used also for the HTTP requests of a RAP client.


The idea of the new protocol is to fully decouple RAP server and RAP client with the intention of making the client exchangeable. At the point of development, the most interesting use cases have been RAP clients for mobile devices (Android and iOS), written in the client's native language. As a consequence, all logic that is specific to the default RAP client has been moved from the server to the client. This includes logic that relies on the existence of JavaScript or the web browser's DOM.

A further objective for the design of the protocol was to avoid anything that would limit the protocol to RAP or to the synchronization of widget trees. In fact, the protocol is supposed to be usable for the synchronization of objects in general.


Apart from the possiblity to connect alternative clients, the new protocol has a number of practical advantages over the previous one:

  • It produces human readable messages and eases debugging of the communication. As an example, browser extension like FireBug allow browsing the JSON messages comfortably.
  • It allows the client to create more informative error messages. With the old protocol, in case of an error, it was not clear which statement in a large message caused the error. With the new protocol, the exact operation can be identified and a strack trace can be made available.
  • It allows to add client-independent client-side scripting.

Protocol Format

The message format is a valid subset of the JavaScript Object Notation (JSON). As a consequence, messages can be parsed with every JSON parser. The mime type of a response from a RAP server is application/json (RFC 4627).

Since JSON's grammar is already specified, we use a sloppy format to describe the protocol in the following in order to improve readability. In particular, we use the asterisk symbol * to indicate any number of items in an array or an object, skipping the comma that separates the items. For example, the following expression

<Foo> ::= { <Key> , <Value> * }

stands for either the empty object {}, an object with a single key-value pair { <Key> : <Value> }, or one with multiple, comma separated key value pairs { <Key> : <Value> , <Key> : <Value> , ... }.

We also skip the definition of the terminal symbols <string>, <number>, <boolean>, <any>, which refer to the types defined in JSON.


There is exactly one message in a response. A message contains a set of headers, followed by a list of operations. Even if a message does not contain any headers or operations, both parts have to be present.

<Message> ::= {
  "meta" : <MetaHeaders> ,
  "operations" : <Operations>

Meta Headers

This part contains headers that describe the message itself.

<MetaHeaders> ::= { <HeaderName> : <HeaderValue> * }
<HeaderName> ::= <string> // name of the header
<HeaderValue> ::= <any> // value of the header


meta : {
  "requestCounter" : 23


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.

Operations must be processed in the order of their appearance in the message.

  <Operations> ::= [ <Operation> * ]
  <Operation> ::= <CreateOperation> | <SetOperation> | <CallOperation> | <ListenOperation> | <DestroyOperation>


operations : [
  { "action" : "destroy", "target" : "w23" },
  { "action" : "create", "target" : "w42", "type" : "rwt.widgets.Button", "properties" : { "visible" : false } }


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

<CreateOperation> ::= {
  "action" : "create",
  "target" : <TargetId>,
  "type" : <TypeName>,
  "properties" : { <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> // the initial value for this property


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> * }
<TargetId> ::= <string> // the id of the object to set properties to
<PropertyName> ::= <string> // the name of a property to set
<PropertyValue> ::= <any> // the new value for this property


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

<CallOperation> ::= { 
  "action" : "call",
  "target" : <TargetId>,
  "method" : <MethodName>,
  "properties" : { <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> // the value for the method parameter


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

<ListenOperation> ::= {
  "action" : "listen",
  "target" : <TargetId>,
  "properties" : { <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


A destroy operation advises the peer to destroy the target object and to discard the id associated with it.

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

Data Type Reference

For common data types in RAP, the following composed types are used:


[ <left>, <top>, <witdh>, <height> ]

All values are integer numbers, only left and top may be negative.


[ <red>, <green>, <blue>, <alpha> ]

All values are integer numbers between 0 and 255. Clients that don't support alpha values must hide the element if alpha is 0.


[ <url>, <width>, <height> ] | null

The url is a string, width and height integer numbers.


[ [ <Color> ], [ <number> ], <boolean> ] | 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


Back to the top