com.davisor.data
Class TimestampData

java.lang.Object
  java.util.Date
      com.davisor.data.TimestampData

All Implemented Interfaces:

java.lang.Cloneable, java.lang.Comparable, Data, DataValue, com.davisor.core.Dupable, java.io.Serializable, SerializableData

Direct Known Subclasses:

CalendarData, DateData, MomentData, TimeData

public class TimestampData

extends java.util.Date

implements DataValue

A TimestampData object represents a timestamp value.

Since:

JDK1.1

See Also:

TimestampType, Serialized Form

Field Summary

protected DateFormatType	M_type The type of this data.
static long	NaT Not-a-Time timestamp value (Long.MIN_VALUE).

Constructor Summary

TimestampData()
Creates a new timestamp data object with the current timestamp and default type.

TimestampData(java.util.Date date)
Creates a new timestamp data object with the default type and given date.

TimestampData(DateFormatType type)
Creates a new timestamp data object with the current timestamp and given type.

TimestampData(DateFormatType type, java.util.Date date)
Creates a new timestamp data object with the given type and date.

TimestampData(DateFormatType type, long milliseconds)
Creates a new timestamp data object with the given type and value.

TimestampData(DateFormatType type, java.lang.String stringValue, java.text.ParsePosition status)
Creates a timestamp data value from a string value.

TimestampData(long milliseconds)
Creates a new timestamp data object with the default type and given value.

TimestampData(TimestampData td, boolean deep)
Deep or shallow copy constructor.

Method Summary

DataValue	abs() Returns absolute data value of current value.
DataValue	add(DataValue value) Adds given value to current value.
DataValue	ceil(DataValue precision) Quantizes the current value up to an even value within given precision.
DataValue	ceil(java.util.Date precision) Quantizes the current value up to an even value within given date precision.
static int	compareTo(java.util.Date data, java.lang.Object o) Compares this timestamp against other Date objects.
int	compareTo(java.lang.Object o) Compares this timestamp against other Date objects.
java.util.Calendar	createCalendar() Creates a new calendar set to the moment of time this object currently represents.
double	deinterpolate(DataValue min, DataValue max) De-interpolates the current data value to a scalar value, in respect, with given data value range.
DataValue	div(DataValue value) Divides the current value with given number value.
com.davisor.core.Dupable	dup() Makes a deep copy of this object.
DataValue	floor(DataValue precision) Quantizes the current value down to an even value within given precision.
DataValue	floor(java.util.Date precision) Quantizes the current value down to an even value within given precision.
java.lang.String	getFormat() Gets the type specification optimal for this particular value.
Type	getType() Gets the data type.
protected static long	initTime(DateFormatType type, long milliseconds) Makes a millisecond timestamp value suitable for given type.
DataValue	interpolate(double value, DataValue max) Interpolates the given scalar value to data value, in respect, with the range defined by this value and the given maximum value.
boolean	isNull() Tests if this data object value is undetermined.
DataValue	max(DataValue value) Finds the largest data value.
DataValue	min(DataValue value) Finds the larger of this and the given data value.
DataValue	mul(DataValue value) Multiplies the current value with given number value.
DataValue	negate() Returns the negation of current value.
void	setTime(java.util.Date value) Sets the timestamp value.
void	setValue(java.lang.String stringValue, java.text.ParsePosition status) Sets data value from a string value.
DataValue	sub(DataValue value) Substracts given value from current value.
void	toStatement(java.sql.PreparedStatement statement, int parameter) Converts data to a prepared statement input parameter.
java.lang.String	toString() Gets the string representation of this timestamp value.
java.lang.String	toXML() Gets the XML string representation of this value.
DataValue	unit(DataValue targetValue, double maxSteps) Gets the largest suitable unit step to represent a value change between this value and the given target value.

Methods inherited from class java.util.Date

after, before, clone, compareTo, equals, getDate, getDay, getHours, getMinutes, getMonth, getSeconds, getTime, getTimezoneOffset, getYear, hashCode, parse, setDate, setHours, setMinutes, setMonth, setSeconds, setTime, setYear, toGMTString, toLocaleString, UTC

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

