Client Server Protocol

This page describes the protocol between a sprotty client and its model source. A model source is configured by binding an implementation to TYPES.ModelSource, e.g. LocalModelSource for a client-only source or WebSocketDiagramServer for a server connected via web socket. Both approaches use the same protocol, so we will assume a remote server for the rest of this page for simplicity.

Layout Computation

The approach for computing model layouts has a strong influence on the client-server protocol, therefore we address this topic before going into more details on the protocol itself.

Both the client and the server may have their share in computing the layout. In the client this is configured with the ViewerOptions:

overrideViewerOptions(container, {
    needsClientLayout: true,
    needsServerLayout: false
});

In the server these options are set on a DefaultDiagramServer instance:

diagramServer.setNeedsClientLayout(true);
diagramServer.setNeedsServerLayout(false);

Usually the client is responsible for the micro layout, that is the positioning and size computation for labels and other elements that add visual information to composite elements such as nodes. The server, in turn, is responsible for the macro layout, that is the arrangement of the main model elements (e.g. nodes and edges) with the goal of optimizing visual clarity and readability. Macro layout computation depends on the results of micro layout computation, hence the client computes its layout before the server does. With the default settings, client layout is switched on and server layout is switched off.

Client layouts are selected with the layout property of model elements that support this, such as SNode and SCompartment. hbox, vbox, and stack are built-in layout types that can be used here.

On the server, the layout is configured with an implementation of ILayoutEngine. Either bind it through dependency injection or set it directly on a DefaultDiagramServer instance. For graph-like models the ElkLayoutEngine can be used, which uses the Eclipse Layout Kernel (ELK).

Set and Update the Model

The primary purpose of the diagram server is to provide models. The protocol for setting or updating the model differs depending on how the layout is computed.

No Layout Computation

In this scenario, the server needs to provide a model with complete layout information, so no further processing is required.

• Client requests a model
  1. Client: RequestModelAction
  2. Server: SetModelAction