messif.objects
Class LocalAbstractObject

java.lang.Object
  extended by messif.objects.UniqueID
      extended by messif.objects.AbstractObject
          extended by messif.objects.LocalAbstractObject
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<UniqueID>, Clearable
Direct Known Subclasses:
BallRegion, LocalAbstractObjectAutoImpl, MetaObject, ObjectByteVector, ObjectFloatVector, ObjectIntVector, ObjectShortVector, ObjectString

public abstract class LocalAbstractObject
extends AbstractObject

This class is ancestor of all objects that hold some data the MESSI Framework can work with. Since MESSIF works with metric-based data, every descendant of LocalAbstractObject must implement a metric function getDistanceImpl(messif.objects.LocalAbstractObject, float) for its own data. To be able to read/write data from text streams, a constructor with one BufferedReader argument should be implemented to parse object data from a line of text. A dual operation should be implemented as the write(java.io.OutputStream) method. Each object can hold an additional data in its suppData attribute. However, no management is guaranteed inside MESSIF, thus, if several algorithms that use supplemental data are combined, unpredictable results might appear. This attribute is never modified inside MESSIF itself apart from the clearSurplusData() method that sets it to null.

See Also:
AbstractObject, NoDataObject, Serialized Form

Nested Class Summary
static class LocalAbstractObject.DataEqualObject
          A wrapper class that allows to hash/equal abstract objects using their data and not ID.
 
Field Summary
protected static StatisticCounter counterDistanceComputations
          Global counter for distance computations (any purpose)
protected static StatisticCounter counterLowerBoundDistanceComputations
          Global counter for lower-bound distance computations (any purpose)
protected static StatisticCounter counterUpperBoundDistanceComputations
          Global counter for upper-bound distance computations (any purpose)
static float MAX_DISTANCE
          Maximal possible distance constant
static float MIN_DISTANCE
          Minimal possible distance constant
 java.lang.Object suppData
          Supplemental data object
static float UNKNOWN_DISTANCE
          Unknown distance constant
 
Constructor Summary
protected LocalAbstractObject()
          Creates a new instance of LocalAbstractObject.
protected LocalAbstractObject(AbstractObjectKey objectKey)
          Creates a new instance of LocalAbstractObject.
protected LocalAbstractObject(BinaryInput input, BinarySerializator serializator)
          Creates a new instance of LocalAbstractObject loaded from binary input.
protected LocalAbstractObject(java.lang.String locatorURI)
          Creates a new instance of LocalAbstractObject.
 
Method Summary
protected  int binarySerialize(BinaryOutput output, BinarySerializator serializator)
          Binary-serialize this object into the output.
 void clearSurplusData()
          Clear non-messif data stored in this object.
 LocalAbstractObject clone()
          Creates and returns a copy of this object.
 LocalAbstractObject clone(boolean cloneFilterChain)
          Creates and returns a copy of this object.
 LocalAbstractObject cloneRandomlyModify(java.lang.Object... args)
          Creates and returns a randomly modified copy of this object.
static
<E extends LocalAbstractObject>
E
create(java.lang.Class<E> objectClass, java.lang.String objectData)
          Creates a new LocalAbstractObject of the specified type from string.
static
<T extends LocalAbstractObject>
T
create(java.lang.Class<T> objectClass, java.io.BufferedReader dataReader)
          Creates a new instance of objectClass from the dataReader.
 float[] createMetaDistancesHolder()
          Returns the array that can hold distances to the respective encapsulated objects.
abstract  boolean dataEquals(java.lang.Object obj)
          Indicates whether some other object has the same data as this one.
abstract  int dataHashCode()
          Returns a hash code value for the data of this object.
 boolean excludeUsingPrecompDist(LocalAbstractObject obj, float radius)
          Returns true if the obj has been excluded (filtered out) using stored precomputed distance.
protected  int getBinarySize(BinarySerializator serializator)
          Returns the exact size of the binary-serialized version of this object in bytes.
 float getDistance(LocalAbstractObject obj)
          Metric distance function.
 float getDistance(LocalAbstractObject obj, float distThreshold)
          Metric distance function.
 float getDistance(LocalAbstractObject obj, float[] metaDistances, float distThreshold)
          Metric distance function.
<T extends PrecomputedDistancesFilter>
T
getDistanceFilter(java.lang.Class<T> filterClass)
          Returns a filter of the specified class (or any of its descendants) from this object's filter chain.
