Merge pull request #361 from marschall/timestamp-with-time-zone-javadoc

Improve TimestampWithTimeZone javadoc

h2/src/main/org/h2/api/TimestampWithTimeZone.java

@@ -46,18 +46,55 @@ public class TimestampWithTimeZone implements Serializable, Cloneable {
         return dateValue;
     }
 
+    /**
+     * Gets the year.
+     *
+     * <p>The year is in the specified time zone and not UTC. So for
+     * {@code 2015-12-31 19:00:00.00-10:00} the value returned
+     * will be {@code 2015} even though in UTC the year is {@code 2016}.</p>
+     *
+     * @return the year
+     */
     public int getYear() {
         return DateTimeUtils.yearFromDateValue(dateValue);
     }
 
+    /**
+     * Gets the month 1-based.
+     *
+     * <p>The month is in the specified time zone and not UTC. So for
+     * {@code 2015-12-31 19:00:00.00-10:00} the value returned
+     * is {@code 12} even though in UTC the month is {@code 1}.</p>
+     *
+     * @return the month
+     */
     public int getMonth() {
         return DateTimeUtils.monthFromDateValue(dateValue);
     }
 
+    /**
+     * Gets the day of month 1-based.
+     *
+     * <p>The day of month is in the specified time zone and not UTC. So for
+     * {@code 2015-12-31 19:00:00.00-10:00} the value returned
+     * is {@code 31} even though in UTC the day of month is {@code 1}.</p>
+     *
+     * @return the day of month
+     */
     public int getDay() {
         return DateTimeUtils.dayFromDateValue(dateValue);
     }
 
+    /**
+     * Gets the nanoseconds since midnight.
+     *
+     * <p>The nanoseconds are relative to midnight in the specified
+     * time zone. So for {@code 2016-09-24 00:00:00.000000001-00:01} the
+     * value returned is {@code 1} even though {@code 60000000001}
+     * nanoseconds have passed since midnight in UTC.</p>
+     *
+     * @return the nanoseconds since midnight
+     */
     public long getNanosSinceMidnight() {
         return timeNanos;
     }

h2/src/test/org/h2/test/unit/TestTimeStampWithTimeZone.java

@@ -37,11 +37,47 @@ public class TestTimeStampWithTimeZone extends TestBase {
         Statement stat = conn.createStatement();
         stat.execute("create table test(id identity, t1 timestamp with timezone)");
         stat.execute("insert into test(t1) values('1970-01-01 12:00:00.00+00:15')");
+        // verify NanosSinceMidnight is in local time and not UTC
+        stat.execute("insert into test(t1) values('2016-09-24 00:00:00.000000001+00:01')");
+        stat.execute("insert into test(t1) values('2016-09-24 00:00:00.000000001-00:01')");
+        // verify year month day is in local time and not UTC
+        stat.execute("insert into test(t1) values('2016-01-01 05:00:00.00+10:00')");
+        stat.execute("insert into test(t1) values('2015-12-31 19:00:00.00-10:00')");
         ResultSet rs = stat.executeQuery("select t1 from test");
         rs.next();
         assertEquals("1970-01-01 12:00:00.0+00:15", rs.getString(1));
         TimestampWithTimeZone ts = (TimestampWithTimeZone) rs.getObject(1);
+        assertEquals(1970, ts.getYear());
+        assertEquals(1, ts.getMonth());
+        assertEquals(1, ts.getDay());
+        assertEquals(15, ts.getTimeZoneOffsetMins());
         assertEquals(new TimestampWithTimeZone(1008673L, 43200000000000L, (short) 15), ts);
+        rs.next();
+        ts = (TimestampWithTimeZone) rs.getObject(1);
+        assertEquals(2016, ts.getYear());
+        assertEquals(9, ts.getMonth());
+        assertEquals(24, ts.getDay());
+        assertEquals(1, ts.getTimeZoneOffsetMins());
+        assertEquals(1L, ts.getNanosSinceMidnight());
+        rs.next();
+        ts = (TimestampWithTimeZone) rs.getObject(1);
+        assertEquals(2016, ts.getYear());
+        assertEquals(9, ts.getMonth());
+        assertEquals(24, ts.getDay());
+        assertEquals(-1, ts.getTimeZoneOffsetMins());
+        assertEquals(1L, ts.getNanosSinceMidnight());
+        rs.next();
+        ts = (TimestampWithTimeZone) rs.getObject(1);
+        assertEquals(2016, ts.getYear());
+        assertEquals(1, ts.getMonth());
+        assertEquals(1, ts.getDay());
+        rs.next();
+        ts = (TimestampWithTimeZone) rs.getObject(1);
+        assertEquals(2015, ts.getYear());
+        assertEquals(12, ts.getMonth());
+        assertEquals(31, ts.getDay());
+        rs.close();
+        stat.close();
         conn.close();
     }