Eclipse Platform Release 3.7

## org.eclipse.core.commands
Class CommandManager

    java.lang.Object
      org.eclipse.core.commands.common.EventManager
          org.eclipse.core.commands.common.HandleObjectManager
              org.eclipse.core.commands.CommandManager

All Implemented Interfaces:
  ICategoryListener, ICommandListener, IParameterTypeListener

    public final class CommandManager

extends HandleObjectManager
implements ICategoryListener, ICommandListener, IParameterTypeListener

A central repository for commands -- both in the defined and undefined states. Commands can be created and retrieved using this manager. It is possible to listen to changes in the collection of commands by attaching a listener to the manager.

Since:
  3.1
See Also:
  `getCommand(String)`

Field Summary
`static String` `AUTOGENERATED_CATEGORY_ID` The identifier of the category in which all auto-generated commands will appear.

Fields inherited from class org.eclipse.core.commands.common.HandleObjectManager
`definedHandleObjects, handleObjectsById`

Constructor Summary
`CommandManager()`

Method Summary
`void` `addCommandManagerListener(ICommandManagerListener listener)` Adds a listener to this command manager.
`void` `addExecutionListener(IExecutionListener listener)` Adds an execution listener to this manager.
`void` `categoryChanged(CategoryEvent categoryEvent)` Notifies that one or more properties of an instance of `Category` have changed.
`void` `commandChanged(CommandEvent commandEvent)` Notifies that one or more properties of an instance of `Command` have changed.
`void` `defineUncategorizedCategory(String name, String description)` Sets the name and description of the category for uncategorized commands.
`ParameterizedCommand` `deserialize(String serializedParameterizedCommand)` Returns a `ParameterizedCommand` with a command and parameterizations as specified in the provided `serializedParameterizedCommand` string.
`void` `fireNotDefined(String commandId, NotDefinedException exception)` Fires the `notDefined` event for `executionListeners`.
`void` `fireNotEnabled(String commandId, NotEnabledException exception)` Fires the `notEnabled` event for `executionListeners`.
`void` `firePostExecuteFailure(String commandId, ExecutionException exception)` Fires the `postExecuteFailure` event for `executionListeners`.
`void` `firePostExecuteSuccess(String commandId, Object returnValue)` Fires the `postExecuteSuccess` event for `executionListeners`.
`void` `firePreExecute(String commandId, ExecutionEvent event)` Fires the `preExecute` event for `executionListeners`.
`Command[]` `getAllCommands()` Returns all of the commands known by this manager -- defined and undefined.
`Category` `getCategory(String categoryId)` Gets the category with the given identifier.
`Command` `getCommand(String commandId)` Gets the command with the given identifier.
`Category[]` `getDefinedCategories()` Returns the categories that are defined.
`Set` `getDefinedCategoryIds()` Returns the set of identifiers for those category that are defined.
`Set` `getDefinedCommandIds()` Returns the set of identifiers for those commands that are defined.
`Command[]` `getDefinedCommands()` Returns the commands that are defined.
`Set` `getDefinedParameterTypeIds()` Returns the set of identifiers for those parameter types that are defined.
`ParameterType[]` `getDefinedParameterTypes()` Returns the command parameter types that are defined.
`String` `getHelpContextId(Command command)` Gets the help context identifier for a particular command.
`ParameterType` `getParameterType(String parameterTypeId)` Gets the command `ParameterType` with the given identifier.
`void` `parameterTypeChanged(ParameterTypeEvent parameterTypeEvent)` Notifies that one or more properties of an instance of `ParameterType` have changed.
`void` `removeCommandManagerListener(ICommandManagerListener listener)` Removes a listener from this command manager.
`void` `removeExecutionListener(IExecutionListener listener)` Removes an execution listener from this command manager.
`void` `setHandlersByCommandId(Map handlersByCommandId)` Block updates all of the handlers for all of the commands.
`void` `setHelpContextId(IHandler handler, String helpContextId)` Sets the help context identifier to associate with a particular handler.

Methods inherited from class org.eclipse.core.commands.common.HandleObjectManager
`checkId, getDefinedHandleObjectIds`

