Jump to: navigation, search

RAP/Protocol

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

Introduction

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.

Rationale

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.

Advantages

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 protocol is based on JSON (http://www.json.org/). The mime type of a response from a RAP server is application/json (http://www.ietf.org/rfc/rfc4627.txt).

Message

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

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

Meta

The meta object contains headers that describe the message.

Meta ::= {
  "requestCounter" : RequestCounter
}
RequestCounter ::= <number> // a positive integer that represents the sequential number of this message

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