messif.operations
Class RankingQueryOperation

java.lang.Object
  extended by messif.operations.AbstractOperation
      extended by messif.operations.QueryOperation<RankedAbstractObject>
          extended by messif.operations.RankingQueryOperation
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Clearable
Direct Known Subclasses:
AggregationFunctionQueryOperation, GetObjectsByLocatorsOperation, IncrementalNNQueryOperation, KNNMultiQueryOperation, KNNQueryOperation, RangeQueryOperation

public abstract class RankingQueryOperation
extends QueryOperation<RankedAbstractObject>

The base class for query operations that return objects ranked by a distance. For example, all basic metric queries are ranking, since range or k-nearest neighbor queries return objects ranked according to their distance to the query object.

Each object in the answer must implement a DistanceRanked interface that provides access to the distance of the particular answer. Note that the distance only makes sense in the context of a query.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class messif.operations.AbstractOperation
AbstractOperation.DataEqualOperation, AbstractOperation.OperationConstructor, AbstractOperation.OperationName
 
Field Summary
 
Fields inherited from class messif.operations.QueryOperation
answerType
 
Fields inherited from class messif.operations.AbstractOperation
errValue, operID, suppData
 
Constructor Summary
protected RankingQueryOperation()
          Creates a new instance of RankingQueryOperation.
protected RankingQueryOperation(AnswerType answerType, int maxAnswerSize)
          Creates a new instance of RankingQueryOperation.
protected RankingQueryOperation(AnswerType answerType, int maxAnswerSize, boolean storeMetaDistances)
          Creates a new instance of RankingQueryOperation.
protected RankingQueryOperation(int maxAnswerSize)
          Creates a new instance of RankingQueryOperation.
 
Method Summary
 RankedAbstractObject addToAnswer(AbstractObject object, float distance, float[] objectDistances)
          Add a distance-ranked object to the answer.
 RankedAbstractObject addToAnswer(LocalAbstractObject queryObject, LocalAbstractObject object, float distThreshold)
          Add an object to the answer.
 void clearSurplusData()
          Clear non-messif data stored in operation.
 RankingQueryOperation clone()
          Create a duplicate of this operation.
 java.util.Iterator<RankedAbstractObject> getAnswer()
          Returns an iterator over all objects in the answer to this query.
 java.util.Iterator<RankedAbstractObject> getAnswer(int skip, int count)
          Returns an iterator over all objects in the answer skipping the first skip items and returning only count elements.
 java.lang.Class<? extends RankedAbstractObject> getAnswerClass()
          Returns the class of objects this operation stores in its answer.
 int getAnswerCount()
          Returns the number of objects in this query answer.
 float getAnswerDistance()
          Returns the distance of the last object in the answer.
 java.util.Iterator<AbstractObject> getAnswerObjects()
          Returns an iterator over all AbstractObjects in the answer to this query.
 float getAnswerThreshold()
          Returns the threshold distance for the current answer of this query.
 RankedAbstractObject getLastAnswer()
          Returns the current last ranked object in the answer.
 boolean isAnswerFull()
          Returns true if the current answer has reached the maximal number of objects, i.e., the maxAnswerSize specified in constructor.
 boolean isStoringMetaDistances()
          Returns true if sub-distances for metaobjects are stored in the answer.
 void resetAnswer()
          Reset the current query answer.
 void setAnswerCollection(RankedSortedCollection collection)
          Set a new collection that maintains the answer list of this ranking query.
 void updateFrom(AbstractOperation operation)
          Update the error code and answer of this operation from another operation.
protected  void updateFrom(RankingQueryOperation operation)
          Update the answer of this operation from a RankingQueryOperation.
 
Methods inherited from class messif.operations.QueryOperation
appendErrorCode, endOperation, evaluate, getAnswerType, wasSuccessful
 
Methods inherited from class messif.operations.AbstractOperation
appendArguments, createOperation, dataEquals, dataEqualsImpl, dataHashCode, endOperation, equals, getAnnotatedConstructor, getAnnotatedConstructor, getArgument, getArgumentCount, 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
 

Constructor Detail

RankingQueryOperation

protected RankingQueryOperation()
Creates a new instance of RankingQueryOperation. Objects added to answer are changed to no-data objects. Unlimited number of objects can be added to the answer.


RankingQueryOperation

protected RankingQueryOperation(int maxAnswerSize)
                         throws java.lang.IllegalArgumentException
Creates a new instance of RankingQueryOperation. Objects added to answer are changed to no-data objects.

Parameters:
maxAnswerSize - sets the maximal answer size
Throws:
java.lang.IllegalArgumentException - if the maximal answer size is negative

RankingQueryOperation

protected RankingQueryOperation(AnswerType answerType,
                                int maxAnswerSize)
                         throws java.lang.IllegalArgumentException
Creates a new instance of RankingQueryOperation.

Parameters:
answerType - the type of objects this operation stores in its answer
maxAnswerSize - sets the maximal answer size
Throws:
java.lang.IllegalArgumentException - if the maximal answer size is negative

RankingQueryOperation

protected RankingQueryOperation(AnswerType answerType,
                                int maxAnswerSize,
                                boolean storeMetaDistances)
                         throws java.lang.IllegalArgumentException
Creates a new instance of RankingQueryOperation.