<T extends PrecomputedDistancesFilter>
T
getDistanceFilter(java.lang.Class<T> filterClass, boolean inheritable)
          Returns a filter of the specified class from this object's filter chain.
 PrecomputedDistancesFilter getDistanceFilter(int position)
          Returns a filter at specified position in this object's filter chain.
protected abstract  float getDistanceImpl(LocalAbstractObject obj, float distThreshold)
          The actual implementation of the metric function (see getDistance(messif.objects.LocalAbstractObject) for full explanation).
 float getDistanceLowerBound(LocalAbstractObject obj, int accuracy)
          Returns the lower bound of a metric distance.
protected  float getDistanceLowerBoundImpl(LocalAbstractObject obj, int accuracy)
          Implementation that actually computes the lower bound on the metric distance.
 float getDistanceUpperBound(LocalAbstractObject obj, int accuracy)
          Returns the upper bound of a metric distance.
protected  float getDistanceUpperBoundImpl(LocalAbstractObject obj, int accuracy)
          Implementation that actually computes the upper bound on the metric distance.
 float getMaxDistance()
          Returns a maximal possible distance for this class.
 float getNormDistance(LocalAbstractObject obj, float distThreshold)
          Normalized metric distance function, i.e. the result of getDistance(messif.objects.LocalAbstractObject) divided by getMaxDistance().
protected static char getRandomChar()
          Returns a pseudorandom character.
protected static double getRandomNormal()
          Returns a pseudorandom number.
abstract  int getSize()
          Returns the size of this object in bytes.
 PrecomputedDistancesFilter chainDestroy()
          Destroys whole filter chain of this object.
 PrecomputedDistancesFilter chainFilter(PrecomputedDistancesFilter filter, boolean replaceIfExists)
          Adds the specified filter to the end of this object's filter chain.
 boolean includeUsingPrecompDist(LocalAbstractObject obj, float radius)
          Returns true if the obj has been included using stored precomputed distance.
protected  java.lang.String readObjectComments(java.io.BufferedReader reader)
          Processes the comment line of text representation of the object.
 boolean unchainFilter(PrecomputedDistancesFilter filter)
          Deletes the specified filter from this object's filter chain.
 void write(java.io.OutputStream stream)
          Writes the object comments and data - key and filters - into an output text stream.
 void write(java.io.OutputStream stream, boolean writeComments)
          Writes the object comments and data - key and filters - into an output text stream.
protected abstract  void writeData(java.io.OutputStream stream)
          Store this object's data to a text stream.
 
Methods inherited from class messif.objects.AbstractObject
clone, getLocatorURI, getNoDataObject, getObjectID, getObjectKey, setObjectKey, toString
 
Methods inherited from class messif.objects.UniqueID
compareTo, equals, hashCode
 
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


counterDistanceComputations

protected static final StatisticCounter counterDistanceComputations
Global counter for distance computations (any purpose)


counterLowerBoundDistanceComputations

protected static final StatisticCounter counterLowerBoundDistanceComputations
Global counter for lower-bound distance computations (any purpose)


counterUpperBoundDistanceComputations

protected static final StatisticCounter counterUpperBoundDistanceComputations
Global counter for upper-bound distance computations (any purpose)


UNKNOWN_DISTANCE

public static final float UNKNOWN_DISTANCE
Unknown distance constant

See Also:
Constant Field Values

MIN_DISTANCE

public static final float MIN_DISTANCE
Minimal possible distance constant

See Also:
Constant Field Values

MAX_DISTANCE

public static final float MAX_DISTANCE
Maximal possible distance constant

See Also:
Constant Field Values
Constructor Detail

LocalAbstractObject

protected LocalAbstractObject()
Creates a new instance of LocalAbstractObject. A new unique object ID is generated and the object's key is set to null.


LocalAbstractObject

protected LocalAbstractObject(AbstractObjectKey objectKey)
Creates a new instance of LocalAbstractObject. A new unique object ID is generated and the object's key is set to the specified key.

Parameters:
objectKey - the key to be associated with this object

LocalAbstractObject

protected LocalAbstractObject(java.lang.String locatorURI)
Creates a new instance of LocalAbstractObject. A new unique object ID is generated and a new AbstractObjectKey is generated for the specified locatorURI.

Parameters:
locatorURI - the locator URI for the new object

LocalAbstractObject

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

Parameters:
input - the input to read the LocalAbstractObject 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

getDistance

public final float getDistance(LocalAbstractObject obj)
Metric distance function. Returns the distance between this object and the object that is supplied as argument.

Parameters:
obj - the object for which to measure the distance
Returns:
the distance between this object and the provided object obj

getDistance

public final float getDistance(LocalAbstractObject obj,
                               float distThreshold)
