@eclipse-glsp/client 1.1.0-next.1e8f67a.219 → 1.1.0-next.256d64d.278

package/src/base/model/diagram-loader.ts

@@ -0,0 +1,201 @@
+/********************************************************************************
+ * 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 { inject, injectable, multiInject, optional, postConstruct } from 'inversify';
+import {
+    AnyObject,
+    ApplicationIdProvider,
+    Args,
+    EMPTY_ROOT,
+    GLSPClient,
+    InitializeParameters,
+    MaybePromise,
+    RequestModelAction,
+    ServerStatusAction,
+    SetModelAction,
+    TYPES,
+    hasNumberProp
+} from '~glsp-sprotty';
+import { GLSPActionDispatcher } from '../action-dispatcher';
+import { Ranked } from '../ranked';
+import { GLSPModelSource } from './glsp-model-source';
+
+/**
+ * Configuration options for a specific GLSP diagram instance.
+ */
+export interface IDiagramOptions {
+    /**
+     * Unique id associated with this diagram. Used on the server side to identify the
+     * corresponding client session.
+     */
+    clientId: string;
+    /**
+     * The diagram type i.e. diagram language this diagram is associated with.
+     */
+    diagramType: string;
+    /**
+     * The provider function to retrieve the GLSP client used by this diagram to communicate with the server.
+     */
+    glspClientProvider: () => Promise<GLSPClient>;
+    /**
+     * The file source URI associated with this diagram.
+     */
+    sourceUri?: string;
+    /**
+     * The initial edit mode of diagram. Defaults to `editable`.
+     */
+    editMode?: string;
+}
+
+/**
+ * Services that implement startup hooks which are invoked during the {@link DiagramLoader.load} process.
+ * Typically used to dispatch additional initial actions and/or activate UI extensions on startup.
+ * Execution order is derived by the `rank` property of the service. If not present, the {@link Ranked.DEFAULT_RANK} will be assumed.
+ */
+export interface IDiagramStartup extends Partial<Ranked> {
+    /**
+     * Hook for services that should be executed before the underlying GLSP client is configured and the server is initialized.
+     */
+    preInitialize?(): MaybePromise<void>;
+    /**
+     * Hook for services that should be executed before the initial model loading request (i.e. `RequestModelAction`) but
+     * after the underlying GLSP client has been configured and the server is initialized.
+     */
+    preRequestModel?(): MaybePromise<void>;
+    /**
+     * Hook for services that should be executed after the initial model loading request (i.e. `RequestModelAction`).
+     * Note that this hook is invoked directly after the `RequestModelAction` has been dispatched. It does not necessarily wait
+     * until the client-server update roundtrip is completed. If you need to wait until the diagram is fully initialized use the
+     * {@link GLSPActionDispatcher.onceModelInitialized} constraint.
+     */
+    postRequestModel?(): MaybePromise<void>;
+}
+
+export namespace IDiagramStartup {
+    export function is(object: unknown): object is IDiagramStartup {
+        return (
+            AnyObject.is(object) &&
+            hasNumberProp(object, 'rank', true) &&
+            ('preInitialize' in object || 'preRequestModel' in object || 'postRequestModel' in object)
+        );
+    }
+}
+
+export interface DiagramLoadingOptions {
+    /**
+     * Optional custom options that should be used the initial {@link RequestModelAction}.
+     * These options will be merged with the default options (`diagramType` and `sourceUri`).
+     * Defaults to an empty object if not defined.
+     */
+    requestModelOptions?: Args;
+
+    /**
+     * Optional partial {@link InitializeParameters} that should be used for `initializeServer` request if the underlying
+     * {@link GLSPClient} has not been initialized yet.
+     */
+    initializeParameters?: Partial<InitializeParameters>;
+
+    /**
+     * Flag to enable/disable client side notifications during the loading process.
+     * Defaults to `true` if not defined
+     */
+    enableNotifications?: boolean;
+}
+
+export interface ResolvedDiagramLoadingOptions {
+    requestModelOptions: Args;
+    initializeParameters: InitializeParameters;
+    enableNotifications: boolean;
+}
+
+/**
+ * The central component responsible for initializing the diagram and loading the graphical model
+ * from the GLSP server.
+ * Invoking the {@link DiagramLoader.load} method is typically the first operation that is executed after
+ * a diagram DI container has been created.
+ */
+@injectable()
+export class DiagramLoader {
+    @inject(TYPES.IDiagramOptions)
+    protected options: IDiagramOptions;
+
+    @inject(GLSPActionDispatcher)
+    protected actionDispatcher: GLSPActionDispatcher;
+
+    @multiInject(TYPES.IDiagramStartup)
+    @optional()
+    protected diagramStartups: IDiagramStartup[] = [];
+
+    @inject(GLSPModelSource)
+    protected modelSource: GLSPModelSource;
+
+    @postConstruct()
+    protected postConstruct(): void {
+        this.diagramStartups.sort((a, b) => Ranked.getRank(a) - Ranked.getRank(b));
+    }
+
+    async load(options: DiagramLoadingOptions = {}): Promise<void> {
+        const resolvedOptions: ResolvedDiagramLoadingOptions = {
+            requestModelOptions: {
+                sourceUri: this.options.sourceUri ?? '',
+                diagramType: this.options.diagramType,
+                ...options.requestModelOptions
+            },
+            initializeParameters: {
+                applicationId: ApplicationIdProvider.get(),
+                protocolVersion: GLSPClient.protocolVersion,
+                ...options.initializeParameters
+            },
+            enableNotifications: options.enableNotifications ?? true
+        };
+        // Set placeholder model until real model from server is available
+        await this.actionDispatcher.dispatch(SetModelAction.create(EMPTY_ROOT));
+        await this.invokeStartupHook('preInitialize');
+        await this.initialize(resolvedOptions);
+        await this.invokeStartupHook('preRequestModel');
+        await this.requestModel(resolvedOptions);
+        await this.invokeStartupHook('postRequestModel');
+    }
+
+    protected async invokeStartupHook(hook: keyof Omit<IDiagramStartup, 'rank'>): Promise<void> {
+        for (const startup of this.diagramStartups) {
+            await startup[hook]?.();
+        }
+    }
+
+    protected requestModel(options: ResolvedDiagramLoadingOptions): Promise<void> {
+        const result = this.actionDispatcher.dispatch(RequestModelAction.create({ options: options.requestModelOptions }));
+        if (options.enableNotifications) {
+            this.actionDispatcher.dispatch(ServerStatusAction.create('', { severity: 'NONE' }));
+        }
+        return result;
+    }
+
+    protected async initialize(options: ResolvedDiagramLoadingOptions): Promise<void> {
+        await this.actionDispatcher.initialize();
+        if (options.enableNotifications) {
+            this.actionDispatcher.dispatch(ServerStatusAction.create('Initializing...', { severity: 'INFO' }));
+        }
+
+        const glspClient = await this.options.glspClientProvider();
+
+        await glspClient.start();
+
+        if (!glspClient.initializeResult) {
+            await glspClient.initializeServer(options.initializeParameters);
+        }
+    }
+}

