messif.operations
Class AbstractOperation

java.lang.Object
  extended by messif.operations.AbstractOperation
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Clearable
Direct Known Subclasses:
BulkInsertOperation, DeleteByLocatorOperation, DeleteOperation, GetObjectCountOperation, InsertOperation, QueryOperation

public abstract class AbstractOperation
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable, Clearable

The base class for all operations. Operations allows to manipulate and query the data held by algorithms. An algorithm is not required to provide implementation for each operation. However, to support an operation, simply create a method with a specific operation class as an argument. See Algorithm for more information. To ease the task of building interfaces, each operation should provide an annotation AbstractOperation.OperationName to specify a user-friendly name of the operation. Also the constructors should be annotated by AbstractOperation.OperationConstructor to specify descriptors for its arguments. See Convert.stringToType(java.lang.String, java.lang.Class, java.util.Map) for the list of types that can be used in operation constructors.

See Also:
QueryOperation, Algorithm, Serialized Form

Nested Class Summary
static class AbstractOperation.DataEqualOperation
          A wrapper class that allows to hash/equal abstract objects using their data and not ID.
static interface AbstractOperation.OperationConstructor
          Annotation for operation constructors.
static interface AbstractOperation.OperationName
          Annotation that specifies operation user-friendly name.
 
Field Summary
protected  ErrorCode errValue
          Operation result code
protected  java.util.UUID operID
          An universaly unique identification of the operation
 java.lang.Object suppData
          Supplemental data object
 
Constructor Summary
AbstractOperation()
           
 
Method Summary
protected  void appendArguments(java.lang.StringBuilder str)
          Appends the constructor arguments of this query to the specified string.
protected  void appendErrorCode(java.lang.StringBuilder str)
          Appends the error code of this query to the specified string.
 void clearSurplusData()
          Clear non-messif data stored in operation.
 AbstractOperation clone()
          Create a duplicate of this operation.
static
<E extends AbstractOperation>
E
createOperation(java.lang.Class<E> operationClass, java.lang.Object... arguments)
          Creates a new operation of the specified class.
 boolean dataEquals(AbstractOperation operation)
          Indicates whether some other operation has the same data as this one.
protected abstract  boolean dataEqualsImpl(AbstractOperation operation)
          Indicates whether some other operation has the same data as this one.
abstract  int dataHashCode()
          Returns a hash code value for the data of this operation.
abstract  void endOperation()
          End operation successfully.
 void endOperation(ErrorCode errValue)
          End operation with a specific error code.
 boolean equals(java.lang.Object obj)
          Indicates whether another operation is equal to this operation.
static
<T extends AbstractOperation>
java.lang.reflect.Constructor<T>
getAnnotatedConstructor(java.lang.Class<? extends T> operationClass)
          Searches the given operationClass for an annotated constructor.
static
<T extends AbstractOperation>
java.lang.reflect.Constructor<T>
getAnnotatedConstructor(java.lang.Class<? extends T> operationClass, int argumentsCount)
          Searches the given operationClass for an annotated constructor that has the given argumentsCount.
 java.lang.Object getArgument(int index)
          Returns argument that was passed while constructing instance.
 int getArgumentCount()
          Returns number of arguments that were passed while constructing this instance.
static java.lang.String[] getConstructorArgumentDescriptions(java.lang.Class<? extends AbstractOperation> operationClass)
          Returns constructor argument descriptions for the provided operation class.
static java.lang.String[] getConstructorArgumentDescriptions(java.lang.Class<? extends AbstractOperation> operationClass, int nArguments)
          Returns constructor argument descriptions for the provided operation class with given number of arguments.
static java.lang.Class<?>[] getConstructorArguments(java.lang.Class<? extends AbstractOperation> operationClass)
          Returns constructor argument types for the provided operation class.
static java.lang.Class<?>[] getConstructorArguments(java.lang.Class<? extends AbstractOperation> operationClass, int nArguments)
          Returns constructor arguments for the provided operation class for an annotated constructor with given number of arguments.
static java.lang.String getConstructorDescription(java.lang.Class<? extends AbstractOperation> operationClass)
          Returns full constructor description for the provided operation class.
 ErrorCode getErrorCode()
          Returns the result code of this operation.
 java.lang.String getName()
          Returns the name of this operation.
static java.lang.String getName(java.lang.Class<? extends AbstractOperation> operationClass)
          Returns the name of operation represented by the provided class.
 java.util.UUID getOperationID()
          Returns the current operation ID.
 int hashCode()
          Returns a hash code value based on this operation ID.
 boolean isFinished()
          Returns true if this operation has finished its processing - either successfully or unsuccessfully.
 java.lang.String toString()
          Returns a string representation of this operation.
 void updateFrom(AbstractOperation operation)
          Update the error code of this operation from another operation.