Parameters:
answerType - the type of objects this operation stores in its answer
maxAnswerSize - sets the maximal answer size
storeMetaDistances - if true, all processed meta objects will store their sub-distances in the answer
Throws:
java.lang.IllegalArgumentException - if the maximal answer size is negative
Method Detail

clone

public RankingQueryOperation clone()
                            throws java.lang.CloneNotSupportedException
Create a duplicate of this operation. The answer of the query is not clonned.

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

setAnswerCollection

public void setAnswerCollection(RankedSortedCollection collection)
Set a new collection that maintains the answer list of this ranking query. Note that this method should be used only for changing the reranking/filtering of the results.

Parameters:
collection - a new instance of answer collection

getAnswerClass

public java.lang.Class<? extends RankedAbstractObject> getAnswerClass()
Description copied from class: QueryOperation
Returns the class of objects this operation stores in its answer.

Specified by:
getAnswerClass in class QueryOperation<RankedAbstractObject>
Returns:
the class of objects this operation stores in its answer

getAnswerCount

public int getAnswerCount()
Description copied from class: QueryOperation
Returns the number of objects in this query answer.

Specified by:
getAnswerCount in class QueryOperation<RankedAbstractObject>
Returns:
the number of objects in this query answer

getAnswer

public java.util.Iterator<RankedAbstractObject> getAnswer()
Description copied from class: QueryOperation
Returns an iterator over all objects in the answer to this query.

Specified by:
getAnswer in class QueryOperation<RankedAbstractObject>
Returns:
an iterator over all objects in the answer to this query

getAnswer

public java.util.Iterator<RankedAbstractObject> getAnswer(int skip,
                                                          int count)
Description copied from class: QueryOperation
Returns an iterator over all objects in the answer skipping the first skip items and returning only count elements. If count is less than or equal to zero, all objects from the answer (except for skip) are returned.

Specified by:
getAnswer in class QueryOperation<RankedAbstractObject>
Parameters:
skip - number of answer objects to skip
count - number of answer objects to iterate (maximally, actual number of results can be smaller)
Returns:
an iterator over the objects in the answer to this query

getAnswerObjects

public java.util.Iterator<AbstractObject> getAnswerObjects()
Description copied from class: QueryOperation
Returns an iterator over all AbstractObjects in the answer to this query. This method unwraps the objects from the results.

Specified by:
getAnswerObjects in class QueryOperation<RankedAbstractObject>
Returns:
an iterator over all AbstractObjects in the answer to this query

getLastAnswer

public RankedAbstractObject getLastAnswer()
                                   throws java.util.NoSuchElementException
Returns the current last ranked object in the answer.

Returns:
the current last ranked object in the answer
Throws:
java.util.NoSuchElementException - if the answer is empty

getAnswerDistance

public float getAnswerDistance()
                        throws java.util.NoSuchElementException
Returns the distance of the last object in the answer.

Returns:
the distance of the last object in the answer
Throws:
java.util.NoSuchElementException - if the answer is empty

isAnswerFull

public boolean isAnswerFull()
Returns true if the current answer has reached the maximal number of objects, i.e., the maxAnswerSize specified in constructor.

Returns:
true if the current answer has reached the maximal size

getAnswerThreshold

public float getAnswerThreshold()
Returns the threshold distance for the current answer of this query. If the answer has not reached the maximal size (specified in constructor) yet, LocalAbstractObject.MAX_DISTANCE is returned. Otherwise, the distance of the last answer's object is returned.

Returns:
the distance to the last object in the answer list or LocalAbstractObject.MAX_DISTANCE if there are not enough objects.

isStoringMetaDistances

public boolean isStoringMetaDistances()
Returns true if sub-distances for metaobjects are stored in the answer.

Returns:
true if sub-distances for metaobjects are stored in the answer

addToAnswer

public RankedAbstractObject addToAnswer(LocalAbstractObject queryObject,
                                        LocalAbstractObject object,
                                        float distThreshold)
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.

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

addToAnswer

public final RankedAbstractObject addToAnswer(AbstractObject object,
                                              float distance,
                                              float[] objectDistances)
                                       throws java.lang.IllegalArgumentException
Add a distance-ranked object to the answer. Preserve the information about distances of the respective sub-objects.

Parameters:
object - the object to add
distance - the distance of object
objectDistances - the array of distances to the respective sub-objects (can be null)
Returns:
the distance-ranked object object that was added to answer or null if the object was not added
Throws:
java.lang.IllegalArgumentException - if the answer type of this operation requires clonning but the passed object cannot be cloned

resetAnswer

public void resetAnswer()
Reset the current query answer. All objects from the answer are deleted, getAnswerCount() will return zero.

Specified by:
resetAnswer in class QueryOperation<RankedAbstractObject>

updateFrom

public final void updateFrom(AbstractOperation operation)
                      throws java.lang.IllegalArgumentException
Update the error code and answer of this operation from another operation.

Overrides:
updateFrom in class AbstractOperation
Parameters:
operation - the source operation from which to get the update
Throws:
java.lang.IllegalArgumentException - if the answer of the specified operation is incompatible with this one

updateFrom

protected void updateFrom(RankingQueryOperation operation)
Update the answer of this operation from a RankingQueryOperation.

Parameters:
operation - the source operation from which to get the update

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 AbstractOperation