Web Socket Bus is used:
to establish the connection between the web browser and server-side web memory slot, thus, creating a new "live" web memory instance;
to synchronize web memory changes; only modificating RAAPI actions (actions that change the the model) are being synced; actions can be synced one-by-one or in bulk;
to synchronize web calls that have to be executed on the other side;
to receive private calls from the server that have to be executed on the browser side.
On the browser side Web Socket Bus is implemented in webappos.js.
The web socket connection is as listed above. The trailing slash is essential!
The browser (usually, webappos.js script running there) initiates the web socket connection to activate a web memory slot (or to join an existing web memory slot, e.g., activated by another user).
To activate the web memory slot the browser sends a string message of one of the 4 types listed below. There must be a single space between every two adjacent parts of the message. In all cases the [login] argument specifies the current user. The [token] argument is either the connection token received during the login process, or a collaboration token received from another user. The [app_url_name] specifies the application to use to open the given project.
As a response, then the server synchronizes the current memory state (usually, in bulk) until action 0xFF (sync max reference). After that, the initial action of the underlying web application is called (see initial_action setting in <app.properties>).
On certain circumstances, the server can send some action from the list of Connection management actions (see below).
Open an existing project [project_id] with the given app. If some other user has already opened the project, the following conditions have to be met:
app_url_name must match the app that was used to open this project;
the collaborative property of that app must be true (usually set in webapp.properties).
A special value "*" for [app_url_name] can be used to indicate that the client wishes to connect to the project that has already been opened by any app. This is useful for debugging purposes.
Try to re-open an existing project, for which the connection has been lost. The [ack#] argument specifies the first action number that is still cached in the browser. Thus, the server can then request to re-sync missing actions. If cached actions are not sufficient for re-sync, the server replies with 0xFA, and the browser must start the connection from scratch by using OPEN. Currently not implemented. If ack#!=0, sends 0xFA. Otherwise, just opens the project.
Creates a new project from the given template. The [template_id] must have one of the following prefixes: "user_template:", "app_template:", "published_template:".
If [template_id] contains spaces, they must be escaped by the backslash as "\ " (the backslash itself cannot be a part of template_id, use ordinary slashes as path separators). The [desired_project_id] can be slightly modified by appending some integer, if it is already used by existing projects (e.g., created from templates earlier).
Bootstraps a new project. Notice that some web apps specify the initial template, thus, new projects are not actually boostrapped, but created from that initial template. The project_id can be slightly modified by appending some integer, if it is already used by existing projects. (e.g., bootstrapped earlier).
An action that does not have a string parameter (non-string-action), is synced as one binary web socket message:
the message is in the form: [action-code, non-string-arg1, non-string-arg2, ...]
non-string arguments (longs, integers, and booleans) are synchronized as IEEE doubles
socket.binaryType is "arraybuffer"; the synced array can be accessed by using JavaScript built-in Float64Array (the received binary data may need to be wrapped by Float64Array)
An action that has a string parameter (string-action) is synced as two web socket messages: one binary and one string message.
The binary message is the same as in case of non-string actions.
The string message contains all string arguments (web sockets, Java, and JavaScript take care of Unicode). If the given action takes multiple string parameters, the arguments are concatenated by '/'; thus, the symbol '/' may not appear in strings, it has to be replaced by '#SLASH#' (in addition, '`' has to be replaced by '#GRAVE#', since the grave symbol is used when synchronizing multiple strings at once; the sharp symbol '#' itself has to be replaced by '#SHARP#' at the last turn).
Actions returning booleans are synchronized only when they succeeded, thus, these boolean return values are not synchronized (assume they are always true).
Multiple actions are always synced as two web socket messages: one binary and one string message.
the binary message is an array of IEEE 64-bit doubles encoding all synced actions and their non-string arguments; the first element is always 0xEE (code for bulk synchronization) followed by variable-length groups of elements in the form
[action-code, non-string-arg1, non-string-arg2, ...]
string message is a long string of concatenated string arguments (for actions having string arguments); strings are concatenated by '`' (the grave accent symbol "`" with decimal code 96); if there are multiple string arguments for a given action, the arguments are concatenated by '/'; we use escape sequences '#GRAVE#', '#SLASH#', and '#SHARP#' to denote symbols '`', '/', and '#', respectively
Using "jsoncall" calling conventions:
Using "webmemcall" calling conventions: