Eclipse EMF.cloud Model Server

v2 Client API:

public interface ModelServerClientApiV2<A> {

  CompletableFuture<Response<String>> get(String modelUri);

  CompletableFuture<Response<A>> get(String modelUri, String format);

  CompletableFuture<Response<List<Model<String>>>> getAll();

  CompletableFuture<Response<List<Model<A>>>> getAll(String format);

  CompletableFuture<Response<List<String>>> getModelUris();

  CompletableFuture<Response<String>> getModelElementById(String modelUri, String elementid);

  CompletableFuture<Response<A>> getModelElementById(String modelUri, String elementid, String format);

  CompletableFuture<Response<String>> getModelElementByName(String modelUri, String elementname);

  CompletableFuture<Response<A>> getModelElementByName(String modelUri, String elementname, String format);

  CompletableFuture<Response<Boolean>> delete(String modelUri);

  CompletableFuture<Response<Boolean>> close(String modelUri);

  CompletableFuture<Response<String>> create(String modelUri, String createdModelAsJsonText);

  CompletableFuture<Response<A>> create(String modelUri, A createdModel, String format);

  CompletableFuture<Response<String>> update(String modelUri, String updatedModelAsJsonText);

  CompletableFuture<Response<A>> update(String modelUri, A updatedModel, String format);

  CompletableFuture<Response<Boolean>> save(String modelUri);

  CompletableFuture<Response<Boolean>> saveAll();

  CompletableFuture<Response<String>> validate(String modelUri);

  CompletableFuture<Response<String>> getValidationConstraints(String modelUri);

  CompletableFuture<Response<String>> getTypeSchema(String modelUri);

  CompletableFuture<Response<String>> getUiSchema(String schemaName);

  CompletableFuture<Response<Boolean>> configure(ServerConfiguration configuration);

  CompletableFuture<Response<Boolean>> ping();

  CompletableFuture<Response<String>> edit(String modelUri, CCommand command, String format);

  CompletableFuture<Response<String>> edit(String modelUri, ArrayNode jsonPatch, String format);

  void subscribe(String modelUri, SubscriptionListener subscriptionListener);

  void subscribe(String modelUri, SubscriptionListener subscriptionListener, String format);

  void subscribe(String modelUri, SubscriptionListener subscriptionListener, long timeout);

  void subscribe(String modelUri, SubscriptionListener subscriptionListener, String format, long timeout);

  void subscribeWithValidation(String modelUri, SubscriptionListener subscriptionListener);

  void subscribeWithValidation(String modelUri, SubscriptionListener subscriptionListener, String format);

  void subscribeWithValidation(String modelUri, SubscriptionListener subscriptionListener, long timeout);

  void subscribeWithValidation(String modelUri, SubscriptionListener subscriptionListener, String format,
    long timeout);

  void subscribe(String modelUri, SubscriptionListener subscriptionListener, SubscriptionOptions options);

  boolean send(String modelUri, String message);

  boolean unsubscribe(String modelUri);

  CompletableFuture<Response<String>> undo(String modelUri);

  CompletableFuture<Response<String>> redo(String modelUri);
}

REST API Example

// You can customize the underlying okhttp instance by passing it in as a 1st parameter
ModelServerClient client = new ModelServerClient("http://localhost:8081/api/v2/");

// perform simple GET
client.get("SuperBrewer3000.json")
      .thenAccept(response -> System.out.println("GET: " + response.body()));

// perform same GET, but obtain the result as an EObject
client.get("SuperBrewer3000.json", "json-v2")
      .thenAccept(response -> System.out.println("GET: " + response.body()));

// perform GET ALL
client.getAll()
      .thenAccept(response -> System.out.println("GET ALL: " + response.body()));

// replace the model content via a PATCH update
EObject coffeeMachine = ...;
client.update("SuperBrewer3000.json", coffeeMachine, "json-v2")
      .thenAccept(response -> System.out.println(response.body()));

Executing Commands

To perform changes on the model, clients may issue PATCH requests to update the model state incrementally in the server. These updates are broadcast to subscribers as incremental updates (see below).

Consider the following JSON payload for a PATCH request to add change the name of the workflow in the example Super Brewer 3000 model and to add another task to it:

