messif.objects
Class PrecomputedDistancesFilter

java.lang.Object
  extended by messif.objects.PrecomputedDistancesFilter
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, BinarySerializable
Direct Known Subclasses:
PrecomputedDistancesFixedArrayFilter, PrecomputedDistancesPivotMapFilter

public abstract class PrecomputedDistancesFilter
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable, BinarySerializable

This class provides a framework for metric-distance filtering techniques. Using a triangle inequality prperty of the metric space, some distance calculations can be avoided provided there is some additional information - the precomputed distances.

A filter is added to a LocalAbstractObject via its chainFilter method. Objects can have several filters chained - if the first filter fails to avoid the computation, the next is used and so on. The filters are then used automatically whenever a distance computation is evaluated.

See Also:
Serialized Form

Field Summary
protected static StatisticCounter counterPrecomputedDistanceSavings
          Global counter for saving distance computations by using precomputed
 
Constructor Summary
protected PrecomputedDistancesFilter()
          Creates a new instance of PrecomputedDistancesFilter.
protected PrecomputedDistancesFilter(BinaryInput input, BinarySerializator serializator)
          Creates a new instance of PrecomputedDistancesFilter loaded from binary input.
 
Method Summary
 int binarySerialize(BinaryOutput output, BinarySerializator serializator)
          Binary-serialize this object into the output.
 java.lang.Object clone()
          Creates and returns a copy of this object.
 boolean excludeUsingPrecompDist(PrecomputedDistancesFilter targetFilter, float radius)
          Returns true if object associated with targetFilter filter can be excluded (filtered out) using this precomputed distances.
protected abstract  boolean excludeUsingPrecompDistImpl(PrecomputedDistancesFilter targetFilter, float radius)
          Returns true if object associated with targetFilter filter can be excluded (filtered out) using this precomputed distances.
 int getBinarySize(BinarySerializator serializator)
          Returns the exact size of the binary-serialized version of this object in bytes.
 PrecomputedDistancesFilter getNextFilter()
          Returns the next filter in this filter's chain.
 float getPrecomputedDistance(LocalAbstractObject obj)
          Returns the precomputed distance to an object.
protected abstract  float getPrecomputedDistanceImpl(LocalAbstractObject obj)
          Implement this method to return the precomputed distance to an object.
 boolean includeUsingPrecompDist(PrecomputedDistancesFilter targetFilter, float radius)
          Returns true if object associated with targetFilter filter can be included using this precomputed distances.
protected abstract  boolean includeUsingPrecompDistImpl(PrecomputedDistancesFilter targetFilter, float radius)
          Returns true if object associated with targetFilter filter can be included using this precomputed distances.
protected abstract  boolean isDataWritable()
          Returns whether this filter's data can be written to a text stream.
abstract  boolean isGetterSupported()
          Returns true if this object supports getPrecomputedDistance(messif.objects.LocalAbstractObject) method.
 void write(java.io.OutputStream stream)
          Writes this distances filter into the output text stream.
protected abstract  void writeData(java.io.OutputStream stream)
          Store this filter's data to a text stream.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

counterPrecomputedDistanceSavings

protected static StatisticCounter counterPrecomputedDistanceSavings
Global counter for saving distance computations by using precomputed

Constructor Detail

PrecomputedDistancesFilter

protected PrecomputedDistancesFilter()
Creates a new instance of PrecomputedDistancesFilter.


PrecomputedDistancesFilter

protected PrecomputedDistancesFilter(BinaryInput input,
                                     BinarySerializator serializator)
                              throws java.io.IOException
Creates a new instance of PrecomputedDistancesFilter loaded from binary input.

Parameters:
input - the input to read the PrecomputedDistancesFilter from
serializator - the serializator used to write objects
Throws:
java.io.IOException - if there was an I/O error reading from the input
Method Detail

getNextFilter

public PrecomputedDistancesFilter getNextFilter()
Returns the next filter in this filter's chain.

Returns:
the next filter in this filter's chain

getPrecomputedDistance

public final float getPrecomputedDistance(LocalAbstractObject obj)
Returns the precomputed distance to an object. If there is no distance associated with the object obj the function returns UNKNOWN_DISTANCE.

Parameters:
obj - the object for which the precomputed distance is returned
Returns:
the precomputed distance to an object

isGetterSupported

