uic.model
Class UICSimpleAction

java.lang.Object
  uic.model.UICSimpleAction

Direct Known Subclasses:

SwingAction, UICAction

public class UICSimpleAction
extends Object

This class represent the glue between a user event and a piece of controlling logic. Events based programming creates the need to execute certain pieces of logic based on the incoming event, conveniently grouped per action. An action can be something like 'print'. Notice that the default version uses the SimpleQueuedPolicy.

Since:

1.2

Nested Class Summary

static class	UICSimpleAction.Arguments A builder class to specify arguments of differing types for a target method.
static class	UICSimpleAction.DirectMultiThreadingPolicy This policy will execute the action in a new thread.
static class	UICSimpleAction.DirectPolicy This policy will execute the action in the calling thread.
static interface	UICSimpleAction.ExecutePolicy Each action that is called 'execute()' on will be executed according to policy.
static class	UICSimpleAction.OnlyLastPolicy This policy will enqueue the action; but will remove others that would call the same target method.
static class	UICSimpleAction.QueuedPolicy This policy will queue each action to be executed serially, while disabling the action when running.
static class	UICSimpleAction.SimpleQueuedPolicy This policy will queue each action to be executed serially.

Field Summary

protected UICSimpleAction.ExecutePolicy	currentPolicy
protected Method	target
protected Object	targetObject

Constructor Summary

UICSimpleAction()
Empty constructor; don't forget to do a setTarget later!.

UICSimpleAction(Object targetObject, String targetMethod)
Constructor with automatic setTarget.

UICSimpleAction(Object targetObject, String targetMethod, UICSimpleAction.Arguments args)
Constructor with automatic setTarget.

Method Summary

static UICSimpleAction.Arguments	createArguments()
protected void	doAction(Object[] args) Called to actually execute the action on the registered method.
boolean	equals(Object o)
void	execute() Convenience method.
void	execute(EventObject source) Execute the action.
void	execute(Object[] args) Execute the action with the arguments for the target method.
void	execute(Object[] args, Object source) Execute the action with the arguments for the target method.
protected Class	getArgumentClass(String argumentType) For the uniquely defined argumentType (as also used in getTargetSignatures()) return the Class.
protected Object	getArgumentValue(EventObject source, String argumentType) For the uniquely defined argumentType (as also used in getTargetSignatures()) return the value.
protected List	getTargetSignatures() Return a List object with instances of the Arguments class.
boolean	isEnabled()
void	setDirect(boolean direct) UIActions queue their work so actions will have to wait for all others to be finished; unless direct is true.
void	setEnabled(boolean enabled) Enable disable this action and all its registered components.
void	setExecutionPolicy(UICSimpleAction.ExecutePolicy policy) Set a new policy for this action.
void	setTarget(Object object, String targetMethod) The target method that is to be called when the action is fired.
void	setTarget(Object object, String targetMethod, UICSimpleAction.Arguments arguments) The target method that is to be called when the action is fired.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

targetObject

protected Object targetObject

target

protected Method target

currentPolicy

protected UICSimpleAction.ExecutePolicy currentPolicy

Constructor Detail

UICSimpleAction

public UICSimpleAction()

Empty constructor; don't forget to do a setTarget later!.

UICSimpleAction

public UICSimpleAction(Object targetObject,
                       String targetMethod)

Constructor with automatic setTarget.

See Also:

setTarget(Object,String)

UICSimpleAction

public UICSimpleAction(Object targetObject,
                       String targetMethod,
                       UICSimpleAction.Arguments args)

Constructor with automatic setTarget.

Since:

2.0

See Also:

setTarget(Object,String,uic.model.UICSimpleAction.Arguments)

Method Detail

getTargetSignatures

protected List getTargetSignatures()

Return a List object with instances of the Arguments class. Extending classes should implement this to return all the target method signatures that are searched for should the user create an action without an Arguments instance.

An example implementation could be this:

  List result = new ArrayList(1);
  result.add( new Arguments().addArgument("Source") );
  return result;

This will result in a call to getArgumentClass(java.lang.String) with the string "Source" which returns a Class instance. In our example that would be java.lang.Object.

The result of this would be that a call to setTarget will try to find a method with an argument of type Object, and will search again if that is not found without any arguments.

Returns:

a List object with instances of the Arguments class.

See Also:

getArgumentValue(java.util.EventObject, java.lang.String), getArgumentClass(java.lang.String)

getArgumentValue

protected Object getArgumentValue(EventObject source,
                                  String argumentType)

For the uniquely defined argumentType (as also used in getTargetSignatures()) return the value. This method will always return 'null'; Extending actions can define various argumentType strings that can be used as an argument in the call to the target method of this action. The user decides on construction of the action which argumentTypes are to be used, if a certain value is requested to be sent to the targetMethod a call is made to this method to find its value based on the source event.

Note that base types can not be returned, since they are instances of object; you should wrap these in their object re-presentation (an Integer object for an int).

Parameters:

source - the event that caused the action to be fired. This is the event that the extending class passed to the execute method; so casting is fine.

