messif.algorithms
Class Algorithm

java.lang.Object
  extended by messif.algorithms.Algorithm
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
ParallelSequentialScan, SequentialScan

public abstract class Algorithm
extends java.lang.Object
implements java.io.Serializable

Abstract algorithm framework - support for algorithm naming and operation executive Every algorithm may suport any number of operations (subclasses of AbstractOperation). This algorithm framework automatically register all methods that have a subclass of AbstractOperation as the only argument. The registered operations are executed using executeOperation method, unsupported operation will throw an AlgorithmMethodException

See Also:
Serialized Form

Nested Class Summary
static interface Algorithm.AlgorithmConstructor
          Annotation for algorithm constructors.
 
Field Summary
protected static java.util.logging.Logger log
          Logger
protected static int maximalConcurrentOperations
          Maximal number of currently executed operations
 
Constructor Summary
Algorithm(java.lang.String algorithmName)
          Create new instance of Algorithm and initialize the operation executor.
 
Method Summary
protected  void backgroundExecute(boolean updateStatistics, java.lang.Object... params)
          Execute operation with additional parameters on background.
 void backgroundExecuteOperation(AbstractOperation operation)
          Execute algorithm operation on background.
 void backgroundExecuteOperation(AbstractOperation operation, boolean updateStatistics)
          Execute algorithm operation on background.
 void destroy()
          Destroy this algorithm.
protected  void execute(boolean addTimeStatistic, java.lang.Object... params)
          Execute operation with additional parameters.
<T extends AbstractOperation>
T
executeOperation(T operation)
          Execute operation on this algorithm.
 void finalize()
          Finalize the algorithm.
static
<E extends Algorithm>
java.util.List<java.lang.reflect.Constructor<E>>
getAnnotatedConstructors(java.lang.Class<E> algorithmClass)
          Returns all annotated constructors of the provided algorithm class.
static java.lang.String[] getConstructorArgumentDescriptions(java.lang.reflect.Constructor<? extends Algorithm> constructor)
          Returns constructor argument descriptions for the provided algorithm constuctor.
static java.lang.String getConstructorDescription(java.lang.reflect.Constructor<? extends Algorithm> constructor)
          Returns algorithm constructor description including descriptions for all its arguments.
static java.lang.String getConstructorDescriptionSimple(java.lang.reflect.Constructor<? extends Algorithm> constructor)
          Returns constructor description (without description of arguments) for the provided algorithm constuctor.
protected  java.lang.Class[] getExecutorParamClasses()
          This method should return an array of additional parameters that are needed for operation execution.
<E extends AbstractOperation>
java.lang.Class<? extends E>
getFirstSupportedOperation(java.lang.Class<? extends E> subclassToSearch)
          Returns the first operation that is a supported by this algorithm and is a subclass of (or the same class as) subclassToSearch.
 java.lang.String getName()
          Returns the name of this algorithm
 java.lang.Class<? extends LocalAbstractObject> getObjectClass()
          Returns the class of objects indexed by this algorithm.
 OperationStatistics getOperationStatistics()
          Returns the statistics of the executed operations.
<T> java.util.Iterator<? extends T>
getQueryAnswer(java.lang.Class<? extends QueryOperation<? extends T>> operationClass, java.lang.Object... arguments)
          Execute query operation on this algorithm and return the answer.
<T> java.util.Iterator<? extends T>
getQueryAnswer(QueryOperation<? extends T> operation)
          Execute query operation on this algorithm and return the answer.
 int getRunningOperationsCount()
          Returns the number of currently evaluated operations.
 java.util.List<java.lang.Class<? extends AbstractOperation>> getSupportedOperations()
          Returns the list of operations this particular algorithm supports.
<E extends AbstractOperation>
java.util.List<java.lang.Class<? extends E>>
getSupportedOperations(java.lang.Class<? extends E> subclassToSearch)
          Returns the list of operations this particular algorithm supports.
 void resetOperationStatistics()
          Resets all the statistics of the executed operations gathered so far.
static Algorithm restoreFromFile(java.lang.String filepath)
          Load the algorithm from the specified file and return it.
static
<T extends Algorithm>
T
restoreFromFile(java.lang.String filepath, java.lang.Class<T> algorithmClass)
          Load the algorithm from the specified file and return it.
 void statisticsAfterOperation(AbstractOperation operation)
          This method can be used by all algorithms after processing any operation to set default (operation) statistics.
 void statisticsBeforeOperation()
          This method can be used by all algorithms before processing any operation to set default (operation) statistics.
 void storeToFile(java.lang.String filepath)
          Store the algorithm to the specified file.
 java.util.List<AbstractOperation> waitBackgroundExecuteOperation()
          Wait for all operations executed on background to finish.