package/src/base/model/glsp-model-source.ts

@@ -0,0 +1,177 @@
+/********************************************************************************
+ * 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 { inject, injectable, postConstruct, preDestroy } from 'inversify';
+import {
+    Action,
+    ActionHandlerRegistry,
+    ActionMessage,
+    Disposable,
+    DisposableCollection,
+    GLSPClient,
+    ILogger,
+    InitializeResult,
+    ModelSource,
+    SModelRootSchema,
+    TYPES
+} from '~glsp-sprotty';
+import { IDiagramOptions } from './diagram-loader';
+/**
+ * A helper interface that allows the client to mark actions that have been received from the server.
+ */
+export interface ServerAction extends Action {
+    __receivedFromServer: true;
+}
+
+export namespace ServerAction {
+    export function is(object: unknown): object is ServerAction {
+        return Action.is(object) && '__receivedFromServer' in object && object.__receivedFromServer === true;
+    }
+
+    /**
+     * Mark the given action as {@link ServerAction} by attaching the "_receivedFromServer" property
+     * @param action The action that should be marked as server action
+     */
+    export function mark(action: Action): void {
+        (action as ServerAction).__receivedFromServer = true;
+    }
+}
+
+/**
+ * Central component for enabling the client-server action flow with the help of an underlying {@link GLSPClient}.
+ * Handles & forwards actions that are intended for the GLSP server. In addition, it handles {@link ActionMessage}s received
+ * from the server and dispatches the corresponding actions locally.
+ *
+ * Note that in sprotty a {@link ModelSource} is serving the model to the event cycle and
+ * is used to commit the local (i.e. client-side) model back to the source.
+ * However, in GLSP the update flow is reversed meaning that changes to the source model are applied
+ * on the server side and then an update is sent to the client.
+ */
+@injectable()
+export class GLSPModelSource extends ModelSource implements Disposable {
+    @inject(TYPES.ILogger)
+    protected logger: ILogger;
+
+    @inject(TYPES.IDiagramOptions)
+    protected options: IDiagramOptions;
+
+    protected toDispose = new DisposableCollection();
+    clientId: string;
+
+    protected _glspClient: GLSPClient | undefined;
+    protected _currentRoot: SModelRootSchema;
+
+    get diagramType(): string {
+        return this.options.diagramType;
+    }
+
+    get sourceUri(): string | undefined {
+        return this.options.sourceUri;
+    }
+
+    get glspClient(): GLSPClient | undefined {
+        return this._glspClient;
+    }
+
+    @postConstruct()
+    protected postConstruct(): void {
+        this.clientId = this.options.clientId ?? this.viewerOptions.baseDiv;
+    }
+
+    configure(registry: ActionHandlerRegistry, initializeResult: InitializeResult): Promise<void> {
+        const serverActions = initializeResult.serverActions[this.diagramType];
+        if (!serverActions || serverActions.length === 0) {
+            throw new Error(`No server-handled actions could be derived from the initialize result for diagramType: ${this.diagramType}!`);
+        }
+        serverActions.forEach(action => registry.register(action, this));
+        this.toDispose.push(this.glspClient!.onActionMessage(message => this.messageReceived(message), this.clientId));
+        return this.glspClient!.initializeClientSession({ clientSessionId: this.clientId, diagramType: this.diagramType });
+    }
+
+    protected messageReceived(message: ActionMessage): void {
+        if (this.clientId !== message.clientId) {
+            return;
+        }
+        const action = message.action;
+        ServerAction.mark(action);
+        this.logger.log(this, 'receiving', action);
+        this.actionDispatcher.dispatch(action);
+    }
+
+    override initialize(registry: ActionHandlerRegistry): void {
+        // Registering actions here is discouraged and it's recommended
+        // to implemented dedicated action handlers.
+        if (!this.clientId) {
+            this.clientId = this.viewerOptions.baseDiv;
+        }
+
+        this.options.glspClientProvider().then(glspClient => {
+            this._glspClient = glspClient;
+            if (glspClient.initializeResult) {
+                this.configure(registry, glspClient.initializeResult);
+            } else {
+                const initializeListener = glspClient.onServerInitialized(result => {
+                    this.configure(registry, result);
+                    initializeListener.dispose();
+                });
+            }
+        });
+    }
+
+    handle(action: Action): void {
+        // Handling additional actions here is discouraged and it's recommended
+        // to implemented dedicated action handlers.
+        if (this.shouldForwardToServer(action)) {
+            this.forwardToServer(action);
+        }
+    }
+
+    protected forwardToServer(action: Action): void {
+        const message: ActionMessage = {
+            clientId: this.clientId,
+            action: action
+        };
+        this.logger.log(this, 'sending', message);
+        if (this.glspClient) {
+            this.glspClient.sendActionMessage(message);
+        } else {
+            throw new Error('GLSPClient is not connected');
+        }
+    }
+
+    protected shouldForwardToServer(action: Action): boolean {
+        return !ServerAction.is(action);
+    }
+
+    commitModel(newRoot: SModelRootSchema): SModelRootSchema {
+        /* In GLSP the model update flow is server-driven. i.e. changes to the graphical model are applied
+         * on server-side an only the server can issue a model update.
+         * The internal/local model should never be committed back to the model source i.e. GLSP server.
+         * => no-op implementation that simply returns the `newRoot`
+         */
+        this._currentRoot = newRoot;
+        return newRoot;
+    }
+
+    override get model(): SModelRootSchema {
+        return this._currentRoot;
+    }
+
+    @preDestroy()
+    dispose(): void {
+        this.toDispose.dispose();
+    }
+}