NaT

public static final long NaT

Not-a-Time timestamp value (Long.MIN_VALUE).

See Also:

Constant Field Values

M_type

protected DateFormatType M_type

The type of this data.

Constructor Detail

TimestampData

public TimestampData()

Creates a new timestamp data object with the current timestamp and default type.

TimestampData

public TimestampData(TimestampData td,
                     boolean deep)

Deep or shallow copy constructor. If it is shallow, then the new object shares an underlying type with the original object. If it is deep, then the type is dupped.

Parameters:

td - timestamp to copy (may be null)

deep - determines if the copying is deep or shallow

See Also:

getType(), Type.dup()

TimestampData

public TimestampData(java.util.Date date)

Creates a new timestamp data object with the default type and given date.

Parameters:

date - timestamp value (may be null)

TimestampData

public TimestampData(long milliseconds)

Creates a new timestamp data object with the default type and given value.

Parameters:

milliseconds - milliseconds value

TimestampData

public TimestampData(DateFormatType type)

Creates a new timestamp data object with the current timestamp and given type.

Parameters:

type - timestamp type

TimestampData

public TimestampData(DateFormatType type,
                     java.util.Date date)

Creates a new timestamp data object with the given type and date.

Parameters:

type - timestamp type

date - timestamp value (may be null)

TimestampData

public TimestampData(DateFormatType type,
                     long milliseconds)

Creates a new timestamp data object with the given type and value.

Parameters:

type - timestamp type

milliseconds - milliseconds value

TimestampData

public TimestampData(DateFormatType type,
                     java.lang.String stringValue,
                     java.text.ParsePosition status)
              throws InvalidDataException

Creates a timestamp data value from a string value.

Parameters:

stringValue - string value to be parsed

status - parse status (may be null)

Throws:

InvalidDataException - if string value could not be parser

See Also:

setValue(String,ParsePosition), DateFormatType.dateValue(String,ParsePosition)

Method Detail

compareTo

public int compareTo(java.lang.Object o)

Compares this timestamp against other Date objects.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - a Date object to compare this timestamp against with

Returns:

-1, 0, or 1 as this object is less than, equal to, or greater than the specified object

Throws:

java.lang.ClassCastException - if the given object is not a Date

See Also:

compareTo(java.util.Date,Object)

getType

public Type getType()
             throws InvalidDataException

Gets the data type.

Specified by:

getType in interface Data

Returns:

Data type.

Throws:

InvalidDataException - if type retrieval fails

isNull

public boolean isNull()

Tests if this data object value is undetermined.

Timestamp values are undetermined if the underlying Date value is equal to NaT.

Specified by:

isNull in interface SerializableData

See Also:

Type.isNull(com.davisor.data.SerializableData)

abs

public DataValue abs()
              throws InvalidDataException

Returns absolute data value of current value.

Absolute values must satisfy a requirement that when added to any other value, the result must be greater than or equal to the original value.

Specified by:

abs in interface DataValue

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if absolute value can not be computed

add

public DataValue add(DataValue value)
              throws InvalidDataException

Adds given value to current value. The nature of the addition operation depends on given value type. In each case, the result will be returned in a time data object type best suited for to represent the result.

If the value is an instance of CalendarData, current timestamp value is converted to a calendar value, to which given value will be added field by field. This correspond to a situation when given number of different calendar units like days and hours are added to a known exact moment of time.

If the value is an instance of CalendarFieldData, current timestamp value is converted to a calendar value, and given field value is added to it. This correspond to a situation when given number of spesific single calendar units are added to a known exact moment of time.

If the value is an instance of Date, it and the current timestamp values are converted to calendar values, which will then be added field by field. This correspond to a situation when a time period expressed in milliseconds is added to a known exact moment of time.

If the value is an instance of Date and the value type is MomentType then the result will be the given value. Note that in that case this operation is not symmetric!

In any other case, the operation fails.

Specified by:

add in interface DataValue

Parameters:

value - a data value to be added to this data value

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if the data values cannot be added

See Also:

createCalendar(), sub(com.davisor.data.DataValue), DateFormatType.toData(java.util.Date)

