How to update properties of a single model element?

[rsoika]

Hi,

still after a lot of trial and error I have no idea how to update an model element and I need some help to get a better understanding of the GLSP Client concept. I have the following scenario:

I have written a custom UIExtension which implements the SelectionListener interface. So I can react on the selection of a model element within my diagram pane.
I am able to see all the properties of the selected element. So I can check which type of element it is and I can see all its custom properties.

Now I have some business method in which I want compute a new value for a specific property of the selected element. (in truth I have implemented a complete Form Editor based on the JSON Forms - see also the discussion here)

But until now I can't figure out how to manipulate my model element. I think I have tried nearly everything, but I have at the end no idea how this can be achieved and I did not found one piece of code where I can find an example:

In my method selectionChanged() I have an readonly instance of the root of my model which looks promising:

selectionChanged(root: Readonly<SModelRoot>, selectedElements: string[]): void {
...
}

I also found this example code in the workflow example to get an instance of the task element from the SModelRoot:

function getTask(ids: string[], element: SModelElement): TaskNode[] {
    return ids.map(id => element.index.getById(id)).filter(isTaskNode);
}

So also here I can see all elements. But as far as I understand these elements are still all read only - why?

I expect that in the universe of the GLSP client there should exist some method to get a writeable instance of a model element by ID? If not, what is the correct way to update a single property, or even a set of properties for one model element. At the beginning I expected that I should send an ActionEvent to the server. But I have no idea how to do this and I am no longer sure if this is necessary. It looks like none of the examples including the coffee editor is sending events from the client to the server actively.

This question sounds to me so idiotic because it should be one of the most easiest things in GLSP.

I hope someone can lead me out of the Valley of the Unsuspecting....

[planger]

You are on the right track! From your UIExtension you'd send an Action to the server, the server manipulates the model element and eventually sends an UpdateModelAction back to the client with the state after the change has been applied.

There is an example for that in the workflow editor, where a UIExtension sends an operation.
On the server, this operation is then processed and changes some property in the model.

The client cannot ever change the model directly, because only the server is supposed to know how to manipulate the model. Essentially the client only knows the GModel, which is the description of what the client should render. It doesn't know, however, from which underlying source model this GModel has been created from. Thus, the client sends operations (ie actions that manipulate the model) to the server, which then based on this operation manipulates the source model, regenerates the GModel and sends the updated GModel back to the client.

[rsoika]

Thanks for your answer. I already saw the ApplyTaskEditOperation class but was not able to understand its behaviour. Now I think I get closer to the point and can sort things out by myself. My main fault was that I did not have implemented the Operations on the server side.

[tortmayr]

On a side note:
As I can see you already raised a similar question in another discussion thread. Typically we try to respond to open question as fast as possible, however community support is something we have to squeeze in alongside our day-to-day business. So depending on our current workload it might take some time until you receive a response. For the future I would kindly ask you to give us a grace period of 2 business days. If you haven't received a response after that feel free to ping us again. Thanks!

[rsoika]

Sorry for my impatience. I will keep this in mind in the future. And also I will write some short tutorial for myself and I will post it into the discussion thread later.

The problem with the example is that things like LabeledAction, ApplyLabelEditOperation or the ApplyTaskEditOperationHandler have no comments at all in the code. This makes it so difficulty for me to understand the idea behind this classes. And I block your time with my questions. The problem is that I am not even able to create a pull request with better comments, because I simply lack the knowledge and you would have to change everything anyway.

So once again - sorry!

[tortmayr]

No worries, we are happy to answer your questions. I just wanted to clarify that it occasionally might take a little bit longer until you receive a response 😉 .

[rsoika]

I now implemented the missing Server Operations (or at least I think so) and I can successful send my ApplyUpdate Action from the client to the server where it is processed. But I still do not understand what you mean with

and eventually sends an UpdateModelAction back to the client

My client seems not to receive this update. The model is not updated. So it looks like I am still missing this UpdateModelAction ?

I have written a Quick Guide describing the procedure. Can you help me to add the missing part. I am not sure if the part with my EditEventOperationHandler makes sense and if this is the UpdateModelAction?