argumentType - the uniquely defined name specifying the type of argument.

Returns:

the value to be passed to the taget method.

getArgumentClass

protected Class getArgumentClass(String argumentType)

For the uniquely defined argumentType (as also used in getTargetSignatures()) return the Class. This method will always return 'null'; Extending actions can define various argumentType strings that can be used as an argument in the call to the target method of this action. The user decides on construction of the action which argumentTypes are to be used, if a certain value is requested to be sent to the targetMethod a call is made to this method to find the Class of the type.

Note that basetypes have a class of their own and you should return the correct one you expect the targetMethod to implement. returning Integer.class will search for an Integer; returing int.class will search for an int. This is important to note since the getArgumentValue(java.util.EventObject, java.lang.String) method should return an Integer object in both cases.

Parameters:

argumentType - the uniquely defined name specifying the type of argument.

Returns:

the class of this argument to be found on the target method

setTarget

public void setTarget(Object object,
                      String targetMethod)
               throws IllegalArgumentException

The target method that is to be called when the action is fired.

Parameters:

object - The object that contains the method we want to connect to.

targetMethod - the name of the method we want to connect to.

Throws:

IllegalArgumentException - when targetMethod could not be found on object. To specify what this action will do on an incoming event you must specify a target. The target is in the form of a method call specified by the object the method lives on, and the name of the method you want to call.

Note; it is possible to provide a class object (System.class for example) to use a static method on that object.

setTarget

public void setTarget(Object object,
                      String targetMethod,
                      UICSimpleAction.Arguments arguments)
               throws IllegalArgumentException

The target method that is to be called when the action is fired.

Parameters:

object - The object that contains the method we want to connect to.

targetMethod - the name of the method we want to connect to.

arguments - to be used in finding the targetMethod signature

Throws:

IllegalArgumentException - when targetMethod could not be found on object. To specify what this action will do on an incoming event you must specify a target. The target is in the form of a method call specified by the object the method lives on, and the name of the method you want to call.

Simply calling a method with no arguments will not be usefull in many cases so the action can generate arguments to be passes if you specify which argument those should be.

Take for example:

      public void onSelectionSlot(int selectedRow, int selectedCol) { }

This method takes 2 arguments which have to be defined by the user (if the action does happen to pre-define them). The action also has to support the logic needed to get the selectedRow and selectedCol from the source of the event.

      myAction.setTarget(this,                // the method is implemented on 'this'
              "onSelectionSlot",              // the name of the method
              UICAction.getArguments()        // helper method
              .addArgument("ROW")             // add 'ROW' which the action
              .addArgument("COL"));           //           should have defined
 
Note; it is possible to provide a class object (System.class for example) to
      use a static method on that object.

setEnabled

public void setEnabled(boolean enabled)

Enable disable this action and all its registered components. Incoming events will not cause the action to be commited when the action is disabled.

Parameters:

enabled - the new state of the action.

isEnabled

public boolean isEnabled()

doAction

protected void doAction(Object[] args)

Called to actually execute the action on the registered method. Notice that this method will never throw any Throwables due to bad implementations in the target method since they are all cought (and ignored) here. That said; exceptions made in the target method will be printed using a simple printStackTrace() call on the throwable.

execute

public void execute()

Convenience method.

execute

public void execute(EventObject source)

Execute the action. Calling execute will register the call and make sure the targetMethod is called. Notice that calling this method will do nothing if the action is not enabled.

Parameters:

source - an event object which is used to gather argument-values.

execute

public void execute(Object[] args)
             throws IllegalArgumentException

Execute the action with the arguments for the target method. Calling execute will register the call and make sure the targetMethod is called. Notice that calling this method will do nothing if the action is not enabled.

Parameters:

args - an array of object where each object is one argument to the target method, or null for a 0-argument target.

Throws:

IllegalArgumentException - is thrown when the target method found does not have the exact same arguments as the amount of objects in the args array.

execute

public void execute(Object[] args,
                    Object source)
             throws IllegalArgumentException

Execute the action with the arguments for the target method. Calling execute will register the call and make sure the targetMethod is called. Notice that calling this method will do nothing if the action is not enabled.

Parameters:

args - an array of object where each object is one argument to the target method, or null for a 0-argument target.

source - the source object that started this execute; Swing applications will typically pass a widget allowing the busy-cursor to be set on long actions.

Throws:

IllegalArgumentException - is thrown when the target method found does not have the exact same arguments as the amount of objects in the args array.

setDirect

public void setDirect(boolean direct)

UIActions queue their work so actions will have to wait for all others to be finished; unless direct is true. In the case of stop/quit and other actions coming from UICActions that by definition should be executed directly; and not after all others, the action should be set to be 'direct'.

Parameters:

direct - if true the action will be executed directly, inside the calling thread.

setExecutionPolicy

public void setExecutionPolicy(UICSimpleAction.ExecutePolicy policy)

Set a new policy for this action.

Parameters:

policy - the new policy

Since:

2.0

equals

public boolean equals(Object o)

Overrides:

equals in class Object

createArguments

public static UICSimpleAction.Arguments createArguments()