ceil

public DataValue ceil(DataValue precision)
               throws InvalidDataException

Quantizes the current value up to an even value within given precision. The returned value is more than or equal with the current value, but not more than the current value added by given precision.

The quantization method depends on given precision type. If the precision is an instance of CalendarData, current timestamp value is converted to a calendar value, which will be quantized field by field.

If the precision is an instance of CalendarFieldData, current timestamp value is converted to a calendar value, and quantized by the field value.

If the precision is an instance of DateData, current timestamp value is converted to a calendar value, which will be quantized field by field by a calendar object constructed from the precision object.

If the precision is an instance of Date, it's milliseconds value will be used as a quantisation factor against which the current milliseconds value will be quantizied.

In any other case, the operation fails.

Specified by:

ceil in interface DataValue

Parameters:

precision - the precision within quantization occurs

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if precision was of unacceptable type

See Also:

createCalendar(), floor(com.davisor.data.DataValue), DateFormatType.toData(java.util.Date)

deinterpolate

public double deinterpolate(DataValue min,
                            DataValue max)
                     throws InvalidDataException

De-interpolates the current data value to a scalar value, in respect, with given data value range. This gives scalar values between [0,1] when the current data value in within the range, negative scalar values when the data value falls below the range and scalar values greater than 1.0 otherwise.

Timestamp values are de-interpolated with the equation:

(thisValue - minValue) / (maxValue - minValue)

Specified by:

deinterpolate in interface DataValue

Parameters:

min - a data value representing a range's lower limit

max - a data value representing a range's higher limit

Returns:

de-interpolated scalar value (may be NaN)

Throws:

InvalidDataException - if the de-interpolation fails

See Also:

DataValue.interpolate(double, com.davisor.data.DataValue), DeinterpolationException, TupleData.deinterpolate(com.davisor.data.DataValue, com.davisor.data.DataValue)

div

public DataValue div(DataValue value)
              throws InvalidDataException

Divides the current value with given number value. Time value divisions against anything else than number values are not defined.

Specified by:

div in interface DataValue

Parameters:

value - the divider (expected to be a Number)

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if divider is not a number

floor

public DataValue floor(DataValue precision)
                throws InvalidDataException

Quantizes the current value down to an even value within given precision. The returned value is more than or equal with the current value, but not more than the current value added by given precision.

The quantization method depends on given precision type. If the precision is an instance of CalendarData, current timestamp value is converted to a calendar value, which will be quantized field by field.

If the precision is an instance of CalendarFieldData, current timestamp value is converted to a calendar value, and quantized by the field value.

If the precision is an instance of DateData, current timestamp value is converted to a calendar value, which will be quantized field by field by a calendar object constructed from the precision object.

If the precision is an instance of Date, it's milliseconds value will be used as a quantisation factor against which the current milliseconds value will be quantizied.

In any other case, the operation fails.

Specified by:

floor in interface DataValue

Parameters:

precision - the precision within quantization occurs

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if precision was of unacceptable type

See Also:

ceil(com.davisor.data.DataValue), createCalendar(), DateFormatType.toData(Object)

getFormat

public java.lang.String getFormat()

Gets the type specification optimal for this particular value. The specification returned may differ from the current type specification. If so, setting the current type specification equal with the value returned by this method will ensure optimal value formatting and parsing for values of the same magnitude as this value.

This method analyzes the magnitude of the calendar time units that the current time value represents. The field is then mapped to a Java SimpleDateFormat pattern that best describes the field values. The current type locale, if any, is also resolved. A DateFormatType specification string is then constructed.

Specified by:

getFormat in interface DataValue

See Also:

Data.getType(), DateFormatType.getFormat(), DateFormatType.setFormat(java.lang.String)

interpolate

public DataValue interpolate(double value,
                             DataValue max)
                      throws InvalidDataException

Interpolates the given scalar value to data value, in respect, with the range defined by this value and the given maximum value. Scalar values between [0,1] result in data values between the current value and the given maximum value. Negative scalar values result in values smaller than this value, and scalar values higher than 1.0 return data values above the given maximum.

