biz.chitec.quarterback.util
Class ValueHistoryStorage

java.lang.Object
  biz.chitec.quarterback.util.ValueHistoryStorage

All Implemented Interfaces:

java.io.Serializable

public class ValueHistoryStorage

extends java.lang.Object

implements java.io.Serializable

Storage for development of a value through the time. Integer values which evolve over the time are a quite common data pattern. This class allows to store those values, evaluate them and do further work on then, especially regarding statistical needs.

The class' main idea is that certain changes of a value occur and will be accumulated. These changes are stored in a relative way first (incremented by one, decremented by two etc.), and can be turned into absolute values in a second step. This "absolutifying" can be done for an arbitrary head part of the stored values only, also. This is useful in case that the data is archieved in a way that it is possible to ensure that no more changes will occur to data earlier than a certain point of time.

Under the same assumption, a split operation is implemented which splits any first part from the storage and returns it separately. Any finished parts can be handled separately this way.

ValueHistoryStorage implements some basic functions for evaluating the selected data. Namely, this is the possibility to generate average values over the cumulated data for certain time ranges. This allows a wide variety of statistical evaluations on the data.

This class is built on the Collection framework of Java 1.2 and supports the chitec GJSA for String-encapsulated transmission over network connections.

Version:

$Id: ccb1826e949925f5c417c3f176724c9c46b21e7d $

Author:

chitec/Dirk Hillbrecht 2002 Distributed under the terms of the GNU LGPL.

See Also:

Serialized Form

Nested Class Summary

private static class	ValueHistoryStorage.QuantiEntry Small helper class for the QuantifiedIterator.
private class	ValueHistoryStorage.QuantifiedIterator Quantification iterator.
static class	ValueHistoryStorage.ValueMark Helper class to store a value at a certain point of time.

Field Summary

private java.util.TreeMap	data The data of the storage.
private static java.text.NumberFormat	doubleformatter Static formatter for debugging purposes.
private boolean	hasabsvalues Internal markers to store whether absolute or relative values exist in the storage.
private boolean	hasrelvalues Internal markers to store whether absolute or relative values exist in the storage.
private EDate	maxabsolutified Maximum date with an absolute value.
private EDate	maxdate minimum and maximum date.
private EDate	mindate minimum and maximum date.
private EDate	minrelativified Minimum date with a relative value.
private EDate	quantifier quantifier for quantifiying on input.

Constructor Summary

	ValueHistoryStorage() Initializes the storage without any date restrictions.
	ValueHistoryStorage(EDate mind, EDate maxd) Initializes the storage with an interval in which it should operate.
	ValueHistoryStorage(EDate mind, EDate maxd, EDate qx) Initializes the storage with an interval in which it should operate and a quantifier.
private	ValueHistoryStorage(EDate mind, EDate maxd, EDate qx, boolean hasabsx, boolean hasrelx, EDate maxabsx, EDate minrelx, java.util.TreeMap dx) Internal constructor setting all values.

Method Summary

void	absolutify() Absolutify the whole storage.
void	absolutify(EDate lastabsolute) Absolutifies from beginning up to a certain date.
void	canonify() Drops unneeded information.
static ValueHistoryStorage	createInstanceGJSA(java.lang.Object[] o) Create an instance of this class by GJSA data.
void	cumulateRelative(EDate thedate, int relval) Cumulate a relative value for any point of time.
private boolean	dateEquals(EDate d1, EDate d2) Convenience function to compare possibly nulled dates.
void	ensureAvailability(EDate adate) Ensures, that for a certain point of time, a value exists.
boolean	equals(java.lang.Object o) Compare storage with another one.
int	get(EDate d) Get absolute data at a certain point of time.
java.lang.Object[]	getGJSAData() Returns the private content of the object as an array.
EDate	getMaxDate() Get maximum date.
EDate	getMinDate() Get minimum date.
java.util.Iterator	getQuantifiedIterator(EDate distance) Get iterator for whole time range of the storage.
java.util.Iterator	getQuantifiedIterator(EDate from, EDate until, EDate distance) Return an iterator with quantified average values for the stored data.
java.util.Iterator	getQuantifiedIterator(java.util.Iterator it) Get iterator for whole time range of the storage.
java.util.Iterator	getQuantifiedIterator(java.util.Iterator it, EDate until) Return iterator with quantified average values for the stored data.
java.util.SortedMap	getQuantifiedMap(EDate distance) Returns map with average values through the whole storage.
java.util.SortedMap	getQuantifiedMap(EDate from, EDate until, EDate distance) Return quantified values as a map.
void	mergeWith(ValueHistoryStorage other) Merges this storage with another. both storages should store data of disjunct time ranges.
private EDate	prepareDate(EDate thedate, boolean dropoutranged) Prepare date internally.
void	relativify() Relativifies the whole storage.
void	relativify(EDate lastrelative) Relativifies from a certain point of time to the end of the storage.
void	setAbsolute(EDate thedate, int absval) Set an absolute value for any point of time.
void	setMaxDate(EDate mdx) Set maximum date.
void	setMinDate(EDate mdx) Set minimum date.
void	setQuantifier(EDate qx) Set quantifier.
ValueHistoryStorage	splitAt(EDate split) Splits the storage into two independant parts.
java.lang.String	toString() For debugging purposes only.

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

