messif.operations.query
Class IncrementalNNQueryOperation

java.lang.Object
  messif.operations.AbstractOperation
      messif.operations.QueryOperation<RankedAbstractObject>
          messif.operations.RankingQueryOperation
              messif.operations.query.IncrementalNNQueryOperation

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Clearable

public class IncrementalNNQueryOperation
extends RankingQueryOperation

Incremental Nearest Neighbor Search. This operation returns only references to the original object. The behavior of an algorithm implementing this operation must hold the following contract:
1/ If there are some objects to pending, the operation must be ended with HAS_NEXT error code by calling endOperation method.
2/ If all objects have been returned in previous calls to the search or in this call, the operation must be ended with RESPONSE_RETURNED error code. This eror code is set automaticly if endOperation is not called with a specific value.
This contract is similar to the behavior of iterators. The call to wasSuccessful() returns true if the error code was set either to HAS_NEXT or RESPONSE_RETURNED.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class messif.operations.AbstractOperation

AbstractOperation.DataEqualOperation, AbstractOperation.OperationConstructor, AbstractOperation.OperationName

Field Summary

protected int	minNN Minimum number of objects returned by this query.
protected int	nnAddedToAnswer The number of nearest neighbors added to the answer since the last call to endOperation().
protected LocalAbstractObject	queryObject kNN query object

Fields inherited from class messif.operations.QueryOperation

answerType

Fields inherited from class messif.operations.AbstractOperation

errValue, operID, suppData

Constructor Summary

IncrementalNNQueryOperation(LocalAbstractObject queryObject)
Creates a new instance of IncrementalNNQueryOperation.

IncrementalNNQueryOperation(LocalAbstractObject queryObject, int minNN)
Creates a new instance of IncrementalNNQueryOperation.

IncrementalNNQueryOperation(LocalAbstractObject queryObject, int minNN, AnswerType answerType)
Creates a new instance of IncrementalNNQueryOperation.

Method Summary

RankedAbstractObject	addToAnswer(LocalAbstractObject queryObject, LocalAbstractObject object, float distThreshold) Add an object to the answer.
void	clearSurplusData() Clear non-messif data stored in operation.
protected boolean	dataEqualsImpl(AbstractOperation obj) Indicates whether some other operation has the same data as this one.
int	dataHashCode() Returns a hash code value for the data of this operation.
void	endOperation() End operation successfully
void	endOperation(ErrorCode errValue) End operation with a specific error code.
int	evaluate(AbstractObjectIterator<? extends LocalAbstractObject> objects) Evaluate this query on a given set of objects.
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.
int	getMinNN() Returns the minimum number of objects returned by this query.
LocalAbstractObject	getQueryObject() Returns the kNN query object.
boolean	isFilledEnough() Returns true if the minimum number of objects has been inserted to the answer during one evaluation of this operation.

Methods inherited from class messif.operations.RankingQueryOperation

addToAnswer, clone, getAnswer, getAnswer, getAnswerClass, getAnswerCount, getAnswerDistance, getAnswerObjects, getAnswerThreshold, getLastAnswer, isAnswerFull, isStoringMetaDistances, resetAnswer, setAnswerCollection, updateFrom, updateFrom

Methods inherited from class messif.operations.QueryOperation

appendErrorCode, getAnswerType, wasSuccessful

Methods inherited from class messif.operations.AbstractOperation

appendArguments, createOperation, dataEquals, equals, getAnnotatedConstructor, getAnnotatedConstructor, getConstructorArgumentDescriptions, getConstructorArgumentDescriptions, getConstructorArguments, getConstructorArguments, getConstructorDescription, getErrorCode, getName, getName, getOperationID, hashCode, isFinished, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

queryObject

protected final LocalAbstractObject queryObject

kNN query object

minNN

protected final int minNN

Minimum number of objects returned by this query. Default value is 1. It can be set to any larger value in order to optimize the process of searching for nearest neighbors. This feature is usually used by distributed incremental search algoritms.

nnAddedToAnswer

protected int nnAddedToAnswer

The number of nearest neighbors added to the answer since the last call to endOperation(). I.e., how many NN were added in one evaluation of this operation.

Constructor Detail

