|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectmessif.objects.UniqueID
messif.objects.AbstractObject
messif.objects.LocalAbstractObject
public abstract class LocalAbstractObject
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.
AbstractObject
,
NoDataObject
,
Serialized FormNested 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
|
create(java.lang.Class<E> objectClass,
java.lang.String objectData)
Creates a new LocalAbstractObject of the specified type from string. |
|
static
|
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. |
|
|
getDistanceFilter(java.lang.Class<T> filterClass)
Returns a filter of the specified class (or any of its descendants) from this object's filter chain. |
|
|
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 |
---|
public java.lang.Object suppData
protected static final StatisticCounter counterDistanceComputations
protected static final StatisticCounter counterLowerBoundDistanceComputations
protected static final StatisticCounter counterUpperBoundDistanceComputations
public static final float UNKNOWN_DISTANCE
public static final float MIN_DISTANCE
public static final float MAX_DISTANCE
Constructor Detail |
---|
protected LocalAbstractObject()
protected LocalAbstractObject(AbstractObjectKey objectKey)
objectKey
- the key to be associated with this objectprotected LocalAbstractObject(java.lang.String locatorURI)
AbstractObjectKey
is generated for
the specified locatorURI
.
locatorURI
- the locator URI for the new objectprotected LocalAbstractObject(BinaryInput input, BinarySerializator serializator) throws java.io.IOException
input
- the input to read the LocalAbstractObject fromserializator
- the serializator used to write objects
java.io.IOException
- if there was an I/O error reading from the inputMethod Detail |
---|
public final float getDistance(LocalAbstractObject obj)
obj
- the object for which to measure the distance
obj
public final float getDistance(LocalAbstractObject obj, float distThreshold)
obj
- the object to compute distance todistThreshold
- the threshold value on the distance (the query radius from the example above)
public final float getDistance(LocalAbstractObject obj, float[] metaDistances, float distThreshold)
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.
obj
- the object to compute distance tometaDistances
- the array that is filled with the distances of the respective encapsulated objects, if it is not nulldistThreshold
- the threshold value on the distance
protected abstract float getDistanceImpl(LocalAbstractObject obj, float distThreshold)
getDistance(messif.objects.LocalAbstractObject)
for full explanation).
The implementation should not increment distanceComputations statistics.
obj
- the object to compute distance todistThreshold
- the threshold value on the distance
public float[] createMetaDistancesHolder()
MetaObject
,
otherwise null is returned.
public final float getNormDistance(LocalAbstractObject obj, float distThreshold)
getDistance(messif.objects.LocalAbstractObject)
divided by getMaxDistance()
. Note that unless an object overrides
the getMaxDistance()
the resulting distance will be too small.
obj
- the object to compute distance todistThreshold
- the threshold value on the distance (see getDistance(messif.objects.LocalAbstractObject)
for explanation)
public float getMaxDistance()
MAX_DISTANCE
.
public final float getDistanceLowerBound(LocalAbstractObject obj, int accuracy)
obj
- the object to compute the lower-bound distance toaccuracy
- the level of precision to use for the lower-bound
obj
protected float getDistanceLowerBoundImpl(LocalAbstractObject obj, int accuracy)
obj
- the object to compute lower-bound distance toaccuracy
- the level of precision to use for lower-bound
obj
public final float getDistanceUpperBound(LocalAbstractObject obj, int accuracy)
obj
- the object to compute the upper-bound distance toaccuracy
- the level of precision to use for the upper-bound
obj
protected float getDistanceUpperBoundImpl(LocalAbstractObject obj, int accuracy)
obj
- the object to compute upper-bound distance toaccuracy
- the level of precision to use for upper-bound
obj
public final boolean excludeUsingPrecompDist(LocalAbstractObject obj, float radius)
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!
obj
- the object to check the distance forradius
- the radius between this
object and obj
to check
obj
has been excluded (filtered out) using stored precomputed distancepublic final boolean includeUsingPrecompDist(LocalAbstractObject obj, float radius)
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!
obj
- the object to check the distance forradius
- the radius between this
object and obj
to check
public final <T extends PrecomputedDistancesFilter> T getDistanceFilter(java.lang.Class<T> filterClass) throws java.lang.NullPointerException
T
- the class of the filter to retrieve from the chainfilterClass
- the class of the filter to retrieve from the chain
java.lang.NullPointerException
- if the filterClass is nullpublic final <T extends PrecomputedDistancesFilter> T getDistanceFilter(java.lang.Class<T> filterClass, boolean inheritable) throws java.lang.NullPointerException
T
- the class of the filter to retrieve from the chainfilterClass
- the class of the filter to retrieve from the chaininheritable
- if false, the exact match of filterClass
is required;
otherwise the first filter that is assignable to filterClass
is returned
java.lang.NullPointerException
- if the filterClass is nullpublic final PrecomputedDistancesFilter getDistanceFilter(int position) throws java.lang.IndexOutOfBoundsException
position
- a zero based position in the chain (zero returns this filter, negative value returns the last filter)
java.lang.IndexOutOfBoundsException
- if the specified position is too bigpublic final PrecomputedDistancesFilter chainFilter(PrecomputedDistancesFilter filter, boolean replaceIfExists) throws java.lang.IllegalArgumentException
filter
- the filter to add to this object's filter chainreplaceIfExists
- if true and there is another filter with the same class as the inserted filter, it is replaced
java.lang.IllegalArgumentException
- if the provided chain has set nextFilter attributepublic final boolean unchainFilter(PrecomputedDistancesFilter filter)
filter
- the concrete instance of filter to delete from this object's filter chain
public final PrecomputedDistancesFilter chainDestroy()
getNextFilter
public void clearSurplusData()
supplemental data
and
all distance filters
.
clearSurplusData
in interface Clearable
clearSurplusData
in class AbstractObject
protected static double getRandomNormal()
double
greater than or equal
to 0.0
and less than 1.0
protected static char getRandomChar()
char
greater than or equal
to a and less than zpublic static <T extends LocalAbstractObject> T create(java.lang.Class<T> objectClass, java.io.BufferedReader dataReader) throws java.lang.IllegalArgumentException, java.lang.reflect.InvocationTargetException
objectClass
from the dataReader
.
The constructor of the LocalAbstractObject
that reads the textual
data is used.
T
- the class of the object to createobjectClass
- the class of the object to createdataReader
- the buffered reader of the object data
objectClass
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 instancepublic static <E extends LocalAbstractObject> E create(java.lang.Class<E> objectClass, java.lang.String objectData) throws java.lang.IllegalArgumentException, java.lang.reflect.InvocationTargetException
E
- the class of the object to createobjectClass
- the class of the object to createobjectData
- the string that contains object's data
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 instancepublic final LocalAbstractObject clone() throws java.lang.CloneNotSupportedException
clone
in class AbstractObject
java.lang.CloneNotSupportedException
- if the object's class does not support clonning or there was an errorpublic LocalAbstractObject clone(boolean cloneFilterChain) throws java.lang.CloneNotSupportedException
cloneFilterChain
- the flag whether the filter chain should be clonned as well
java.lang.CloneNotSupportedException
- if the object's class does not support clonning or there was an errorpublic LocalAbstractObject cloneRandomlyModify(java.lang.Object... args) throws java.lang.CloneNotSupportedException
args
- any parameters required by the subclass implementation - usually two objects with
the miminal and the maximal possible values
java.lang.CloneNotSupportedException
- if the object's class does not support clonning or there was an errorpublic abstract int getSize()
public abstract boolean dataEquals(java.lang.Object obj)
obj
- the reference object with which to compare.
true
if this object is the same as the obj
argument; false
otherwise.public abstract int dataHashCode()
protected java.lang.String readObjectComments(java.io.BufferedReader reader) throws java.io.EOFException, java.io.IOException
sets the object key
adds a precomputed distances filter
reader
- the reader from which to get lines with comments
java.io.EOFException
- if the last line was read
java.io.IOException
- if the comment type was recognized but its value is illegalpublic final void write(java.io.OutputStream stream) throws java.io.IOException
writeData
.
stream
- the stream to write the comments and data to
java.io.IOException
- if any problem occures during comment writingpublic final void write(java.io.OutputStream stream, boolean writeComments) throws java.io.IOException
writeData
.
stream
- the stream to write the comments and data towriteComments
- if true then the comments are written
java.io.IOException
- if any problem occures during comment writingprotected abstract void writeData(java.io.OutputStream stream) throws java.io.IOException
stream
- the stream to store this object to
java.io.IOException
- if there was an error while writing to streamprotected int binarySerialize(BinaryOutput output, BinarySerializator serializator) throws java.io.IOException
output
.
binarySerialize
in class AbstractObject
output
- the output that this object is binary-serialized intoserializator
- the serializator used to write objects
java.io.IOException
- if there was an I/O error during serializationprotected int getBinarySize(BinarySerializator serializator)
getBinarySize
in class AbstractObject
serializator
- the serializator used to write objects
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |