messif.executor
Class MethodExecutor

java.lang.Object
  extended by messif.executor.MethodExecutor
Direct Known Subclasses:
MethodClassExecutor, MethodNameExecutor

public abstract class MethodExecutor
extends java.lang.Object

This class is a generic framework for executing methods on a specified object. Methods must match the specified prototype. Then the method execute method can be called. This method invokes the method of the instance (provided in constructor), which is appropriate for the provided arguments. Method backgroundExecute can be called to invoke the method in a new thread. A returned thread can be used for wait calls to test, whether the execution has finished and also to retrieve the data.


Nested Class Summary
static interface MethodExecutor.ExecutableMethod
          Annotation for methods that provide usage description.
 
Field Summary
protected  java.lang.Object executionObject
          The object that the operations are invoked on
 
Constructor Summary
protected MethodExecutor(java.lang.Object executionObject)
          Create new instance of MethodExecutor
 
Method Summary
 MethodThread backgroundExecute(java.lang.Object... arguments)
          Execute a registered method by arguments on background.
 MethodThread backgroundExecute(java.lang.Object[] arguments, Executable executeBefore, Executable executeAfter)
          Execute a registered method by arguments on background.
 MethodThread backgroundExecute(java.lang.Object[] arguments, java.util.List<Executable> executeBefore, java.util.List<Executable> executeAfter)
          Execute a registered method by arguments on background.
protected static java.lang.Object execute(java.lang.reflect.Method method, java.lang.Object executionObject, java.lang.Object[] arguments)
          Execute specified method on exectutionObject with specified arguments and handle exceptions properly.
 java.lang.Object execute(java.lang.Object... arguments)
          Execute a registered method using the specified arguments.
protected abstract  java.lang.reflect.Method getMethod(java.lang.Object[] arguments)
          Returns the method that is appropriate for the provided arguments.
protected abstract  java.util.Collection<java.lang.reflect.Method> getRegisteredMethods()
          Returns all methods that are registered within this executor.
 void printUsage(java.io.PrintStream out, boolean printArguments, boolean printDescription)
          Prints usage of all methods managed by this executor.
static void printUsage(java.io.PrintStream out, boolean printArguments, boolean printDescription, java.lang.reflect.Method method)
          Prints the method usage built from the MethodExecutor.ExecutableMethod annotation.
 void printUsage(java.io.PrintStream out, boolean printArguments, boolean printDescription, java.lang.Object[] arguments)
          Prints usage of method that is to be called for the given arguments.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

executionObject

protected final java.lang.Object executionObject
The object that the operations are invoked on

Constructor Detail

MethodExecutor

protected MethodExecutor(java.lang.Object executionObject)
                  throws java.lang.IllegalArgumentException
Create new instance of MethodExecutor

Parameters:
executionObject - an instance of the object to execute the operations on
Throws:
java.lang.IllegalArgumentException - if the execution object is null
Method Detail

getRegisteredMethods

protected abstract java.util.Collection<java.lang.reflect.Method> getRegisteredMethods()
Returns all methods that are registered within this executor.

Returns:
all methods that are registered within this executor

printUsage

public static void printUsage(java.io.PrintStream out,
                              boolean printArguments,
                              boolean printDescription,
                              java.lang.reflect.Method method)
Prints the method usage built from the MethodExecutor.ExecutableMethod annotation. If the annotation is not present, nothing is printed out. Otherwise the concatenation of the method name, its argument descriptions (in sharp parenthesis) and the method's description is printed out.

Parameters:
out - the print stream where the usage is print
printArguments - flag whether to print the method's argument descriptions
printDescription - flag whether to print the method's description
method - the method for which to get the usage

printUsage

public void printUsage(java.io.PrintStream out,
                       boolean printArguments,
                       boolean printDescription)
Prints usage of all methods managed by this executor.

Parameters:
out - the print stream where the usage is print
printArguments - flag whether to print the method's argument descriptions
printDescription - flag whether to print the method's description

printUsage

