ptolemy.data

Class DateToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.AbstractConvertibleToken

ptolemy.data.DateToken

All Implemented Interfaces:

PartiallyOrderedToken

public class DateToken
extends AbstractConvertibleToken
implements PartiallyOrderedToken

A token that contains a date. Note: Java 8 provides a much improved implementation of dates and times. This implementation should be upgraded eventually.

Since:

Ptolemy II 10.0

Version:

$Id: DateToken.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Patricia Derler, Christopher based on DateToken in Kepler by Daniel Crawl and Christopher Brooks

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (cxh)

Field Summary

Fields

Modifier and Type	Field and Description
protected static java.lang.String	_SIMPLE_DATE_FORMAT The format in which dates are reported.
static DateToken	NIL A token that represents a missing value.
static int	PRECISION_MICROSECOND The flag indicating that the the precision is microseconds.
static int	PRECISION_MILLISECOND The flag indicating that the the precision is milliseconds.
static int	PRECISION_NANOSECOND The flag indicating that the the precision is nanoseconds.
static int	PRECISION_SECOND The flag indicating that the the precision is seconds.

Constructor Summary

Constructors

Constructor and Description
DateToken() Construct a date token.
DateToken(long value) Construct a DateToken that represents the time since January 1, 1970.
DateToken(long value, int precision) Construct a DateToken that represents the time since January 1, 1970.
DateToken(long value, int precision, java.lang.String timeZone) Construct a DateToken that represents the time since January 1, 1970.
DateToken(long value, int precision, java.util.TimeZone timeZone) Construct a DateToken that represents the time since January 1, 1970.
DateToken(java.lang.String value) Construct a DateToken that represents the time specified as a string.

Method Summary

Modifier and Type	Method and Description
protected Token	_add(Token rightArgument) Subtract is not supported for Dates.
protected Token	_divide(Token rightArgument) Subtract is not supported for Dates.
protected BooleanToken	_isCloseTo(Token token, double epsilon) The isCloseTo() method is not supported for Dates because epsilon is not losslessly convertable to Long.
protected BooleanToken	_isEqualTo(Token rightArgument) Return true of the the value of this token is equal to the value of the argument according to java.util.Date.
protected BooleanToken	_isLessThan(DateToken rightArgument) Test for ordering of the values of this Token and the argument Token.
protected Token	_modulo(Token rightArgument) Modulo is not supported for Dates.
protected Token	_multiply(Token rightArgument) Multiply is not supported for Dates.
protected Token	_subtract(Token rightArgument) Subtract is not supported for Dates.
void	addMicroseconds(int microseconds) Add microseconds to time.
void	addNanoseconds(int nanoseconds) Add nanoseconds to time.
static DateToken	convert(Token token) Convert the specified token into an instance of DateToken.
java.util.Calendar	getCalendarInstance() Get the calendar instance representing this date.
int	getDay() Get the date of the month part of this date.
int	getHour() Get the hour part of this date.
int	getMicrosecond() Get the microsecond part of this date.
int	getMillisecond() Get the millisecond part of this date.
int	getMinute() Get the minute part of this date.
int	getMonth() Get the month part of this date.
int	getNanosecond() Get the nanosecond part of this date.
int	getPrecision() Get the precision of this date.
int	getSecond() Get the second part of this date.
long	getTimeInMilliseconds() Get time in milliseconds since January 1, 1970.
java.util.TimeZone	getTimeZone() Get the time zone of this date.
java.lang.String	getTimezoneID() Get the time zone id of this date.
Type	getType() Return the type of this token.
long	getValue() Get the time since January 1, 1970 in the given precision.
int	getYear() Get the year of this date.
BooleanToken	isGreaterThan(PartiallyOrderedToken rightArgument) Check whether the value of this token is strictly greater than that of the argument token.
BooleanToken	isLessThan(DateToken rightArgument) Check whether the value of this token is strictly less than that of the argument token.
BooleanToken	isLessThan(PartiallyOrderedToken rightArgument) Check whether the value of this token is strictly less than that of the argument token.
boolean	isNil() Return true if the token is nil, (aka null or missing).
java.lang.String	toString() Return a String representation of the DateToken.

Methods inherited from class ptolemy.data.AbstractConvertibleToken

add, addReverse, divide, divideReverse, isCloseTo, isEqualTo, modulo, moduloReverse, multiply, multiplyReverse, subtract, subtractReverse

Methods inherited from class ptolemy.data.Token

isCloseTo, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, one, pow, zero, zeroReturnType

Methods inherited from class java.lang.Object

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

Field Detail

NIL

public static final DateToken NIL

A token that represents a missing value. Null or missing tokens are common in analytical systems like R and SAS where they are used to handle sparsely populated data sources. In database parlance, missing tokens are sometimes called null tokens. Since null is a Java keyword, we use the term "nil". The toString() method on a nil token returns the string "nil".

PRECISION_SECOND

public static final int PRECISION_SECOND

The flag indicating that the the precision is seconds.

See Also:

Constant Field Values

