Eclipse Plug-in Developer Guide (Galileo) - Command (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.core.commands
Class Command


java.lang.Object
  

org.eclipse.core.commands.common.EventManager
      

org.eclipse.core.commands.common.HandleObject
          

org.eclipse.core.commands.common.NamedHandleObject
              
org.eclipse.core.commands.Command

All Implemented Interfaces:: Comparable, IIdentifiable, IObjectWithState

public final class Command
extends NamedHandleObject
implements Comparable
extends NamedHandleObject
implements Comparable

A command is an abstract representation for some semantic behaviour. It is not the actual implementation of this behaviour, nor is it the visual appearance of this behaviour in the user interface. Instead, it is a bridge between the two.

The concept of a command is based on the command design pattern. The notable difference is how the command delegates responsibility for execution. Rather than allowing concrete subclasses, it uses a handler mechanism (see the handlers extension point). This provides another level of indirection.

A command will exist in two states: defined and undefined. A command is defined if it is declared in the XML of a resolved plug-in. If the plug-in is unloaded or the command is simply not declared, then it is undefined. Trying to reference an undefined command will succeed, but trying to access any of its functionality will fail with a NotDefinedException. If you need to know when a command changes from defined to undefined (or vice versa), then attach a command listener.

Commands are mutable and will change as their definition changes.

Since:: 3.1

Field Summary

static boolean DEBUG_COMMAND_EXECUTION
          This flag can be set to true if commands should print information to System.out when executing.

static boolean DEBUG_HANDLERS
          This flag can be set to true if commands should print information to System.out when changing handlers.

static String DEBUG_HANDLERS_COMMAND_ID
          This flag can be set to a particular command identifier if only that command should print information to System.out when changing handlers.

Fields inherited from class org.eclipse.core.commands.common. NamedHandleObject

description, name

Fields inherited from class org.eclipse.core.commands.common. HandleObject

defined, id, string

Method Summary

void addCommandListener ( ICommandListener commandListener)
          Adds a listener to this command that will be notified when this command's state changes.

void addExecutionListener ( IExecutionListener executionListener)
          Adds a listener to this command that will be notified when this command is about to execute.

void addState ( String id, State state)
           Adds a state to this command.

int compareTo ( Object object)
          Compares this command with another command by comparing each of its non-transient attributes.

void define ( String name, String description, Category category)
           Defines this command by giving it a name, and possibly a description as well.

void define ( String name, String description, Category category, IParameter[] parameters)
           Defines this command by giving it a name, and possibly a description as well.

void define ( String name, String description, Category category, IParameter[] parameters, ParameterType returnType)
           Defines this command by giving it a name, and possibly a description as well.

void define ( String name, String description, Category category, IParameter[] parameters, ParameterType returnType, String helpContextId)
           Defines this command by giving it a name, and possibly a description as well.

Object execute ( ExecutionEvent event)
          Deprecated. Please use executeWithChecks(ExecutionEvent) instead.

Object executeWithChecks ( ExecutionEvent event)
          Executes this command by delegating to the current handler, if any.

Category getCategory ()
          Returns the category for this command.

String getDescription ()
          Returns the description for this handle.

IHandler getHandler ()
          Returns the current handler for this command.

String getName ()
          Returns the name for this handle.

IParameter getParameter ( String parameterId)
          Returns the parameter with the provided id or null if this command does not have a parameter with the id.

IParameter[] getParameters ()
          Returns the parameters for this command.

ParameterType getParameterType ( String parameterId)
          Returns the ParameterType for the parameter with the provided id or null if this command does not have a parameter type with the id.

ParameterType getReturnType ()
          Returns the ParameterType for the return value of this command or null if this command does not declare a return value parameter type.

State getState ( String stateId)
          Gets the state with the given id.

String[] getStateIds ()
          Gets the identifiers for all of the state associated with this object.

boolean isEnabled ()
          Returns whether this command has a handler, and whether this handler is also handled and enabled.

boolean isHandled ()
          Returns whether this command has a handler, and whether this handler is also handled.

void removeCommandListener ( ICommandListener commandListener)
          Removes a listener from this command.

void removeExecutionListener ( IExecutionListener executionListener)
          Removes a listener from this command.

void removeState ( String stateId)
           Removes a state from this command.

void setEnabled ( Object evaluationContext)
          Called be the framework to allow the handler to update its enabled state.

boolean setHandler ( IHandler handler)
          Changes the handler for this command.

String toString ()
          The string representation of this command -- for debugging purposes only.

void undefine ()
          Makes this command become undefined.

Methods inherited from class org.eclipse.core.commands.common. HandleObject

equals, getId, hashCode, isDefined

Methods inherited from class org.eclipse.core.commands.common. EventManager

addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject

Methods inherited from class java.lang. Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEBUG_COMMAND_EXECUTION

public static boolean DEBUG_COMMAND_EXECUTION

This flag can be set to true if commands should print information to System.out when executing.

DEBUG_HANDLERS

public static boolean DEBUG_HANDLERS

This flag can be set to true if commands should print information to System.out when changing handlers.

DEBUG_HANDLERS_COMMAND_ID

public static 
String DEBUG_HANDLERS_COMMAND_ID

This flag can be set to a particular command identifier if only that command should print information to System.out when changing handlers.

Method Detail

addCommandListener

public final void addCommandListener(
ICommandListener commandListener)

Adds a listener to this command that will be notified when this command's state changes.

Parameters:: commandListener - The listener to be added; must not be null.

addExecutionListener

public final void addExecutionListener(
IExecutionListener executionListener)

Adds a listener to this command that will be notified when this command is about to execute.

Parameters:: executionListener - The listener to be added; must not be null.

addState

public void addState(
String id,
                     
State state)

Adds a state to this command. This will add this state to the active handler, if the active handler is an instance of IObjectWithState.

A single instance of State cannot be registered with multiple commands. Each command requires its own unique instance.

Specified by:: addState in interface IObjectWithState

Parameters:: id - The identifier of the state to add; must not be null.; state - The state to add; must not be null.
Since:: 3.2

compareTo

public final int compareTo(
Object object)

Compares this command with another command by comparing each of its non-transient attributes.

Specified by:: compareTo in interface Comparable

Parameters:: object - The object with which to compare; must be an instance of Command.
Returns:: A negative integer, zero or a postivie integer, if the object is greater than, equal to or less than this command.

define

public final void define(
String name,
                         
String description,
                         
Category category)

Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes true.

Notification is sent to all listeners that something has changed.

Parameters:: name - The name of this command; must not be null.; description - The description for this command; may be null.; category - The category for this command; must not be null.
Since:: 3.2

define

public final void define(
String name,
                         
String description,
                         
Category category,
                         
IParameter[] parameters)

Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes true.

Notification is sent to all listeners that something has changed.

Parameters:: name - The name of this command; must not be null.; description - The description for this command; may be null.; category - The category for this command; must not be null.; parameters - The parameters understood by this command. This value may be either null or empty if the command does not accept parameters.

define

public final void define(
String name,
                         
String description,
                         
Category category,
                         
IParameter[] parameters,
                         
ParameterType returnType)

Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes true.

Notification is sent to all listeners that something has changed.

Parameters:: name - The name of this command; must not be null.; description - The description for this command; may be null.; category - The category for this command; must not be null.; parameters - The parameters understood by this command. This value may be either null or empty if the command does not accept parameters.; returnType - The type of value returned by this command. This value may be null if the command does not declare a return type.
Since:: 3.2

define

public final void define(
String name,
                         
String description,
                         
Category category,
                         
IParameter[] parameters,
                         
ParameterType returnType,
                         
String helpContextId)

Defines this command by giving it a name, and possibly a description as well. The defined property automatically becomes true.

Notification is sent to all listeners that something has changed.

Parameters:: name - The name of this command; must not be null.; description - The description for this command; may be null.; category - The category for this command; must not be null.; parameters - The parameters understood by this command. This value may be either null or empty if the command does not accept parameters.; returnType - The type of value returned by this command. This value may be null if the command does not declare a return type.; helpContextId - The identifier of the help context to associate with this command; may be null if this command does not have any help associated with it.
Since:: 3.2

execute

public final 
Object execute(
ExecutionEvent event)
                     throws 
ExecutionException,
                            
NotHandledException

Deprecated. Please use executeWithChecks(ExecutionEvent) instead.

Executes this command by delegating to the current handler, if any. If the debugging flag is set, then this method prints information about which handler is selected for performing this command. This method will succeed regardless of whether the command is enabled or defined. It is generally preferred to call executeWithChecks(ExecutionEvent).

Parameters:: event - An event containing all the information about the current state of the application; must not be null.
Returns:: The result of the execution; may be null. This result will be available to the client executing the command, and execution listeners.
Throws:: ExecutionException - If the handler has problems executing this command.; NotHandledException - If there is no handler.

executeWithChecks

public final 
Object executeWithChecks(
ExecutionEvent event)
                               throws 
ExecutionException,
                                      
NotDefinedException,
                                      
NotEnabledException,
                                      
NotHandledException

Executes this command by delegating to the current handler, if any. If the debugging flag is set, then this method prints information about which handler is selected for performing this command. This does checks to see if the command is enabled and defined. If it is not both enabled and defined, then the execution listeners will be notified and an exception thrown.

Parameters:: event - An event containing all the information about the current state of the application; must not be null.
Returns:: The result of the execution; may be null. This result will be available to the client executing the command, and execution listeners.
Throws:: ExecutionException - If the handler has problems executing this command.; NotDefinedException - If the command you are trying to execute is not defined.; NotEnabledException - If the command you are trying to execute is not enabled.; NotHandledException - If there is no handler.
Since:: 3.2

getCategory

public final 
Category getCategory()
                           throws 
NotDefinedException

Returns the category for this command.

Returns:: The category for this command; never null.
Throws:: NotDefinedException - If the handle is not currently defined.

getHandler

public final 
IHandler getHandler()

Returns the current handler for this command. This is used by the command manager for determining the appropriate help context identifiers and by the command service to allow handlers to update elements.

This value can change at any time and should never be cached.

Returns:: The current handler for this command; may be null.
Since:: 3.3

getParameter

public final 
IParameter getParameter(
String parameterId)
                              throws 
NotDefinedException

Returns the parameter with the provided id or null if this command does not have a parameter with the id.

Parameters:: parameterId - The id of the parameter to retrieve.
Returns:: The parameter with the provided id or null if this command does not have a parameter with the id.
Throws:: NotDefinedException - If the handle is not currently defined.
Since:: 3.2

getParameters

public final 
IParameter[] getParameters()
                                 throws 
NotDefinedException

Returns the parameters for this command. This call triggers provides a copy of the array, so excessive calls to this method should be avoided.

Returns:: The parameters for this command. This value might be null, if the command has no parameters.
Throws:: NotDefinedException - If the handle is not currently defined.

getParameterType

public final 
ParameterType getParameterType(
String parameterId)
                                     throws 
NotDefinedException

Returns the ParameterType for the parameter with the provided id or null if this command does not have a parameter type with the id.

Parameters:: parameterId - The id of the parameter to retrieve the ParameterType of.
Returns:: The ParameterType for the parameter with the provided id or null if this command does not have a parameter type with the provided id.
Throws:: NotDefinedException - If the handle is not currently defined.
Since:: 3.2

getReturnType

public final 
ParameterType getReturnType()
                                  throws 
NotDefinedException

Returns the ParameterType for the return value of this command or null if this command does not declare a return value parameter type.

Returns:: The ParameterType for the return value of this command or null if this command does not declare a return value parameter type.
Throws:: NotDefinedException - If the handle is not currently defined.
Since:: 3.2

isEnabled

public final boolean isEnabled()

Returns whether this command has a handler, and whether this handler is also handled and enabled.

Returns:: true if the command is handled; false otherwise.

setEnabled

public void setEnabled(
Object evaluationContext)

Called be the framework to allow the handler to update its enabled state.

Parameters:: evaluationContext - the state to evaluate against. May be null which indicates that the handler can query whatever model that is necessary. This context must not be cached.
Since:: 3.4

isHandled

public final boolean isHandled()

Returns whether this command has a handler, and whether this handler is also handled.

Returns:: true if the command is handled; false otherwise.

removeCommandListener

public final void removeCommandListener(
ICommandListener commandListener)

Removes a listener from this command.

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

removeExecutionListener

public final void removeExecutionListener(
IExecutionListener executionListener)

Removes a listener from this command.

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

removeState

public void removeState(
String stateId)

Removes a state from this command. This will remove the state from the active handler, if the active handler is an instance of IObjectWithState.

Specified by:: removeState in interface IObjectWithState

Parameters:: stateId - The identifier of the state to remove; must not be null.
Since:: 3.2

setHandler

public final boolean setHandler(
IHandler handler)

Changes the handler for this command. This will remove all the state from the currently active handler (if any), and add it to handler. If debugging is turned on, then this will also print information about the change to System.out.

Parameters:: handler - The new handler; may be null if none.
Returns:: true if the handler changed; false otherwise.

toString

public final 
String toString()

The string representation of this command -- for debugging purposes only. This string should not be shown to an end user.

Specified by:: toString in class HandleObject

Returns:: The string representation; never null.

undefine

public final void undefine()

Makes this command become undefined. This has the side effect of changing the name and description to null. This also removes all state and disposes of it. Notification is sent to all listeners.

Specified by:: undefine in class HandleObject

getDescription

public final 
String getDescription()
                            throws 
NotDefinedException

Description copied from class: NamedHandleObject

Returns the description for this handle.

Overrides:: getDescription in class NamedHandleObject

Returns:: The description; may be null if there is no description.
Throws:: NotDefinedException - If the handle is not currently defined.

getName

public final 
String getName()
                     throws 
NotDefinedException

Description copied from class: NamedHandleObject

Returns the name for this handle.

Overrides:: getName in class NamedHandleObject

Returns:: The name for this handle; never null.
Throws:: NotDefinedException - If the handle is not currently defined.

getState

public final 
State getState(
String stateId)

Description copied from interface: IObjectWithState

Gets the state with the given id.

Specified by:: getState in interface IObjectWithState

Parameters:: stateId - The identifier of the state to retrieve; must not be null.
Returns:: The state; may be null if there is no state with the given id.

getStateIds

public final 
String[] getStateIds()

Description copied from interface: IObjectWithState

Gets the identifiers for all of the state associated with this object.

Specified by:: getStateIds in interface IObjectWithState

Returns:: All of the state identifiers; may be empty, but never null.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.core.commands Class Command

DEBUG_COMMAND_EXECUTION

DEBUG_HANDLERS

DEBUG_HANDLERS_COMMAND_ID

addCommandListener

addExecutionListener

addState

compareTo

define

define

define

define

execute

executeWithChecks

getCategory

getHandler

getParameter

getParameters

getParameterType

getReturnType

isEnabled

setEnabled

isHandled

removeCommandListener

removeExecutionListener

removeState

setHandler

toString

undefine

getDescription

getName

getState

getStateIds

org.eclipse.core.commands
Class Command