public abstract boolean isGetterSupported()
Returns true if this object supports getPrecomputedDistance(messif.objects.LocalAbstractObject) method.

Returns:
true if this object supports getPrecomputedDistance(messif.objects.LocalAbstractObject) method

getPrecomputedDistanceImpl

protected abstract float getPrecomputedDistanceImpl(LocalAbstractObject obj)
Implement this method to return the precomputed distance to an object. If there is no distance associated with the object obj the function should return UNKNOWN_DISTANCE.

Parameters:
obj - the object for which the precomputed distance is returned
Returns:
the precomputed distance to an object

excludeUsingPrecompDist

public final boolean excludeUsingPrecompDist(PrecomputedDistancesFilter targetFilter,
                                             float radius)
Returns true if object associated with targetFilter filter can be excluded (filtered out) using this precomputed distances. See LocalAbstractObject.excludeUsingPrecompDist(messif.objects.LocalAbstractObject, float) for full explanation.

Parameters:
targetFilter - the target precomputed distances
radius - the radius to check the precomputed distances for
Returns:
true if object associated with targetFilter filter can be excluded (filtered out) using this precomputed distances

includeUsingPrecompDist

public final boolean includeUsingPrecompDist(PrecomputedDistancesFilter targetFilter,
                                             float radius)
Returns true if object associated with targetFilter filter can be included using this precomputed distances. See LocalAbstractObject.includeUsingPrecompDist(messif.objects.LocalAbstractObject, float) for full explanation.

Parameters:
targetFilter - the target precomputed distances
radius - the radius to check the precomputed distances for
Returns:
true if object associated with targetFilter filter can be included using this precomputed distances

excludeUsingPrecompDistImpl

protected abstract boolean excludeUsingPrecompDistImpl(PrecomputedDistancesFilter targetFilter,
                                                       float radius)
Returns true if object associated with targetFilter filter can be excluded (filtered out) using this precomputed distances. See LocalAbstractObject.excludeUsingPrecompDist(messif.objects.LocalAbstractObject, float) for full explanation.

Parameters:
targetFilter - the target precomputed distances
radius - the radius to check the precomputed distances for
Returns:
true if object associated with targetFilter filter can be excluded (filtered out) using this precomputed distances

includeUsingPrecompDistImpl

protected abstract boolean includeUsingPrecompDistImpl(PrecomputedDistancesFilter targetFilter,
                                                       float radius)
Returns true if object associated with targetFilter filter can be included using this precomputed distances. See LocalAbstractObject.includeUsingPrecompDist(messif.objects.LocalAbstractObject, float) for full explanation.

Parameters:
targetFilter - the target precomputed distances
radius - the radius to check the precomputed distances for
Returns:
true if object associated with targetFilter filter can be included using this precomputed distances

write

public final void write(java.io.OutputStream stream)
                 throws java.io.IOException
Writes this distances filter into the output text stream. The key is written using the following format:
#filter filterClass filter value

Parameters:
stream - the stream to write the key to
Throws:
java.io.IOException - if any problem occures during comment writing

writeData

protected abstract void writeData(java.io.OutputStream stream)
                           throws java.io.IOException
Store this filter's data to a text stream. This method should have the opposite deserialization in constructor. Note that this method should not write a line separator (\n).

Parameters:
stream - the stream to store this object to
Throws:
java.io.IOException - if there was an error while writing to stream

isDataWritable

protected abstract boolean isDataWritable()
Returns whether this filter's data can be written to a text stream. Note that the method writeData(java.io.OutputStream) should provide a valid writing implementation.

Returns:
true if this filter can be written to a text stream

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Creates and returns a copy of this object.

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

binarySerialize

public int binarySerialize(BinaryOutput output,
                           BinarySerializator serializator)
                    throws java.io.IOException
Binary-serialize this object into the output.

Specified by:
binarySerialize in interface BinarySerializable
Parameters:
output - the output that this object is binary-serialized into
serializator - the serializator used to write objects
Returns:
the number of bytes actually written
Throws:
java.io.IOException - if there was an I/O error during serialization

getBinarySize

public int getBinarySize(BinarySerializator serializator)
Returns the exact size of the binary-serialized version of this object in bytes.

Specified by:
getBinarySize in interface BinarySerializable
Parameters:
serializator - the serializator used to write objects
Returns:
size of the binary-serialized version of this object