Bug 570454 - Make EHanderService and ECommandService API official The following classes were made API: * EHanderService * ECommandService The bundle was updated to version 1.0.0 since API is published. IDE bundle updated to match the version range o.e.e4.ui.wb.addons.swt.test updated to match the version range Change-Id: Ie844d1f9b35ec4c732d001a62d6571ad55f09ad9 Reviewed-on: https://git.eclipse.org/r/c/platform/eclipse.platform.ui/+/175290 Tested-by: Platform Bot <platform-bot@eclipse.org> Tested-by: Wim Jongman <wim.jongman@remainsoftware.com> Reviewed-by: Wim Jongman <wim.jongman@remainsoftware.com> Reviewed-by: Lars Vogel <Lars.Vogel@vogella.com>
diff --git a/bundles/org.eclipse.e4.core.commands/.settings/.api_filters b/bundles/org.eclipse.e4.core.commands/.settings/.api_filters new file mode 100644 index 0000000..c70c7f1 --- /dev/null +++ b/bundles/org.eclipse.e4.core.commands/.settings/.api_filters
@@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<component id="org.eclipse.e4.core.commands" version="2"> + <resource path="META-INF/MANIFEST.MF"> + <filter comment="Bug 570454 - Make EHanderService and ECommandService API official" id="925892614"> + <message_arguments> + <message_argument value="1.0.0"/> + <message_argument value="0.13.0"/> + </message_arguments> + </filter> + </resource> +</component>
diff --git a/bundles/org.eclipse.e4.core.commands/META-INF/MANIFEST.MF b/bundles/org.eclipse.e4.core.commands/META-INF/MANIFEST.MF index 49bae55..c98f974 100644 --- a/bundles/org.eclipse.e4.core.commands/META-INF/MANIFEST.MF +++ b/bundles/org.eclipse.e4.core.commands/META-INF/MANIFEST.MF
@@ -4,7 +4,7 @@ Bundle-Name: %pluginName Bundle-Vendor: %providerName Bundle-Localization: plugin -Bundle-Version: 0.13.0.qualifier +Bundle-Version: 1.0.0.qualifier Bundle-RequiredExecutionEnvironment: JavaSE-11 Import-Package: javax.annotation, javax.inject;version="1.0.0", @@ -14,14 +14,7 @@ org.eclipse.e4.core.contexts, org.eclipse.e4.core.services.log, org.osgi.framework;version="1.5.0" -Export-Package: org.eclipse.e4.core.commands; - x-friends:="org.eclipse.e4.ui.bindings, - org.eclipse.e4.ui.workbench, - org.eclipse.e4.ui.workbench.renderers.swt, - org.eclipse.ui.workbench, - org.eclipse.e4.ui.workbench.swt, - org.eclipse.e4.ui.progress, - org.eclipse.e4.core.commands.tests", +Export-Package: org.eclipse.e4.core.commands, org.eclipse.e4.core.commands.internal;x-friends:="org.eclipse.e4.ui.bindings,org.eclipse.ui.workbench" Require-Bundle: org.eclipse.equinox.common;bundle-version="[3.6.0,4.0.0)", org.eclipse.e4.core.di;bundle-version="0.9.0"
diff --git a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/CommandServiceAddon.java b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/CommandServiceAddon.java index 1d0edbc..9874a88 100644 --- a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/CommandServiceAddon.java +++ b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/CommandServiceAddon.java
@@ -25,10 +25,12 @@ import org.eclipse.e4.core.contexts.IEclipseContext; /** - * Provide the command and handler service as an add-on. Must be instantiated against the - * application level context. + * Provide the command and handler service as an add-on. Must be instantiated + * against the application level context. * - * @noinstantiate + * @noinstantiate This class is not intended to be instantiated by clients. + * @noreference This class is not intended to be referenced by clients. + * @noextend This class is not intended to be subclassed by clients. */ public class CommandServiceAddon {
diff --git a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ECommandService.java b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ECommandService.java index 15e1d55..afa98d6 100644 --- a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ECommandService.java +++ b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ECommandService.java
@@ -21,7 +21,52 @@ import org.eclipse.core.commands.ParameterizedCommand; /** - * @noimplement + * This service allows access to the command subsystem. + * + * A <code>command</code> is an abstract notion of a user action like "copy" and + * "paste". A handler is an object that executes the actual code when the + * command is activated. + * + * <p> + * Many handlers may be associated with a command (e.g. "copy") because each + * handler typically only handles the command when in a specific context. An + * example of different contexts is the use of the "copy" command in a text + * editor versus in a table. In each case the command is the same, but the code + * to handle the case in that context is very different. + * <p> + * You should not implement this service, an implementation is provided by + * Eclipse. + * <p> + * It is usually not needed to use this service in your programs because command + * creation is done by Eclipse using the application model. However, in some + * cases it may be needed to programmatically create commands, or activate a + * handler using the <code>EHandlerService</code> + * <p> + * Example usage: + * + * <pre> + * <code> + * @inject ECommandService cs; + * @inject EHandlerService hs; + * + * Command command = cs.getCommand(commandId); + * if (command.isDefined()) { + * Map<String, Object> parameters = new HashMap<String, Object>(); + * parameters.put("parm1", "hello, world"); + * ParameterizedCommand parmCmd = cs.createCommand(commandId, parameters); + * if (hs.canExecute(parmCmd)) { + * hs.executeHandler(parmCmd); + * } + * else {logger.error("Cannot execute command");} + * } + * else {logger.error("Command is not defined");} + * </code> + * </pre> + * + * @since 1.0 + * @see EHandlerService + * @noimplement This interface is not intended to be implemented by clients. + * @noextend This interface is not intended to be extended by clients. */ public interface ECommandService { /**
diff --git a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/EHandlerService.java b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/EHandlerService.java index f4e3936..e017d05 100644 --- a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/EHandlerService.java +++ b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/EHandlerService.java
@@ -17,16 +17,94 @@ import org.eclipse.e4.core.contexts.IEclipseContext; /** - * @noimplement + * This service enables actions on handlers. + * + * A handler is an object which has methods that are annotated with + * <code>@CanExecute</code> (optional) and <code>@Execute</code>. A handler is + * associated with a <code>Command</code> which is an abstract notion of a user + * action like "copy" and "paste". + * <p> + * Many handlers may be associated with a command (e.g. "copy") because each + * handler typically only handles the command when in a specific context. + * <p> + * An example of different contexts, is the use of the "copy" command in a text + * editor versus in a table. In every case the command is the same, but the code + * executed is very different. + * <p> + * You should not implement this interface, an implementation is provided by + * Eclipse. + * <p> + * It is usually not needed to use this service in your programs because handler + * activation is done by Eclipse using binding contexts that are evaluated when + * a part is made active. Execution is done by Eclipse when a user presses a + * button or uses a context menu. However, in some cases it may be needed to + * programmatically manipulate handler activation, or execute the handler that + * is active for a give command. + * <p> + * Example usage: + * + * <pre> + * <code> + * @inject ECommandService cs; + * @inject EHandlerService hs; + * + * Command command = cs.getCommand(commandId); + * if (command.isDefined()) { + * Map<String, Object> parameters = new HashMap<String, Object>(); + * parameters.put("parm1", "hello, world"); + * ParameterizedCommand parmCmd = cs.createCommand(commandId, parameters); + * if (hs.canExecute(parmCmd)) { + * hs.executeHandler(parmCmd); + * } + * else {logger.error("Cannot execute command");} + * } + * else {logger.error("Command is not defined");} + * </code> + * </pre> + * + * @see ECommandService + * @since 1.0 + * @noimplement This interface is not intended to be implemented by clients. + * @noextend This interface is not intended to be extended by clients. */ public interface EHandlerService { + /** + * Makes the passed <code>handler</code> active for the command with the passed + * <code>commandId</code>. + * + * @param commandId Must not be <code>null</code> + * @param handler Must not be <code>null</code> + * + */ public void activateHandler(String commandId, Object handler); + /** + * Deactivates the passed <code>handler</code> from the command with the passed + * id. + * + * @param commandId Must not be <code>null</code> + * @param handler Must not be <code>null</code> + */ public void deactivateHandler(String commandId, Object handler); + /** + * Executes the active handler of the passed <code>command</code>. + * + * @param command Must not be <code>null</code> + * + * @return the return value of the handler, could be null + */ public Object executeHandler(ParameterizedCommand command); + /** + * Tests if the active handler associated with the passed <code>command</code> + * can be executed. + * + * @param command Must not be <code>null</code> + * @return true of the handler can be executed, false if it cannot be executed + * or if no handler is active for the passed command. + */ public boolean canExecute(ParameterizedCommand command); /**
diff --git a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ExpressionContext.java b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ExpressionContext.java index ad045ff..eff2770 100644 --- a/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ExpressionContext.java +++ b/bundles/org.eclipse.e4.core.commands/src/org/eclipse/e4/core/commands/ExpressionContext.java
@@ -21,8 +21,9 @@ import org.eclipse.e4.core.contexts.IEclipseContext; /** - * @noreference - * @since 1.0 + * @noinstantiate This class is not intended to be instantiated by clients. + * @noreference This class is not intended to be referenced by clients. + * @noextend This class is not intended to be subclassed by clients. */ public class ExpressionContext implements IEvaluationContext { /**
diff --git a/bundles/org.eclipse.ui.ide/META-INF/MANIFEST.MF b/bundles/org.eclipse.ui.ide/META-INF/MANIFEST.MF index 4ced099..cdeda4f 100644 --- a/bundles/org.eclipse.ui.ide/META-INF/MANIFEST.MF +++ b/bundles/org.eclipse.ui.ide/META-INF/MANIFEST.MF
@@ -63,7 +63,7 @@ org.eclipse.e4.core.services;bundle-version="2.0.0", org.eclipse.e4.core.contexts;bundle-version="[1.3.100,2.0.0)", org.eclipse.e4.ui.workbench;bundle-version="[1.3.0,2.0.0)", - org.eclipse.e4.core.commands;bundle-version="[0.11.0,1.0.0)", + org.eclipse.e4.core.commands;bundle-version="1.0.0", org.eclipse.e4.ui.model.workbench;bundle-version="[2.0.0,3.0.0)", org.eclipse.e4.ui.ide;bundle-version="[3.15.0,4.0.0)";visibility:=reexport, org.eclipse.e4.core.di;bundle-version="[1.6.0,2.0.0)",
diff --git a/tests/org.eclipse.e4.ui.workbench.addons.swt.test/META-INF/MANIFEST.MF b/tests/org.eclipse.e4.ui.workbench.addons.swt.test/META-INF/MANIFEST.MF index 398488e..df9256d 100644 --- a/tests/org.eclipse.e4.ui.workbench.addons.swt.test/META-INF/MANIFEST.MF +++ b/tests/org.eclipse.e4.ui.workbench.addons.swt.test/META-INF/MANIFEST.MF
@@ -7,7 +7,7 @@ Fragment-Host: org.eclipse.e4.ui.workbench.addons.swt;bundle-version="[1.1.0,2.0.0)" Bundle-RequiredExecutionEnvironment: JavaSE-11 Require-Bundle: org.junit;bundle-version="[4.12.0,5.0.0)", - org.eclipse.e4.core.commands;bundle-version="[0.10.2,1.0.0)", + org.eclipse.e4.core.commands;bundle-version="[1.0.0,2.0.0)", org.eclipse.core.databinding.observable;bundle-version="[1.4.0,2.0.0)", org.eclipse.jface.databinding;bundle-version="[1.6.200,2.0.0)", org.eclipse.e4.ui.workbench.swt;bundle-version="[0.12.100,1.0.0)"