Methods inherited from class org.eclipse.core.commands.common.EventManager
`addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### AUTOGENERATED_CATEGORY_ID

    public static final String AUTOGENERATED_CATEGORY_ID

  The identifier of the category in which all auto-generated commands will appear. This value must never be `null`.

  Since:
    3.2
  See Also:
    Constant Field Values

Constructor Detail

### CommandManager

    public CommandManager()

Method Detail

### addCommandManagerListener

    public final void addCommandManagerListener(ICommandManagerListener listener)

  Adds a listener to this command manager. The listener will be notified when the set of defined commands changes. This can be used to track the global appearance and disappearance of commands.

  Parameters:
    `listener` - The listener to attach; must not be `null`.

### addExecutionListener

    public final void addExecutionListener(IExecutionListener listener)

  Adds an execution listener to this manager. This listener will be notified if any of the commands controlled by this manager execute. This can be used to support macros and instrumentation of commands.

  Parameters:
    `listener` - The listener to attach; must not be `null`.

### categoryChanged

    public final void categoryChanged(CategoryEvent categoryEvent)

  Description copied from interface: `ICategoryListener`
  Notifies that one or more properties of an instance of `Category` have changed. Specific details are described in the `CategoryEvent`.

  Specified by:
    `categoryChanged` in interface `ICategoryListener`
  Parameters:
    `categoryEvent` - the category event. Guaranteed not to be `null`.

### commandChanged

    public final void commandChanged(CommandEvent commandEvent)

  Description copied from interface: `ICommandListener`
  Notifies that one or more properties of an instance of `Command` have changed. Specific details are described in the `CommandEvent`.

  Specified by:
    `commandChanged` in interface `ICommandListener`
  Parameters:
    `commandEvent` - the command event. Guaranteed not to be `null`.

### defineUncategorizedCategory

    public final void defineUncategorizedCategory(String name,
                                                  String description)

  Sets the name and description of the category for uncategorized commands. This is the category that will be returned if `getCategory(String)` is called with `null`.

  Parameters:
    `name` - The name of the category for uncategorized commands; must not be `null`.
    `description` - The description of the category for uncategorized commands; may be `null`.
  Since:
    3.2

### deserialize

    public final ParameterizedCommand deserialize(String serializedParameterizedCommand)
                                           throws NotDefinedException,
                                                  SerializationException

  Returns a `ParameterizedCommand` with a command and parameterizations as specified in the provided `serializedParameterizedCommand` string. The `serializedParameterizedCommand` must use the format returned by `ParameterizedCommand.serialize()` and described in the Javadoc for that method.

  If a parameter id encoded in the `serializedParameterizedCommand` does not exist in the encoded command, that parameter id and value are ignored. A given parameter id should not be used more than once in `serializedParameterizedCommand`. This will not result in an exception, but in this case the value of the parameter when the command is executed is unspecified.

  This method will never return `null`, however it may throw an exception if there is a problem processing the serialization string or the encoded command is undefined.

  Parameters:
    `serializedParameterizedCommand` - a string representing a command id and parameter ids and values; must not be `null`
  Returns:
    a `ParameterizedCommand` with the command and parameterizations encoded in the `serializedParameterizedCommand`; never `null`.
  Throws:
    `NotDefinedException` - if the command indicated in `serializedParameterizedCommand` is not defined
    `SerializationException` - if there is an error deserializing `serializedParameterizedCommand`
  Since:
    3.2
  See Also:
    `ParameterizedCommand.serialize()`

### getAllCommands

    public final Command[] getAllCommands()

  Returns all of the commands known by this manager -- defined and undefined.

  Returns:
    All of the commands; may be empty, but never `null`.
  Since:
    3.2

### getCategory

    public final Category getCategory(String categoryId)

  Gets the category with the given identifier. If no such category currently exists, then the category will be created (but be undefined).

  Parameters:
    `categoryId` - The identifier to find; must not be `null`. If the category is `null`, then a category suitable for uncategorized items is defined and returned.
  Returns:
    The category with the given identifier; this value will never be `null`, but it might be undefined.
  See Also:
    `Category`

### getCommand

    public final Command getCommand(String commandId)

  Gets the command with the given identifier. If no such command currently exists, then the command will be created (but will be undefined).

  Parameters:
    `commandId` - The identifier to find; must not be `null` and must not be zero-length.
  Returns:
    The command with the given identifier; this value will never be `null`, but it might be undefined.
  See Also:
    `Command`

### getDefinedCategories

    public final Category[] getDefinedCategories()

  Returns the categories that are defined.

  Returns:
    The defined categories; this value may be empty, but it is never `null`.
  Since:
    3.2

### getDefinedCategoryIds

    public final Set getDefinedCategoryIds()

  Returns the set of identifiers for those category that are defined.

  Returns:
    The set of defined category identifiers; this value may be empty, but it is never `null`.

### getDefinedCommandIds

    public final Set getDefinedCommandIds()

  Returns the set of identifiers for those commands that are defined.

  Returns:
    The set of defined command identifiers; this value may be empty, but it is never `null`.

### getDefinedCommands

    public final Command[] getDefinedCommands()

  Returns the commands that are defined.

  Returns:
    The defined commands; this value may be empty, but it is never `null`.
  Since:
    3.2

### getDefinedParameterTypeIds

    public final Set getDefinedParameterTypeIds()

  Returns the set of identifiers for those parameter types that are defined.

  Returns:
    The set of defined command parameter type identifiers; this value may be empty, but it is never `null`.
  Since:
    3.2

### getDefinedParameterTypes

    public final ParameterType[] getDefinedParameterTypes()

  Returns the command parameter types that are defined.

  Returns:
    The defined command parameter types; this value may be empty, but it is never `null`.
  Since:
    3.2

### getHelpContextId

    public final String getHelpContextId(Command command)
                                  throws NotDefinedException

  Gets the help context identifier for a particular command. The command's handler is first checked for a help context identifier. If the handler does not have a help context identifier, then the help context identifier for the command is returned. If neither has a help context identifier, then `null` is returned.

  Parameters:
    `command` - The command for which the help context should be retrieved; must not be `null`.
  Returns:
    The help context identifier to use for the given command; may be `null`.
  Throws:
    `NotDefinedException` - If the given command is not defined.
  Since:
    3.2

### getParameterType

    public final ParameterType getParameterType(String parameterTypeId)

  Gets the command `ParameterType` with the given identifier. If no such command parameter type currently exists, then the command parameter type will be created (but will be undefined).

  Parameters:
    `parameterTypeId` - The identifier to find; must not be `null` and must not be zero-length.
  Returns:
    The `ParameterType` with the given identifier; this value will never be `null`, but it might be undefined.
  Since:
    3.2

### parameterTypeChanged

    public final void parameterTypeChanged(ParameterTypeEvent parameterTypeEvent)

  Notifies that one or more properties of an instance of `ParameterType` have changed. Specific details are described in the `ParameterTypeEvent`.

  Specified by:
    `parameterTypeChanged` in interface `IParameterTypeListener`
  Parameters:
    `parameterTypeEvent` - the event. Guaranteed not to be `null`.
  Since:
    3.2

### removeCommandManagerListener

    public final void removeCommandManagerListener(ICommandManagerListener listener)

  Removes a listener from this command manager.

  Parameters:
    `listener` - The listener to be removed; must not be `null`.

### removeExecutionListener

    public final void removeExecutionListener(IExecutionListener listener)

  Removes an execution listener from this command manager.

  Parameters:
    `listener` - The listener to be removed; must not be `null`.

### setHandlersByCommandId

    public final void setHandlersByCommandId(Map handlersByCommandId)

  Block updates all of the handlers for all of the commands. If the handler is `null` or the command id does not exist in the map, then the command becomes unhandled. Otherwise, the handler is set to the corresponding value in the map.

  Parameters:
    `handlersByCommandId` - A map of command identifiers (`String`) to handlers (`IHandler`). This map may be `null` if all handlers should be cleared. Similarly, if the map is empty, then all commands will become unhandled.

### setHelpContextId

    public final void setHelpContextId(IHandler handler,
                                       String helpContextId)

  Sets the help context identifier to associate with a particular handler.

  Parameters:
    `handler` - The handler with which to register a help context identifier; must not be `null`.
    `helpContextId` - The help context identifier to register; may be `null` if the help context identifier should be removed.
  Since:
    3.2

### fireNotEnabled

    public void fireNotEnabled(String commandId,
                               NotEnabledException exception)

  Fires the `notEnabled` event for `executionListeners`.

  Note: This supports bridging actions to the command framework, and should not be used outside the framework.

  Parameters:
    `commandId` - The command id of the command about to execute, never `null`.
    `exception` - The exception, never `null`.
  Since:
    3.4

### fireNotDefined

    public void fireNotDefined(String commandId,
                               NotDefinedException exception)

  Fires the `notDefined` event for `executionListeners`.

  Note: This supports bridging actions to the command framework, and should not be used outside the framework.

  Parameters:
    `commandId` - The command id of the command about to execute, never `null`.
    `exception` - The exception, never `null`.
  Since:
    3.4

### firePreExecute

    public void firePreExecute(String commandId,
                               ExecutionEvent event)

  Fires the `preExecute` event for `executionListeners`.

  Note: This supports bridging actions to the command framework, and should not be used outside the framework.

  Parameters:
    `commandId` - The command id of the command about to execute, never `null`.
    `event` - The event that triggered the command, may be `null`.
  Since:
    3.4

### firePostExecuteSuccess

    public void firePostExecuteSuccess(String commandId,
                                       Object returnValue)

  Fires the `postExecuteSuccess` event for `executionListeners`.

  Note: This supports bridging actions to the command framework, and should not be used outside the framework.

  Parameters:
    `commandId` - The command id of the command executed, never `null`.
    `returnValue` - The value returned from the command, may be `null`.
  Since:
    3.4

### firePostExecuteFailure

    public void firePostExecuteFailure(String commandId,
                                       ExecutionException exception)

  Fires the `postExecuteFailure` event for `executionListeners`.

  Note: This supports bridging actions to the command framework, and should not be used outside the framework.

  Parameters:
    `commandId` - The command id of the command executed, never `null`.
    `exception` - The exception, never `null`.
  Since:
    3.4

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.