data

private java.util.TreeMap data

The data of the storage.

mindate

private EDate mindate

minimum and maximum date. Can be null.

maxdate

private EDate maxdate

minimum and maximum date. Can be null.

quantifier

private EDate quantifier

quantifier for quantifiying on input. Should not be used.

hasabsvalues

private boolean hasabsvalues

Internal markers to store whether absolute or relative values exist in the storage.

hasrelvalues

private boolean hasrelvalues

Internal markers to store whether absolute or relative values exist in the storage.

maxabsolutified

private EDate maxabsolutified

Maximum date with an absolute value. Later, there are only relative values. It is, however, possible, that there are relative values before this date.

minrelativified

private EDate minrelativified

Minimum date with a relative value. Earlier, there are only absolute values. It is, however, possible, that there are also absolute values after this one.

doubleformatter

private static java.text.NumberFormat doubleformatter

Static formatter for debugging purposes.

Constructor Detail

ValueHistoryStorage

public ValueHistoryStorage()

Initializes the storage without any date restrictions.

ValueHistoryStorage

public ValueHistoryStorage(EDate mind,
                           EDate maxd)

Initializes the storage with an interval in which it should operate.

Parameters:

mind - Description of the Parameter

maxd - Description of the Parameter

ValueHistoryStorage

public ValueHistoryStorage(EDate mind,
                           EDate maxd,
                           EDate qx)

Initializes the storage with an interval in which it should operate and a quantifier. The quantifier is used when inserting the values into the storage. It should be left out for the moment.

Parameters:

mind - Description of the Parameter

maxd - Description of the Parameter

qx - Description of the Parameter

ValueHistoryStorage

private ValueHistoryStorage(EDate mind,
                            EDate maxd,
                            EDate qx,
                            boolean hasabsx,
                            boolean hasrelx,
                            EDate maxabsx,
                            EDate minrelx,
                            java.util.TreeMap dx)

Internal constructor setting all values. Called by all other constructors.

Parameters:

mind - Description of the Parameter

maxd - Description of the Parameter

qx - Description of the Parameter

hasabsx - Description of the Parameter

hasrelx - Description of the Parameter

maxabsx - Description of the Parameter

minrelx - Description of the Parameter

dx - Description of the Parameter

Method Detail

getGJSAData

public java.lang.Object[] getGJSAData()

Returns the private content of the object as an array. Allows GJSA to access private components of this object.

createInstanceGJSA

public static ValueHistoryStorage createInstanceGJSA(java.lang.Object[] o)

Create an instance of this class by GJSA data. Needed as the constructor used by this method is private.

setMinDate

public void setMinDate(EDate mdx)

Set minimum date. Does not change already stored data. Better do not use at the moment.

Parameters:

mdx - The new minDate value

getMinDate

public EDate getMinDate()

Get minimum date.

Returns:

The minDate value

setMaxDate

public void setMaxDate(EDate mdx)

Set maximum date. Does not change already stored data. Better do not use at the moment.

Parameters:

mdx - The new maxDate value

getMaxDate

public EDate getMaxDate()

Get maximum date.

Returns:

The maxDate value

setQuantifier

public void setQuantifier(EDate qx)

Set quantifier. Does not change already stored data. Better do not use at the moment.

Parameters:

qx - The new quantifier value

prepareDate

private EDate prepareDate(EDate thedate,
                          boolean dropoutranged)

Prepare date internally. The date is compared to minimum and maximum date (if available). If it is outside the time range, it is dropped accordingly to the second parameter. If quantifier is set, the date is normed to the quantifier.

Parameters:

thedate - Description of the Parameter

dropoutranged - Description of the Parameter

Returns:

Description of the Return Value

setAbsolute

public void setAbsolute(EDate thedate,
                        int absval)

Set an absolute value for any point of time. If the date exceeds the time range for the storage, the value is dropped silently.

