public abstract class Algorithm
extends java.lang.Object
implements java.io.Serializable
Modifier and Type | Class and Description |
---|---|
static interface |
Algorithm.AlgorithmConstructor
Annotation for algorithm constructors.
|
Modifier and Type | Field and Description |
---|---|
protected static java.util.logging.Logger |
log
Logger
|
protected static int |
maximalConcurrentOperations
Maximal number of currently executed operations
|
Constructor and Description |
---|
Algorithm(java.lang.String algorithmName)
Create new instance of Algorithm and initialize the operation executor.
|
Modifier and Type | Method and Description |
---|---|
protected void |
afterStoreToFile(java.lang.String filepath,
boolean successful)
This method is executed after the method
storeToFile(java.lang.String)
was called. |
<T extends AbstractOperation> |
backgroundExecuteOperation(T operation)
Execute algorithm operation on background.
|
void |
backgroundExecuteOperationIndependent(AbstractOperation operation)
Execute algorithm operation on background independently, i.e. without the
possibility to wait for its finish.
|
<T extends AbstractOperation> |
backgroundExecuteOperationWithStatistics(T operation)
Execute algorithm operation on background.
|
protected void |
beforeStoreToFile(java.lang.String filepath)
This method is executed BEFORE the method
storeToFile(java.lang.String)
was called. |
protected <T extends AbstractOperation> |
createBackgroundExecutionCallable(T operation)
Creates a new
Callable that simply runs the executeOperation(T) method on the given operation. |
void |
destroy()
Destroy this algorithm.
|
protected void |
execute(boolean statisticsOn,
java.lang.Object... params)
Execute operation with additional parameters.
|
java.lang.Object |
executeMethodWithStringArguments(java.lang.String[] methodNameAndArguments,
int methodNameIndex,
java.util.Map<java.lang.String,java.lang.Object> namedInstances)
Executes a given method on this algorithm and returns the result.
|
<T extends AbstractOperation> |
executeOperation(T operation)
Execute operation on this algorithm.
|
boolean |
executeUsingNavDir(java.lang.Object navigationDirectory,
java.lang.Object operation,
boolean statisticsOn)
Executes a given
operation by the processor provided by NavigationDirectory . |
void |
finalize()
Finalize the algorithm.
|
java.util.Collection<AbstractOperation> |
getAllRunningOperations()
Returns all operations currently executed by this algorithm.
|
static <E extends Algorithm> |
getAnnotatedConstructors(java.lang.Class<? extends E> algorithmClass)
Returns all annotated constructors of the provided algorithm class.
|
static <E extends Algorithm> |
getAnnotatedConstructorsArray(java.lang.Class<? extends E> algorithmClass)
Returns all annotated constructors of the provided algorithm class as array.
|
static java.lang.String[] |
getConstructorArgumentDescriptions(java.lang.reflect.Constructor<? extends Algorithm> constructor)
Returns constructor argument descriptions for the provided algorithm constructor.
|
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 constructor.
|
protected java.lang.Class<?>[] |
getExecutorParamClasses()
This method should return an array of additional parameters that are needed for operation execution.
|
<E extends AbstractOperation> |
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.
|
int |
getObjectCount()
Returns the number of objects currently stored in the algorithm.
|
OperationStatistics |
getOperationStatistics()
Returns the statistics of the executed operations.
|
java.util.concurrent.ExecutorService |
getOperationsThreadPool()
Returns the current thread pool used for processing operations.
|
static <E extends AbstractOperation> |
getOperationSubClasses(java.util.Collection<java.lang.Class<? extends AbstractOperation>> operations,
java.lang.Class<? extends E> subclassToSearch)
Given a list of abstract operation classes and a required class,
this auxiliary static method returns list of all classes that are subclass of the required class.
|
<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.
|
AbstractOperation |
getRunningOperationById(java.util.UUID operationId)
Returns the currently executed operation with the given identifier.
|
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> |
getSupportedOperations(java.lang.Class<? extends E> subclassToSearch)
Returns the list of operations this particular algorithm supports.
|
java.lang.Object |
methodExecute(java.lang.String methodName,
java.lang.Object[] methodArguments)
Executes a given method on this algorithm and returns the result.
|
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> |
restoreFromFile(java.lang.String filepath,
java.lang.Class<T> algorithmClass)
Load the algorithm from the specified file and return it.
|
void |
setExecutedOperationsLogVerbosity(int executedOperationsLogVerbosity)
Set the verbosity of the logging of the last executed operation.
|
void |
setOperationsThreadPool(java.util.concurrent.ExecutorService operationsThreadPool)
Sets a new
thread pool used for processing operations (via NavigationProcessor ). |
<T extends AbstractOperation> |
setupStatsAndExecuteOperation(T operation,
java.lang.String operationStatsRegexp)
Reset
operation statistics ,
bind the operation statistics according to the given regular expression,
and execute operation on this algorithm. |
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.
|
boolean |
terminateOperation(AbstractOperation operation)
Terminates processing of the given operation.
|
boolean |
terminateOperation(java.util.UUID operationId)
Terminates processing of the operation with given identifier.
|
static <T extends AbstractOperation> |
waitBackgroundExecution(java.util.concurrent.Future<? extends T> future)
Helper method for waiting for an operation executed on background.
|
protected static final java.util.logging.Logger log
protected static final int maximalConcurrentOperations
public Algorithm(java.lang.String algorithmName) throws java.lang.IllegalArgumentException
algorithmName
- the name of this algorithmjava.lang.IllegalArgumentException
- if the prototype returned by getExecutorParamClasses
has no itemspublic void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
- if there was an error finalizingpublic void destroy() throws java.lang.Throwable
This implementation defaults to call finalize()
, but should be overridden
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.
java.lang.Throwable
- if there was an error while cleaningpublic java.lang.String getName()
public java.lang.Class<? extends LocalAbstractObject> getObjectClass()
LocalAbstractObject
class.public int getObjectCount() throws AlgorithmMethodException
GetObjectCountOperation
but can be overridden if a more efficient method is available.
If the number of objects is unknown, -1 is returned.AlgorithmMethodException
- if there was an error during the executionpublic void setOperationsThreadPool(java.util.concurrent.ExecutorService operationsThreadPool)
thread pool
used for processing operations (via NavigationProcessor
).
The previously set operationsThreadPool
is shut down (destroyed).
If operationsThreadPool
is not null, parallel processing is used.operationsThreadPool
- the new thread pool instance to set (can be null)public java.util.concurrent.ExecutorService getOperationsThreadPool()
public void setExecutedOperationsLogVerbosity(int executedOperationsLogVerbosity)
executedOperationsLogVerbosity
- the verbosity levelpublic 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
T
- class of the stored algorithmalgorithmClass
- class of the stored algorithmfilepath
- the path to a file from which the algorithm should be restoredjava.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 nulljava.lang.ClassNotFoundException
- if the class of serialized object cannot be foundjava.lang.ClassCastException
- if the filename doesn't contain serialized algorithmpublic static Algorithm restoreFromFile(java.lang.String filepath) throws java.io.IOException, java.lang.NullPointerException, java.lang.ClassNotFoundException, java.lang.ClassCastException
filepath
- the path to file from which the algorithm should be restoredjava.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 nulljava.lang.ClassNotFoundException
- if the class of serialized object cannot be foundjava.lang.ClassCastException
- if the filename doesn't contain serialized algorithmpublic void storeToFile(java.lang.String filepath) throws java.io.IOException
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.java.io.IOException
- if the specified filename is not writable or if an error occurs during the serialization
(see writeObject
method for detailed description)protected void beforeStoreToFile(java.lang.String filepath)
storeToFile(java.lang.String)
was called. It is empty and expected to be overridden.filepath
- the path to a file where the algorithm was storedprotected void afterStoreToFile(java.lang.String filepath, boolean successful)
storeToFile(java.lang.String)
was called. It is empty and expected to be overridden.filepath
- the path to a file where the algorithm was storedsuccessful
- true, if the write to file was successful, false otherwisepublic int getRunningOperationsCount()
public AbstractOperation getRunningOperationById(java.util.UUID operationId)
operationId
- the identifier of the operation to getpublic java.util.Collection<AbstractOperation> getAllRunningOperations()
public OperationStatistics getOperationStatistics()
resetOperationStatistics()
, the cumulative statistics
for all operations run in this thread are returned.public void resetOperationStatistics()
public java.util.List<java.lang.Class<? extends AbstractOperation>> getSupportedOperations()
public <E extends AbstractOperation> java.util.List<java.lang.Class<? extends E>> getSupportedOperations(java.lang.Class<? extends E> subclassToSearch)
E
- type of the returned operationssubclassToSearch
- ancestor class of the returned operations.public final <E extends AbstractOperation> java.lang.Class<? extends E> getFirstSupportedOperation(java.lang.Class<? extends E> subclassToSearch) throws java.lang.NoSuchMethodException
subclassToSearch
.
The operations returned can be further queried on arguments by static methods in AbstractOperation.E
- type of the returned operationssubclassToSearch
- ancestor class of the returned operationssubclassToSearch
that is a supported by this algorithmjava.lang.NoSuchMethodException
- if this algorithm does not support any operation of the given subclassToSearch
public static <E extends AbstractOperation> java.util.List<java.lang.Class<? extends E>> getOperationSubClasses(java.util.Collection<java.lang.Class<? extends AbstractOperation>> operations, java.lang.Class<? extends E> subclassToSearch)
E
- type of the returned operationsoperations
- list of operation classes to search withinsubclassToSearch
- ancestor class of the returned operationspublic boolean executeUsingNavDir(java.lang.Object navigationDirectory, java.lang.Object operation, boolean statisticsOn) throws java.lang.InterruptedException, AlgorithmMethodException, java.lang.CloneNotSupportedException
operation
by the processor provided by NavigationDirectory
.
If the passed objects are not instances of NavigationDirectory
or AbstractOperation
,
or the directory does not provide processor for the given operation, false is returned
and no processing is done. Otherwise, the sequential or asynchronous processing
is executed for the given operation.navigationDirectory
- an instance of NavigationDirectory
as plain Object
operation
- an instance of AbstractOperation
as plain Object
compatible with the given NavigationDirectory
statisticsOn
- run the before/after operation statistics, see statisticsBeforeOperation()
and statisticsAfterOperation(messif.operations.AbstractOperation)
operation
was processed using the navigationDirectory
or
false if no processing was performedjava.lang.InterruptedException
- if the processing thread is interrupted during the processingAlgorithmMethodException
- if there was an error during the processingjava.lang.CloneNotSupportedException
- if there was a need for cloning (due to asynchronous access) but cloning was not supportedprotected final void execute(boolean statisticsOn, java.lang.Object... params) throws AlgorithmMethodException, java.lang.NoSuchMethodException
MethodExecutor.execute(java.lang.reflect.Method, java.lang.Object, java.lang.Object[])
.statisticsOn
- add the execution time statistics to OperationStatistics
params
- the parameters compatible with getExecutorParamClasses()
AlgorithmMethodException
- if the execution has thrown an exceptionjava.lang.NoSuchMethodException
- if the operation is unsupported (there is no method for the operation)public <T extends AbstractOperation> T executeOperation(T operation) throws AlgorithmMethodException, java.lang.NoSuchMethodException
T
- the type of executed operationoperation
- the operation to execute on this algorithmAlgorithmMethodException
- if the execution has thrown an exceptionjava.lang.NoSuchMethodException
- if the operation is unsupported (there is no method for the operation)public <T extends AbstractOperation> T setupStatsAndExecuteOperation(T operation, java.lang.String operationStatsRegexp) throws AlgorithmMethodException, java.lang.NoSuchMethodException
operation statistics
,
bind the operation statistics according to the given regular expression,
and execute operation on this algorithm.T
- the type of executed operationoperation
- the operation to execute on this algorithmoperationStatsRegexp
- regular expression matching the statistics to bindAlgorithmMethodException
- if the execution has thrown an exceptionjava.lang.NoSuchMethodException
- if the operation is unsupported (there is no method for the operation)public final <T> java.util.Iterator<? extends T> getQueryAnswer(QueryOperation<? extends T> operation) throws AlgorithmMethodException, java.lang.NoSuchMethodException
executeOperation(messif.operations.AbstractOperation)
and
QueryOperation.getAnswer()
.T
- the type of query operation answeroperation
- the operation to execute on this algorithmAlgorithmMethodException
- if the execution has thrown an exceptionjava.lang.NoSuchMethodException
- if the operation is unsupported (there is no method for the operation)public final <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
AbstractOperation.createOperation(java.lang.Class, java.lang.Object[])
and
getQueryAnswer(messif.operations.QueryOperation)
.T
- the type of query operation answeroperationClass
- the class of the operation to execute on this algorithmarguments
- the arguments for the operation constructorjava.lang.reflect.InvocationTargetException
- if the operation constructor has thrown an exceptionjava.lang.NoSuchMethodException
- if the operation is unknown or unsupported by this algorithmAlgorithmMethodException
- if the execution has thrown an exceptionprotected <T extends AbstractOperation> java.util.concurrent.Callable<T> createBackgroundExecutionCallable(T operation)
Callable
that simply runs the executeOperation(T)
method on the given operation.T
- the type of operationoperation
- the operation to runCallable
public <T extends AbstractOperation> java.util.concurrent.Future<T> backgroundExecuteOperation(T operation)
T
- the type of the executed operationoperation
- the operation to execute on this algorithmFuture
that can be used to wait for the execution to finish and retrieve the resulting executed operation;
note that a NoSuchMethodException
exception can be thrown if the operation is unsupported (there is no method for the operation)public <T extends AbstractOperation> FutureWithStatistics<T> backgroundExecuteOperationWithStatistics(T operation)
T
- the type of the executed operationoperation
- the operation to execute on this algorithmFuture
that can be used to wait for the execution to finish and retrieve the resulting executed operation;
note that a NoSuchMethodException
exception can be thrown if the operation is unsupported (there is no method for the operation)public static <T extends AbstractOperation> T waitBackgroundExecution(java.util.concurrent.Future<? extends T> future) throws java.lang.InterruptedException, AlgorithmMethodException, java.lang.NoSuchMethodException
FutureWithStatistics
.T
- the type of the executed operationfuture
- a future of the previously executed operationAlgorithmMethodException
- if there was an exception during the background executionjava.lang.InterruptedException
- if the waiting was interruptedjava.lang.NoSuchMethodException
- if the operation is not supportedpublic void backgroundExecuteOperationIndependent(AbstractOperation operation)
getAllRunningOperations()
or getRunningOperationById(java.util.UUID)
to access the operation.
Method terminateOperation(java.util.UUID)
can be used to stop the operation.
After the operation is finished, there is no way to access it.operation
- the operation to execute on this algorithmpublic boolean terminateOperation(java.util.UUID operationId)
Thread.isInterrupted()
regularly and act accordingly if it is set.operationId
- the identifier of the operation to terminatepublic boolean terminateOperation(AbstractOperation operation)
Thread.isInterrupted()
regularly and act accordingly if it is set.operation
- the operation to terminatepublic void statisticsBeforeOperation() throws java.lang.ClassCastException
java.lang.ClassCastException
- if new statistic cannot be createdpublic void statisticsAfterOperation(AbstractOperation operation)
statisticsBeforeOperation()
method was used before.operation
- (typically query) operation that was just processedprotected java.lang.Class<?>[] getExecutorParamClasses()
execute(boolean, java.lang.Object...)
and #backgroundExecute
.public final java.lang.Object executeMethodWithStringArguments(java.lang.String[] methodNameAndArguments, int methodNameIndex, java.util.Map<java.lang.String,java.lang.Object> namedInstances) throws java.lang.reflect.InvocationTargetException, NoSuchInstantiatorException, java.lang.IllegalArgumentException
methodNameAndArguments
- the array that contains a method name and its arguments as stringmethodNameIndex
- the index in the methodNameAndArguments
array where the method name is (the following arguments are considered to be the arguments)namedInstances
- map of named instances - an instance from this map is returned if the string
matches a key in the mapjava.lang.reflect.InvocationTargetException
- if the executed method throws an exceptionNoSuchInstantiatorException
- if the there is no method for the given name and prototypejava.lang.IllegalArgumentException
- if there was a problem reading the class in the remote algorithm's resultpublic final java.lang.Object methodExecute(java.lang.String methodName, java.lang.Object[] methodArguments) throws java.lang.reflect.InvocationTargetException, NoSuchInstantiatorException, java.lang.IllegalArgumentException
methodName
- the name of the method to execute on the remote algorithmmethodArguments
- the arguments for the methodjava.lang.reflect.InvocationTargetException
- if the executed method throws an exceptionNoSuchInstantiatorException
- if the there is no method for the given name and prototypejava.lang.IllegalArgumentException
- if there was a problem reading the class in the remote algorithm's resultpublic static <E extends Algorithm> java.util.List<java.lang.reflect.Constructor<E>> getAnnotatedConstructors(java.lang.Class<? extends E> algorithmClass)
E
- class of algorithm for which to get constructorsalgorithmClass
- the class of an algorithm for which to get constructorspublic static <E extends Algorithm> java.lang.reflect.Constructor<E>[] getAnnotatedConstructorsArray(java.lang.Class<? extends E> algorithmClass)
E
- class of algorithm for which to get constructorsalgorithmClass
- the class of an algorithm for which to get constructorspublic static java.lang.String[] getConstructorArgumentDescriptions(java.lang.reflect.Constructor<? extends Algorithm> constructor)
getAnnotatedConstructors
.
This is used by auto-generated clients to show description during algorithm creation.constructor
- an algorithm constructor to get the descriptions forpublic static java.lang.String getConstructorDescriptionSimple(java.lang.reflect.Constructor<? extends Algorithm> constructor)
getAnnotatedConstructors
.
This is used by auto-generated clients to show description during algorithm creation.constructor
- an algorithm constructor to get the descriptions forpublic static java.lang.String getConstructorDescription(java.lang.reflect.Constructor<? extends Algorithm> constructor)
getAnnotatedConstructors
.
This is used by auto-generated clients to show description during algorithm creation.constructor
- an algorithm constructor to get the descriptions for