Eclipse Platform
Release 3.6

org.eclipse.debug.core.commands
Class AbstractDebugCommand

java.lang.Object
  extended by org.eclipse.debug.core.commands.AbstractDebugCommand
All Implemented Interfaces:
IDebugCommandHandler

public abstract class AbstractDebugCommand
extends Object
implements IDebugCommandHandler

Abstract implementation of a debug command handler. Handles IDebugCommandRequest and IEnabledStateRequest updates asynchronously using jobs.

Clients may subclass this class.

Since:
3.6

Constructor Summary
AbstractDebugCommand()
           
 
Method Summary
 void canExecute(IEnabledStateRequest request)
          Determines whether this handler can execute on the elements specified in the given request by reporting enabled state to the request.
protected abstract  void doExecute(Object[] targets, IProgressMonitor monitor, IRequest request)
          Executes this command synchronously on the specified targets, reporting progress.
 boolean execute(IDebugCommandRequest request)
          Executes this command on the elements specified in the given request reporting status to the given request and returns whether this handler should remain enabled while the command is executing.
protected  Object getAdapter(Object element, Class type)
          Convenience method to return an adapter of the specified type for the given object or null if none.
protected  Object getEnabledStateJobFamily(IDebugCommandRequest request)
          Returns the job family for the this command's IEnabledStateRequest update job or null if none.
protected  ISchedulingRule getEnabledStateSchedulingRule(IDebugCommandRequest request)
          Returns a scheduling rule for this command's IEnabledStateRequest update job or null if none.
protected  String getEnabledStateTaskName()
          Returns the name to use for a job and progress monitor task names when performing an IEnabledStateRequest.
protected  Object getExecuteJobFamily(IDebugCommandRequest request)
          Returns the job family for the this command's IDebugCommandRequest execute job or null if none.
protected  ISchedulingRule getExecuteSchedulingRule(IDebugCommandRequest request)
          Returns a scheduling rule for this command's IDebugCommandRequest execute job or null if none.
protected  String getExecuteTaskName()
          Returns the name to use for jobs and progress monitor task names when executing an IDebugCommandRequest.
protected abstract  Object getTarget(Object element)
          Returns the appropriate target for this command handler for the given object.
protected abstract  boolean isExecutable(Object[] targets, IProgressMonitor monitor, IEnabledStateRequest request)
          Returns whether this command is executable on the specified targets, reporting progress.
protected  boolean isRemainEnabled(IDebugCommandRequest request)
          Returns whether this command should remain enabled after starting execution of the specified request.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractDebugCommand

public AbstractDebugCommand()
Method Detail

execute

public boolean execute(IDebugCommandRequest request)
Description copied from interface: IDebugCommandHandler
Executes this command on the elements specified in the given request reporting status to the given request and returns whether this handler should remain enabled while the command is executing.

Implementations must be non-blocking and may respond asynchronously to the given request. Errors can reported by setting an appropriate status on the given request. A request can be canceled by this handler or the caller. A null status is equivalent to an OK status. When a request is complete, has encountered an error, or canceled, implementations must call done() on the given collector.

Handlers are expected to poll the request (using isCanceled) periodically and abort at their earliest convenience calling done() on the request.

Specified by:
execute in interface IDebugCommandHandler
Parameters:
request - specifies elements to operate on and collects execution status
Returns:
whether this handler remains enabled while command is executing

isRemainEnabled

protected boolean isRemainEnabled(IDebugCommandRequest request)
Returns whether this command should remain enabled after starting execution of the specified request.

Parameters:
request - the request being executed
Returns:
whether to remain enabled while executing the request

canExecute

public void canExecute(IEnabledStateRequest request)
Description copied from interface: IDebugCommandHandler
Determines whether this handler can execute on the elements specified in the given request by reporting enabled state to the request.

Implementations must be non-blocking and may respond asynchronously to the given request. Errors can reported by setting an appropriate status on the given request. A request can be canceled by this handler or caller. A null status is equivalent to an OK status. When a request succeeds, fails, or is canceled, implementations must call done() on the given request.

