Date and Timestamp Types

Date, Time and Timestamp types that are passed as parameters to the runQuery method may be constructed using any way chosen by the developer.

It should be noted that the dates passed to the Api are assumed to be UTC.

Java date types are all based on an underlying long value which is the number of milliseconds since Jan 1st 1970 UTC.

All date types have constructors to create a date using this long value, for example:

Date(long date)
Timestamp(long time)

As detailed here:

https://docs.oracle.com/javase/8/docs/api/java/sql/Date.html#Date-long-

https://docs.oracle.com/javase/8/docs/api/java/sql/Timestamp.html#Timestamp-long-

This method of constructing dates and times requires the programmer to create or derive this long value for the desired time parameter.

Alternatively, where a client process is running in a local time zone (one which is not UTC), it may be convenient to use convenient methods which create dates relative to the local time zone.

For example, a client machine running in New York (Eastern Standard Time with Daylight Savings) can create a date of January 1st and time 5p.m in this time zone using:

Date myDate = new Date(2019-1900, 0, 1);

//Note this constructor has zero indexed month and year -1900.
Time marketCloseTime = new Time(17,00,00);
//or
Time marketCloseTime = new Time.valueOf(&quot;17:00:00&quot;);

This date and time means Jan 1st 17:00:00. The time is resilient to Daylight savings changes where the date parameter is in a daylight savings period.

If you want to specify sub milliseconds use the setNanos method of the Timestamp class

https://docs.oracle.com/javase/8/docs/api/java/sql/Timestamp.html#setNanos-int-

For explicit examples of this being used, see the check_nanosecond_output() listed in the Service Tests in the Appendix. Timestamp objects may be used in place of Times where nanosecond granularity is required. Where Timestamps are used in place of Times , the date component of the Timestamp is disregarded.

Note that no parameters are required to indicate what time zone is applicable to date and time parameters passed in queries, and these parameters are not now supported.

In the case of Dates, these will automatically be adjusted to an absolute date corresponding to the Calendar day in the local time zone.

In the case of Times, it is not necessary to specify the time zone as all times are based on underlying UTC time stamps.