From 5212538cd8f2db88e042a1bd5e45809c7517eea7 Mon Sep 17 00:00:00 2001 From: Nina Doschek Date: Wed, 22 Dec 2021 08:49:24 +0100 Subject: [PATCH] #487 Improve GLSP Server API documentation (#146) Improve API documentation for service interfaces Fixed eclipse-glsp/issues/146 Co-authored-by: Tobias Ortmayr Contributed on behalf of STMicroelectronics --- CHANGELOG.md | 10 ++ .../glsp/graph/GModelChangeNotifier.java | 33 ++++- .../org/eclipse/glsp/graph/GModelIndex.java | 123 +++++++++++++++--- .../eclipse/glsp/graph/GModelListener.java | 11 +- .../eclipse/glsp/graph/GraphExtension.java | 10 +- .../glsp/graph/impl/GModelIndexImpl.java | 8 +- .../glsp/server/actions/ActionDispatcher.java | 4 + .../server/actions/ActionHandlerRegistry.java | 9 ++ .../glsp/server/actions/ActionRegistry.java | 45 +++++++ .../glsp/server/disposable/IDisposable.java | 6 + .../CommandPaletteActionProvider.java | 20 ++- .../ContextActionsProvider.java | 18 +++ .../ContextActionsProviderRegistry.java | 3 + .../contextmenu/ContextMenuItemProvider.java | 20 +++ .../directediting/ContextEditValidator.java | 17 +++ .../ContextEditValidatorRegistry.java | 3 + .../directediting/LabelEditValidator.java | 10 ++ .../navigation/NavigationTargetProvider.java | 14 ++ .../NavigationTargetProviderRegistry.java | 3 + .../navigation/NavigationTargetResolver.java | 49 ++++++- .../features/popup/PopupModelFactory.java | 15 +++ .../toolpalette/ToolPaletteItemProvider.java | 18 +++ .../features/validation/ModelValidator.java | 11 ++ .../glsp/server/layout/LayoutEngine.java | 2 +- .../glsp/server/model/GModelState.java | 20 ++- .../operations/CreateOperationHandler.java | 21 ++- .../operations/OperationHandlerRegistry.java | 3 + .../glsp/server/session/ClientSession.java | 7 +- 28 files changed, 483 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 87986755..8d647e36 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,14 @@ # Eclipse GLSP Server Changelog +## v0.10.0 - Upcoming + +### Changes + +- [documentation] Improved existing API javadoc and added missing documentation for service interfaces. [#487](https://github.com/eclipse-glsp/glsp-server/pull/146) - Contributed on behalf of STMicroelectronics +- + +### Breaking Changes + + ## [v0.9.0- 09/12/2021](https://github.com/eclipse-glsp/glsp/releases/tag/0.9.0) diff --git a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelChangeNotifier.java b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelChangeNotifier.java index 8afb2d4e..95cab701 100644 --- a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelChangeNotifier.java +++ b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelChangeNotifier.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -21,8 +21,18 @@ import org.eclipse.emf.ecore.util.EcoreUtil; import org.eclipse.glsp.graph.impl.GModelChangeNotifierImpl; +/** + * A notifier interface to notify registered {@link GModelListener}s if a {@link GModelElement} changes. + * Mostly, changes of the {@link GModelRoot} will be tracked and broadcasted. + */ public interface GModelChangeNotifier { + /** + * Get the GModelChangeNotifier for a given GModelElement. + * + * @param element The GModelElement to observe for changes. + * @return The {@link GModelChangeNotifier} instance that observers the given element. + */ static GModelChangeNotifier get(final GModelElement element) { EObject root = EcoreUtil.getRootContainer(element); GModelChangeNotifier existingNotifier = (GModelChangeNotifierImpl) EcoreUtil.getExistingAdapter(root, @@ -30,10 +40,21 @@ static GModelChangeNotifier get(final GModelElement element) { return Optional.ofNullable(existingNotifier).orElseGet(() -> create(element)); } + /** + * Create a new GModelChangeNotifier instance to notify about changes of the given {@link GModelElement}. + * + * @param element The GModelElement to observe for changes. + * @return A new instance of {@link GModelChangeNotifier} that observers the given element. + */ static GModelChangeNotifier create(final GModelElement element) { return new GModelChangeNotifierImpl(EcoreUtil.getRootContainer(element)); } + /** + * Remove an observed {@link GModelElement} from the notifier instance. + * + * @param element The GModelElement to remove from the observed notifier target. + */ static void remove(final GModelElement element) { EObject root = EcoreUtil.getRootContainer(element); GModelChangeNotifierImpl existingNotifier = (GModelChangeNotifierImpl) EcoreUtil.getExistingAdapter(root, @@ -44,8 +65,18 @@ static void remove(final GModelElement element) { existingNotifier.unsetTarget(root); } + /** + * Add a {@link GModelListener} to the {@link GModelChangeNotifier} to observe GModelElement changes. + * + * @param listener The listener to add. + */ void addListener(GModelListener listener); + /** + * Remove a {@link GModelListener} from the {@link GModelChangeNotifier} to stop observing GModelElement changes. + * + * @param listener The listener to remove. + */ void removeListener(GModelListener listener); } diff --git a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelIndex.java b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelIndex.java index 99495846..ad0d9705 100644 --- a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelIndex.java +++ b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelIndex.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -28,18 +28,39 @@ import org.eclipse.emf.ecore.util.EcoreUtil; import org.eclipse.glsp.graph.impl.GModelIndexImpl; +/** + * Is used to index all child elements of a {@link GModelRoot} by their id. Offers a set + * of query methods to retrieve indexed elements. + */ public interface GModelIndex { + /** + * Returns the GModelIndex instance that contains the root of the given {@link GModelElement}. + * + * @param element The GModelElement for which an index instance should be returned. + * @return The GModelIndex instance that contains the root of the given GModelElement. + */ static GModelIndex get(final GModelElement element) { EObject root = EcoreUtil.getRootContainer(element); GModelIndex existingIndex = (GModelIndexImpl) EcoreUtil.getExistingAdapter(root, GModelIndexImpl.class); return Optional.ofNullable(existingIndex).orElseGet(() -> (create(element))); } + /** + * Create a new GModelIndex instance of the root of the given {@link GModelElement}. + * + * @param element The GModelElement for which a new index instance should be created. + * @return A new GModelIndex instance that contains the root of the given GModelElement. + */ static GModelIndex create(final GModelElement element) { return new GModelIndexImpl(EcoreUtil.getRootContainer(element)); } + /** + * Removes the root of the given {@link GModelElement} from an existing GModelIndex instance. + * + * @param element The GModelElement which root should be removed from the index instance. + */ static void remove(final GModelElement element) { EObject root = EcoreUtil.getRootContainer(element); GModelIndexImpl existingIndex = (GModelIndexImpl) EcoreUtil.getExistingAdapter(root, GModelIndexImpl.class); @@ -49,28 +70,70 @@ static void remove(final GModelElement element) { existingIndex.unsetTarget(root); } + /** + * Returns an optional {@link GModelElement} by its elementId. + * + * @param elementId The id of the requested {@link GModelElement}. + * @return An optional instance of the {@link GModelElement}. + */ Optional get(String elementId); + /** + * Returns a set of {@link GModelElement} instances by a Collection of elementIds. + * + * @param elementIds The ids to request the {@link GModelElement} instances. + * @return A set of {@link GModelElement}s. + */ Set getAll(Collection elementIds); + /** + * Returns a collection of all incoming edges for a {@link GModelElement}. + * + * @param node The requested {@link GModelElement}. + * @return A collection of all incoming edges for a {@link GModelElement}. + */ Collection getIncomingEdges(GModelElement node); + /** + * Returns a collection of all outgoing edges for a {@link GModelElement}. + * + * @param node The requested {@link GModelElement}. + * @return A collection of all outgoing edges for a {@link GModelElement}. + */ Collection getOutgoingEdges(GModelElement node); + /** + * Returns a set of all {@link GModelElement} ids contained in this instance of the GModelIndex. + * + * @return A set of elementIds. + */ Set allIds(); + /** + * Returns the contained {@link GModelRoot} in this instance of the GModelIndex. + * + * @return The contained {@link GModelRoot} instance. + */ GModelElement getRoot(); + /** + * Returns the current amount of occurrences of an EClass in this instance of the GModelIndex. + * + * @param eClass The EClass to be counted in this instance of the GModelIndex. + * @param idProvider A function that provides an id based on the counter result. + * + * @return The amount of occurrences of an EClass. + */ int getCounter(EClass eClass, Function idProvider); /** * Returns the first element of type clazz starting from the element with the * given id and walking up the parent hierarchy. * - * @param elementId id of the element to start the search from - * @param clazz class of which the found element should be an instance - * @param type of the element to be found - * @return an optional with the element of type clazz or an empty optional + * @param elementId The id of the element to start the search from. + * @param clazz The class of which the found element should be an instance. + * @param The type of the element to be found. + * @return An optional with the element of type clazz or an empty optional. */ default Optional findElementByClass(final String elementId, final Class clazz) { Optional element = get(elementId); @@ -84,10 +147,10 @@ default Optional findElementByClass(final String el * Returns the first element of type clazz starting from the given element and * walking up the parent hierarchy. * - * @param element element to start the search from - * @param clazz class of which the found element should be an instance - * @param type of the element to be found - * @return an optional with the element of type clazz or an empty optional + * @param element The element to start the search from. + * @param clazz The class of which the found element should be an instance. + * @param The type of the element to be found. + * @return An optional with the element of type clazz or an empty optional. * * */ @@ -107,9 +170,9 @@ default Optional findElementByClass(final GModelEle * Returns the first element matching the predicate starting element with the * given id and walking up the parent hierarchy. * - * @param elementId element to start the search from - * @param predicate predicate which the element should match - * @return an optional with the first element matching the predicate or an empty + * @param elementId The element to start the search from + * @param predicate The predicate which the element should match + * @return An optional with the first element matching the predicate or an empty * optional */ default Optional findElement(final String elementId, final Predicate predicate) { @@ -124,10 +187,10 @@ default Optional findElement(final String elementId, final Predic * Returns the first element matching the predicate starting from the given * element and walking up the parent hierarchy. * - * @param element element to start the search from - * @param predicate predicate which the element should match - * @return an optional with the first element matching the predicate or an empty - * optional + * @param element The element to start the search from. + * @param predicate The predicate which the element should match. + * @return An optional with the first element matching the predicate or an empty + * optional. */ default Optional findElement(final GModelElement element, final Predicate predicate) { if (element == null) { @@ -141,15 +204,36 @@ default Optional findElement(final GModelElement element, final P return parent != null ? findElement(parent, predicate) : Optional.empty(); } + /** + * Returns all elements of the type clazz contained in the {@link GModelRoot}. + * + * @param Type of the elements to be returned. + * @param clazz The class of which the returned elements should be instances. + * @return A set containing the elements of type clazz. + */ default Set getAllByClass(final Class clazz) { return findAll(this.getRoot(), clazz); } + /** + * Returns all elements of the type clazz contained in a given parent {@link GModelElement}. + * + * @param Type of the elements to be returned. + * @param parent The parent element to start the element search from. + * @param clazz The class of which the returned elements should be instances. + * @return A set containing the elements of type clazz. + */ default Set findAll(final GModelElement parent, final Class type) { return getStream(parent).flatMap(this::getStream).filter(type::isInstance).map(type::cast) .collect(Collectors.toSet()); } + /** + * Returns a {@link Stream} of all contained {@link GModelElement} in the given {@link GModelElement}. + * + * @param element The element to retrieve all contained elements as stream. + * @return A stream of all elements. + */ default Stream getStream(final GModelElement element) { if (element == null) { return Stream.empty(); @@ -160,6 +244,13 @@ default Stream getStream(final GModelElement element) { return Stream.concat(Stream.of(element), element.getChildren().stream()); } + /** + * Returns the current amount of type occurrences in this instance of the GModelIndex. + * + * @param eClass The EClass to be counted in this instance of the GModelIndex. + * + * @return The amount of type occurrences. + */ int getTypeCount(EClass eClass); } diff --git a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelListener.java b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelListener.java index 1632bdfb..25be3f93 100644 --- a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelListener.java +++ b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelListener.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -17,8 +17,17 @@ import org.eclipse.emf.common.notify.Notification; +/** + * A listener to observe changes of the {@link GModelRoot}. + * It is typically associated with a {@link GModelChangeNotifier}. + */ public interface GModelListener { + /** + * Triggered if a change to the {@link GModelRoot} has occurred. + * + * @param notification A description of the change to the GModelRoot. + */ void notifyChanged(Notification notification); } diff --git a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GraphExtension.java b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GraphExtension.java index 63a47553..95db96c0 100644 --- a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GraphExtension.java +++ b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GraphExtension.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -18,9 +18,13 @@ import org.eclipse.emf.ecore.EFactory; import org.eclipse.emf.ecore.EPackage; +/** + * Is used to configure a graph extension for a diagram language. A graph extension + * is a custom Ecore model that extends the default GLSP Graph ecore model, e.g by adding new GModelElement types. + */ public interface GraphExtension { /** - * Unique identifier for this graph extension (Default: NSURI of the Epackage). + * Unique identifier for this graph extension (Default: NSURI of the EPackage). * * @return Id as String */ @@ -37,7 +41,7 @@ public interface GraphExtension { /** * Returns the EFactory for this {@link GraphExtension}. * - * @return the EFfactory + * @return the EFactory */ EFactory getEFactory(); } diff --git a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/impl/GModelIndexImpl.java b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/impl/GModelIndexImpl.java index ab9acdd1..ce5f33f9 100644 --- a/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/impl/GModelIndexImpl.java +++ b/plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/impl/GModelIndexImpl.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -38,9 +38,15 @@ import org.eclipse.glsp.graph.GEdge; import org.eclipse.glsp.graph.GModelElement; import org.eclipse.glsp.graph.GModelIndex; +import org.eclipse.glsp.graph.GModelRoot; import com.google.common.base.Preconditions; +/** + * Default implementation of {@link GModelIndex}. Registers itself as adapter of the {@link GModelRoot} + * to receive change notifications. This enables auto updating of the internal index if a child elements is + * added or removed from the {@link GModelRoot}. + */ public class GModelIndexImpl extends ECrossReferenceAdapter implements GModelIndex { private final Map idToElement = new HashMap<>(); diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionDispatcher.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionDispatcher.java index 8acd8bd9..636e7804 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionDispatcher.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionDispatcher.java @@ -22,6 +22,10 @@ import org.eclipse.glsp.server.disposable.IDisposable; import org.eclipse.glsp.server.features.core.model.UpdateModelAction; +/** + * The central component that process all {@link Action}s by dispatching them to their designated + * handlers. + */ public interface ActionDispatcher extends IDisposable { /** diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionHandlerRegistry.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionHandlerRegistry.java index 74d96a76..48e860ab 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionHandlerRegistry.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionHandlerRegistry.java @@ -19,7 +19,16 @@ import org.eclipse.glsp.server.registry.MultiRegistry; +/** + * An action handler registry keeps track of registered action handlers for a certain action. + */ public interface ActionHandlerRegistry extends MultiRegistry, ActionHandler> { + /** + * Returns the registered {@link ActionHandler} for a given {@link Action}. + * + * @param action The action for which the handler should be returned. + * @return The registered ActionHandler for the given action. + */ default List get(final Action action) { return get(action.getClass()); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionRegistry.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionRegistry.java index 08ce8de6..72245bc1 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionRegistry.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionRegistry.java @@ -20,24 +20,69 @@ import org.eclipse.glsp.server.registry.Registry; +/** + * An action registry keeps track of registered actions for a certain diagramType. + */ public interface ActionRegistry extends Registry>> { + /** + * Registers an action for a diagramType. + * + * @param diagramType The diagramType for which the action is registered. + * @param actionKind The actionKind of the action to be registered. + * @param action The action to be registered. + * @param isServerAction This flag indicates if the given action is handled by the server. + * @return A boolean flag that indicates if the registration was successful. + */ boolean register(String diagramType, String actionKind, Class action, boolean isServerAction); + /** + * Registers a server handled action for a diagramType. + * + * @param diagramType The diagramType for which the action is registered. + * @param actionKind The actionKind of the action to be registered. + * @param action The action to be registered. + * @return A boolean flag that indicates if the registration was successful. + */ default boolean register(final String diagramType, final String actionKind, final Class action) { return register(diagramType, actionKind, action, true); } + /** + * Registers a set of server handled actions for a diagramType. + * + * @param diagramType The diagramType for which the action is registered. + * @param actionMap A map of actionKind and actions to be registered. + * @return A boolean flag that indicates if the registration was successful. + */ @Override default boolean register(final String diagramType, final Map> actionMap) { return register(diagramType, actionMap, true); } + /** + * Registers a set of actions for a diagramType. + * + * @param diagramType The diagramType for which the action is registered. + * @param actionMap A map of actionKind and actions to be registered. + * @param isServerAction This flag indicates if the given actions are handled by the server. + * @return A boolean flag that indicates if the registration was successful. + */ boolean register(String diagramType, Map> actionMap, boolean isServerAction); + /** + * Returns a list of actions that are handled by the server for the given diagramType. + * + * @return A list of actions that are handled on the server for the given diagramType. + */ List getServerHandledAction(String diagramType); + /** + * Returns a map of all registered diagramTypes and their server-handled actions. + * + * @return A map of all registered diagramTypes and their server-handled actions. + */ Map> getServerHandledActions(); /** diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/disposable/IDisposable.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/disposable/IDisposable.java index 80b15d6d..703e6b7f 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/disposable/IDisposable.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/disposable/IDisposable.java @@ -42,6 +42,12 @@ static void disposeIfExists(final IDisposable disposable) { } } + /** + * Creates a new IDisposable for a given runnable. + * + * @param runnable The runnable for which a new IDisposable instance is created. + * @return A new instance of an IDisposable. + */ static IDisposable create(final Runnable runnable) { return new Disposable() { @Override diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/commandpalette/CommandPaletteActionProvider.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/commandpalette/CommandPaletteActionProvider.java index 3be9912d..ade222c8 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/commandpalette/CommandPaletteActionProvider.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/commandpalette/CommandPaletteActionProvider.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -19,6 +19,9 @@ import org.eclipse.glsp.server.features.contextactions.ContextActionsProvider; +/** + * A {@link ContextActionsProvider} for CommandPaletteActions. + */ @FunctionalInterface public interface CommandPaletteActionProvider extends ContextActionsProvider { @@ -26,13 +29,28 @@ public interface CommandPaletteActionProvider extends ContextActionsProvider { String TEXT = "text"; String INDEX = "index"; + /** + * Returns the context id of the provider. + */ @Override default String getContextId() { return CommandPaletteActionProvider.CONTEXT_ID; } + /** + * Retrieves the value for the "text" key from the given arguments Map. + * + * @param args The given map of string arguments. + * @return The value associated with the "text" key. + */ default String getText(final Map args) { return args.getOrDefault(TEXT, ""); } + /** + * Returns the value of the "index" key from a given Map of arguments. + * + * @param args The given map of string arguments. + * @return The value associated with the "index" key. + */ default int getIndex(final Map args) { return (int) Double.parseDouble(args.getOrDefault(INDEX, "0.0")); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProvider.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProvider.java index 9827e1f5..9ba64909 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProvider.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProvider.java @@ -20,12 +20,30 @@ import org.eclipse.glsp.server.features.directediting.LabeledAction; import org.eclipse.glsp.server.types.EditorContext; +/** + * A provider for a certain contextId that provides {@link LabeledAction}s. + */ public interface ContextActionsProvider { + /** + * Returns the context id of the {@link ContextActionsProvider}. + */ String getContextId(); + /** + * Returns a list of {@link LabeledAction}s for a given {@link EditorContext}. + * + * @param editorContext The editorContext for which the actions are returned. + * @return A list of {@link LabeledAction}s for a given {@link EditorContext}. + */ List getActions(EditorContext editorContext); + /** + * Validates if a ContextActionsProvider can handle the given contextId. + * + * @param contextId The contextIf that to be checked. + * @return `true` if a ContextActionsProvider can handle a given contextId. + */ default boolean handles(final String contextId) { return getContextId().equals(contextId); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProviderRegistry.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProviderRegistry.java index 3aa83ea2..a0d4f021 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProviderRegistry.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextactions/ContextActionsProviderRegistry.java @@ -17,4 +17,7 @@ import org.eclipse.glsp.server.registry.Registry; +/** + * A registry that keeps track of all registered {@link ContextActionsProvider}s. + */ public interface ContextActionsProviderRegistry extends Registry {} diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextmenu/ContextMenuItemProvider.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextmenu/ContextMenuItemProvider.java index 193fb349..1a13fb9b 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextmenu/ContextMenuItemProvider.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/contextmenu/ContextMenuItemProvider.java @@ -25,16 +25,36 @@ import org.eclipse.glsp.server.features.directediting.LabeledAction; import org.eclipse.glsp.server.types.EditorContext; +/** + * A {@link ContextActionsProvider} for {@link MenuItem}s. + */ @FunctionalInterface public interface ContextMenuItemProvider extends ContextActionsProvider { String KEY = "context-menu"; + /** + * Returns the context id of the {@link ContextMenuItemProvider}. + */ @Override default String getContextId() { return ContextMenuItemProvider.KEY; } + /** + * Returns a list of {@link MenuItem}s for a given list of selected elements at a certain mouse position. + * + * @param selectedElementIds The list of currently selected elementIds. + * @param position The current mouse position. + * @param args Additional arguments. + * @return A list of {@link MenuItem}s for a given list of selected elements at a certain mouse position. + */ List getItems(List selectedElementIds, GPoint position, Map args); + /** + * Returns a list of {@link LabeledAction}s for a given {@link EditorContext}. + * + * @param editorContext The editorContext for which the actions are returned. + * @return A list of {@link LabeledAction}s for a given {@link EditorContext}. + */ @Override default List getActions(final EditorContext editorContext) { final GPoint position = editorContext.getLastMousePosition().orElse(point(0, 0)); diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidator.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidator.java index a979d6ff..a603c0f4 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidator.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidator.java @@ -15,12 +15,29 @@ ********************************************************************************/ package org.eclipse.glsp.server.features.directediting; +import org.eclipse.glsp.server.features.contextactions.ContextActionsProvider; + public interface ContextEditValidator { + /** + * Returns the context id of the {@link ContextActionsProvider}. + */ String getContextId(); + /** + * Returns the {@link ValidationStatus} for a given {@link RequestEditValidationAction}. + * + * @param action The RequestEditValidationAction to validate. + * @return The {@link ValidationStatus} for a given {@link RequestEditValidationAction}. + */ ValidationStatus validate(RequestEditValidationAction action); + /** + * Validates if the validator can handle a given contextId. + * + * @param contextId The contextId to check. + * @return `true` if the validator can handle a given contextId. + */ default boolean handles(final String contextId) { return getContextId().equals(contextId); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidatorRegistry.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidatorRegistry.java index d0c9df27..ced033af 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidatorRegistry.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/ContextEditValidatorRegistry.java @@ -17,4 +17,7 @@ import org.eclipse.glsp.server.registry.Registry; +/** + * A registry that keeps track of all registered {@link ContextEditValidator}s. + */ public interface ContextEditValidatorRegistry extends Registry {} diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/LabelEditValidator.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/LabelEditValidator.java index ab6c0b44..93b4df90 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/LabelEditValidator.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/directediting/LabelEditValidator.java @@ -17,9 +17,19 @@ import org.eclipse.glsp.graph.GModelElement; +/** + * A validator that validates a new label for a given {@link GModelElement}. + */ public interface LabelEditValidator { String CONTEXT_ID = "label-edit"; + /** + * Returns the {@link ValidationStatus} for a given edited label of a {@link GModelElement}. + * + * @param label The edited label to validate. + * @param element The element for which the label is going to be edited. + * @return The {@link ValidationStatus} of the label. + */ ValidationStatus validate(String label, GModelElement element); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProvider.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProvider.java index fa0ab4ec..b35aa378 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProvider.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProvider.java @@ -19,6 +19,9 @@ import org.eclipse.glsp.server.types.EditorContext; +/** + * This provider retrieves navigation targets for its target type from a given {@link EditorContext}. + */ public interface NavigationTargetProvider { String JSON_OPENER_OPTIONS = "jsonOpenerOptions"; @@ -43,8 +46,19 @@ public interface NavigationTargetProvider { */ List getTargets(EditorContext editorContext); + /** + * Returns the targetTypeId of the provider. + * + * @return The targetTypeId of the provider. + */ String getTargetTypeId(); + /** + * Returns whether a provider can handle a given targetTypeId. + * + * @param targetTypeId The targetTypeId to be checked. + * @return A boolean that indicates if the targetTypeId can be handled by the provider. + */ default boolean handles(final String targetTypeId) { return getTargetTypeId().equals(targetTypeId); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProviderRegistry.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProviderRegistry.java index 924aa07f..ec9d2f19 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProviderRegistry.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetProviderRegistry.java @@ -17,4 +17,7 @@ import org.eclipse.glsp.server.registry.Registry; +/** + * This registry keeps track of registered {@link NavigationTargetProvider} for a certain target types. + */ public interface NavigationTargetProviderRegistry extends Registry {} diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetResolver.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetResolver.java index dcc42d5b..f0b0738e 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetResolver.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/navigation/NavigationTargetResolver.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2020 EclipseSource and others. + * Copyright (c) 2020-2021 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 @@ -24,38 +24,85 @@ public interface NavigationTargetResolver { String WARNING = "warning"; String ERROR = "error"; + /** + * Returns a {@link NavigationTargetResolution} for a given {@link NavigationTarget}. + * + * @param navigationTarget The given {@link NavigationTarget} to be resolved. + * @return A {@link NavigationTargetResolution} instance for the given target. + */ NavigationTargetResolution resolve(NavigationTarget navigationTarget); + /** + * Creates a map of string arguments. + * + * @return A new map of string arguments. + */ default Map createArgs() { return new HashMap<>(); } + /** + * Creates a map of string arguments and adds an information message as separate "info" argument. + * + * @param message The information message that should be added as "info" argument to the map. + * @return A new map of string arguments with an additional information message. + */ default Map createArgsWithInfo(final String message) { Map args = createArgs(); addInfo(message, args); return args; } + /** + * Creates a map of string arguments and adds a warning message as separate "warning" argument. + * + * @param message The warning message that should be added as "warning" argument to the map. + * @return A new map of string arguments with an additional warning message. + */ default Map createArgsWithWarning(final String message) { Map args = createArgs(); addWarning(message, args); return args; } + /** + * Creates a map of string arguments and adds an error message as separate "error" argument. + * + * @param message The error message that should be added as "error" argument to the map. + * @return A new map of string arguments with an additional error message. + */ default Map createArgsWithError(final String message) { Map args = createArgs(); addError(message, args); return args; } + /** + * Adds an information message as separate "info" argument to an existing map of string arguments. + * + * @param message The information message to add. + * @param args The map of string arguments to add the message to. + */ default void addInfo(final String message, final Map args) { args.put(INFO, message); } + /** + * Adds a warning message as separate "warning" argument to an existing map of string arguments. + * + * @param message The warning message to add. + * @param args The map of string arguments to add the message to. + */ default void addWarning(final String message, final Map args) { args.put(WARNING, message); } + /** + * Adds an error message as separate "error" argument to an existing map of string arguments. + * + * @param message The error message to add. + * @param args The map of string arguments to add the message to. + */ default void addError(final String message, final Map args) { args.put(ERROR, message); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/popup/PopupModelFactory.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/popup/PopupModelFactory.java index b7038e29..ad4e0152 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/popup/PopupModelFactory.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/popup/PopupModelFactory.java @@ -19,8 +19,23 @@ import org.eclipse.glsp.graph.GHtmlRoot; import org.eclipse.glsp.graph.GModelElement; +import org.eclipse.glsp.graph.GPreRenderedElement; +/** + * A PopupModelFactory creates a popup model for the given element. + * A popup model is a {@link GHtmlRoot} that is self contained and not part of the diagram model. + * In contrast to diagram elements popup models typically don't contain dynamically rendered {@link GModelElement}s and + * use{@link GPreRenderedElement}s that contain server-side computed html or svg code instead. + */ public interface PopupModelFactory { + /** + * Returns an optional {@link GHtmlRoot} for a given {@link GModelElement} triggered by a + * {@link RequestPopupModelAction}. + * + * @param element The element to create the popup model for. + * @param action The {@link RequestPopupModelAction} that triggered this popup model creation. + * @return An optional {@link GHtmlRoot} for a given {@link GModelElement}. + */ Optional createPopupModel(GModelElement element, RequestPopupModelAction action); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/toolpalette/ToolPaletteItemProvider.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/toolpalette/ToolPaletteItemProvider.java index de74c2ef..efa8fdfa 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/toolpalette/ToolPaletteItemProvider.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/toolpalette/ToolPaletteItemProvider.java @@ -22,16 +22,34 @@ import org.eclipse.glsp.server.features.directediting.LabeledAction; import org.eclipse.glsp.server.types.EditorContext; +/** + * A {@link ContextActionsProvider} for {@link PaletteItem}s. + */ public interface ToolPaletteItemProvider extends ContextActionsProvider { String CONTEXT_ID = "tool-palette"; + /** + * Returns the context id of the provider. + */ @Override default String getContextId() { return ToolPaletteItemProvider.CONTEXT_ID; } + /** + * Returns a list of {@link LabeledAction}s for a given {@link EditorContext}. + * + * @param editorContext The editorContext for which the actions are returned. + * @return A list of {@link LabeledAction}s for a given {@link EditorContext}. + */ @Override default List getActions(final EditorContext editorContext) { return getItems(editorContext.getArgs()); } + /** + * Constructs a list of {@link PaletteItem}s from a given map of string arguments. + * + * @param args A map of string arguments. + * @return A list of {@link PaletteItem}s for a given map of string arguments. + */ List getItems(Map args); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/validation/ModelValidator.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/validation/ModelValidator.java index ff97cf8e..ba67f791 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/validation/ModelValidator.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/features/validation/ModelValidator.java @@ -19,7 +19,18 @@ import org.eclipse.glsp.graph.GModelElement; +/** + * Validates a list of {@link GModelElement}s based on a set of validation rules and returns corresponding issue + * {@link Marker}s. + * An issue marker is a serializable description of the validation violation that can be visualised by the GLSP client. + */ public interface ModelValidator { + /** + * Validates the given list of {@link GModelElement}s and returns a list of {@link Marker}s. + * + * @param elements The list of {@link GModelElement} to validate. + * @return A list of {@link Marker}s for the validated {@link GModelElement}s. + */ List validate(GModelElement... elements); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/layout/LayoutEngine.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/layout/LayoutEngine.java index 81a94185..b10cd662 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/layout/LayoutEngine.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/layout/LayoutEngine.java @@ -19,7 +19,7 @@ * A layout engine is able to compute layout information for a model. */ public interface LayoutEngine { - /* + /** * Compute a layout for the model state and modify the model accordingly. */ void layout(); diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/model/GModelState.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/model/GModelState.java index bce91542..e9ea274d 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/model/GModelState.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/model/GModelState.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2019 EclipseSource and others. + * Copyright (c) 2019-2021 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 @@ -15,15 +15,33 @@ ******************************************************************************/ package org.eclipse.glsp.server.model; +import org.eclipse.emf.common.command.BasicCommandStack; import org.eclipse.emf.common.command.Command; import org.eclipse.glsp.graph.GModelIndex; import org.eclipse.glsp.graph.GModelRoot; +/** + * This state represents the status of the diagram based on the {@link GModelRoot}, contains the @link GModelIndex and + * is able to execute commands via its {@link BasicCommandStack}. + */ public interface GModelState extends ModelState { + /** + * Returns the {@link GModelIndex} of the current diagram. + * + * @return The {@link GModelIndex} of the current diagram. + */ GModelIndex getIndex(); + /** + * Called after a save has been successfully performed. + */ void saveIsDone(); + /** + * Uses its {@link BasicCommandStack} to execute a given {@link Command}. + * + * @param command The {@link Command} to be executed. + */ void execute(Command command); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/CreateOperationHandler.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/CreateOperationHandler.java index 8ef82c84..65b840a9 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/CreateOperationHandler.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/CreateOperationHandler.java @@ -1,5 +1,5 @@ /******************************************************************************** - * Copyright (c) 2020 EclipseSource and others. + * Copyright (c) 2020-2021 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 @@ -24,11 +24,25 @@ import com.google.common.collect.Lists; +/** + * A special {@link OperationHandler} that is responsible for the handling of {@link CreateOperation}s. Depending on its + * operation type the triggered actions are {@link TriggerNodeCreationAction} or {@link TriggerEdgeCreationAction}s. + */ public interface CreateOperationHandler extends OperationHandler { + /** + * Returns the {@link CreateOperation} type this handler has registered for. + * + * @return The {@link CreateOperation} type this handler has registered for. + */ @Override Class getHandledOperationType(); + /** + * Returns a list of {@link TriggerElementCreationAction}s for registered element types. + * + * @return A list of {@link TriggerElementCreationAction}s. + */ default List getTriggerActions() { if (CreateNodeOperation.class.isAssignableFrom(getHandledOperationType())) { return getHandledElementTypeIds().stream().map(TriggerNodeCreationAction::new).collect(Collectors.toList()); @@ -38,5 +52,10 @@ default List getTriggerActions() { return Lists.newArrayList(); } + /** + * Returns the list of element types for which this handler has registered for. + * + * @return The list of element types for which this handler has registered for. + */ List getHandledElementTypeIds(); } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/OperationHandlerRegistry.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/OperationHandlerRegistry.java index ef8f8409..b1cce28c 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/OperationHandlerRegistry.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/operations/OperationHandlerRegistry.java @@ -17,6 +17,9 @@ import org.eclipse.glsp.server.registry.Registry; +/** + * This registry contains {@link OperationHandler}s that are registered for certain {@link Operation} types. + */ public interface OperationHandlerRegistry extends Registry { } diff --git a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/session/ClientSession.java b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/session/ClientSession.java index d20f0b73..dd53237b 100644 --- a/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/session/ClientSession.java +++ b/plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/session/ClientSession.java @@ -40,14 +40,15 @@ public interface ClientSession extends IDisposable { /** * Retrieve the diagram type of the client session. * - * @return The diagram type + * @return The diagram type. */ String getDiagramType(); - /* + /** * Return the action dispatcher of this diagram type. The action dispatcher is typically created by the session * specific injector and is basically the entrypoint to the session specific injection context. - * @return + * + * @return The action dispatcher of this diagram type. */ ActionDispatcher getActionDispatcher();