Clients are expected to poll the request (using isCanceled) periodically and abort at their earliest convenience calling done() on the request.

Specified by:
canExecute in interface IDebugCommandHandler
Parameters:
request - specifies elements to operate on and collects enabled state

getEnabledStateTaskName

protected String getEnabledStateTaskName()
Returns the name to use for a job and progress monitor task names when performing an IEnabledStateRequest.

Returns:
task name

getExecuteTaskName

protected String getExecuteTaskName()
Returns the name to use for jobs and progress monitor task names when executing an IDebugCommandRequest.

Returns:
task name

doExecute

protected abstract void doExecute(Object[] targets,
                                  IProgressMonitor monitor,
                                  IRequest request)
                           throws CoreException
Executes this command synchronously on the specified targets, reporting progress. This method is called by a job. If an exception is thrown, the calling job will set the associated status on the request object. The calling job also calls #done() on the request object after this method is called, and sets a cancel status on the progress monitor if the request is canceled.

Handlers must override this method.

Parameters:
targets - objects to perform this command on
monitor - progress monitor
request - can be used to cancel this command
Throws:
CoreException - if this handler fails to perform the request

isExecutable

protected abstract boolean isExecutable(Object[] targets,
                                        IProgressMonitor monitor,
                                        IEnabledStateRequest request)
                                 throws CoreException
Returns whether this command is executable on the specified targets, reporting progress. This method is called by a job. If an exception is thrown, the calling job will set the associated status on the request object and report that this command is not enabled. The calling job also calls #done() on the request object after this method is called, and sets a cancel status on the progress monitor if the request is canceled. Enabled state is set to false if the request is canceled.

Handlers must override this method.

Parameters:
targets - objects to check command enabled state for
monitor - progress monitor
request - can be used to cancel this update request
Returns:
whether this command can be executed for the given targets
Throws:
CoreException

getTarget

protected abstract Object getTarget(Object element)
Returns the appropriate target for this command handler for the given object. This method is called to map each element in a command request to the target object that is used in doExecute(Object[], IProgressMonitor, IRequest) and isExecutable(Object[], IProgressMonitor, IEnabledStateRequest). The target may be the element itself, or some other object. Allows for redirection.

Clients must override this method.

Parameters:
element - element from a IDebugCommandRequest
Returns:
associated target object for execution or enabled state update. Cannot return null.

getAdapter

protected Object getAdapter(Object element,
                            Class type)
Convenience method to return an adapter of the specified type for the given object or null if none.

Parameters:
element - element to retrieve adapter for
type - adapter type
Returns:
adapter or null

getEnabledStateSchedulingRule

protected ISchedulingRule getEnabledStateSchedulingRule(IDebugCommandRequest request)
Returns a scheduling rule for this command's IEnabledStateRequest update job or null if none. By default a rule is created to serialize jobs on the first element in the request.

Clients may override this method as required.

Parameters:
request - request that a scheduling rule is required for
Returns:
scheduling rule or null

getExecuteSchedulingRule

protected ISchedulingRule getExecuteSchedulingRule(IDebugCommandRequest request)
Returns a scheduling rule for this command's IDebugCommandRequest execute job or null if none. By default, execution jobs have no scheduling rule.

Clients may override this method as required.

Parameters:
request - request that a scheduling rule is required for
Returns:
scheduling rule or null

getEnabledStateJobFamily

protected Object getEnabledStateJobFamily(IDebugCommandRequest request)
Returns the job family for the this command's IEnabledStateRequest update job or null if none. The default implementation returns null.

Clients may override this method as required.

Parameters:
request - request the job family is required for
Returns:
job family object or null if none

getExecuteJobFamily

protected Object getExecuteJobFamily(IDebugCommandRequest request)
Returns the job family for the this command's IDebugCommandRequest execute job or null if none. The default implementation returns null.

Clients may override this method as required.

Parameters:
request - request the job family is required for
Returns:
job family object or null if none

Eclipse Platform
Release 3.6

Guidelines for using Eclipse APIs.

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