Command (JGUIraffe BOM 1.3.1 API)

All Known Implementing Classes:

BgTaskCommand, CommandBase, CommandWrapper, CreateFileCommand, CreateViewSettingsCommand, OpenViewSettingsDlgCommand, OpenWindowCommand
```
public interface Command
```
Definition of an interface for command objects.

This interface is a typical application of the famous Command pattern. It allows constructing objects that can be executed in a worker thread in the background of a Java GUI (e.g. Swing) application. This is important for every longer running task that would block the whole GUI (i.e. the event dispatch thread) otherwise. The life-cycle of a Command object is a follows:

Objects implementing this interface can be passed to a CommandQueue object. When the CommandQueue object decides to execute the command it invokes its execute() method in a background thread. execute() can implement whatever logic is needed for the command. It can also throw an arbitrary exception. If an exception is thrown, the command's onException(Throwable) method is invoked (this also happens in the background thread). After completing execute() the onFinally() method is invoked (it does not matter whether an exception occurred or not; this method is always called), also in the background thread.

Command typically need to update the UI after executing their business logic. This must be done in the event dispatch thread. The Command interface supports updating the UI through its getGUIUpdater() method. Here an implementation can return a Runnable object that will be executed synchronously on the event dispatch thread; here arbitrary updates of the application's UI can be performed.

Version:

$Id: Command.java 205 2012-01-29 18:29:57Z oheger $

Author:

Oliver Heger

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`execute()` Executes this command.
`Runnable`	`getGUIUpdater()` This method is invoked after the background processing of the command ends.
`void`	`onException(Throwable t)` Callback method that is invoked if an exception occurs during command execution.
`void`	`onFinally()` This method will be executed after each command execution, no matter if an exception has occurred or not.

- Method Detail
  - execute
```
void execute()
      throws Exception
```
    Executes this command. Here the business logic of this command has to be implemented. The execute() method is invoked on a background thread so that the event dispatch thread of the application is not blocked.
    
    Throws:
    
    Exception - if an error occurs
  - onException
```
void onException(Throwable t)
```
    Callback method that is invoked if an exception occurs during command execution. If execute() throws an exception, this method is called (also on the background thread). Here actions like logging or special exception handling can be performed. Note that UI updates are not allowed in this method because it runs on a separate thread.
    
    Parameters:
    
    t - the exception that occurred
  - onFinally
```
void onFinally()
```
    This method will be executed after each command execution, no matter if an exception has occurred or not. It can be used for instance to free resources. Like execute() it is called on a background thread, so no UI updates are allowed.
  - getGUIUpdater
```
Runnable getGUIUpdater()
```
    This method is invoked after the background processing of the command ends. It can return a Runnable object that will be executed in the application's event dispatching thread, which means that it is allowed to update GUI widgets. The idea of this method is that after a command has been executed often GUI updates have to be performed. These can be done using this mechanism in a safe manner.
    
    Returns:
    
    an object to be executed in the event dispatching thread (may be null

Interface Command

Method Summary

Method Detail

execute

onException

onFinally

getGUIUpdater