abstract  boolean wasSuccessful()
          Returns true if this operation has finished successfuly.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

suppData

public java.lang.Object suppData
Supplemental data object


operID

protected final java.util.UUID operID
An universaly unique identification of the operation


errValue

protected ErrorCode errValue
Operation result code

Constructor Detail

AbstractOperation

public AbstractOperation()
Method Detail

getOperationID

public java.util.UUID getOperationID()
Returns the current operation ID.

Returns:
the current operation ID

hashCode

public final int hashCode()
Returns a hash code value based on this operation ID.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this operation

equals

public final boolean equals(java.lang.Object obj)
Indicates whether another operation is equal to this operation. Two operations are equal if their classes and IDs match. Note that the clonned operations are equal as well as the serialized and then deserialized operations.

Overrides:
equals in class java.lang.Object
Parameters:
obj - the reference object with which to compare
Returns:
true if this object is the same as the obj argument; false otherwise

dataEquals

public final boolean dataEquals(AbstractOperation operation)
Indicates whether some other operation has the same data as this one.

Parameters:
operation - the reference object with which to compare.
Returns:
true if this object has the same data as the obj argument; false otherwise.

dataEqualsImpl

protected abstract boolean dataEqualsImpl(AbstractOperation operation)
Indicates whether some other operation has the same data as this one.

Parameters:
operation - the reference object with which to compare.
Returns:
true if this object has the same data as the obj argument; false otherwise.

dataHashCode

public abstract int dataHashCode()
Returns a hash code value for the data of this operation. Override this method if the operation has its own data.

Returns:
a hash code value for the data of this operation

wasSuccessful

public abstract boolean wasSuccessful()
Returns true if this operation has finished successfuly. Otherwise, false is returned - the operation was either unsuccessful or is has not finished yet.

Returns:
true if this operation has finished successfuly

getErrorCode

public ErrorCode getErrorCode()
Returns the result code of this operation.

Returns:
the result code of this operation

isFinished