Metric distance function. This method is intended to be used in situations such as: We are executing a range query, so all objects distant from the query object up to the query radius must be returned. In other words, all objects farther from the query object than the query radius are uninteresting. From the distance point of view, during the evaluation process of the distance between a pair of objects we can find out that the distance cannot be lower than a certain value. If this value is greater than the query radius, we can safely abort the distance evaluation since we are dealing with one of those uninteresting objects.

Parameters:
obj - the object to compute distance to
distThreshold - the threshold value on the distance (the query radius from the example above)
Returns:
the actual distance between obj and this if the distance is lower than distThreshold. Otherwise the returned value is not guaranteed to be exact, but in this respect the returned value must be greater than the threshold distance.

getDistance

public final float getDistance(LocalAbstractObject obj,
                               float[] metaDistances,
                               float distThreshold)
Metric distance function. Measures the distance between this object and obj. The array metaDistances is filled with the distances of the respective encapsulated objects if this object contains any, i.e. this object is a descendant of MetaObject.

Note that this method does not use the fast access to the precomputed distances even if there is a filter that supports it.

Parameters:
obj - the object to compute distance to
metaDistances - the array that is filled with the distances of the respective encapsulated objects, if it is not null
distThreshold - the threshold value on the distance
Returns:
the actual distance between obj and this if the distance is lower than distThreshold. Otherwise the returned value is not guaranteed to be exact, but in this respect the returned value must be greater than the threshold distance.

getDistanceImpl

protected abstract float getDistanceImpl(LocalAbstractObject obj,
                                         float distThreshold)
The actual implementation of the metric function (see getDistance(messif.objects.LocalAbstractObject) for full explanation). The implementation should not increment distanceComputations statistics.

Parameters:
obj - the object to compute distance to
distThreshold - the threshold value on the distance
Returns:
the actual distance between obj and this if the distance is lower than distThreshold

createMetaDistancesHolder

public float[] createMetaDistancesHolder()
Returns the array that can hold distances to the respective encapsulated objects. This method returns a valid array only for descendants of MetaObject, otherwise null is returned.

Returns:
the array that can hold distances to meta distances

getNormDistance

public final float getNormDistance(LocalAbstractObject obj,
                                   float distThreshold)
Normalized metric distance function, i.e. the result of getDistance(messif.objects.LocalAbstractObject) divided by getMaxDistance(). Note that unless an object overrides the getMaxDistance() the resulting distance will be too small.

Parameters:
obj - the object to compute distance to
distThreshold - the threshold value on the distance (see getDistance(messif.objects.LocalAbstractObject) for explanation)
Returns:
the actual normalized distance between obj and this if the distance is lower than distThreshold

getMaxDistance

public float getMaxDistance()
Returns a maximal possible distance for this class. This method must return the same value for all instances of this class. Default implementation returns MAX_DISTANCE.

Returns:
a maximal possible distance for this class

getDistanceLowerBound

public final float getDistanceLowerBound(LocalAbstractObject obj,
                                         int accuracy)
Returns the lower bound of a metric distance. More precisely, this method returns the lower bound on the distance between this object and the object that is supplied as argument. The function allows several levels of precision (parameter accuracy).

Parameters:
obj - the object to compute the lower-bound distance to
accuracy - the level of precision to use for the lower-bound
Returns:
the lower bound of the distance between this object and obj

getDistanceLowerBoundImpl

protected float getDistanceLowerBoundImpl(LocalAbstractObject obj,
                                          int accuracy)
Implementation that actually computes the lower bound on the metric distance.

Parameters:
obj - the object to compute lower-bound distance to
accuracy - the level of precision to use for lower-bound
Returns:
the lower bound of the distance between this object and obj

getDistanceUpperBound

public final float getDistanceUpperBound(LocalAbstractObject obj,
                                         int accuracy)
Returns the upper bound of a metric distance. More precisely, this method returns the upper bound on the distance between this object and the object that is supplied as argument. The function allows several levels of precision (parameter accuracy).

Parameters:
obj - the object to compute the upper-bound distance to
accuracy - the level of precision to use for the upper-bound
Returns:
the upper bound of the distance between this object and obj

getDistanceUpperBoundImpl

protected float getDistanceUpperBoundImpl(LocalAbstractObject obj,
                                          int accuracy)
Implementation that actually computes the upper bound on the metric distance.

Parameters:
obj - the object to compute upper-bound distance to
accuracy - the level of precision to use for upper-bound
Returns:
the upper bound of the distance between this object and obj

excludeUsingPrecompDist