PRECISION_MILLISECOND

public static final int PRECISION_MILLISECOND

The flag indicating that the the precision is milliseconds.

See Also:

Constant Field Values

PRECISION_MICROSECOND

public static final int PRECISION_MICROSECOND

The flag indicating that the the precision is microseconds.

See Also:

Constant Field Values

PRECISION_NANOSECOND

public static final int PRECISION_NANOSECOND

The flag indicating that the the precision is nanoseconds.

See Also:

Constant Field Values

_SIMPLE_DATE_FORMAT

protected static final java.lang.String _SIMPLE_DATE_FORMAT

The format in which dates are reported. Milliseconds are included so that the toString() method returns a string that can be parsed to the same Date.

See Also:

Constant Field Values

Constructor Detail

DateToken

public DateToken()

Construct a date token. The current time is used for the date, the default precision is milliseconds and the default time zone is the local time zone.

DateToken

public DateToken(long value)

Construct a DateToken that represents the time since January 1, 1970. The time zone defaults to the local time zone.

Parameters:

value - The time since January 1, 1970 in the default precision of milliseconds.

DateToken

public DateToken(long value,
                 int precision)

Construct a DateToken that represents the time since January 1, 1970. The time zone defaults to the local time zone.

Parameters:

value - The time since January 1, 1970 in the given precision.

precision - The precision.

DateToken

public DateToken(long value,
                 int precision,
                 java.lang.String timeZone)

Construct a DateToken that represents the time since January 1, 1970.

Parameters:

value - The time since January 1, 1970 in the given precision.

precision - The precision.

timeZone - The string representation of the time zone ID.

DateToken

public DateToken(long value,
                 int precision,
                 java.util.TimeZone timeZone)

Construct a DateToken that represents the time since January 1, 1970.

Parameters:

value - The time since January 1, 1970 in the given precision.

precision - The precision.

timeZone - The time zone.

DateToken

public DateToken(java.lang.String value)
          throws IllegalActionException

Construct a DateToken that represents the time specified as a string. The string is first parsed by the default java.text.DateFormat parser. Because we have up to nanosecond precision, we might have to pre-process the string and take out the digits representing nanoseconds and microseconds. Then any leading and trailing double quotes are removed and a java.text.SimpleDateFormat with a parser with the value of _SIMPLE_DATE_FORMAT is used.

Parameters:

value - The date specified in a format acceptable to java.text.DateFormat.

Throws:

IllegalActionException - If the date is not parseable by java.text.DateFormat.

Method Detail

addNanoseconds

public void addNanoseconds(int nanoseconds)

Add nanoseconds to time. If the precision is less than nanoseconds, do nothing.

Parameters:

nanoseconds - The nanoseconds to add.

addMicroseconds

public void addMicroseconds(int microseconds)

Add microseconds to time. If the precision is less than microseconds, do nothing.

Parameters:

microseconds - The microseconds to add.

convert

public static DateToken convert(Token token)
                         throws IllegalActionException

Convert the specified token into an instance of DateToken. This method does lossless conversion. If the argument is already an instance of DateToken, it is returned without any change. If the argument is a nil token, then a new nil Token is returned, see NIL. Otherwise, if the argument is below DateToken in the type hierarchy, it is converted to an instance of DateToken or one of the subclasses of DateToken and returned. If none of the above condition is met, an exception is thrown.

Parameters:

token - The token to be converted to a DateToken.

Returns:

A DateToken.

Throws:

IllegalActionException - If the conversion cannot be carried out.

getCalendarInstance

public java.util.Calendar getCalendarInstance()

Get the calendar instance representing this date.

Returns:

The calendar instance.

getDay

public int getDay()

Get the date of the month part of this date.

Returns:

The date of the month.

getHour

public int getHour()

Get the hour part of this date.

Returns:

The hour.

getMinute

public int getMinute()

Get the minute part of this date.

Returns:

The minute.

getMicrosecond

public int getMicrosecond()

Get the microsecond part of this date.

Returns:

The microsecond.

getMillisecond

public int getMillisecond()

Get the millisecond part of this date.

Returns:

The millisecond.

getMonth

public int getMonth()

Get the month part of this date.

Returns:

The month.

getNanosecond

public int getNanosecond()

Get the nanosecond part of this date.

Returns:

The nanosecond.

getPrecision

public int getPrecision()

Get the precision of this date.

Returns:

The precision.

getSecond

public int getSecond()

Get the second part of this date.

Returns:

The second.

getTimeZone

public java.util.TimeZone getTimeZone()

Get the time zone of this date.

Returns:

The time zone.

getTimezoneID

public java.lang.String getTimezoneID()

Get the time zone id of this date.

Returns:

The time zone.

getValue

public long getValue()

Get the time since January 1, 1970 in the given precision.

Returns:

The time since Januarly 1, 1970.

getTimeInMilliseconds

public long getTimeInMilliseconds()

Get time in milliseconds since January 1, 1970.

Returns:

The time as a long value.

getType

public Type getType()

Return the type of this token.

