Package ptolemy.data

Class 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 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.

      • _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.