public final boolean excludeUsingPrecompDist(LocalAbstractObject obj,
                                             float radius)
Returns true if the obj has been excluded (filtered out) using stored precomputed distance. Otherwise returns false, i.e. when obj must be checked using original distance (see getDistance(messif.objects.LocalAbstractObject)). In other words, method returns true if this object and obj are more distant than radius. By analogy, returns false if this object and obj are within distance radius. However, both this cases use only precomputed distances. Thus, the real distance between this object and obj can be greater than radius although the method returned false!

Parameters:
obj - the object to check the distance for
radius - the radius between this object and obj to check
Returns:
true if the obj has been excluded (filtered out) using stored precomputed distance

includeUsingPrecompDist

public final boolean includeUsingPrecompDist(LocalAbstractObject obj,
                                             float radius)
Returns true if the obj has been included using stored precomputed distance. Otherwise returns false, i.e. when obj must be checked using original distance (see getDistance(messif.objects.LocalAbstractObject)). In other words, method returns true if the distance of this object and obj is below the radius. By analogy, returns false if this object and obj are more distant than radius. However, both this cases use only precomputed distances. Thus, the real distance between this object and obj can be lower than radius although the method returned false!

Parameters:
obj - the object to check the distance for
radius - the radius between this object and obj to check
Returns:
true if the obj has been included using stored precomputed distance

getDistanceFilter

public final <T extends PrecomputedDistancesFilter> T getDistanceFilter(java.lang.Class<T> filterClass)
                                                             throws java.lang.NullPointerException
Returns a filter of the specified class (or any of its descendants) from this object's filter chain. If there is no filter with requested class, this method returns null. If there are more filters of the same class, the first one is returned.

Type Parameters:
T - the class of the filter to retrieve from the chain
Parameters:
filterClass - the class of the filter to retrieve from the chain
Returns:
a filter of specified class from this object's filter chain
Throws:
java.lang.NullPointerException - if the filterClass is null

getDistanceFilter

public final <T extends PrecomputedDistancesFilter> T getDistanceFilter(java.lang.Class<T> filterClass,
                                                                        boolean inheritable)
                                                             throws java.lang.NullPointerException
Returns a filter of the specified class from this object's filter chain. If there is no filter with requested class, this method returns null. If there are more filters of the same class, the first one is returned.

Type Parameters:
T - the class of the filter to retrieve from the chain
Parameters:
filterClass - the class of the filter to retrieve from the chain
inheritable - if false, the exact match of filterClass is required; otherwise the first filter that is assignable to filterClass is returned
Returns:
a filter of specified class from this object's filter chain
Throws:
java.lang.NullPointerException - if the filterClass is null

getDistanceFilter

public final PrecomputedDistancesFilter getDistanceFilter(int position)
                                                   throws java.lang.IndexOutOfBoundsException
Returns a filter at specified position in this object's filter chain.

Parameters:
position - a zero based position in the chain (zero returns this filter, negative value returns the last filter)
Returns:
a filter at specified position in this filter's chain
Throws:
java.lang.IndexOutOfBoundsException - if the specified position is too big

chainFilter

public final PrecomputedDistancesFilter chainFilter(PrecomputedDistancesFilter filter,
                                                    boolean replaceIfExists)
                                             throws java.lang.IllegalArgumentException
Adds the specified filter to the end of this object's filter chain.

Parameters:
filter - the filter to add to this object's filter chain
replaceIfExists - if true and there is another filter with the same class as the inserted filter, it is replaced
Returns:
either the replaced or the existing filter that has the same class as the newly inserted one; null is returned if the filter was appended to the end of the chain
Throws:
java.lang.IllegalArgumentException - if the provided chain has set nextFilter attribute

unchainFilter

public final boolean unchainFilter(PrecomputedDistancesFilter filter)
Deletes the specified filter from this object's filter chain. A concerete instance of filter is deleted (the same reference must be present in the chain).

Parameters:
filter - the concrete instance of filter to delete from this object's filter chain
Returns:
true if the filter was unchained (deleted). If the given filter was not found, false is returned.

chainDestroy

public final PrecomputedDistancesFilter chainDestroy()
Destroys whole filter chain of this object. The first (head of the chain) filter is returned.

Returns:
the first filter in the chain; the rest of the chain can be obtained by calling getNextFilter

clearSurplusData

public void clearSurplusData()
Clear non-messif data stored in this object. In addition to changing object key, this method removes the supplemental data and all distance filters.

Specified by:
clearSurplusData in interface Clearable
Overrides:
clearSurplusData in class AbstractObject