v2 Patch, using an EMF Command:

{
    "type": "modelserver.emfcommand",
    "data": {
        "eClass": "http://www.eclipse.org/emfcloud/modelserver/command#//CompoundCommand",
        "type": "compound",
        "commands": [
            {
                "eClass": "http://www.eclipse.org/emfcloud/modelserver/command#//Command",
                "type": "set",
                "owner": {
                    "eClass": "http://www.eclipsesource.com/modelserver/example/coffeemodel#//AutomaticTask",
                    "$ref": "SuperBrewer3000.json#//@workflows.0"
                },
                "feature": "name",
                "dataValues": [
                    "Auto Brew"
                ]
            },
            {
                "eClass": "http://www.eclipse.org/emfcloud/modelserver/command#//Command",
                "type": "add",
                "owner": {
                    "eClass": "http://www.eclipsesource.com/modelserver/example/coffeemodel#//AutomaticTask",
                    "$ref": "SuperBrewer3000.json#//@workflows.0"
                },
                "feature": "nodes",
                "objectValues": [
                    {
                        "eClass": "http://www.eclipsesource.com/modelserver/example/coffeemodel#//AutomaticTask",
                        "$ref": "//@commands.1/@objectsToAdd.0"
                    }
                ],
                "objectsToAdd": [
                    {
                        "eClass": "http://www.eclipsesource.com/modelserver/example/coffeemodel#//AutomaticTask",
                        "name": "Brew"
                    }
                ],
                "indices": [
                    1
                ]
            }
        ]
    }
}

This is a JSON representation of an EMF CompoundCommand containing two commands, a SetCommand that changes the name of the first workflow in the model, and an AddCommand that adds a new AutomaticTask to that workflow. The SetCommand does not require any index because the name feature is single-valued. The AddCommand here explicitly adds an position 1, but this can also be omitted to simply append to the end of the list. Notice how each command indicates the owner object in the model to which the change is applied using a cross-document reference. And in the case of the AddCommand, the object to be added does not yet exist in the model, so it must be included in the payload of the command, itself. Thus it is contained in the objectsToAdd property and indicate via an in-document reference in the objectValues property. Other commands, such as the RemoveCommand, would indicate objects in the objectValues property that already exist in the model (to be removed in that case), and so those would be cross-document references and the objectsToAdd is unused.

To execute this command, issue a PATCH request to the models endpoint like:

PATCH http://localhost:8081/api/v2/models?modeluri=SuperBrewer3000.json
Content-type: application/json
{ "data" : <payload> }

The model server project already provides a default set of commands but it is also possible to plug in your custom metamodel-specific commands by providing CommandContributions specified with your model server module.

All commands are executed on a transactional command stack within an EMF transactional editing domain. The use of an EMF transactional editing domain on the server side provides a more reliable way of executing commands through transactions and therefore making a clear separation between the end user's operations. In addition, it enables us to make use of RecordingCommands which record the changes made to objects via the custom metamodel's API and therefore provide automatic undo/redo support for custom commands.

v2 Patch, using a Json Patch with EMF-like paths:

  {
    "type": "modelserver.patch",
    "data": [
      {
        "op": "replace",
        "path": "SuperBrewer3000.json#//@workflows.0/name",
        "value": "Auto Brew"
      },
      {
        "op": "add",
        "path": "SuperBrewer3000.json#//@workflows.0/nodes/-",
        "value": {
          "$type": "http://www.eclipsesource.com/modelserver/example/coffeemodel#//AutomaticTask",
          "name": "Brew"
        }
      }
    ]
  }

This Json Patch is equivalent to the EMF Command above, and can be used in the same way. This is the recommended format to use for Web clients, as manipulating this Json Patch format is a lot easier than EMF Commands.

In this case, we still use an EMF-like path, which contains the URI of the model to edit, the ID of the Object to edit, and the feature to edit:

modeluri#objectID/featureName or modeluri#objectID/featureName/index (Where the special value - can be used to represent the last element of the list).

v2 Patch, using a Json Patch with standard Json Pointer paths:

