Eclipse Platform
Release 3.1

org.eclipse.core.commands
Class Command

java.lang.Object
  extended byorg.eclipse.core.commands.common.HandleObject
      extended byorg.eclipse.core.commands.common.NamedHandleObject
          extended byorg.eclipse.core.commands.Command
All Implemented Interfaces:
Comparable

public final class Command
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.
 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, IParameter[] parameters)
           Defines this command by giving it a name, and possibly a description as well.
 boolean equals(Object object)
          Tests whether this command is equal to another object.
 Object execute(ExecutionEvent event)
          Executes this command by delegating to the current handler, if any.
 Category getCategory()
          Returns the category for this command.
 IParameter[] getParameters()
          Returns the parameters for this command.
 boolean isEnabled()
          Returns whether this command has a handler, and whether this handler is also handled.
 boolean isHandled()
          Returns whether this command has a handler, and whether this handler is also enabled.
 void removeCommandListener(ICommandListener commandListener)
          Removes a listener from this command.
 void removeExecutionListener(IExecutionListener executionListener)
          Removes a listener from this command.
 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 scheme become undefined.
 
Methods inherited from class org.eclipse.core.commands.common.NamedHandleObject
getDescription, getName
 
Methods inherited from class org.eclipse.core.commands.common.HandleObject
getId, hashCode, isDefined
 
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.

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,
                         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; may be null.
parameters - The parameters understood by this command. This value may be either null or empty if the command does not accept parameters.

equals

public final boolean equals(Object object)
Tests whether this command is equal to another object. A command is only equal to another command with the same parameters.

Specified by:
equals in class HandleObject
Parameters:
object - The object with which to compare; may be null.
Returns:
true if the commands are equal; false otherwise.

execute

public final Object execute(ExecutionEvent event)
                     throws ExecutionException,
                            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.

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.

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.

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.

isEnabled

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

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

isHandled

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

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.

setHandler

public final boolean setHandler(IHandler handler)
Changes the handler for this command. 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 scheme become undefined. This has the side effect of changing the name and description to null. Notification is sent to all listeners.

Specified by:
undefine in class HandleObject

Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.