talx.controller
Interface ActionHandler

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

BusyComposerHandler, BusyInboxHandler, ComposerHandler, ComposerHandler, ComposerHandler, InboxHandler, InboxHandler, InboxHandler, MixedComposerHandler, MixedInboxHandler, ReaderHandler, ReaderHandler

public interface ActionHandler

extends java.io.Serializable

Stateless objects to handle actions. Although the interface definition cannot specify this, the Thinkandlink specification requires that each ActionHandler implementation class also have a static, no argument getInstance() method that returns an object of that class's type. ActionHandlers are not allowed to be stateful, so no public constructors should be present. The only method for getting a new ActionHandler reference should be to call the getInstance() method on an implementation class.

Method Summary

boolean	canRun(GUIState state, Controller c) This method tells the controller whether the given handler will function in the given GUIState.
ActionHandler	handleAction(java.awt.event.ActionEvent ev, Controller c) Handles an action event and transitions to a new action handler.

Method Detail

handleAction

public ActionHandler handleAction(java.awt.event.ActionEvent ev,
                                  Controller c)
                           throws ActionVetoException

Handles an action event and transitions to a new action handler. If there is no need to switch action handlers, this method should return "this". If the handler determines that it cannot handle the event, it should fire an Illegal button click event and then throw an action veto exception.

If the GUIState changes as a result of the action, this method should call the controller's fireControllerChange method after setting the new state. Although a normal return from this method will trigger a controller change finished event, visual components are not required to listen for changes that were not introduced via controller change events.

It is also customary for handlers to "initialize" themselves and/or the controller when ev == null. The interpretation of initialization is left to the handler writer; however, handler classes that are used as initial handlers will be called with ev == null at system start-up. Classes that cannot be used as initialHandlers should throw a NullPointerException when called with a null event.

Throws:

java.lang.NullPointerException - if ev is null and this handler cannot be used as the initial handler class.

ActionVetoException - to suppress a controller change finished event upon termination.

canRun

public boolean canRun(GUIState state,
                      Controller c)

This method tells the controller whether the given handler will function in the given GUIState. For example, if a given handler only responds to Inbox actions, then this method should test the given GUIState to make sure the inbox flag is set.

Parameters:

state - the current visual state of the system

Returns:

true if the given visual state will support this behavioral state. False if using this handler would lock up the system.