/********************************************************************************
* Copyright (c) 2021-2023 STMicroelectronics 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 * as sprotty from 'sprotty-protocol/lib/actions';
import { TypeGuard } from '../utils/type-util';
import { Args } from './types';
/**
* An action is a declarative description of a behavior that shall be invoked by the receiver upon receipt of the action.
* It is a plain data structure, and as such transferable between server and client. An action must never contain actual
* SModelElement instances, but either refer to them via their ids or contain serializable schema for model elements.
* Additional typeguard functions are provided via the corresponding namespace.
*/
export interface Action extends sprotty.Action {
/**
* Unique identifier specifying the kind of action to process.
*/
kind: string;
}
export declare namespace Action {
function is(object: any): object is Action;
/**
* Typeguard function to check wether the given object is an {@link Action} with the given `kind`.
* @param object The object to check.
* @param kind The expected action kind.
* @returns A type literal indicating wether the given object is an action with the given kind.
*/
function hasKind(object: any, kind: string): object is Action;
}
/**
* A general message serves as an envelope carrying an action to be transmitted between the client and the server via a DiagramServer.
* @typeParam A the {@link Action} type that is contained by this message.
* A typeguard function is provided via the corresponding namespace.
*/
export interface ActionMessage extends sprotty.ActionMessage {
/**
* The unique client id
* */
clientId: string;
/**
* The action to execute.
*/
action: A;
}
export declare namespace ActionMessage {
function is(object: any, typeguard?: TypeGuard): object is ActionMessage;
}
/**
* A request action is tied to the expectation of receiving a corresponding response action. The requestId property is used to match the
* received response with the original request. Typically its not necessary to create an explicit requestId. The requestId can be set
* to an empty string. The action dispatcher than auto generates an request id if needed (i.e. the action was dispatched as request).
*
* A typeguard function, and a generic helper function to generate a request id are provided via the corresponding namespace.
*/
export interface RequestAction extends Action, sprotty.RequestAction {
/**
* Unique id for this request. In order to match a response to this request, the response needs to have the same id.
*/
requestId: string;
/**
* Used to ensure correct typing. Clients must not use this property
*/
readonly _?: Res;
}
export declare namespace RequestAction {
function is(object: any): object is RequestAction;
/**
* Typeguard function to check wether the given object is an {@link RequestAction} with the given `kind`.
* @param object The object to check.
* @param kind The expected action kind.
* @returns A type literal indicating wether the given object is a request action with the given kind.
*/
function hasKind(object: any, kind: string): object is Action;
function generateRequestId(): string;
}
/**
* A response action is sent to respond to a request action. The responseId must match the requestId of the preceding request.
* In case the responseId is empty, the action is handled as standalone, i.e. it was fired without a preceding request.
* The action dispatcher of the GLSP server has a special handling for {@link RequestAction} handlers
* and automatically sets the `responseId` of the corresponding responseAction. So on the server side its typically enough
* to set the `responseId` to an empty string and rely on the `ActionDispatcher` for assigning the correct `responseId.
* Additional typeguard functions are provided via the corresponding namespace.
*/
export interface ResponseAction extends Action, sprotty.ResponseAction {
/**
* Id corresponding to the request this action responds to.
*/
responseId: string;
}
export declare namespace ResponseAction {
function is(object: any): object is ResponseAction;
/**
* Typeguard function to check wether the given object is an {@link ResponseAction} with a non-empty response id.
* @param object The object to check.
* @returns A type literal indicating wether the given object is a response action with a non-empty response id.
*/
function hasValidResponseId(object: any): object is ResponseAction;
}
/**
* A reject action is a {@link ResponseAction} fired to indicate that a certain {@link ResponseAction}
* has been rejected.
* The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
* and creating new `RejectActions`.
*/
export interface RejectAction extends ResponseAction, sprotty.RejectAction {
kind: typeof RejectAction.KIND;
/**
* A human-readable description of the reject reason. Typically this is an error message
* that has been thrown when handling the corresponding {@link RequestAction}.
*/
message: string;
/**
* Optional additional details.
*/
detail?: string;
}
export declare namespace RejectAction {
const KIND = "rejectRequest";
function is(object: unknown): object is RejectAction;
function create(message: string, options?: {
detail?: string;
responseId?: string;
}): RejectAction;
}
/**
* Operations are actions that denote requests from the client to _modify_ the model. Model modifications are always performed by the
* server. After a successful modification, the server sends the updated model back to the client using the `UpdateModelAction`.
* An operation contains a dedicated `isOperation` property that is used as a discriminator. This is necessary so that the server
* can distinguish between plain actions and operations.
* The corresponding namespace offers a helper function for type guard checks.
*/
export interface Operation extends Action {
/**
* Discriminator property to make operations distinguishable from plain {@link Action}s.
*/
isOperation: true;
/**
* Optional custom arguments.
*/
args?: Args;
}
export declare namespace Operation {
function is(object: unknown): object is Operation;
/**
* Typeguard function to check wether the given object is an {@link Operation} with the given `kind`.
* @param object The object to check.
* @param kind The expected operation kind.
* @returns A type literal indicating wether the given object is an operation with the given kind.
*/
function hasKind(object: unknown, kind: string): object is Operation;
}
/**
* An operation that executes a list of sub-operations.
* The corresponding namespace declares the action kind as constant and offers helper functions for type guard checks
* and creating new `CompoundOperations`.
*/
export interface CompoundOperation extends Operation {
kind: typeof CompoundOperation.KIND;
/**
* List of operations that should be executed.
*/
operationList: Operation[];
}
export declare namespace CompoundOperation {
const KIND = "compound";
function is(object: unknown): object is CompoundOperation;
function create(operationList: Operation[], options?: {
args?: Args;
}): CompoundOperation;
}
//# sourceMappingURL=base-protocol.d.ts.map