All number values can interpolate with this simple equation:

minValue + value * (maxValue - minValue)

Specified by:

interpolate in interface DataValue

Parameters:

value - the scalar value to be interpolated

max - a data value representing a range's higher limit

Returns:

a new data object containing the result

Throws:

InvalidDataException - if the interpolation fails

See Also:

DateFormatType.toData(Object)

max

public DataValue max(DataValue value)
              throws InvalidDataException

Finds the largest data value.

This method assumes that the given data value is an instance of Date. The comparison is done by comparing the date millisecond time values.

If the given value is null or an instance of VoidValue, a reference to this instance is returned.

Specified by:

max in interface DataValue

Parameters:

value - a data value to be compared with this data value

Returns:

Returns the largest of the compared data values.

Throws:

InvalidDataException - if the data value cannot be compared

See Also:

min(com.davisor.data.DataValue)

min

public DataValue min(DataValue value)
              throws InvalidDataException

Finds the larger of this and the given data value.

This method assumes that the given data value is an instance of Date. The comparison is done by comparing the date millisecond time values.

If the given value is null or an instance of VoidValue, a reference to this instance is returned.

Specified by:

min in interface DataValue

Parameters:

value - a data value to be compared with this data value

Returns:

Returns the smallest of the compared data values.

Throws:

InvalidDataException - if the data value cannot be compared

See Also:

max(com.davisor.data.DataValue)

mul

public DataValue mul(DataValue value)
              throws InvalidDataException

Multiplies the current value with given number value. Time value multiplications against anything else than number values are not defined.

Specified by:

mul in interface DataValue

Parameters:

value - the multiplier (expected to be a Number)

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if multiplier is not a number

negate

public DataValue negate()
                 throws InvalidDataException

Returns the negation of current value.

Specified by:

negate in interface DataValue

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if absolute value can not be computed

setValue

public void setValue(java.lang.String stringValue,
                     java.text.ParsePosition status)
              throws InvalidDataException

Sets data value from a string value.

Specified by:

setValue in interface DataValue

Parameters:

stringValue - string value to be parsed (may be null)

status - parse status (may be null)

Throws:

InvalidDataException - if string value could not be parser

See Also:

DateFormatType.dateValue(String,ParsePosition)

sub

public DataValue sub(DataValue value)
              throws InvalidDataException

Substracts given value from current value. The nature of the substraction operation depends on given value type. In each case, the result will be returned in a time data object type best suited for to represent the result.

If the value is an instance of CalendarData, current timestamp value is converted to a calendar value, from which given value will be substracted field by field. This correspond to a situation when given number of different calendar units like days and hours are substracted from a known exact moment of time.

If the value is an instance of CalendarFieldData, current timestamp value is converted to a calendar value, and given field value is substracted from it. This correspond to a situation when given number of spesific single calendar units are substracted from a known exact moment of time.

If the value is an instance of Date, it's millisecond value is simply substracted from the current timestamp value. This correspond to a situation when a time period expressed in milliseconds is substracted from a known exact moment of time.

If the value is an instance of Date and the value type is MomentType then the result will be the given value.

In any other case, the operation fails.

Specified by:

sub in interface DataValue

Parameters:

value - a data value to be substracted from this data value

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if the data values cannot be substracted

See Also:

createCalendar(), add(com.davisor.data.DataValue), DateFormatType.toData(java.util.Date)

toStatement

public void toStatement(java.sql.PreparedStatement statement,
                        int parameter)
                 throws java.sql.SQLException

Converts data to a prepared statement input parameter.

Specified by:

toStatement in interface DataValue

Throws:

java.sql.SQLException - if a SQL error occurs

toXML

public java.lang.String toXML()

Gets the XML string representation of this value.

Specified by:

toXML in interface DataValue

Returns:

complete string representing the data.

See Also:

toString(), XMLUnicodeEncoder.encode(java.lang.String, boolean)

unit

public DataValue unit(DataValue targetValue,
                      double maxSteps)
               throws InvalidDataException