<E extends AbstractOperation>
java.util.List<E>
waitBackgroundExecuteOperation(java.lang.Class<E> argClass)
          Wait for all operations executed on background to finish.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

protected static java.util.logging.Logger log
Logger


maximalConcurrentOperations

protected static final int maximalConcurrentOperations
Maximal number of currently executed operations

See Also:
Constant Field Values
Constructor Detail

Algorithm

public Algorithm(java.lang.String algorithmName)
          throws java.lang.IllegalArgumentException
Create new instance of Algorithm and initialize the operation executor.

Parameters:
algorithmName - the name of this algorithm
Throws:
java.lang.IllegalArgumentException - if the prototype returned by getExecutorParamClasses has no items
Method Detail

finalize

public void finalize()
              throws java.lang.Throwable
Finalize the algorithm. All transient resources associated with this algorithm are released. After this method is called, the behavior of executing any operation is unpredictable.

Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable - if there was an error finalizing

destroy

public void destroy()
             throws java.lang.Throwable
Destroy this algorithm. This method releases all resources (transient and persistent) associated with this algorithm. After this method is called, the behavior of executing any operation is unpredictable.

This implementation defaults to call finalize(), but should be overriden if the algorithm needs to differentiate between finalizing and destroying. In that case the "super.destroy()" should not be called if finalizing is not part of destroy.

Throws:
java.lang.Throwable - if there was an error while cleaning

getName

public java.lang.String getName()
Returns the name of this algorithm

Returns:
the name of this algorithm

getObjectClass

public java.lang.Class<? extends LocalAbstractObject> getObjectClass()
Returns the class of objects indexed by this algorithm. This methods returns a generic LocalAbstractObject class.

Returns:
the class of objects indexed by this algorithm

restoreFromFile

public static <T extends Algorithm> T restoreFromFile(java.lang.String filepath,
                                                      java.lang.Class<T> algorithmClass)
                                           throws java.io.IOException,
                                                  java.lang.NullPointerException,
                                                  java.lang.ClassNotFoundException,
                                                  java.lang.ClassCastException
Load the algorithm from the specified file and return it.

Type Parameters:
T - class of the stored algorithm
Parameters:
algorithmClass - class of the stored algorithm
filepath - the path to a file from which the algorithm should be restored
Returns:
the loaded algorithm
Throws:
java.io.IOException - if the specified filename is not a readable serialized algorithm (see readObject method for detailed description)
java.lang.NullPointerException - if the specified filename is null
java.lang.ClassNotFoundException - if the class of serialized object cannot be found
java.lang.ClassCastException - if the filename doesn't contain serialized algorithm

restoreFromFile

public static Algorithm restoreFromFile(java.lang.String filepath)
                                 throws java.io.IOException,
                                        java.lang.NullPointerException,
                                        java.lang.ClassNotFoundException,
                                        java.lang.ClassCastException
Load the algorithm from the specified file and return it.

Parameters:
filepath - the path to file from which the algorithm should be restored
Returns:
the loaded algorithm
Throws:
java.io.IOException - if the specified filename is not a readable serialized algorithm (see readObject method for detailed description)
java.lang.NullPointerException - if the specified filename is null
java.lang.ClassNotFoundException - if the class of serialized object cannot be found
java.lang.ClassCastException - if the filename doesn't contain serialized algorithm

storeToFile

public void storeToFile(java.lang.String filepath)
                 throws java.io.IOException
Store the algorithm to the specified file.

Parameters:
filepath - the path to a file where the algorithm should be stored. If this path is a directory, the algorithm name (all non alphanumeric characters are replaced by underscore) with .bin extension is appended to the path.
Throws:
java.io.IOException - if the specified filename is not writable or if an error occurrs during the serialization (see writeObject method for detailed description)

getRunningOperationsCount

public int getRunningOperationsCount()
Returns the number of currently evaluated operations. Every thread inside executeOperation is counted as well as every invocation of backgroundExecute that was not yet exctracted by waitBackgroundExecuteOperation.

Returns:
the number of currently evaluated operations

getOperationStatistics

public OperationStatistics getOperationStatistics()
Returns the statistics of the executed operations. Unless you call resetOperationStatistics(), the cumulative statistics for all operations run in this thread are returned.

Returns:
the statistics of the executed operations

resetOperationStatistics

public void resetOperationStatistics()
Resets all the statistics of the executed operations gathered so far.


getSupportedOperations

public java.util.List<java.lang.Class<? extends AbstractOperation>> getSupportedOperations()
Returns the list of operations this particular algorithm supports. The operations returned can be further queried on arguments by static methods in AbstractOperation.

Returns:
the list of operations this particular algorithm supports

getSupportedOperations