How to update a Model Element

If you have changed values for element properties on the client side you need to send an action event to the model server to apply the new values to the model. For this you need to implement a corresponding GLSP Server Action so that your client can send an update. On the Server Side you need to generate than another Action to update you model state.

The Server Side

In the following example I assume that we have a model element named 'Event' with the properties 'name' and 'documentation'.
First let's define the corresponding classes on the server side:

The Apply Operation

First of all you need to define an Apply Operation on your Server which accepts the ID of the element and an expression describing what changed. This action is later send from your client to the server:

public class ApplyEventUpdateOperation extends Operation {

    private String id;
    private String expression;

    public ApplyEventUpdateOperation() {
        super("applyEventUpdate");
    }

    public ApplyEventUpdateOperation(final String nodeId, final String expression) {
        this();
        this.id = nodeId;
        this.expression = expression;
    }

    public String getId() {
        return id;
    }

    public void setId(final String nodeId) {
        this.id = nodeId;
    }

    public String getExpression() {
        return expression;
    }

    public void setExpression(final String expression) {
        this.expression = expression;
    }
}

The expression can be any string describing the change. For example this can be simple the name of the property and the new value:

name:My New Task Name

Or you can also describe your changes into some kind of XML.

The Apply Operation Handler

Next you need implement a OperationHandler for your Apply Action. This class handles the incomming action:

public class ApplyEventUpdateOperation extends AbstractOperationHandler<ApplyEventUpdateOperation> {

    @Inject
    protected ActionDispatcher actionDispatcher;

    @Inject
    protected GModelState modelState;

    @Override
    protected void executeOperation(final ApplyEventUpdateOperation operation) {
        String text = operation.getExpression();
        if (text.startsWith("name:")) {
	        // extract the property and the value
	        ....
	        // dispatch a new EventEditOperation
	        ....
	        actionDispatcher.dispatch(new EventEditOperation(operation.getId(), "name", value));
        }
    }

}

The OperationHandler extracts the property name and the value from the expression. If you send more complex data like XML you have to parse the data here.

The Operation Handler now need to create a new Event to update the concrete model object. For that reason we define a EditEventOperation.

The Edit Operation

public class EditEventOperation extends Operation {

    private String id;
    private String feature;
    private String value;

    public EditEventOperation() {
        super("editEvent");
    }

    public EditEventOperation(final String id, final String feature, final String value) {
        this();
        System.out.println("...create new EventEditOperation - ID=" + id + " feature=" + feature + " value=" + value);
        this.id = id;
        this.feature = feature;
        this.value = value;
    }
	
	// getter and setters ....
}

Also we need an Operation Handler for this event.

The Edit Operation Handler

The Edit Operation Handler class fetches the corresponding Element from the Server model and updates the corresponding properties (features).

public class EditEventOperationHandler extends AbstractOperationHandler<EditEventOperation> {
    @Inject
    protected GModelState modelState;

    @Override
    protected void executeOperation(final EditEventOperation operation) {
        Optional<EventNode> element = modelState.getIndex().findElementByClass(operation.getId(), EventNode.class);
        if (element.isEmpty()) {
            throw new RuntimeException("Cannot find element with id '" + operation.getId() + "'");
        }
        switch (operation.getFeature()) {
        case "name":
            logger.info("...feature = name - value = " + operation.getValue());
            element.get().setName(operation.getValue());
            break;
        case "documentation":
            element.get().setDocumentation(operation.getValue());
            break;
        default:
            throw new GLSPServerException("Cannot edit element at feature '" + operation.getFeature() + "'");
        }
    }
}

Binding the Operation Handlers

Finally you need to bind the handler to your DiagramModule in the method configureOperationHandlers

public class BPMNDiagramModule extends GModelJsonDiagramModule {
    ....
    @Override
    protected void configureOperationHandlers(final MultiBinding<OperationHandler> binding) {
        super.configureOperationHandlers(binding);

		.....

        // bind Apply Operation Hander (send from the client)
        binding.add(ApplyEventUpdateOperationHandler.class);
        // bind Edit Operation Handler (send by the server)
        binding.add(EditEventOperationHandler.class);
    }
}

