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.
This class tries to support both sub-millisecond precision and string parsing of dates. This means that there are two fields, a value, which is a Java long, and a calendar, which is a java.util.Calendar. The Calendar class only support milliseconds, it does not support microseconds and nanoseconds. When operations are performed, it is essential that setTimeInMilliseconds(long) be called so that both fields are updated.

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$

Author:

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

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

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

All Methods Static Methods Instance Methods Concrete Methods
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 brings both tokens to the same precision.
`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.
`static DateToken`	`date(java.lang.String value)` Create a DateToken with a value.
`java.util.Calendar`	`getCalendarInstance()` Get the calendar instance representing this date.
`int`	`getDay()` Get the date of the month part of this date.
`int`	`getDayOfWeek()` Get the day of week.
`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).
`void`	`setTimeInMilliseconds(long newValue)` Set the time in milliseconds since January 1, 1970.
`java.lang.String`	`stringValue()` Return the value of the token as a String.
`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.
  - date
```
public static DateToken date(java.lang.String value)
                      throws IllegalActionException
```
    Create a DateToken with a value.
    
    Parameters:
    
    value - The date specified in a format acceptable to java.text.DateFormat.
    
    Returns:
    
    a DateToken.
    
    Throws:
    
    IllegalActionException - If thrown while creating the DateToken.
  - getDay
```
public int getDay()
```
    Get the date of the month part of this date.
    
    Returns:
    
    The date of the month.
  - getDayOfWeek
```
public int getDayOfWeek()
```
    Get the day of week.
    
    Returns:
    
    The day of week.
  - 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.
    
    See Also:
    
    setTimeInMilliseconds(long)
  - 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.
  - setTimeInMilliseconds
```
public void setTimeInMilliseconds(long newValue)
```
    Set the time in milliseconds since January 1, 1970.
    
    Parameters:
    
    newValue - The time as a long value.
    
    See Also:
    
    getTimeInMilliseconds()
  - stringValue
```
public java.lang.String stringValue()
```
    Return the value of the token as a String.
    
    Returns:
    
    The string value, which is the same as the value returned by toString(), except toString() wraps the string value in double quotes.
  - 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 brings both tokens to the same precision. Then compute difference between time value in given lower precision. If difference is less than epsilon (casted to an int), return true.
    
    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.

Class DateToken

Field Summary

Constructor Summary

Method Summary

Methods inherited from class ptolemy.data.AbstractConvertibleToken

Methods inherited from class ptolemy.data.Token

Methods inherited from class java.lang.Object

Field Detail

NIL

PRECISION_SECOND

PRECISION_MILLISECOND

PRECISION_MICROSECOND

PRECISION_NANOSECOND

_SIMPLE_DATE_FORMAT

Constructor Detail

DateToken

DateToken

DateToken

DateToken

DateToken

DateToken

Method Detail

addNanoseconds

addMicroseconds

convert

getCalendarInstance

date

getDay

getDayOfWeek

getHour

getMinute

getMicrosecond

getMillisecond

getMonth

getNanosecond

getPrecision

getSecond

getTimeZone

getTimezoneID

getValue

getTimeInMilliseconds

getType

getYear

isGreaterThan

isLessThan

isLessThan

isNil

setTimeInMilliseconds

stringValue

toString

_add

_divide

_isCloseTo

_isEqualTo

_isLessThan

_modulo

_multiply

_subtract