getRandomNormal

protected static double getRandomNormal()
Returns a pseudorandom number. The generator has normal distribution not the default standardized.

Returns:
a pseudorandom double greater than or equal to 0.0 and less than 1.0

getRandomChar

protected static char getRandomChar()
Returns a pseudorandom character.

Returns:
a pseudorandom char greater than or equal to a and less than z

create

public static <T extends LocalAbstractObject> T create(java.lang.Class<T> objectClass,
                                                       java.io.BufferedReader dataReader)
                                            throws java.lang.IllegalArgumentException,
                                                   java.lang.reflect.InvocationTargetException
Creates a new instance of objectClass from the dataReader. The constructor of the LocalAbstractObject that reads the textual data is used.

Type Parameters:
T - the class of the object to create
Parameters:
objectClass - the class of the object to create
dataReader - the buffered reader of the object data
Returns:
a new instance of objectClass
Throws:
java.lang.IllegalArgumentException - if the class has is no stream constructor
java.lang.reflect.InvocationTargetException - if there was an error during creating a new object instance

create

public static <E extends LocalAbstractObject> E create(java.lang.Class<E> objectClass,
                                                       java.lang.String objectData)
                                            throws java.lang.IllegalArgumentException,
                                                   java.lang.reflect.InvocationTargetException
Creates a new LocalAbstractObject of the specified type from string. The object data is feeded through string buffer stream to the stream constructor of the object.

Type Parameters:
E - the class of the object to create
Parameters:
objectClass - the class of the object to create
objectData - the string that contains object's data
Returns:
a new instance of the specified class
Throws:
java.lang.IllegalArgumentException - if the specified class lacks a public BufferedReader constructor
java.lang.reflect.InvocationTargetException - if there was an error during creating a new object instance

clone

public final LocalAbstractObject clone()
                                throws java.lang.CloneNotSupportedException
Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object.

Overrides:
clone in class AbstractObject
Returns:
a clone of this instance
Throws:
java.lang.CloneNotSupportedException - if the object's class does not support clonning or there was an error

clone

public LocalAbstractObject clone(boolean cloneFilterChain)
                          throws java.lang.CloneNotSupportedException
Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object.

Parameters:
cloneFilterChain - the flag whether the filter chain should be clonned as well
Returns:
a clone of this instance
Throws:
java.lang.CloneNotSupportedException - if the object's class does not support clonning or there was an error

cloneRandomlyModify

public LocalAbstractObject cloneRandomlyModify(java.lang.Object... args)
                                        throws java.lang.CloneNotSupportedException
Creates and returns a randomly modified copy of this object. The modification depends on particular subclass implementation.

Parameters:
args - any parameters required by the subclass implementation - usually two objects with the miminal and the maximal possible values
Returns:
a randomly modified clone of this instance
Throws:
java.lang.CloneNotSupportedException - if the object's class does not support clonning or there was an error

getSize

public abstract int getSize()
Returns the size of this object in bytes.

Returns:
the size of this object in bytes

dataEquals

public abstract boolean dataEquals(java.lang.Object obj)
Indicates whether some other object has the same data as this one.

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

dataHashCode

public abstract int dataHashCode()
Returns a hash code value for the data of this object.

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

readObjectComments

protected java.lang.String readObjectComments(java.io.BufferedReader reader)
                                       throws java.io.EOFException,
                                              java.io.IOException
Processes the comment line of text representation of the object. The comment is of format "#typeOfComment class value". Recognized types of comments are:

Parameters:
reader - the reader from which to get lines with comments
Returns:
the first line that does not have the requested format (this method never returns null)
Throws:
java.io.EOFException - if the last line was read
java.io.IOException - if the comment type was recognized but its value is illegal

write

public final void write(java.io.OutputStream stream)
                 throws java.io.IOException
Writes the object comments and data - key and filters - into an output text stream. Writes the following comments: The data are stored by a overriden method writeData.

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

write

public final void write(java.io.OutputStream stream,
                        boolean writeComments)
                 throws java.io.IOException
Writes the object comments and data - key and filters - into an output text stream. Writes the following comments: The data are stored by a overriden method writeData.

Parameters:
stream - the stream to write the comments and data to
writeComments - if true then the comments are written
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 object's data to a text stream. This method should have the opposite deserialization in constructor of a given object class.

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

binarySerialize

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

Overrides:
binarySerialize in class AbstractObject
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

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

Overrides:
getBinarySize in class AbstractObject
Parameters:
serializator - the serializator used to write objects
Returns:
size of the binary-serialized version of this object