Parameters:

thedate - The new absolute value

absval - The new absolute value

cumulateRelative

public void cumulateRelative(EDate thedate,
                             int relval)

Cumulate a relative value for any point of time. If the date exceeds the time range of the storage, the relative information is cumulated to the information at the appropriate end of the interval.

Parameters:

thedate - Description of the Parameter

relval - Description of the Parameter

get

public int get(EDate d)

Get absolute data at a certain point of time. This method does _not_ interpolate the dates. If no data exist for the given point of time Integer.MIN_VALUE is returned.

Parameters:

d - Description of the Parameter

Returns:

Description of the Return Value

canonify

public void canonify()

Drops unneeded information. Unneeded are absolute values which do not differ from the previous absolute value and relative values of zero. A value for the minimum date of the interval is never deleted.

absolutify

public void absolutify()

Absolutify the whole storage. This method does work even if absolute and relative values are mixed, as is relativities the storage first in this case.

absolutify

public void absolutify(EDate lastabsolute)

Absolutifies from beginning up to a certain date.

Parameters:

lastabsolute - Description of the Parameter

relativify

public void relativify()

Relativifies the whole storage.

relativify

public void relativify(EDate lastrelative)

Relativifies from a certain point of time to the end of the storage.

Parameters:

lastrelative - Description of the Parameter

ensureAvailability

public void ensureAvailability(EDate adate)

Ensures, that for a certain point of time, a value exists. This is somehow an inverse operation to canonify().

Parameters:

adate - Description of the Parameter

splitAt

public ValueHistoryStorage splitAt(EDate split)

Splits the storage into two independant parts. The storage is split into one part containing only information for dates before the given split date and another one with everything at and after the given date. The actual data is not copied for this operation, but the map structures are.

The returned storage contains only absolute values.

Parameters:

split - Description of the Parameter

Returns:

Description of the Return Value

mergeWith

public void mergeWith(ValueHistoryStorage other)

Merges this storage with another. both storages should store data of disjunct time ranges. If any values are on equal date, other's value will override this' ones. Note that both storages are absolutified before merging.

Parameters:

other - Description of the Parameter

dateEquals

private boolean dateEquals(EDate d1,
                           EDate d2)

Convenience function to compare possibly nulled dates.

Parameters:

d1 - Description of the Parameter

d2 - Description of the Parameter

Returns:

Description of the Return Value

equals

public boolean equals(java.lang.Object o)

Compare storage with another one.

Parameters:

o - Description of the Parameter

Returns:

Description of the Return Value

getQuantifiedIterator

public java.util.Iterator getQuantifiedIterator(EDate from,
                                                EDate until,
                                                EDate distance)

Return an iterator with quantified average values for the stored data. The data is evaluated in the given time range and in portions of distance size. The iterator returns Map.Entry-pairs, one for each interval. The key is the date of the beginning of the interval, the value is the average of all stored data in this interval.

Parameters:

from - Description of the Parameter

until - Description of the Parameter

distance - Description of the Parameter

Returns:

The quantifiedIterator value

getQuantifiedIterator

public java.util.Iterator getQuantifiedIterator(java.util.Iterator it,
                                                EDate until)

Return iterator with quantified average values for the stored data. The quantification intervals are obtained from the given iterator, what allows non-equally-sized intervals.

Parameters:

it - Description of the Parameter

until - Description of the Parameter

Returns:

The quantifiedIterator value

getQuantifiedIterator

public java.util.Iterator getQuantifiedIterator(EDate distance)

Get iterator for whole time range of the storage. Works only with storages being resticted on both sides.

Parameters:

distance - Description of the Parameter

Returns:

The quantifiedIterator value

getQuantifiedIterator

public java.util.Iterator getQuantifiedIterator(java.util.Iterator it)

Get iterator for whole time range of the storage. Between-points are given by the iterator.

Parameters:

it - Description of the Parameter

Returns:

The quantifiedIterator value

getQuantifiedMap

public java.util.SortedMap getQuantifiedMap(EDate from,
                                            EDate until,
                                            EDate distance)

Return quantified values as a map. Iterates internally through the iterator and delivers the result as a map.

Parameters:

from - Description of the Parameter

until - Description of the Parameter

distance - Description of the Parameter

Returns:

The quantifiedMap value

getQuantifiedMap

public java.util.SortedMap getQuantifiedMap(EDate distance)

Returns map with average values through the whole storage.

Parameters:

distance - Description of the Parameter

Returns:

The quantifiedMap value

toString

public java.lang.String toString()

For debugging purposes only.

Returns:

Description of the Return Value