public void printUsage(java.io.PrintStream out,
                       boolean printArguments,
                       boolean printDescription,
                       java.lang.Object[] arguments)
                throws java.lang.NoSuchMethodException
Prints usage of method that is to be called for the given arguments.

Parameters:
out - the print stream where the usage is print
printArguments - flag whether to print the method's argument descriptions
printDescription - flag whether to print the method's description
arguments - the arguments for the method
Throws:
java.lang.NoSuchMethodException - if there is no method for the specified parameters in this executor

getMethod

protected abstract java.lang.reflect.Method getMethod(java.lang.Object[] arguments)
                                               throws java.lang.NoSuchMethodException
Returns the method that is appropriate for the provided arguments.

Parameters:
arguments - the arguments for the method
Returns:
the method that is appropriate for the provided arguments
Throws:
java.lang.NoSuchMethodException - if there is no method that can process the provided arguments in this executor

execute

protected static java.lang.Object execute(java.lang.reflect.Method method,
                                          java.lang.Object executionObject,
                                          java.lang.Object[] arguments)
                                   throws java.lang.NoSuchMethodException,
                                          java.lang.reflect.InvocationTargetException
Execute specified method on exectutionObject with specified arguments and handle exceptions properly.

Parameters:
method - the method to execute
executionObject - the instance on which to invoke the method
arguments - the method arguments
Returns:
the method's return value
Throws:
java.lang.NoSuchMethodException - if the arguments are not compatible with the method
java.lang.reflect.InvocationTargetException - if an exeception was thrown when the method was executed

execute

public java.lang.Object execute(java.lang.Object... arguments)
                         throws java.lang.NoSuchMethodException,
                                java.lang.reflect.InvocationTargetException
Execute a registered method using the specified arguments.

Parameters:
arguments - the array of arguments for the execution method (must be consistent with the prototype in constructor)
Returns:
the method's return value (if method returns void, null is returned instead)
Throws:
java.lang.NoSuchMethodException - if there is no method that can process the provided arguments in this executor
java.lang.reflect.InvocationTargetException - if an exeception was thrown when the method was executed

backgroundExecute

public MethodThread backgroundExecute(java.lang.Object[] arguments,
                                      Executable executeBefore,
                                      Executable executeAfter)
                               throws java.lang.NoSuchMethodException
Execute a registered method by arguments on background. Another methods - executeBefore and executeAfter - can be called before and after the execution in the same thread.

Parameters:
arguments - the array of arguments for the execution method (must be consistent with the prototype in constructor)
executeBefore - method to call before registered method
executeAfter - method to call after registered method
Returns:
a method execution thread object - method MethodThread.waitExecutionEnd() can be used to retrieve the results
Throws:
java.lang.NoSuchMethodException - if there is no method that can process the provided arguments in this executor

backgroundExecute

public MethodThread backgroundExecute(java.lang.Object[] arguments,
                                      java.util.List<Executable> executeBefore,
                                      java.util.List<Executable> executeAfter)
                               throws java.lang.NoSuchMethodException
Execute a registered method by arguments on background. Another methods - executeBefore and executeAfter - can be called before and after the execution in the same thread.

Parameters:
arguments - The array of arguments for the execution method (must be consistent with the prototype in constructor)
executeBefore - list of methods to call before registered method
executeAfter - list of methods to call after registered method
Returns:
a method execution thread object - method MethodThread.waitExecutionEnd() can be used to retrieve the results
Throws:
java.lang.NoSuchMethodException - if there is no method that can process the provided arguments in this executor

backgroundExecute

public MethodThread backgroundExecute(java.lang.Object... arguments)
                               throws java.lang.NoSuchMethodException
Execute a registered method by arguments on background.

Parameters:
arguments - the array of arguments for the execution method (must be consistent with the prototype in constructor)
Returns:
a method execution thread object - method MethodThread.waitExecutionEnd() can be used to retrieve the results
Throws:
java.lang.NoSuchMethodException - if there is no method that can process the provided arguments in this executor