Gets the largest suitable unit step to represent a value change between this value and the given target value. If the values are equal, a type specific default unit step is returned. If the values are not equal, then the given target value must be reached from this value by adding the returned unit step to this value once or more.

The returned unit time values are expressed with CalendarFieldData objects, which tell what and how many time units would be a suitable step between this and given target value.

If the target value is an instance of CalendarFieldData, the source value is ignored, and the result is computed solely from given target value. If the target calendar field value is greater than one, the result is the same calendar field, but with the value of one. If the target field value is one, the result is the next less significant calendar field, again with the value of one. For example, a target value of 5 hours would result a unit time of 1 hour, while 1 hour would result 1 minute.

In all other cases, the given source and target values are first converted to calendar values. The most significant time field that is then different between the two calendars is resolved. If the difference is greater than one, the calendar field is returned with a value of one. If the difference is exactly one, the next less significant calendar field is returned, again with the value of one. If the target value equals current value, the most significant calendar field of current time value is returned, with the step value of one.

For example, if the current value is the first of May in some year at 9 a clock in the morning, and the target value is the third of May in that same year and at 10 a clock, the result will be 1 day. If the target value would have been the second of May, the result would have been 1 hour. If the target value would have been first of May, the result would haven been 1 minute. And if the target value would have been equal to current value, the result would have been 1 month.

Specified by:

unit in interface DataValue

Parameters:

targetValue - target value to be reached (may be null)

maxSteps - maximum number of steps (zero leaves the choise open)

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if target value is unsuitable

dup

public com.davisor.core.Dupable dup()

Makes a deep copy of this object.

Specified by:

dup in interface com.davisor.core.Dupable

toString

public java.lang.String toString()

Gets the string representation of this timestamp value.

Specified by:

toString in interface DataValue

See Also:

setValue(String,ParsePosition), DateFormatType.stringValue(Date)

initTime

protected static long initTime(DateFormatType type,
                               long milliseconds)

Makes a millisecond timestamp value suitable for given type. The millisecond value is first placed into a calendar object, created by DateFormatType.createCalendar(java.util.Date). The calendar fields are then stripped with DateFormatType.strip(java.util.Calendar) to mach the nature of current type. Finally, the resulting timestamp is restored back to a milliseconds value, and returned.

The method is static so that it can be used in constructors to process superclass initialization parameters, too.

Parameters:

type - the type the timestamp value is prepared for

milliseconds - the timestamp value to prepare

See Also:

DateType.strip(java.util.Calendar), TimeType.strip(java.util.Calendar)

ceil

public DataValue ceil(java.util.Date precision)
               throws InvalidDataException

Quantizes the current value up to an even value within given date precision. The returned value is more than or equal with the current value, but not more than the current value added by given precision.

Parameters:

precision - the precision within quantization occurs

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if precision was of unacceptable type

See Also:

ceil(DataValue), floor(java.util.Date)

createCalendar

public java.util.Calendar createCalendar()

Creates a new calendar set to the moment of time this object currently represents.

compareTo

public static int compareTo(java.util.Date data,
                            java.lang.Object o)

Compares this timestamp against other Date objects.

Parameters:

o - a Date object to compare this timestamp against with

Returns:

-1, 0, or 1 as this object is less than, equal to, or greater than the specified object

Throws:

java.lang.ClassCastException - if the given object is not a Date

See Also:

compareTo(Object)

floor

public DataValue floor(java.util.Date precision)
                throws InvalidDataException

Quantizes the current value down to an even value within given precision. The returned value is more than or equal with the current value, but not more than the current value added by given precision.

Parameters:

precision - the precision within quantization occurs

Returns:

a new data object, sharing the current type of this object

Throws:

InvalidDataException - if precision was of unacceptable type

See Also:

ceil(java.util.Date), floor(DataValue)

setTime

public void setTime(java.util.Date value)

Sets the timestamp value. The value is set using the setTime method, which sub-classes may override to implement explicit time value constraints.

If given timestamp value is null current timestamp is set to special NaT value that indicates that the timestamp value is undetermined.

Parameters:

value - a timestamp value (may be null)

See Also:

DateData.setTime(long), TimeData.setTime(long)