Overrides:

getType in class Token

Returns:

BaseType.DATE, the least upper bound of all the date types.

getYear

public int getYear()

Get the year of this date.

Returns:

The year.

isGreaterThan

public final BooleanToken isGreaterThan(PartiallyOrderedToken rightArgument)
                                 throws IllegalActionException

Check whether the value of this token is strictly greater than that of the argument token. The argument and this token are converted to equivalent types, and then compared. Generally, this is the higher of the type of this token and the argument type. This method defers to the _isLessThan() method to perform a type-specific equality check. Derived classes should implement that method to provide type specific actions for equality testing.

Parameters:

rightArgument - The token to compare against.

Returns:

A boolean token with value true if this token has the same units as the argument, and is strictly greater than the argument.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or have different units, or the operation does not make sense for the given types.

isLessThan

public BooleanToken isLessThan(PartiallyOrderedToken rightArgument)
                        throws IllegalActionException

Check whether the value of this token is strictly less than that of the argument token. Only a partial order is assumed, so !(a < b) need not imply (a ≥ b).

Specified by:

isLessThan in interface PartiallyOrderedToken

Parameters:

rightArgument - The token on greater than side of the inequality.

Returns:

BooleanToken.TRUE, if this token is less than the argument token. BooleanToken.FALSE, otherwise.

Throws:

IllegalActionException - If the tokens are incomparable.

isLessThan

public BooleanToken isLessThan(DateToken rightArgument)
                        throws IllegalActionException

Check whether the value of this token is strictly less than that of the argument token.

Parameters:

rightArgument - The token to compare against.

Returns:

A boolean token with value true if this token is strictly less than the argument.

Throws:

IllegalActionException - If the argument token and this token are of incomparable types, or have different units, or the operation does not make sense for the given types.

isNil

public boolean isNil()

Return true if the token is nil, (aka null or missing). Nil or missing tokens occur when a data source is sparsely populated. To create a nil DateToken, call new DateToken("nil");

Overrides:

isNil in class Token

Returns:

True if the token is the NIL token.

toString

public java.lang.String toString()

Return a String representation of the DateToken. The string is surrounded by double-quotes; without them, the Ptolemy expression parser fails to parse it.

Unfortunately, the Java Date class has a fatal flaw in that Date.toString() does not return the value of the number of ms., so we use a format that includes the number of ms.

Overrides:

toString in class Token

Returns:

A String representation of the DateToken.

_add

protected Token _add(Token rightArgument)
              throws IllegalActionException

Subtract is not supported for Dates.

Specified by:

_add in class AbstractConvertibleToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - Always thrown because multiplying a Date does not make sense.

_divide

protected Token _divide(Token rightArgument)
                 throws IllegalActionException

Subtract is not supported for Dates.

Specified by:

_divide in class AbstractConvertibleToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - Always thrown because dividing a Date does not make sense.

_isCloseTo

protected BooleanToken _isCloseTo(Token token,
                                  double epsilon)
                           throws IllegalActionException

The isCloseTo() method is not supported for Dates because epsilon is not losslessly convertable to Long.

Specified by:

_isCloseTo in class AbstractConvertibleToken

Parameters:

token - The token to compare to this token

epsilon - the epsilon

Returns:

A new token containing the result.

Throws:

IllegalActionException - Always thrown because isCloseTo() on a Date does not make sense.

_isEqualTo

protected BooleanToken _isEqualTo(Token rightArgument)
                           throws IllegalActionException

Return true of the the value of this token is equal to the value of the argument according to java.util.Date. Two DateTokens are considered equal if the their values are non-null and the java.util.Date.equals() method returns true. It is assumed that the type of the argument is the same as the type of this class.

Specified by:

_isEqualTo in class AbstractConvertibleToken

Parameters:

rightArgument - The token with which to test equality.

Returns:

true if the right argument is equal to this token.

Throws:

IllegalActionException - Not thrown in this baseclass

_isLessThan

protected BooleanToken _isLessThan(DateToken rightArgument)
                            throws IllegalActionException

Test for ordering of the values of this Token and the argument Token.

Parameters:

rightArgument - The token to compare to this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this method is not supported by the derived class.

_modulo

protected Token _modulo(Token rightArgument)
                 throws IllegalActionException

Modulo is not supported for Dates.

Specified by:

_modulo in class AbstractConvertibleToken

Parameters:

rightArgument - The token to divide into this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - Always thrown because modulo of a Date does not make sense.

_multiply

protected Token _multiply(Token rightArgument)
                   throws IllegalActionException

Multiply is not supported for Dates.

Specified by:

_multiply in class AbstractConvertibleToken

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new token containing the result.

Throws:

IllegalActionException - Always thrown because multiplying a Date does not make sense.

_subtract

protected Token _subtract(Token rightArgument)
                   throws IllegalActionException

Subtract is not supported for Dates.

Specified by:

_subtract in class AbstractConvertibleToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new token containing the result.

Throws:

IllegalActionException - Always thrown because subtracting a Date does not make sense.