public abstract class RankingQueryOperation extends QueryOperation<RankedAbstractObject>
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 is a RankedAbstractObject
that provides access to the distance and the object of the particular answer.
Note that the distance only makes sense in the context of a query.
QueryOperation.DataEqualOperation
AbstractOperation.OperationConstructor, AbstractOperation.OperationName
suppData, uuidOperationComparator
Modifier | Constructor and Description |
---|---|
protected |
RankingQueryOperation()
Creates a new instance of RankingQueryOperation.
|
protected |
RankingQueryOperation(AnswerType answerType)
Creates a new instance of RankingQueryOperation.
|
protected |
RankingQueryOperation(AnswerType answerType,
int maxAnswerSize)
Creates a new instance of RankingQueryOperation.
|
protected |
RankingQueryOperation(AnswerType answerType,
RankedSortedCollection answerCollection)
Creates a new instance of RankingQueryOperation.
|
protected |
RankingQueryOperation(int maxAnswerSize)
Creates a new instance of RankingQueryOperation.
|
Modifier and Type | Method and Description |
---|---|
RankedAbstractObject |
addToAnswer(AbstractObject object,
float distance,
float[] objectDistances)
Add a distance-ranked object to the answer.
|
RankingQueryOperation |
clone(boolean preserveAnswer)
Create a duplicate of this operation.
|
void |
endOperation(ErrorCode errValue)
End operation with a specific error code.
|
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.
|
java.lang.Class<? extends RankedSortedCollection> |
getAnswerCollectionClass()
Class of the current answer assigned in the operation.
|
RankedSortedCollection |
getAnswerCollectionClone()
Returns an empty clone of the answer collection of this operation.
|
java.util.Comparator<? super RankedAbstractObject> |
getAnswerComparator()
Returns the internal comparator of the answer collection (often null).
|
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<RankedAbstractObject> |
getAnswerDistanceRestricted(float maxDistance)
Returns an iterator over all objects in the answer that are ranked lower
than the
maxDistance . |
java.util.Iterator<RankedAbstractObject> |
getAnswerDistanceRestricted(float minDistance,
float maxDistance)
Returns an iterator over all objects in the answer that are ranked higher
than the
minDistance but lower than the maxDistance . |
int |
getAnswerMaximalCapacity()
Returns the maximal capacity of the answer collection.
|
java.util.Iterator<AbstractObject> |
getAnswerObjects()
Returns an iterator over all
AbstractObject s 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.
|
java.util.Iterator<? extends RankedAbstractObject> |
getSubAnswer(int index)
Returns an iterator over all objects in the answer sub-collection with the given index.
|
java.util.Iterator<? extends RankedAbstractObject> |
getSubAnswer(java.lang.Object key)
Returns an iterator over all objects in the answer sub-collection with the given key.
|
int |
getSubAnswerCount()
Returns the number of answer sub-collections.
|
boolean |
isAnswerFull()
Returns true if the current answer has reached
the maximal number of objects, i.e., the
maxAnswerSize
specified in constructor. |
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 |
setAnswerIgnoringDuplicates(boolean ignoringDuplicates)
Set the flag whether the
addToAnswer(messif.objects.AbstractObject, float, float[]) method checks if an equal object exists already in the collection. |
void |
setAnswerThresholdComputation(boolean useOriginalThresholdDistance,
boolean ignoreThresholdDistance,
int computeSize)
Set the operation
answer threshold distance computation. |
static <T extends RankingQueryOperation> |
setAnswerThresholdComputation(T operation,
boolean useOriginalThresholdDistance,
boolean ignoreThresholdDistance,
int computeSize)
Set the given operation
answer threshold distance computation. |
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 . |
appendErrorCode, clone, dataEquals, dataEqualsImpl, dataHashCode, endOperation, evaluate, getAllSubAnswers, getAnswerType, getQueryAnswer, iterator, setAnswerType, wasSuccessful
appendArguments, clearSurplusData, containsParameter, createOperation, equals, getAnnotatedConstructor, getAnnotatedConstructor, getArgument, getArgumentCount, getArgumentString, getConstructorArgumentDescriptions, getConstructorArgumentDescriptions, getConstructorArguments, getConstructorArguments, getConstructorDescription, getErrorCode, getName, getName, getOperationID, getParameter, getParameter, getParameter, getParameterCount, getParameterMap, getParameterNames, getRequiredParameter, getRequiredParameter, hashCode, isErrorCode, isFinished, removeParameter, setParameter, toString
protected RankingQueryOperation()
changed to no-data objects
.
Unlimited number of objects can be added to the answer.protected RankingQueryOperation(int maxAnswerSize) throws java.lang.IllegalArgumentException
changed to no-data objects
.maxAnswerSize
- sets the maximal answer sizejava.lang.IllegalArgumentException
- if the maximal answer size is negativeprotected RankingQueryOperation(AnswerType answerType) throws java.lang.IllegalArgumentException
answerType
- the type of objects this operation stores in its answerjava.lang.IllegalArgumentException
- if the maximal answer size is negativeprotected RankingQueryOperation(AnswerType answerType, int maxAnswerSize) throws java.lang.IllegalArgumentException
answerType
- the type of objects this operation stores in its answermaxAnswerSize
- sets the maximal answer sizejava.lang.IllegalArgumentException
- if the maximal answer size is negativeprotected RankingQueryOperation(AnswerType answerType, RankedSortedCollection answerCollection)
answerType
- the type of objects this operation stores in its answeranswerCollection
- collection to be used as answer (it must be empty, otherwise it will be cleared)java.lang.NullPointerException
- if the passed collection is null
public RankingQueryOperation clone(boolean preserveAnswer) throws java.lang.CloneNotSupportedException
QueryOperation
preserveAnswer
is true the answer is
not cloned but both this and the cloned operation share the same answer collection.clone
in class QueryOperation<RankedAbstractObject>
preserveAnswer
- flag whether to clone the answer (false) or preserve
the same answer collection (true) in the cloned operationjava.lang.CloneNotSupportedException
- if the operation instance cannot be clonedpublic void setAnswerCollection(RankedSortedCollection collection)
collection
- a new instance of answer collectionpublic void setAnswerIgnoringDuplicates(boolean ignoringDuplicates)
addToAnswer(messif.objects.AbstractObject, float, float[])
method checks if an equal object exists already in the collection.ignoringDuplicates
- the flag whether the method checks for duplicate objectspublic java.lang.Class<? extends RankedAbstractObject> getAnswerClass()
QueryOperation
getAnswerClass
in class QueryOperation<RankedAbstractObject>
public java.lang.Class<? extends RankedSortedCollection> getAnswerCollectionClass()
public int getAnswerCount()
QueryOperation
getAnswerCount
in class QueryOperation<RankedAbstractObject>
public int getAnswerMaximalCapacity()
public java.util.Comparator<? super RankedAbstractObject> getAnswerComparator()
public java.util.Iterator<RankedAbstractObject> getAnswer()
QueryOperation
getAnswer
in class QueryOperation<RankedAbstractObject>
public java.util.Iterator<RankedAbstractObject> getAnswer(int skip, int count)
QueryOperation
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.getAnswer
in class QueryOperation<RankedAbstractObject>
skip
- number of answer objects to skipcount
- number of answer objects to iterate (maximally, actual number of results can be smaller)public RankedSortedCollection getAnswerCollectionClone() throws java.lang.CloneNotSupportedException
java.lang.CloneNotSupportedException
- if the collection cannot be clonnedpublic java.util.Iterator<RankedAbstractObject> getAnswerDistanceRestricted(float minDistance, float maxDistance)
minDistance
but lower than the maxDistance
.minDistance
- the minimal distance of the answer objects to returnmaxDistance
- the maximal distance of the answer objects to returnpublic java.util.Iterator<RankedAbstractObject> getAnswerDistanceRestricted(float maxDistance)
maxDistance
.maxDistance
- the maximal distance of the answer objects to returnpublic java.util.Iterator<AbstractObject> getAnswerObjects()
QueryOperation
AbstractObject
s in the answer to this query.
This method unwraps the objects from the results.getAnswerObjects
in class QueryOperation<RankedAbstractObject>
AbstractObject
s in the answer to this querypublic int getSubAnswerCount()
QueryOperation
getSubAnswerCount
in class QueryOperation<RankedAbstractObject>
public java.util.Iterator<? extends RankedAbstractObject> getSubAnswer(int index) throws java.lang.IndexOutOfBoundsException
QueryOperation
getSubAnswer
in class QueryOperation<RankedAbstractObject>
index
- the index of the answer sub-collection to returnjava.lang.IndexOutOfBoundsException
- if the given index is negative or
greater or equal to QueryOperation.getSubAnswerCount()
public java.util.Iterator<? extends RankedAbstractObject> getSubAnswer(java.lang.Object key)
QueryOperation
getSubAnswer
in class QueryOperation<RankedAbstractObject>
key
- the key of the answer sub-collection to returnpublic RankedAbstractObject getLastAnswer() throws java.util.NoSuchElementException
java.util.NoSuchElementException
- if the answer is emptypublic float getAnswerDistance() throws java.util.NoSuchElementException
java.util.NoSuchElementException
- if the answer is emptypublic boolean isAnswerFull()
maxAnswerSize
specified in constructor.public void setAnswerThresholdComputation(boolean useOriginalThresholdDistance, boolean ignoreThresholdDistance, int computeSize) throws java.lang.IllegalStateException
answer threshold distance
computation.
By default, the original threshold distance is used.
If the useOriginalThresholdDistance
is false, the threshold
distance is always LocalAbstractObject.MAX_DISTANCE
if ignoreThresholdDistance
is true. Or the threshold is computed from the first computeSize
objects.useOriginalThresholdDistance
- the flag whether the operation answer collection computes the threshold distanceignoreThresholdDistance
- the flag whether the operation ignores answer threshold distance completelycomputeSize
- the number of candidate objects to compute the threshold distance to;
effective only if both useOriginalThresholdDistance
and ignoreThresholdDistance
are falsejava.lang.IllegalStateException
- if some answer has been computed alreadypublic static <T extends RankingQueryOperation> T setAnswerThresholdComputation(T operation, boolean useOriginalThresholdDistance, boolean ignoreThresholdDistance, int computeSize)
answer threshold distance
computation.
If the useOriginalThresholdDistance
is false, the threshold
distance is always LocalAbstractObject.MAX_DISTANCE
if ignoreThresholdDistance
is true. Or the threshold is computed from the first computeSize
objects.T
- the type of the operation to set the flag foroperation
- the operation to set the flag foruseOriginalThresholdDistance
- the flag whether the operation answer collection computes the threshold distanceignoreThresholdDistance
- the flag whether the operation ignores answer threshold distance completelycomputeSize
- the number of candidate objects to compute the threshold distance to;
effective only if both useOriginalThresholdDistance
and ignoreThresholdDistance
are falsepublic float getAnswerThreshold()
LocalAbstractObject.MAX_DISTANCE
is returned.
Otherwise, the distance of the last answer's object is returned.LocalAbstractObject.MAX_DISTANCE
if there are not enough objects.public RankedAbstractObject addToAnswer(AbstractObject object, float distance, float[] objectDistances) throws java.lang.IllegalArgumentException
object
- the object to adddistance
- the distance of objectobjectDistances
- the array of distances to the respective sub-objects (can be null)java.lang.IllegalArgumentException
- if the answer type of this operation requires cloning but the passed object cannot be clonedpublic void resetAnswer()
getAnswerCount()
will return zero.resetAnswer
in class QueryOperation<RankedAbstractObject>
public final void updateFrom(AbstractOperation operation) throws java.lang.IllegalArgumentException
updateFrom
in class AbstractOperation
operation
- the source operation from which to get the updatejava.lang.IllegalArgumentException
- if the answer of the specified operation is incompatible with this oneprotected void updateFrom(RankingQueryOperation operation)
RankingQueryOperation
.operation
- the source operation from which to get the updatepublic void endOperation(ErrorCode errValue) throws java.lang.IllegalArgumentException
AbstractOperation
endOperation
in class AbstractOperation
errValue
- the error code to setjava.lang.IllegalArgumentException
- if the specified error value is null or ErrorCode.NOT_SET