public <E extends AbstractOperation> java.util.List<java.lang.Class<? extends E>> getSupportedOperations(java.lang.Class<? extends E> subclassToSearch)
Returns the list of operations this particular algorithm supports. The operations returned can be restricted to a specified subclass, such as QueryOperation, etc. The operations returned can be further queried on arguments by static methods in AbstractOperation.

Type Parameters:
E - type of the returned operations
Parameters:
subclassToSearch - ancestor class of the returned operations.
Returns:
the list of operations this particular algorithm supports

getFirstSupportedOperation

public final <E extends AbstractOperation> java.lang.Class<? extends E> getFirstSupportedOperation(java.lang.Class<? extends E> subclassToSearch)
                                                                                        throws java.lang.NoSuchMethodException
Returns the first operation that is a supported by this algorithm and is a subclass of (or the same class as) subclassToSearch. The operations returned can be further queried on arguments by static methods in AbstractOperation.

Type Parameters:
E - type of the returned operations
Parameters:
subclassToSearch - ancestor class of the returned operations
Returns:
the first operation of subclassToSearch that is a supported by this algorithm
Throws:
java.lang.NoSuchMethodException - if this algorithm does not support any operation of the given subclassToSearch

execute

protected final void execute(boolean addTimeStatistic,
                             java.lang.Object... params)
                      throws AlgorithmMethodException,
                             java.lang.NoSuchMethodException
Execute operation with additional parameters. This is a synchronized wrapper around MethodExecutor.execute(java.lang.reflect.Method, java.lang.Object, java.lang.Object[]).

Parameters:
addTimeStatistic - add the execution time statistic to OperationStatistics
params - the parameters compatible with getExecutorParamClasses()
Throws:
AlgorithmMethodException - if the execution has thrown an exception
java.lang.NoSuchMethodException - if the operation is unsupported (there is no method for the operation)

backgroundExecute

protected final void backgroundExecute(boolean updateStatistics,
                                       java.lang.Object... params)
                                throws java.lang.NoSuchMethodException
Execute operation with additional parameters on background. This is a synchronized wrapper around MethodExecutor.backgroundExecute(java.lang.Object[], messif.executor.Executable, messif.executor.Executable).

Parameters:
updateStatistics - set to true if the operations statistic should be updated after the operation finishes its background execution
params - the parameters compatible with getExecutorParamClasses()
Throws:
java.lang.NoSuchMethodException - if the operation is unsupported (there is no method for the operation)

executeOperation

public <T extends AbstractOperation> T executeOperation(T operation)
                                             throws AlgorithmMethodException,
                                                    java.lang.NoSuchMethodException
Execute operation on this algorithm.

Type Parameters:
T - the type of executed operation
Parameters:
operation - the operation to execute on this algorithm
Returns:
the executed operation (same as the argument)
Throws:
AlgorithmMethodException - if the execution has thrown an exception
java.lang.NoSuchMethodException - if the operation is unsupported (there is no method for the operation)

getQueryAnswer

public <T> java.util.Iterator<? extends T> getQueryAnswer(QueryOperation<? extends T> operation)
                                               throws AlgorithmMethodException,
                                                      java.lang.NoSuchMethodException
Execute query operation on this algorithm and return the answer. This is a shortcut method for calling executeOperation(messif.operations.AbstractOperation) and QueryOperation.getAnswer().

Type Parameters:
T - the type of query operation answer
Parameters:
operation - the operation to execute on this algorithm
Returns:
iterator for the answer of the executed query
Throws:
AlgorithmMethodException - if the execution has thrown an exception
java.lang.NoSuchMethodException - if the operation is unsupported (there is no method for the operation)

getQueryAnswer

public <T> java.util.Iterator<? extends T> getQueryAnswer(java.lang.Class<? extends QueryOperation<? extends T>> operationClass,
                                                          java.lang.Object... arguments)
                                               throws java.lang.reflect.InvocationTargetException,
                                                      AlgorithmMethodException,
                                                      java.lang.NoSuchMethodException
Execute query operation on this algorithm and return the answer. The operation to execute is created according to the given class and arguments. This is a shortcut method for calling AbstractOperation.createOperation(java.lang.Class, java.lang.Object[]) and getQueryAnswer(messif.operations.QueryOperation).

Type Parameters:
T - the type of query operation answer
Parameters:
operationClass - the class of the operation to execute on this algorithm
arguments - the arguments for the operation constructor
Returns:
iterator for the answer of the executed query
Throws:
java.lang.reflect.InvocationTargetException - if the operation constructor has thrown an exception
java.lang.NoSuchMethodException - if the operation is unknown or unsupported by this algorithm
AlgorithmMethodException - if the execution has thrown an exception

