Package org.apache.derby.iapi.types

Class SQLTimestamp

  • All Implemented Interfaces:
    java.io.Externalizable, java.io.Serializable, java.lang.Comparable, Formatable, Storable, TypedFormat, DataValueDescriptor, DateTimeDataValue, Orderable
    public final class SQLTimestamp
extends DataType
implements DateTimeDataValue
    This contains an instance of a SQL Timestamp object.

    SQLTimestamp is stored in 3 ints - an encoded date, an encoded time and nanoseconds encodedDate = 0 indicates a null WSCTimestamp SQLTimestamp is similar to SQLTimestamp, but it does conserves space by not keeping a GregorianCalendar object PERFORMANCE OPTIMIZATION: We only instantiate the value field when required due to the overhead of the Date methods. Thus, use isNull() instead of "value == null" and getTimestamp() instead of using value directly.

    See Also:
    Serialized Form

    • Field Detail

      • encodedDate

        private int encodedDate

      • encodedTime

        private int encodedTime

      • nanos

        private int nanos

      • BASE_MEMORY_USAGE

        private static final int BASE_MEMORY_USAGE

      • DATE_SEPARATORS

        private static final char[] DATE_SEPARATORS

      • IBM_DATE_TIME_SEPARATOR

        private static final char IBM_DATE_TIME_SEPARATOR
        See Also:
        Constant Field Values

      • ODBC_DATE_TIME_SEPARATOR

        private static final char ODBC_DATE_TIME_SEPARATOR
        See Also:
        Constant Field Values

      • DATE_TIME_SEPARATORS

        private static final char[] DATE_TIME_SEPARATORS

      • DATE_TIME_SEPARATORS_OR_END

        private static final char[] DATE_TIME_SEPARATORS_OR_END

      • TIME_SEPARATORS

        private static final char[] TIME_SEPARATORS

      • TIME_SEPARATORS_OR_END

        private static final char[] TIME_SEPARATORS_OR_END

      • END_OF_STRING

        private static final char[] END_OF_STRING

    • Constructor Detail

      • SQLTimestamp

        public SQLTimestamp()
        no-arg constructor required by Formattable

      • SQLTimestamp

        public SQLTimestamp​(java.sql.Timestamp value,
                    java.util.Calendar cal)
             throws StandardException
        Create a new SQLTimestamp instance that represents the specified Timestamp in the time zone of the given Calendar.
        Parameters:
        value - the Timestamp value to be represented by this instance
        cal - the time zone of the calendar is used to construct the database timestamp value
        Throws:
        StandardException - if an error occurs

      • SQLTimestamp

        public SQLTimestamp​(java.sql.Timestamp value)
             throws StandardException
        Create a new SQLTimestamp instance that represents the specified Timestamp in the local time zone.
        Parameters:
        value - the Timestamp value to be represented by this instance
        Throws:
        StandardException - if an error occurs

      • SQLTimestamp

        SQLTimestamp​(int encodedDate,
             int encodedTime,
             int nanos)

      • SQLTimestamp

        public SQLTimestamp​(java.lang.String timestampStr,
                    boolean isJDBCEscape,
                    LocaleFinder localeFinder)
             throws StandardException
        Construct a timestamp from a string. The allowed formats are:
        1. JDBC escape: yyyy-mm-dd hh:mm:ss[.fffff]
        2. IBM: yyyy-mm-dd-hh.mm.ss[.nnnnnn]
        The format is specified by a parameter to the constructor. Leading zeroes may be omitted from the month, day, and hour part of the timestamp. The microsecond part may be omitted or truncated.
        Throws:
        StandardException

      • SQLTimestamp

        public SQLTimestamp​(java.lang.String timestampStr,
                    boolean isJDBCEscape,
                    LocaleFinder localeFinder,
                    java.util.Calendar cal)
             throws StandardException
        Construct a timestamp from a string. The allowed formats are:
        1. JDBC escape: yyyy-mm-dd hh:mm:ss[.fffff]
        2. IBM: yyyy-mm-dd-hh.mm.ss[.nnnnnn]
        The format is specified by a parameter to the constructor. Leading zeroes may be omitted from the month, day, and hour part of the timestamp. The microsecond part may be omitted or truncated.
        Throws:
        StandardException

    • Method Detail

      • estimateMemoryUsage

        public int estimateMemoryUsage()
        Description copied from interface: DataValueDescriptor
        Estimate the memory usage in bytes of the data value and the overhead of the class.
        Specified by:
        estimateMemoryUsage in interface DataValueDescriptor
        Returns:
        the estimated memory usage

      • getString

        public java.lang.String getString()
        Description copied from interface: DataValueDescriptor
        Gets the value in the data value descriptor as a String. Throws an exception if the data value is not a string.
        Specified by:
        getString in interface DataValueDescriptor
        Returns:
        The data value as a String.

      • getDate

        public java.sql.Date getDate​(java.util.Calendar cal)
                      throws StandardException
        getDate returns the date portion of the timestamp Time is set to 00:00:00.0 Since Date is a JDBC object we use the JDBC definition for the time portion. See JDBC API Tutorial, 47.3.12.
        Specified by:
        getDate in interface DataValueDescriptor
        Overrides:
        getDate in class DataType
        Parameters:
        cal - calendar for object creation
        Returns:
        The data value as a java.sql.Date.
        Throws:
        StandardException - thrown on failure

      • getTime

        public java.sql.Time getTime​(java.util.Calendar cal)
                      throws StandardException
        getTime returns the time portion of the timestamp Date is set to 1970-01-01 Since Time is a JDBC object we use the JDBC definition for the date portion. See JDBC API Tutorial, 47.3.12.
        Specified by:
        getTime in interface DataValueDescriptor
        Overrides:
        getTime in class DataType
        Parameters:
        cal - calendar for object creation
        Returns:
        The data value as a java.sql.Time.
        Throws:
        StandardException - thrown on failure

      • getObject

        public java.lang.Object getObject()
        Description copied from class: DataType
        Gets the value in the data value descriptor as a int. Throws an exception if the data value is not receivable as a int.
        Specified by:
        getObject in interface DataValueDescriptor
        Overrides:
        getObject in class DataType
        Returns:
        The data value as a int.

      • getLength

        public int getLength()
        Description copied from interface: DataValueDescriptor
        Gets the length of the data value. The meaning of this is implementation-dependent. For string types, it is the number of characters in the string. For numeric types, it is the number of bytes used to store the number. This is the actual length of this value, not the length of the type it was defined as. For example, a VARCHAR value may be shorter than the declared VARCHAR (maximum) length.
        Specified by:
        getLength in interface DataValueDescriptor
        Returns:
        The length of the data value

      • writeExternal

        public void writeExternal​(java.io.ObjectOutput out)
                   throws java.io.IOException
        Specified by:
        writeExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException - error writing data

      • readExternal

        public void readExternal​(java.io.ObjectInput in)
                  throws java.io.IOException
        Specified by:
        readExternal in interface java.io.Externalizable
        Throws:
        java.io.IOException - Thrown on error reading the object
        See Also:
        Externalizable.readExternal(java.io.ObjectInput)

      • cloneValue

        public DataValueDescriptor cloneValue​(boolean forceMaterialization)
        Description copied from interface: DataValueDescriptor
        Clone this DataValueDescriptor. Results in a new object that has the same value as this but can be modified independently.

        Even though the objects can be modified independently regardless of the value of forceMaterialization, both the clone and the original may be dependent on the store state if forceMaterialization is set to false. An example is if you need to access the value you just read using cloneValue after the current transaction has ended, or after the source result set has been closed.

        Specified by:
        cloneValue in interface DataValueDescriptor
        Parameters:
        forceMaterialization - any streams representing the data value will be materialized if true, the data value will be kept as a stream if possible if false
        Returns:
        A clone of the DataValueDescriptor with the same initial value as this.
        See Also:
        DataValueDescriptor.cloneValue(boolean)

      • compare

        public int compare​(DataValueDescriptor other)
            throws StandardException
        Description copied from interface: DataValueDescriptor
        Compare this Orderable with a given Orderable for the purpose of index positioning. This method treats nulls as ordered values - that is, it treats SQL null as equal to null and greater than all other values.
        Specified by:
        compare in interface DataValueDescriptor
        Parameters:
        other - The Orderable to compare this one to.
        Returns:
        <0 - this Orderable is less than other. 0 - this Orderable equals other. >0 - this Orderable is greater than other. The code should not explicitly look for -1, or 1.
        Throws:
        StandardException - Thrown on error

      • compare

        public boolean compare​(int op,
                       DataValueDescriptor other,
                       boolean orderedNulls,
                       boolean unknownRV)
                throws StandardException
        Description copied from interface: DataValueDescriptor
        Compare this Orderable with a given Orderable for the purpose of qualification and sorting. The caller gets to determine how nulls should be treated - they can either be ordered values or unknown values.
        Specified by:
        compare in interface DataValueDescriptor
        Overrides:
        compare in class DataType
        Parameters:
        op - Orderable.ORDER_OP_EQUALS means do an = comparison. Orderable.ORDER_OP_LESSTHAN means compare this < other. Orderable.ORDER_OP_LESSOREQUALS means compare this <= other.
        other - The DataValueDescriptor to compare this one to.
        orderedNulls - True means to treat nulls as ordered values, that is, treat SQL null as equal to null, and less than all other values. False means to treat nulls as unknown values, that is, the result of any comparison with a null is the UNKNOWN truth value.
        unknownRV - The return value to use if the result of the comparison is the UNKNOWN truth value. In other words, if orderedNulls is false, and a null is involved in the comparison, return unknownRV. This parameter is not used orderedNulls is true.
        Returns:
        true if the comparison is true (duh!)
        Throws:
        StandardException - thrown on error

      • parseLocalTimestamp

        static int[] parseLocalTimestamp​(java.lang.String str,
                                 LocaleFinder localeFinder,
                                 java.util.Calendar cal)
                          throws StandardException,
                                 java.text.ParseException
        Parse a localized timestamp.
        Parameters:
        str - the timestamp string, with trailing blanks removed.
        localeFinder -
        Returns:
        a {encodedDate, encodedTime} array.
        Throws:
        java.text.ParseException - If the string is not a valid timestamp.
        StandardException

      • parseDateOrTimestamp

        static int[] parseDateOrTimestamp​(DateTimeParser parser,
                                  boolean timeRequired)
                           throws StandardException
        Parse a timestamp or a date. DB2 allows timestamps to be used as dates or times. So date('2004-04-15-16.15.32') is valid, as is date('2004-04-15'). This method does not handle localized timestamps.
        Parameters:
        parser - a DateTimeParser initialized with a string.
        timeRequired - If true then an error will be thrown if the time is missing. If false then the time may be omitted.
        Returns:
        {encodedDate, encodedTime, nanosecond} array.
        Throws:
        StandardException - if the syntax is incorrect for an IBM standard timestamp.

      • setFrom

        protected void setFrom​(DataValueDescriptor theValue)
                throws StandardException
        Description copied from class: DataType
        Set the value of this DataValueDescriptor based on the value of the specified DataValueDescriptor.
        Overrides:
        setFrom in class DataType
        Parameters:
        theValue - The DataValueDescriptor that holds the value to which we want to set this DataValueDescriptor's value.
        Throws:
        StandardException

      • setValue

        public void setValue​(java.sql.Timestamp value,
                     java.util.Calendar cal)
              throws StandardException
        Description copied from class: DataType
        Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override
        Specified by:
        setValue in interface DataValueDescriptor
        Overrides:
        setValue in class DataType
        Parameters:
        value - The Timestamp value to set this DataValueDescriptor to
        cal - The time zone from the calendar is used to construct the database timestamp value
        Throws:
        StandardException
        See Also:
        DataValueDescriptor.setValue(int)

      • setValue

        public void setValue​(java.lang.String theValue)
              throws StandardException
        Description copied from class: DataType
        Set the value of this DataValueDescriptor. At DataType level just throws an error lower classes will override
        Specified by:
        setValue in interface DataValueDescriptor
        Overrides:
        setValue in class DataType
        Parameters:
        theValue - The BigDecimal value to set this DataValueDescriptor to
        Throws:
        StandardException

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • typePrecedence

        public int typePrecedence()
        Description copied from class: DataType
        Each built-in type in JSQL has a precedence. This precedence determines how to do type promotion when using binary operators. For example, float has a higher precedence than int, so when adding an int to a float, the result type is float. The precedence for some types is arbitrary. For example, it doesn't matter what the precedence of the boolean type is, since it can't be mixed with other types. But the precedence for the number types is critical. The SQL standard requires that exact numeric types be promoted to approximate numeric when one operator uses both. Also, the precedence is arranged so that one will not lose precision when promoting a type.
        Specified by:
        typePrecedence in interface DataValueDescriptor
        Overrides:
        typePrecedence in class DataType
        Returns:
        The precedence of this type.
        See Also:
        DataValueDescriptor.typePrecedence()

      • isNull

        public final boolean isNull()
        Check if the value is null. encodedDate value of 0 is null
        Specified by:
        isNull in interface Storable
        Returns:
        Whether or not value is logically null.

      • getTimestamp

        public java.sql.Timestamp getTimestamp​(java.util.Calendar cal)
        Get the value field. We instantiate the field on demand.
        Specified by:
        getTimestamp in interface DataValueDescriptor
        Overrides:
        getTimestamp in class DataType
        Parameters:
        cal - calendar for object creation
        Returns:
        The value field.

      • setCalendar

        private void setCalendar​(java.util.Calendar cal)

      • setNumericTimestamp

        private void setNumericTimestamp​(java.sql.Timestamp value,
                                 java.util.Calendar cal)
                          throws StandardException
        Set the encoded values for the timestamp
        Throws:
        StandardException

      • computeEncodedDate

        private static int computeEncodedDate​(java.util.Date value,
                                      java.util.Calendar currentCal)
                               throws StandardException
        computeEncodedDate sets the date in a Calendar object and then uses the SQLDate function to compute an encoded date The encoded date is year << 16 + month << 8 + date
        Parameters:
        value - the value to convert
        Returns:
        the encodedDate
        Throws:
        StandardException

      • computeEncodedTime

        private static int computeEncodedTime​(java.util.Date value,
                                      java.util.Calendar currentCal)
                               throws StandardException
        computeEncodedTime extracts the hour, minute and seconds from a java.util.Date value and encodes them as hour << 16 + minute << 8 + second using the SQLTime function for encoding the data
        Parameters:
        value - the value to convert
        Returns:
        the encodedTime
        Throws:
        StandardException

      • setInto

        public void setInto​(java.sql.PreparedStatement ps,
                    int position)
             throws java.sql.SQLException,
                    StandardException
        Description copied from interface: DataValueDescriptor
        Set this value into a PreparedStatement. This method must handle setting NULL into the PreparedStatement.
        Specified by:
        setInto in interface DataValueDescriptor
        Overrides:
        setInto in class DataType
        Throws:
        java.sql.SQLException - thrown by the PreparedStatement object
        StandardException - thrown by me accessing my value.

      • timestampAdd

        public DateTimeDataValue timestampAdd​(int intervalType,
                                      NumberDataValue count,
                                      java.sql.Date currentDate,
                                      DateTimeDataValue resultHolder)
                               throws StandardException
        Add a number of intervals to a datetime value. Implements the JDBC escape TIMESTAMPADD function.
        Specified by:
        timestampAdd in interface DateTimeDataValue
        Parameters:
        intervalType - One of FRAC_SECOND_INTERVAL, SECOND_INTERVAL, MINUTE_INTERVAL, HOUR_INTERVAL, DAY_INTERVAL, WEEK_INTERVAL, MONTH_INTERVAL, QUARTER_INTERVAL, or YEAR_INTERVAL
        count - The number of intervals to add
        currentDate - Used to convert time to timestamp
        resultHolder - If non-null a DateTimeDataValue that can be used to hold the result. If null then generate a new holder
        Returns:
        startTime + intervalCount intervals, as a timestamp
        Throws:
        StandardException

      • timestampDiff

        public NumberDataValue timestampDiff​(int intervalType,
                                     DateTimeDataValue time1,
                                     java.sql.Date currentDate,
                                     NumberDataValue resultHolder)
                              throws StandardException
        Finds the difference between two datetime values as a number of intervals. Implements the JDBC TIMESTAMPDIFF escape function.
        Specified by:
        timestampDiff in interface DateTimeDataValue
        Parameters:
        intervalType - One of FRAC_SECOND_INTERVAL, SECOND_INTERVAL, MINUTE_INTERVAL, HOUR_INTERVAL, DAY_INTERVAL, WEEK_INTERVAL, MONTH_INTERVAL, QUARTER_INTERVAL, or YEAR_INTERVAL
        time1 -
        currentDate - Used to convert time to timestamp
        resultHolder - If non-null a NumberDataValue that can be used to hold the result. If null then generate a new holder
        Returns:
        the number of intervals by which this datetime is greater than time1
        Throws:
        StandardException

      • promote

        static SQLTimestamp promote​(DateTimeDataValue dateTime,
                            java.sql.Date currentDate)
                     throws StandardException
        Promotes a DateTimeDataValue to a timestamp.
        Returns:
        the corresponding timestamp, using the current date if datetime is a time, or time 00:00:00 if datetime is a date.
        Throws:
        StandardException