The Client Side

Now you can fire a corresponding applyEventUpdate Action each time a property of you Event Element has changed:

@injectable()
export class MyUIExtension extends AbstractUIExtension implements EditModeListener, SelectionListener {

	@inject(TYPES.IActionDispatcher)
	protected readonly actionDispatcher: ActionDispatcher;

	....
	// Update the property 'name' for the selected element ID
	const action = new ApplyEventUpdateOperation(this.selectedElementId, 'name:' + _newValue);
	this.actionDispatcher.dispatch(action);

}

export class ApplyEventUpdateOperation implements Action {
	static readonly KIND = 'applyEventUpdate';
	readonly kind = ApplyEventUpdateOperation.KIND;
	constructor(readonly id: string, readonly expression: string) { }
}

[planger]

But I still do not understand what you mean with

and eventually sends an UpdateModelAction back to the client

My client seems not to receive this update. The model is not updated. So it looks like I am still missing this UpdateModelAction ?

Exactly, the server should send after each change of the model an UpdateModelAction. As typically only an Operation changes the model, this is done after the operation has been executed by the OperationActionHandler.

   protected List<Action> executeHandler(final Operation operation, final OperationHandler handler) {
      ...
      modelState.execute(command);
      return modelSubmissionHandler.submitModel(SetDirtyStateAction.Reason.OPERATION); // <- this sends the update model action
   }

I'm not sure why this isn't the case for you? I'd double-check the implementation of the OperationActionHandler that you have bound, whether it invokes the model submission handler and what the model submission handler does with it.

Depending on the scenario, you typically need an adjusted implementation of the OperationActionHandler.
E.g. if your operation only manipulates an external model, you also need to invoke the model factory first to generate a new version of the GModel from your external source model before sending the update of the GModel via the model submission handler.
If your operation directly modifies the GModel, as it is the case for the workflow example, this regeneration of the GModel is not required.
In yet another scenario, e.g. with the model server, the GModel listens to updates of the model server anyway and sends an update whenever it changes. So there is no explicit update after the operation needed at all.

PS: It would be nice at some point, if you could enhance the GLSP documentation directly where you feel necessary following the format and form that it currently has. Feel free to open a PR against the docs. Thanks!

[rsoika]

ok, I now recognized that it is working! I made a fault in my GModel with an attribute 'name' and a child element 'text' holding the same value. But I only updated the 'name' and not the 'text'. I always checked the update on the wrong place. I think I need to clarify my GModel which looks very strange.

As you can see below, my Element has a 'name' which is the relevant attribute. But the Element has child entries to display a text with the name below the icon

So this is a very bad construction of my GModel I think...

    {
      "category": [
        "start"
      ],
      "name": "StartEvent My New Name",
      "documentation": "...some new documentation",
      "id": "664bb14d-53cf-4e55-8716-eb37ae852676",
      "cssClasses": [
        "event",
        "start"
      ],
      "children": [
        {
          "id": "664bb14d-53cf-4e55-8716-eb37ae852676_classname",
          "type": "label:heading",
          "position": {
            "x": 0.0,
            "y": 40.0
          },
          "size": {
            "width": 80.15625,
            "height": 16.0
          },
          "text": "StartEvent3",           /* <====== This is the attribute I did not update */
          "alignment": {
            "x": 40.078125,
            "y": 13.0
          }
        },

So everything is fine. Thanks for clarification.

[rsoika]

I finally have one more conceptional question:
In the workflow example, which I took as the base for my own implementation and also for the tutorial, there are two Actions defined. The ApplyTaskEditOperation and the EditTaskOperation. The ApplyTaskEditOperationHandler simply transforms the data and sends a new EditTaskOperation. Than finally the EditTaskOperationHandler updates the GModel.
I wonder why this is necessary? Would it be not easier if the ApplyTaskEditOperationHandler updates the GModelState directly without sending another action?