{
  "type": "modelserver.patch",
  "data": [
    {
      "op": "replace",
      "path": "/workflows/0/name",
      "value": "Auto Brew"
    },
    {
      "op": "add",
      "path": "/workflows/0/nodes/-",
      "value": {
        "$type": "http://www.eclipsesource.com/modelserver/example/coffeemodel#//AutomaticTask",
        "name": "Brew"
      }
    }
  ]
}

In this last case, we use standard Json Pointer paths, instead of EMF-like paths. The model URI is no longer part of the path, as this concept doesn't exist with Json Patch/Json Pointers. Instead, the ?modeluri= query parameter will be used. Currently, this format can't be used to edit multiple resources with a single operation.

WebSocket Subscriptions Example

If you want to be notified about any changes happening on a certain model, you can subscribe with a SubscriptionListener and define a format for the responses, which is an EObjectSubscriptionListener for json-v2 format in this example.

Please also see a basic running example in org.eclipse.emfcloud.modelserver.example.client.

ModelServerClient client = new ModelServerClient("http://localhost:8081/api/v2/");
String subscriptionId = "SuperBrewer3000.json";

client.subscribe(subscriptionId, new EObjectSubscriptionListener(new JsonCodecV2()) {
  @Override
  public void onOpen(final Response<String> response) {
    System.out.println("Connected: " + response.getMessage());
  }

  @Override
  public void onSuccess(final Optional<String> message) {
    System.out.println("Success: " + message.get());
  }

  @Override
  public void onIncrementalUpdate(final JsonPatch patch) {
     System.out.println("Patch update from model server received: " + patch.toString());
  }

  @Override
  public void onDirtyChange(final boolean isDirty) {
    System.out.println("Dirty State: " + isDirty);
  }

  @Override
  public void onUnknown(final ModelServerNotification notification) {
    System.out.println("Unknown notification of type " + notification.getType() + ": " + notification.getData());
  }

  @Override
  public void onFullUpdate(final EObject fullUpdate) {
    System.out.println("Full <EObject> update from model server received: " + fullUpdate.toString());
  }

  @Override
  public void onError(final Optional<String> message) {
    System.out.println("Error from model server received: " + message.get());
  }

  @Override
  public void onFailure(final Throwable t, final Response<String> response) {
    System.out.println("Failure: " + response.getMessage());
    t.printStackTrace();
  }

  @Override
  public void onFailure(final Throwable t) {
    System.out.println("Failure: ");
    t.printStackTrace();
  }

  @Override
  public void onClosing(final int code, final String reason) {
    System.out.println("Closing connection to model server, reason: " + reason);
  }

  @Override
  public void onClosed(final int code, final String reason) {
    System.out.println("Closed connection to model server, reason: " + reason);
  }
});

// ...

client.unsubscribe(subscriptionId);

The kind of message received depends on the operation. For an update call (PATCH request on the model), the message is the new content of the model (onFullUpdate). For an edit call (incremental update applied by a PATCH request with an edit command or JSON patch — see above), the message is the result of the command that was executed (onIncrementalUpdate). In the case of an API v2 client with json-v2 message format, the incremental update takes the form of a JSON patch describing the changes performed on the server. The patch can be applied to a local copy of the model to synchronize with the server and is modeled in EMF as a JsonPatch object.

Subscriptions support a number of options to tweak their behaviour. For example, to customize the idle timeout interval and receive incremental updates in which the Operations in the JSON Patches use EObject fragment URIs in the path property instead of standard JSON Pointers:

ModelServerClient client = new ModelServerClient("http://localhost:8081/api/v2/");
String subscriptionId = "SuperBrewer3000.json";
SubscriptionListener listener = /* as above */ ;

client.subscribe(subscriptionId, listener, SubscriptionOptions.builder()
    .withTimeout(60, TimeUnit.SECONDS)
    .withPathScheme(ModelServerPathParametersV2.PATHS_URI_FRAGMENTS)
    .build());

Contributing

All involved code must adhere to the provided codestyle and checkstyle settings.

Eclipse IDE Setup

Requirements

• Please make sure your Eclipse workspace uses a JRE of Java 11 or higher.
• Install the Eclipse Checkstyle Plug-in via its update site https://checkstyle.org/eclipse-cs/#!/install.

Configure Checkstyle