public boolean isFinished()
Returns true if this operation has finished its processing - either successfully or unsuccessfully. In other words, true is returned if the error code of this operation is set. If the operation has not finished yet (i.e. the error code is not set, false is returned.

Returns:
true if this operation has finished its processing

endOperation

public void endOperation(ErrorCode errValue)
                  throws java.lang.IllegalArgumentException
End operation with a specific error code.

Parameters:
errValue - the error code to set
Throws:
java.lang.IllegalArgumentException - if the specified error value is null or ErrorCode.NOT_SET

endOperation

public abstract void endOperation()
End operation successfully.


clone

public AbstractOperation clone()
                        throws java.lang.CloneNotSupportedException
Create a duplicate of this operation. Check (and override) the implementation in subclasses if there are mutable object attributes. Note that supplemental data (suppData) is not clonned.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this operation
Throws:
java.lang.CloneNotSupportedException - if the operation instance cannot be cloned

updateFrom

public void updateFrom(AbstractOperation operation)
                throws java.lang.ClassCastException
Update the error code of this operation from another operation.

Parameters:
operation - the source operation from which to get the update
Throws:
java.lang.ClassCastException - if the specified operation is incompatible with this operation

clearSurplusData

public void clearSurplusData()
Clear non-messif data stored in operation. This method is intended to be called whenever the operation is sent back to client in order to minimize problems with unknown classes after deserialization.

Specified by:
clearSurplusData in interface Clearable

appendArguments

protected void appendArguments(java.lang.StringBuilder str)
Appends the constructor arguments of this query to the specified string. Arguments are enclosed in < and > and separated by commas. They are added in the same order as in the constructor. Leading space is added.

Parameters:
str - the string to add the arguments to

appendErrorCode

protected void appendErrorCode(java.lang.StringBuilder str)
Appends the error code of this query to the specified string. If the error code is not set yet, the "has not finished yet" string is added. If the operation was successful, the "was successful" string is added. Otherwise, a string "failed: " with the error code name is added. Leading space is added.

Parameters:
str - the string to add the error code to

toString

public java.lang.String toString()
Returns a string representation of this operation.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of this operation.

getName

public static java.lang.String getName(java.lang.Class<? extends AbstractOperation> operationClass)
Returns the name of operation represented by the provided class.

Parameters:
operationClass - the operation class for which to get the name
Returns:
the operation name

getName

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

Returns:
the name of this operation

getAnnotatedConstructor

public static <T extends AbstractOperation> java.lang.reflect.Constructor<T> getAnnotatedConstructor(java.lang.Class<? extends T> operationClass)
                                                                                          throws java.lang.NoSuchMethodException
Searches the given operationClass for an annotated constructor. The constructor with the smallest number of arguments is returned.

Type Parameters:
T - the operation class
Parameters:
operationClass - the operation class to search the constructor for
Returns:
the constructor for the operation
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

getAnnotatedConstructor

public static <T extends AbstractOperation> java.lang.reflect.Constructor<T> getAnnotatedConstructor(java.lang.Class<? extends T> operationClass,
                                                                                                     int argumentsCount)
                                                                                          throws java.lang.NoSuchMethodException
Searches the given operationClass for an annotated constructor that has the given argumentsCount.

Type Parameters:
T - the operation class
Parameters:
operationClass - the operation class to search the constructor for
argumentsCount - number of arguments that the constructor must have
Returns:
the constructor for the operation
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

getConstructorArgumentDescriptions

public static java.lang.String[] getConstructorArgumentDescriptions(java.lang.Class<? extends AbstractOperation> operationClass)
                                                             throws java.lang.NoSuchMethodException
Returns constructor argument descriptions for the provided operation class. This is used by auto-generated clients to show descriptiron during operation creation.

Parameters:
operationClass - class to get the descriptions for
Returns:
constructor argument descriptions
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

getConstructorArgumentDescriptions

public static java.lang.String[] getConstructorArgumentDescriptions(java.lang.Class<? extends AbstractOperation> operationClass,
                                                                    int nArguments)
                                                             throws java.lang.NoSuchMethodException
Returns constructor argument descriptions for the provided operation class with given number of arguments. This is used by auto-generated clients to show descriptiron during operation creation.

Parameters:
operationClass - class to get the descriptions for
nArguments - the number of arguments of the constructor
Returns:
constructor argument descriptions
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

getConstructorArguments

public static java.lang.Class<?>[] getConstructorArguments(java.lang.Class<? extends AbstractOperation> operationClass)
                                                    throws java.lang.NoSuchMethodException
Returns constructor argument types for the provided operation class.

Parameters:
operationClass - class to get the constructor types for
Returns:
constructor argument types
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

getConstructorArguments

public static java.lang.Class<?>[] getConstructorArguments(java.lang.Class<? extends AbstractOperation> operationClass,
                                                           int nArguments)
                                                    throws java.lang.NoSuchMethodException
Returns constructor arguments for the provided operation class for an annotated constructor with given number of arguments.

Parameters:
operationClass - class to get the constructor types for
nArguments - the number of arguments of the constructor
Returns:
constructor argument types
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

getConstructorDescription

public static java.lang.String getConstructorDescription(java.lang.Class<? extends AbstractOperation> operationClass)
                                                  throws java.lang.NoSuchMethodException
Returns full constructor description for the provided operation class.

Parameters:
operationClass - class to get the constructor types for
Returns:
full constructor description
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName

createOperation

public static <E extends AbstractOperation> E createOperation(java.lang.Class<E> operationClass,
                                                              java.lang.Object... arguments)
                                                   throws java.lang.NoSuchMethodException,
                                                          java.lang.IllegalArgumentException,
                                                          java.lang.reflect.InvocationTargetException
Creates a new operation of the specified class.

Type Parameters:
E - the class of the operation that should be created
Parameters:
operationClass - the class of the operation that should be created
arguments - arguments supplied to the constructor; they should match the types of getConstructorArguments(operationClass)
Returns:
a new instance of operation
Throws:
java.lang.NoSuchMethodException - if either the operationClass is null or the class is not annotated using AbstractOperation.OperationName
java.lang.IllegalArgumentException - if the argument count or their types don't match the specified operation class constructor
java.lang.reflect.InvocationTargetException - if there was an exception in the operation's constructor

getArgument

public java.lang.Object getArgument(int index)
                             throws java.lang.IndexOutOfBoundsException,
                                    java.lang.UnsupportedOperationException
Returns argument that was passed while constructing instance. If the argument is not stored within operation, null is returned.

Parameters:
index - zero-based index of an argument passed to constructor
Returns:
argument that was passed while constructing instance
Throws:
java.lang.IndexOutOfBoundsException - if index parameter is out of range
java.lang.UnsupportedOperationException - if this operation doesn't support construction argument retrieval

getArgumentCount

public int getArgumentCount()
Returns number of arguments that were passed while constructing this instance. Negative number is returned if this operation doesn't support construction argument retrieval.

Returns:
number of arguments that were passed while constructing this instance