Difference between revisions of "RAP/Protocol"

Revision as of 17:22, 20 January 2012

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