@eclipse-glsp/server 1.1.0-next.f0fc2cf.63 → 2.0.0

package/src/common/features/model/model-submission-handler.ts

@@ -13,13 +13,14 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-import { GModelRootSchema } from '@eclipse-glsp/graph';
 import {
     Action,
     DirtyStateChangeReason,
+    GModelRootSchema,
     MarkersReason,
     MaybePromise,
     RequestBoundsAction,
+    RequestModelAction,
     SetDirtyStateAction,
     SetMarkersAction,
     SetModelAction,
@@ -35,6 +36,15 @@ import { GModelFactory } from './gmodel-factory';
 import { GModelSerializer } from './gmodel-serializer';
 import { ModelState } from './model-state';
 
+/**
+ * Helper class that provides utility methods to handle model updates i.e.
+ * submit a new model to the client. In addition, to the core model update action this class
+ * also takes care of related behavior like dirty state handling, validation and client/server side layouting.
+ * Note that the submissions handler is only responsible for deriving the set of actions that comprise a model update
+ * but does not actually dispatch them. The returned actions should be either manually dispatched
+ * to the `ActionDispatcher`, or simply returned as the result of an
+ * `ActionHandler.execute` method.
+ */
 @injectable()
 export class ModelSubmissionHandler {
     @inject(DiagramConfiguration)
@@ -60,8 +70,34 @@ export class ModelSubmissionHandler {
     @optional()
     protected validator?: ModelValidator;
 
+    protected requestModelAction?: RequestModelAction;
+
+    /**
+     * Returns a list of actions to submit the initial revision of the client-side model, based on the injected
+     * {@link GModelState}. Typically this method is invoked by the {@link RequestModelActionHandler} when the diagram
+     * is (re)loaded.
+     * <p>
+     * These actions are not processed by this {@link ModelSubmissionHandler}, but should be either manually dispatched
+     * to the {@link ActionDispatcher}, or simply returned as the result of an
+     * {@link ActionHandler#execute(Action)} method.
+     * </p>
+     *
+     * @param requestAction The {@link RequestModelAction} that triggere the initial model update
+     * @return A list of actions to be processed in order to submit the intial model.
+     *
+     */
+    submitInitialModel(requestAction: RequestModelAction): MaybePromise<Action[]> {
+        /*
+         * In the default update action flow a `RequestModelAction` does not directly trigger a `SetModelAction` response
+         * (RequestModelAction (C) -> RequestBoundsAction (S) -> ComputedBoundsAction (C) -> SetModelACtion (S)
+         * Therefore we temporarily store the action later retrival
+         */
+        this.requestModelAction = requestAction;
+        return this.submitModel();
+    }
+
     /**
-     * Returns a list of actions to update the client-side model, based on the specified <code>modelState</code>.
+     * Returns a list of actions to update the client-side model, based on the injected {@link ModelState}
      *
      * These actions are not processed by this {@link ModelSubmissionHandler}, but should be either manually dispatched
      * to the `ActionDispatcher`, or simply returned as the result of an `ActionHandler.execute()` method.
@@ -71,13 +107,15 @@ export class ModelSubmissionHandler {
      */
     submitModel(reason?: DirtyStateChangeReason): MaybePromise<Action[]> {
         this.modelFactory.createModel();
-        this.modelState.root.revision = (this.modelState.root.revision ?? 0) + 1;
-        const root = this.serializeGModel();
+
+        const revision = this.requestModelAction ? 0 : this.modelState.root.revision! + 1;
+        this.modelState.root.revision = revision;
 
         if (this.diagramConfiguration.needsClientLayout) {
+            const root = this.serializeGModel();
             return [RequestBoundsAction.create(root), SetDirtyStateAction.create(this.commandStack.isDirty, { reason })];
         }
-        return [SetModelAction.create(root)];
+        return this.submitModelDirectly(reason);
     }
 
     /**
@@ -102,8 +140,8 @@ export class ModelSubmissionHandler {
         }
         const result: Action[] = [];
         result.push(
-            root.revision === 0
-                ? SetModelAction.create(root)
+            this.requestModelAction
+                ? this.createSetModeAction(root)
                 : UpdateModelAction.create(root, { animate: this.diagramConfiguration.animatedUpdate })
         );
         if (!this.diagramConfiguration.needsClientLayout) {
@@ -116,6 +154,13 @@ export class ModelSubmissionHandler {
         return result;
     }
 
+    protected createSetModeAction(newRoot: GModelRootSchema): SetModelAction {
+        const responseId = this.requestModelAction?.requestId ?? '';
+        const response = SetModelAction.create(newRoot, { responseId });
+        this.requestModelAction = undefined;
+        return response;
+    }
+
     protected serializeGModel(): GModelRootSchema {
         return this.serializer.createSchema(this.modelState.root);
     }

package/src/common/features/model/request-model-action-handler.ts

@@ -13,7 +13,7 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-import { Action, RequestModelAction, ServerStatusAction } from '@eclipse-glsp/protocol';
+import { Action, RequestModelAction, StatusAction } from '@eclipse-glsp/protocol';
 import { inject, injectable } from 'inversify';
 import { ActionDispatcher } from '../../actions/action-dispatcher';
 import { ActionHandler } from '../../actions/action-handler';
@@ -61,7 +61,7 @@ export class RequestModelActionHandler implements ActionHandler {
         }
         this.reportModelLoadingFinished(progress);
 
-        return this.submissionHandler.submitModel();
+        return this.submissionHandler.submitInitialModel(action);
     }
 
     protected async handleReconnect(action: RequestModelAction): Promise<void> {
@@ -76,12 +76,12 @@ export class RequestModelActionHandler implements ActionHandler {
     }
 
     protected reportModelLoading(message: string): ProgressMonitor {
-        this.actionDispatcher.dispatch(ServerStatusAction.create(message, { severity: 'INFO' }));
+        this.actionDispatcher.dispatch(StatusAction.create(message, { severity: 'INFO' }));
         return this.progressService.start(message);
     }
 
     protected reportModelLoadingFinished(monitor: ProgressMonitor): void {
-        this.actionDispatcher.dispatch(ServerStatusAction.create('', { severity: 'NONE' }));
+        this.actionDispatcher.dispatch(StatusAction.create('', { severity: 'NONE' }));
         monitor.end();
     }
 }

package/src/common/features/type-hints/edge-creation-checker.ts

@@ -0,0 +1,44 @@
+/********************************************************************************
+ * Copyright (c) 2023 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+
+import { GModelElement } from '@eclipse-glsp/graph';
+
+/**
+ * Optional service used to check the validity of an edge being created. Used in combination with `dynamic`
+ * `EdgeTypeHints`.
+ * A dynamic edge type hint is used for cases where a plain list of allowed source and target element ids is not enough
+ * to determine wether an edge being created is valid. In this cases the client will query the server to determine wether the edge
+ * is valid. The `EdgeCreationChecker` then checks the given edge information and returns wether the edge being created is
+ * valid.
+ */
+export interface EdgeCreationChecker {
+    /**
+     * Checks wether the given source element for an edge being created is valid i.e. if the
+     * given source is and allowed source element for the given edge type.
+     *
+     * @returns `true` if the edge source is valid, `false` otherwise
+     */
+    isValidSource(edgeType: string, sourceElement: GModelElement): boolean;
+
+    /**
+     * Checks wether the given information for an edge being created is valid i.e. if the
+     * given target is an allowed target for the given source and edge type.
+     *
+     * @return `true` if the edge target is valid, `false` otherwise
+     */
+    isValidTarget(edgeType: string, sourceElement: GModelElement, targetElement: GModelElement): boolean;
+}
+export const EdgeCreationChecker = Symbol('EdgeCreationChecker');

package/src/common/features/type-hints/request-check-edge-action-handler.ts

@@ -0,0 +1,62 @@
+/********************************************************************************
+ * Copyright (c) 2023 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { Action, CheckEdgeResultAction, MaybePromise, RequestCheckEdgeAction } from '@eclipse-glsp/protocol';
+import { inject, injectable, optional } from 'inversify';
+import { ActionHandler } from '../../actions/action-handler';
+import { DiagramConfiguration } from '../../diagram/diagram-configuration';
+import { GLSPServerError, getOrThrow } from '../../utils/glsp-server-error';
+import { ModelState } from '../model/model-state';
+import { EdgeCreationChecker } from './edge-creation-checker';
+
+@injectable()
+export class RequestCheckEdgeActionHandler implements ActionHandler {
+    @inject(ModelState)
+    protected modelState: ModelState;
+
+    @inject(DiagramConfiguration)
+    protected diagramConfiguration: DiagramConfiguration;
+
+    @inject(EdgeCreationChecker)
+    @optional()
+    protected edgeCreationChecker?: EdgeCreationChecker;
+
+    readonly actionKinds: string[] = [RequestCheckEdgeAction.KIND];
+
+    execute(action: RequestCheckEdgeAction): MaybePromise<Action[]> {
+        const hasDynamicHint = this.diagramConfiguration.edgeTypeHints.some(hint => hint.elementTypeId === action.edgeType && hint.dynamic);
+        const { edgeType, sourceElementId, targetElementId } = action;
+        const isValid = this.edgeCreationChecker && hasDynamicHint ? this.validate(action) : true;
+
+        return [CheckEdgeResultAction.create({ edgeType, isValid, sourceElementId, targetElementId })];
+    }
+
+    protected validate(action: RequestCheckEdgeAction): boolean {
+        const sourceElement = getOrThrow(
+            this.modelState.index.get(action.sourceElementId),
+            'Invalid `RequestCheckEdgeTargetAction`!. Could not find a source element with id: ' + action.sourceElementId
+        );
+        const targetElement = action.targetElementId ? this.modelState.index.get(action.targetElementId) : undefined;
+
+        if (action.targetElementId && !targetElement) {
+            throw new GLSPServerError(
+                'Invalid `RequestCheckEdgeTargetAction`! Could not find a target element with id: ' + action.targetElementId
+            );
+        }
+        return targetElement
+            ? this.edgeCreationChecker!.isValidTarget(action.edgeType, sourceElement, targetElement)
+            : this.edgeCreationChecker!.isValidSource(action.edgeType, sourceElement);
+    }
+}

package/src/common/{diagram → features/type-hints}/request-type-hints-action-handler.spec.ts

@@ -16,8 +16,8 @@
 import { EdgeTypeHint, RequestTypeHintsAction, SetTypeHintsAction, ShapeTypeHint } from '@eclipse-glsp/protocol';
 import { expect } from 'chai';
 import { Container, ContainerModule } from 'inversify';
-import * as mock from '../test/mock-util';
-import { DiagramConfiguration } from './diagram-configuration';
+import { DiagramConfiguration } from '../../diagram/diagram-configuration';
+import * as mock from '../../test/mock-util';
 import { RequestTypeHintsActionHandler } from './request-type-hints-action-handler';
 
 describe('test RequestTypeHintsActionHandler', () => {

package/src/common/{diagram → features/type-hints}/request-type-hints-action-handler.ts

@@ -15,13 +15,12 @@
  ********************************************************************************/
 import { Action, MaybePromise, RequestTypeHintsAction, SetTypeHintsAction } from '@eclipse-glsp/protocol';
 import { inject, injectable } from 'inversify';
-import { ActionHandler } from '../actions/action-handler';
-import { DiagramConfiguration } from './diagram-configuration';
+import { ActionHandler } from '../../actions/action-handler';
+import { DiagramConfiguration } from '../../diagram/diagram-configuration';
 
 @injectable()
 export class RequestTypeHintsActionHandler implements ActionHandler {
     @inject(DiagramConfiguration) protected diagramConfiguration: DiagramConfiguration;
-    static KINDS = [RequestTypeHintsAction.KIND];
 
     execute(action: RequestTypeHintsAction): MaybePromise<Action[]> {
         return [

package/src/common/gmodel/cut-operation-handler.ts

@@ -28,9 +28,11 @@ export class GModelCutOperationHandler extends GModelOperationHandler {
 
     createCommand(operation: CutOperation): MaybePromise<Command | undefined> {
         const cuttableElementIds = this.getElementToCut(operation);
-        return cuttableElementIds.length > 0 //
-            ? this.commandOf(() => this.actionDispatcher.dispatch(DeleteElementOperation.create(cuttableElementIds)))
-            : undefined;
+        // If we have cuttable elements we dispatch a DeleteElementOperation otherwise do nothing
+        if (cuttableElementIds.length > 0) {
+            this.actionDispatcher.dispatch(DeleteElementOperation.create(cuttableElementIds));
+        }
+        return undefined;
     }
 
     protected getElementToCut(cutOperation: CutOperation): string[] {

package/src/common/gmodel/delete-operation-handler.ts

@@ -72,7 +72,7 @@ export class GModelDeleteOperationHandler extends GModelOperationHandler {
         }
 
         const dependents = new Set<GModelElement>();
-        this.collectDependents(dependents, nodeToDelete);
+        this.collectDependents(dependents, nodeToDelete, false);
 
         dependents.forEach(dependant => {
             const index = this.modelState.root.children.findIndex(element => element === dependant);
@@ -85,22 +85,23 @@ export class GModelDeleteOperationHandler extends GModelOperationHandler {
         return true;
     }
 
-    protected collectDependents(dependents: Set<GModelElement>, nodeToDelete: GModelElement): void {
+    protected collectDependents(dependents: Set<GModelElement>, nodeToDelete: GModelElement, isChild: boolean): void {
         if (dependents.has(nodeToDelete)) {
             return;
         }
 
         if (nodeToDelete.children.length > 0) {
-            nodeToDelete.children.forEach(child => this.collectDependents(dependents, child));
+            nodeToDelete.children.forEach(child => this.collectDependents(dependents, child, true));
         }
 
         if (nodeToDelete instanceof GNode) {
             const index = this.modelState.index;
+
             index.getIncomingEdges(nodeToDelete).forEach(incoming => {
-                this.collectDependents(dependents, incoming);
+                dependents.add(incoming);
             });
             index.getOutgoingEdges(nodeToDelete).forEach(outgoing => {
-                this.collectDependents(dependents, outgoing);
+                dependents.add(outgoing);
             });
         }
 

package/src/common/gmodel/gmodel-create-edge-operation-handler.ts

@@ -19,7 +19,7 @@ import { GNode } from '@eclipse-glsp/graph/lib/gnode';
 import { CreateEdgeOperation, MaybePromise, TriggerEdgeCreationAction } from '@eclipse-glsp/protocol';
 import { injectable } from 'inversify';
 import { Command } from '../command/command';
-import { CreateOperationHandler, CreateOperationKind } from '../operations/create-operation-handler';
+import { CreateEdgeOperationHandler } from '../operations/create-operation-handler';
 import { GModelOperationHandler } from './gmodel-operation-handler';
 
 /**
@@ -28,8 +28,8 @@ import { GModelOperationHandler } from './gmodel-operation-handler';
  * (i.e. all operation handlers directly modify the graphical model).
  */
 @injectable()
-export abstract class GModelCreateEdgeOperationHandler extends GModelOperationHandler implements CreateOperationHandler {
-    override readonly operationType: CreateOperationKind = CreateEdgeOperation.KIND;
+export abstract class GModelCreateEdgeOperationHandler extends GModelOperationHandler implements CreateEdgeOperationHandler {
+    override readonly operationType = CreateEdgeOperation.KIND;
     abstract override label: string;
     abstract elementTypeIds: string[];
 

package/src/common/gmodel/gmodel-create-node-operation-handler.ts

@@ -19,7 +19,7 @@ import { CreateNodeOperation, MaybePromise, Point, SelectAction, TriggerNodeCrea
 import { inject, injectable } from 'inversify';
 import { ActionDispatcher } from '../actions/action-dispatcher';
 import { Command } from '../command/command';
-import { CreateOperationHandler, CreateOperationKind } from '../operations/create-operation-handler';
+import { CreateNodeOperationHandler } from '../operations/create-operation-handler';
 import { getRelativeLocation } from '../utils/layout-util';
 import { GModelOperationHandler } from './gmodel-operation-handler';
 
@@ -29,7 +29,7 @@ import { GModelOperationHandler } from './gmodel-operation-handler';
  * (i.e. all operation handlers directly modify the graphical model).
  */
 @injectable()
-export abstract class GModelCreateNodeOperationHandler extends GModelOperationHandler implements CreateOperationHandler {
+export abstract class GModelCreateNodeOperationHandler extends GModelOperationHandler implements CreateNodeOperationHandler {
     @inject(ActionDispatcher)
     protected actionDispatcher: ActionDispatcher;
 
@@ -37,7 +37,7 @@ export abstract class GModelCreateNodeOperationHandler extends GModelOperationHa
 
     abstract override label: string;
 
-    override operationType: CreateOperationKind = CreateNodeOperation.KIND;
+    override readonly operationType = CreateNodeOperation.KIND;
 
     override createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined> {
         return this.commandOf(() => this.executeCreation(operation));

package/src/common/gmodel/paste-operation-handler.ts

@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { GBoundsAware, GEdge, GModelElement, isGBoundsAware } from '@eclipse-glsp/graph';
-import { EditorContext, MaybePromise, PasteOperation, Point, SModelElementSchema } from '@eclipse-glsp/protocol';
+import { EditorContext, GModelElementSchema, MaybePromise, PasteOperation, Point } from '@eclipse-glsp/protocol';
 import { inject, injectable } from 'inversify';
 import * as uuid from 'uuid';
 import { Command } from '../command/command';
@@ -38,7 +38,7 @@ export class GModelPasteOperationHandler extends GModelOperationHandler {
     }
 
     protected getCopiedElements(jsonString: string): GModelElement[] {
-        const schemas: SModelElementSchema[] = JSON.parse(jsonString);
+        const schemas: GModelElementSchema[] = JSON.parse(jsonString);
         return schemas.map(schema => this.modelSerializer.createElement(schema, this.modelState.root));
     }
 

package/src/common/index.ts

@@ -33,7 +33,6 @@ export * from './di/multi-binding';
 export * from './di/server-module';
 export * from './di/service-identifiers';
 export * from './diagram/diagram-configuration';
-export * from './diagram/request-type-hints-action-handler';
 export * from './features/clipboard/request-clipboard-data-action-handler';
 export * from './features/contextactions/command-palette-action-provider';
 export * from './features/contextactions/context-actions-provider';
@@ -65,12 +64,15 @@ export * from './features/navigation/request-navigation-targets-action-handler';
 export * from './features/navigation/resolve-navigation-targets-action-handler';
 export * from './features/popup/popup-model-factory';
 export * from './features/popup/request-popup-model-action-handler';
+export * from './features/type-hints/edge-creation-checker';
+export * from './features/type-hints/request-type-hints-action-handler';
 export * from './features/validation/model-validator';
 export * from './features/validation/request-markers-handler';
 export * from './gmodel/index';
 export * from './launch/glsp-server-launcher';
 export * from './operations/compound-operation-handler';
 export * from './operations/create-operation-handler';
+export * from './operations/json-operation-handler';
 export * from './operations/operation-action-handler';
 export * from './operations/operation-handler';
 export * from './operations/operation-handler-registry';

package/src/common/operations/compound-operation-handler.ts

@@ -19,6 +19,11 @@ import { Command, CompoundCommand } from '../command/command';
 import { OperationHandler } from './operation-handler';
 import { OperationHandlerRegistry } from './operation-handler-registry';
 
+/**
+ * Generic {@link OperationHandler} from {@link CompoundOperations}.
+ * Retrieves the corresponding execution commands for the list of (sub) operations
+ * and constructs a {@link CompoundCommand} for them.
+ */
 @injectable()
 export class CompoundOperationHandler extends OperationHandler {
     @inject(OperationHandlerRegistry)
@@ -27,7 +32,7 @@ export class CompoundOperationHandler extends OperationHandler {
     operationType = CompoundOperation.KIND;
 
     async createCommand(operation: CompoundOperation): Promise<Command | undefined> {
-        const maybeCommands = operation.operationList.map(op => this.operationHandlerRegistry.getExecutableCommand(op));
+        const maybeCommands = operation.operationList.map(op => this.operationHandlerRegistry.getOperationHandler(op)?.execute(op));
         const commands: Command[] = [];
 
         for await (const command of maybeCommands) {

package/src/common/operations/create-operation-handler.ts

@@ -19,21 +19,37 @@ import {
     hasArrayProp,
     hasFunctionProp,
     hasStringProp,
+    MaybePromise,
     TriggerEdgeCreationAction,
     TriggerNodeCreationAction
 } from '@eclipse-glsp/protocol';
+import { Command } from '../command/command';
 import { OperationHandler } from './operation-handler';
 
 /**
- * A special {@link OperationHandler} that is responsible for the handling of {@link CreateOperation}s. Depending on its
+ * A special {@link OperationHandler} that is responsible for the handling of (a subset of) {@link CreateEdgeOperation}s. Depending on its
  * operation type the triggered actions are {@link TriggerNodeCreationAction} or {@link TriggerEdgeCreationAction}s.
  */
-export interface CreateOperationHandler extends OperationHandler {
+export interface CreateEdgeOperationHandler extends OperationHandler {
+    label: string;
+    elementTypeIds: string[];
+    operationType: typeof CreateEdgeOperation.KIND;
+    getTriggerActions(): TriggerEdgeCreationAction[];
+    createCommand(operation: CreateEdgeOperation): MaybePromise<Command | undefined>;
+}
+
+export interface CreateNodeOperationHandler extends OperationHandler {
     readonly label: string;
     elementTypeIds: string[];
-    operationType: CreateOperationKind;
-    getTriggerActions(): (TriggerEdgeCreationAction | TriggerNodeCreationAction)[];
+    operationType: typeof CreateNodeOperation.KIND;
+    getTriggerActions(): TriggerNodeCreationAction[];
+    createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined>;
 }
+/**
+ * A special {@link OperationHandler} that is responsible for the handling of a node or edge creation operation. Depending on its
+ * operation type the triggered actions are {@link TriggerNodeCreationAction} or {@link TriggerEdgeCreationAction}s.
+ */
+export type CreateOperationHandler = CreateNodeOperationHandler | CreateEdgeOperationHandler;
 
 export type CreateOperationKind = typeof CreateNodeOperation.KIND | typeof CreateEdgeOperation.KIND;
 
@@ -41,9 +57,10 @@ export namespace CreateOperationHandler {
     export function is(object: unknown): object is CreateOperationHandler {
         return (
             object instanceof OperationHandler &&
+            hasStringProp(object, 'operationType') &&
             hasStringProp(object, 'label') &&
             hasArrayProp(object, 'elementTypeIds') &&
-            hasFunctionProp(object, 'getTriggerActions')
+            hasFunctionProp(object, 'getTriggerActions', true)
         );
     }
 }

package/src/common/operations/json-operation-handler.ts

@@ -0,0 +1,147 @@
+/********************************************************************************
+ * Copyright (c) 2023 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0.
+ *
+ * This Source Code may also be made available under the following Secondary
+ * Licenses when the conditions for such availability set forth in the Eclipse
+ * Public License v. 2.0 are satisfied: GNU General Public License, version 2
+ * with the GNU Classpath Exception which is available at
+ * https://www.gnu.org/software/classpath/license.html.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+ ********************************************************************************/
+import { GModelElement } from '@eclipse-glsp/graph';
+import {
+    AnyObject,
+    CreateEdgeOperation,
+    CreateNodeOperation,
+    MaybePromise,
+    Point,
+    TriggerEdgeCreationAction,
+    TriggerNodeCreationAction,
+    hasFunctionProp,
+    hasObjectProp
+} from '@eclipse-glsp/protocol';
+import { injectable } from 'inversify';
+import { Command } from '../command/command';
+import { AbstractRecordingCommand } from '../command/recording-command';
+import { ModelState } from '../features/model/model-state';
+import { getRelativeLocation } from '../utils/layout-util';
+import { CreateEdgeOperationHandler, CreateNodeOperationHandler } from './create-operation-handler';
+import { OperationHandler } from './operation-handler';
+
+/**
+ * Helper interface for {@link ModelState} implementations of diagram languages that use a (serializable) JSON-based source model.
+ * Has to be implemented in order to reuse the {@link JsonOperationHandler} API.
+ */
+export interface JsonModelState<JsonObject extends AnyObject = AnyObject> extends ModelState {
+    readonly sourceModel: JsonObject;
+    updateSourceModel(sourceModel: JsonObject): void;
+}
+
+export namespace JsonModelState {
+    export function is(modelState: ModelState): modelState is JsonModelState {
+        return hasObjectProp(modelState, 'sourceModel') && hasFunctionProp(modelState, 'updateSourceModel');
+    }
+}
+
+/**
+ * Simple base implementation of {@link AbstractRecordingCommand} that allows recording of changes made
+ * to the `sourceModel` of the given {@link JsonModelState} during the given `doExecute` function
+ */
+export class JsonRecordingCommand<JsonObject extends AnyObject = AnyObject> extends AbstractRecordingCommand<JsonObject> {
+    constructor(protected modelState: JsonModelState<JsonObject>, protected doExecute: () => MaybePromise<void>) {
+        super();
+    }
+
+    protected override getJsonObject(): MaybePromise<JsonObject> {
+        return this.modelState.sourceModel;
+    }
+
+    protected override postChange(newModel: JsonObject): MaybePromise<void> {
+        this.modelState.updateSourceModel(newModel);
+    }
+}
+
+/**
+ * Reusable {@link OperationHandler} base implementation for diagram languages that use a (serializable) JSON-based source model.
+ * To use this class (or its subclasses) the injected {@link ModelState} has to implement the {@link JsonModelState} interface.
+ *
+ */
+@injectable()
+export abstract class JsonOperationHandler extends OperationHandler {
+    protected commandOf(runnable: () => void): Command {
+        if (!JsonModelState.is(this.modelState)) {
+            throw new Error('Cannot create command. The underlying model state does not implement the `JsonModelState` interface');
+        }
+        return new JsonRecordingCommand(this.modelState, runnable);
+    }
+}
+
+/**
+ * Reusable {@link CreateNodeOperationHandler} base implementation for diagram languages that use a (serializable) JSON-based source model.
+ */
+@injectable()
+export abstract class JsonCreateNodeOperationHandler extends JsonOperationHandler implements CreateNodeOperationHandler {
+    abstract elementTypeIds: string[];
+    abstract override label: string;
+    override readonly operationType = CreateNodeOperation.KIND;
+
+    abstract override createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined>;
+
+    getTriggerActions(): TriggerNodeCreationAction[] {
+        return this.elementTypeIds.map(typeId => TriggerNodeCreationAction.create(typeId));
+    }
+
+    /**
+     * Return the GModelElement that will contain the newly created node. It is usually
+     * the target element ({@link CreateNodeOperation.containerId}), but could also
+     * be e.g. an intermediate compartment, or even a different Node.
+     *
+     * @param operation
+     * @return the GModelElement that will contain the newly created node.
+     */
+    getContainer(operation: CreateNodeOperation): GModelElement | undefined {
+        const index = this.modelState.index;
+        return operation.containerId ? index.get(operation.containerId) : undefined;
+    }
+
+    getLocation(operation: CreateNodeOperation): Point | undefined {
+        return operation.location;
+    }
+
+    /**
+     * Retrieves the diagram absolute location and the target container from the given {@link CreateNodeOperation}
+     * and converts the absolute location to coordinates relative to the given container.
+     *  Relative coordinates can only be retrieved if the given container element is part of
+     * a hierarchy of {@link GBoundsAware} elements. This means each (recursive) parent element need to
+     * implement {@link GBoundsAware}. If that is not the case this method returns `undefined`.
+     * @param absoluteLocation The diagram absolute position.
+     * @param container The container element.
+     * @returns The relative position or `undefined`.
+     */
+    getRelativeLocation(operation: CreateNodeOperation): Point | undefined {
+        const container = this.getContainer(operation) ?? this.modelState.root;
+        const absoluteLocation = this.getLocation(operation) ?? Point.ORIGIN;
+        return getRelativeLocation(absoluteLocation, container);
+    }
+}
+
+/**
+ * Reusable {@link CreateEdgeOperationHandler} base implementation for diagram languages that use a (serializable) JSON-based source model.
+ */
+@injectable()
+export abstract class JsonCreateEdgeOperationHandler extends JsonOperationHandler implements CreateEdgeOperationHandler {
+    abstract elementTypeIds: string[];
+    abstract override label: string;
+    override readonly operationType = CreateEdgeOperation.KIND;
+
+    abstract override createCommand(operation: CreateEdgeOperation): MaybePromise<Command | undefined>;
+
+    getTriggerActions(): TriggerEdgeCreationAction[] {
+        return this.elementTypeIds.map(typeId => TriggerEdgeCreationAction.create(typeId));
+    }
+}