package/src/base/model/model-registry.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2021-2022 EclipseSource and others.
+ * Copyright (c) 2021-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
@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { injectable } from 'inversify';
-import { SModelElement, SModelRegistry } from 'sprotty';
+import { SModelElement, SModelRegistry } from '~glsp-sprotty';
 
 @injectable()
 export class GLSPModelRegistry extends SModelRegistry {

package/src/base/model-initialization-constraint.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2020-2022 EclipseSource and others.
+ * Copyright (c) 2020-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
@@ -13,9 +13,8 @@
  *
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
-import { Action, Deferred, SetModelAction, UpdateModelAction } from '@eclipse-glsp/protocol';
 import { injectable } from 'inversify';
-import { InitializeCanvasBoundsAction } from 'sprotty';
+import { Action, Deferred, InitializeCanvasBoundsAction, SetModelAction, UpdateModelAction } from '~glsp-sprotty';
 
 /**
  * The constraint defining when the initialization of the GLSP model is completed.

package/src/base/ranked.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * Copyright (c) 2019-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 { AnyObject, hasNumberProp } from '~glsp-sprotty';
+
+/**
+ * A common interface for services/listeners that should be
+ * orderable by a type or rank/priority.
+ */
+export interface Ranked {
+    rank: number;
+}
+
+export namespace Ranked {
+    export const DEFAULT_RANK = 0;
+    export function is(object: unknown): object is Ranked {
+        return AnyObject.is(object) && hasNumberProp(object, 'rank');
+    }
+
+    /**
+     * Tries to retrieve the rank form the given object. If the object
+     * implements the {@link Ranked} interface the corresponding rank is returned
+     * otherwise the {@link DEFAULT_RANK} is returned.
+     * @param object
+     */
+    export function getRank(object: unknown): number {
+        return is(object) ? object.rank : DEFAULT_RANK;
+    }
+}

package/src/base/selection-clearing-mouse-listener.ts

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2020-2022 EclipseSource and others.
+ * Copyright (c) 2020-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
@@ -14,7 +14,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
  ********************************************************************************/
 import { injectable } from 'inversify';
-import { MouseListener, SModelElement } from 'sprotty';
+import { MouseListener, SModelElement } from '~glsp-sprotty';
 
 /**
  * A mouse listener that clears the document selection on click