backgroundExecuteOperation

public void backgroundExecuteOperation(AbstractOperation operation)
                                throws java.lang.NoSuchMethodException
Execute algorithm operation on background. Note: Method waitBackgroundExecuteOperation() MUST be called in the future to release resources.

Parameters:
operation - the operation to execute on this algorithm
Throws:
java.lang.NoSuchMethodException - if the operation is unsupported (there is no method for the operation)

backgroundExecuteOperation

public void backgroundExecuteOperation(AbstractOperation operation,
                                       boolean updateStatistics)
                                throws java.lang.NoSuchMethodException
Execute algorithm operation on background. Note: Method waitBackgroundExecuteOperation() MUST be called in the future to release resources.

Parameters:
operation - the operation to execute on this algorithm
updateStatistics - set to true if the operations statistic should be updated after the operation finishes its background execution
Throws:
java.lang.NoSuchMethodException - if the operation is unsupported (there is no method for the operation)

waitBackgroundExecuteOperation

public java.util.List<AbstractOperation> waitBackgroundExecuteOperation()
                                                                 throws AlgorithmMethodException,
                                                                        java.lang.InterruptedException
Wait for all operations executed on background to finish.

Returns:
the list of operations that were executed
Throws:
AlgorithmMethodException - if there was an exception during the background execution
java.lang.InterruptedException - if the waiting was interrupted

waitBackgroundExecuteOperation

public <E extends AbstractOperation> java.util.List<E> waitBackgroundExecuteOperation(java.lang.Class<E> argClass)
                                                                           throws AlgorithmMethodException,
                                                                                  java.lang.InterruptedException
Wait for all operations executed on background to finish. Only objects (executed methods' arguments) with the specified class are returned.

Type Parameters:
E - type of the returned operations
Parameters:
argClass - filter on the returned operation classes
Returns:
the list of operations that were executed
Throws:
AlgorithmMethodException - if there was an exception during the background execution
java.lang.InterruptedException - if the waiting was interrupted

statisticsBeforeOperation

public void statisticsBeforeOperation()
                               throws java.lang.ClassCastException
This method can be used by all algorithms before processing any operation to set default (operation) statistics.

Throws:
java.lang.ClassCastException - if new statistic cannot be created

statisticsAfterOperation

public void statisticsAfterOperation(AbstractOperation operation)
This method can be used by all algorithms after processing any operation to set default (operation) statistics. The results are right only when the statisticsBeforeOperation() method was used before.

Parameters:
operation - (typically query) operation that was just processed

getExecutorParamClasses

protected java.lang.Class[] getExecutorParamClasses()
This method should return an array of additional parameters that are needed for operation execution. The list must be consistent with the parameters array passed to execute(boolean, java.lang.Object...) and backgroundExecute(boolean, java.lang.Object...).

Returns:
array of additional parameters that are needed for operation execution

getAnnotatedConstructors

public static <E extends Algorithm> java.util.List<java.lang.reflect.Constructor<E>> getAnnotatedConstructors(java.lang.Class<E> algorithmClass)
Returns all annotated constructors of the provided algorithm class.

Type Parameters:
E - class of algorithm for which to get constructors
Parameters:
algorithmClass - the class of an algorithm for which to get constructors
Returns:
all annotated constructors of the provided algorithm class

getConstructorArgumentDescriptions

public static java.lang.String[] getConstructorArgumentDescriptions(java.lang.reflect.Constructor<? extends Algorithm> constructor)
Returns constructor argument descriptions for the provided algorithm constuctor. List of available constructors of an algorithm class can be retrieved using getAnnotatedConstructors. This is used by auto-generated clients to show descriptiron during algorithm creation.

Parameters:
constructor - an algorithm constructor to get the descriptions for
Returns:
constructor argument descriptions

getConstructorDescriptionSimple

public static java.lang.String getConstructorDescriptionSimple(java.lang.reflect.Constructor<? extends Algorithm> constructor)
Returns constructor description (without description of arguments) for the provided algorithm constuctor. List of available constructors of an algorithm class can be retrieved using getAnnotatedConstructors. This is used by auto-generated clients to show descriptiron during algorithm creation.

Parameters:
constructor - an algorithm constructor to get the descriptions for
Returns:
constructor description

getConstructorDescription

public static java.lang.String getConstructorDescription(java.lang.reflect.Constructor<? extends Algorithm> constructor)
Returns algorithm constructor description including descriptions for all its arguments. List of available constructors of an algorithm class can be retrieved using getAnnotatedConstructors. This is used by auto-generated clients to show descriptiron during algorithm creation.

Parameters:
constructor - an algorithm constructor to get the descriptions for
Returns:
constructor description including descriptions for all its arguments