IncrementalNNQueryOperation

public IncrementalNNQueryOperation(LocalAbstractObject queryObject)

Creates a new instance of IncrementalNNQueryOperation. At least one next nearest neighbor will be returned for each execution. AnswerType.NODATA_OBJECTS will be returned in the result.

Parameters:

queryObject - the object to which the nearest neighbors are searched

IncrementalNNQueryOperation

public IncrementalNNQueryOperation(LocalAbstractObject queryObject,
                                   int minNN)

Creates a new instance of IncrementalNNQueryOperation. AnswerType.NODATA_OBJECTS will be returned in the result.

Parameters:

queryObject - the object to which the nearest neighbors are searched

minNN - the minimal number of nearest neighbors to retrieve

IncrementalNNQueryOperation

public IncrementalNNQueryOperation(LocalAbstractObject queryObject,
                                   int minNN,
                                   AnswerType answerType)

Creates a new instance of IncrementalNNQueryOperation.

Parameters:

queryObject - the object to which the nearest neighbors are searched

minNN - the minimal number of nearest neighbors to retrieve

answerType - the type of objects this operation stores in its answer

Method Detail

getQueryObject

public LocalAbstractObject getQueryObject()

Returns the kNN query object.

Returns:

the kNN query object

getMinNN

public int getMinNN()

Returns the minimum number of objects returned by this query.

Returns:

the minimum number of objects returned by this query

getArgument

public java.lang.Object getArgument(int index)
                             throws java.lang.IndexOutOfBoundsException

Returns argument that was passed while constructing instance. If the argument is not stored within operation, null is returned.

Overrides:

getArgument in class AbstractOperation

Parameters:

index - 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

getArgumentCount

public int getArgumentCount()

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

Overrides:

getArgumentCount in class AbstractOperation

Returns:

number of arguments that were passed while constructing this instance

endOperation

public void endOperation()

End operation successfully

Overrides:

endOperation in class QueryOperation<RankedAbstractObject>

endOperation

public void endOperation(ErrorCode errValue)
                  throws java.lang.IllegalArgumentException

End operation with a specific error code.

Overrides:

endOperation in class AbstractOperation

Parameters:

errValue - the error code to set

Throws:

java.lang.IllegalArgumentException - if the specified error value is null or ErrorCode.NOT_SET

evaluate

public int evaluate(AbstractObjectIterator<? extends LocalAbstractObject> objects)

Evaluate this query on a given set of objects. The objects found by this evaluation are added to answer of this query via addToAnswer(messif.objects.LocalAbstractObject, messif.objects.LocalAbstractObject, float). Note that the incremental kNN search can't use filtering, because the maximal radius is unknown

Specified by:

evaluate in class QueryOperation<RankedAbstractObject>

Parameters:

objects - the collection of objects on which to evaluate this query

Returns:

number of objects satisfying the query

isFilledEnough

public boolean isFilledEnough()

Returns true if the minimum number of objects has been inserted to the answer during one evaluation of this operation.

Returns:

true if the current answer has a minimal number of objects

addToAnswer

public RankedAbstractObject addToAnswer(LocalAbstractObject queryObject,
                                        LocalAbstractObject object,
                                        float distThreshold)

Description copied from class: RankingQueryOperation

Add an object to the answer. The rank of the object is computed automatically as a distance between the query object and the specified object.

Overrides:

addToAnswer in class RankingQueryOperation

Parameters:

queryObject - the query object against which to compute the distance (rank)

object - the object to add

distThreshold - the threshold on distance; if the computed distance exceeds the threshold (sharply), the object is not added to the answer

Returns:

the distance-ranked object object that was added to answer or null if the object was not added

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

Overrides:

clearSurplusData in class RankingQueryOperation

dataEqualsImpl

protected boolean dataEqualsImpl(AbstractOperation obj)

Indicates whether some other operation has the same data as this one.

Specified by:

dataEqualsImpl in class AbstractOperation

Parameters:

obj - the reference object with which to compare.

Returns:

true if this object has the same data as the obj argument; false otherwise.

dataHashCode

public int dataHashCode()

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

Specified by:

dataHashCode in class AbstractOperation

Returns:

a hash code value for the data of this operation