Time and Date

The basics of Time and Date

Some definitions:

The "computer epoch" is a fixed point in time January 1, 1970 00:00:00 GMT. System times are stored as long (64 bit) integers specifying the number of milli-seconds since the "epoch". GMT stands for Greenwich mean time, time in a Greenwich, England which sits on 0⁰ longitude.
Time is not a simple concept. Though you' probably learned how to read a clock when you were in kindergarten, the actual accurate setting of the clock depends on what time zone you are in, whether or not day light savings is in effect, whether this is a leap year, and lets not forget adding the leap seconds which come up every few years as well!

The actual definition of "second" has been changed twice in my lifetime:

1960- it was defined as: the fraction 1/31,556,925.9747 of the tropical year for 1900 January 0 at12 hours ephemeris time
1967 - it was redefined as: the duration of 9,192,631,770 periods of the radiation corresponding to the transition between the two hyperfine levels of the ground state of the cesium 133 atom

Due to the fact that the earth does not rotate at a constant rate, actually its decelerating 1.4 milliseconds per day per century, and people like noon to mean a time near the time the sun is at its hightest point, clocks continually have to be adjusted. For more about time, see the Navy at http://tycho.usno.navy.mil/time.html

The measurement of and timing of leap years has changed, under the Julian calendar, a day was added every 4 years, the leap year. In 1582 it was determined that adding a day every four years was incorrect, the Julian calendar specifies leap years every four years, whereas the Gregorian calendar omits century years which are not divisible by 400. When this change ocurred, they adjust all the calendars by 11 days, thus October 4, 1582 was thus followed by October 15, 1582.
Why is this important? Under the global economy you have to be very specific about times in order for airlines, communications, network tv, etc. to work. Also, if you are storing or retrieving a date in a database, you have to be able to accurately interpret it.
And if you don't have enough to worry about, a lot of computer times are kept in 32 bit integers, and their ability to track time will cease as of 2038!!!

Java Objects:

java.util.Date - represents a specific instant in time, with millisecond precision.

constructors:

Date() - create a date object using the current time
Date(long value) - create a date object based on the specified time in milliseconds since "the epoch"

methods :

String toString() - returns a string reprentation in the form "dow mon dd hh:mm:ss zzz yyyy", e.g. Tue Feb 24 11:32:01 EST 2004.

java.util.GregorianCalendar - class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. Years are the actual year (2001, 2004, etc), DAY_OF_MONTH is one relative, that is March 1 is a 1. MONTH is zero relative, January is 0, February is 1, etc.

constructors:

GregorianCalendar() - create an object based on the current time and date
GregorianCalendar(int year, int month, int date, int hour, int minute, int second) - create an object based on the specified information

methods:

int get(int field) - returns an integer specified by field. Field is a constant (DAY_OF_YEAR, DAY_OF_MONTH, HOUR_OF_DAY, MONTH, YEAR, etc). Note: MONTH is zero relative!
void set(int field, int value) - sets a specified field to a given value
void add(int field, int value) - adjusts the date by a given amount. field indicates the field (day, month, year, etc), value is the amount to add.
Date getTime() - returns a date object based on the calendar object
long getTimeInMillis() - returns the time as a long integer milliseconds since the epoch
other methods

comparison methods, before, after, compareTo
roll methods to change a day or month without carrying up/down to the next higher field.

java.text.SimpleDateFormat - used for formatting and parsing dates in a locale-sensitive manner. It allows for formatting (date -> text), parsing (text -> date), and normalization.

constructors:

SimpleDateFormat(String pattern) - pattern is a string specifying what the date should look like.

methods:

String format(Date time) - format the given date object and return a string
Date parse(String obj) - parse the given String and return a Date object.

Pattern letter
Time component
Example output:

G Era designator AD

y Year 1996; 96

M Month in year July; Jul; 07

w Week in year 27

W Week in month 2

D Day in year 189

d Day in month 10

F Day of week in month 2

E Day in week Tuesday; Tue

a Am/pm marker PM

H Hour in day (0-23) 0

k Hour in day (1-24) 24

K Hour in am/pm (0-11) 0

h Hour in am/pm (1-12) 12

m Minute in hour 30

s Second in minute 55

S Millisecond 978

z Time zone Pacific Standard Time; PST; GMT-08:00

Z Time zone -0800

Examples:

Date and Time Pattern Result

"yyyy.MM.dd G 'at' HH:mm:ss z" 2001.07.04 AD at 12:08:56 PDT

"EEE, MMM d, ''yy" Wed, Jul 4, '01

"h:mm a" 12:08 PM

"hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time

"K:mm a, z" 0:08 PM, PDT

"yyyyy.MMMMM.dd GGG hh:mm aaa" 02001.July.04 AD 12:08 PM

"EEE, d MMM yyyy HH:mm:ss Z" Wed, 4 Jul 2001 12:08:56 -0700

Date and Time Pattern	Result
`"yyyy.MM.dd G 'at' HH:mm:ss z"`	`2001.07.04 AD at 12:08:56 PDT`
`"EEE, MMM d, ''yy"`	`Wed, Jul 4, '01`
`"h:mm a"`	`12:08 PM`
`"hh 'o''clock' a, zzzz"`	`12 o'clock PM, Pacific Daylight Time`
`"K:mm a, z"`	`0:08 PM, PDT`
`"yyyyy.MMMMM.dd GGG hh:mm aaa"`	`02001.July.04 AD 12:08 PM`
`"EEE, d MMM yyyy HH:mm:ss Z"`	`Wed, 4 Jul 2001 12:08:56 -0700`

java.sql.Date - based on java.util.Date, this class gives JDBC the ability to identify this as an SQL DATE value. To conform to SQL's definition of DATE, the millisecond values wrapped by a java.sql.Date instance must be 'normalized' by setting the hours, minutes, seconds, and milliseconds to zero in the particular time zone with which the instance is associated.

constructors

Date(long date) - creates a date object the specified time.

methods

String toString() - returns a string in the format yyyy-mm-dd
Date valueOf(String obj) - Converts a string in JDBC date escape format to a Date value. yyyy-mm-dd

java.sql.Time - an extention java.util.Date class that allows the JDBC API to identify this as an SQL TIME value. The Time class adds formatting and parsing operations to support the JDBC escape syntax for time values. The date components should be set to the "zero epoch" value of January 1, 1970 and should not be accessed.

constructors

Time(long time) - creates a Time object based on milliseconds since January 1, 1970, 00:00:00 GMT; a negative number is milliseconds before January 1, 1970, 00:00:00 GMT.

methods

Time valueOf(String s) - Converts a string in JDBC time escape format(hh:mm:ss) to a Time value.
String toString() - Formats a time in JDBC time escape format. (hh:mm:ss).

java.sql.Timestamp - An extension java.util.Date that allows the JDBC API to identify this as an SQL TIMESTAMP value. This allows the holding of time in terms of nanoseconds.

constructor

Timestamp(long time) - creates a Timestamp object based on milliseconds since January 1, 1970, 00:00:00 GMT; a negative number is milliseconds before January 1, 1970, 00:00:00 GMT.

methods

Time valueOf(String s) - Converts a string in JDBC time escape format(yyyy-mm-dd hh:mm:ss.fffffffff ) to a Time value.
String toString() - Formats a time in JDBC timestamp escape format. (yyyy-mm-dd hh:mm:ss.fffffffff ).

Note: you can retrieve the current time in milliseconds using System.currentTimeMillis()

When to use what objects:

For most programming purposes dealing with the current time and local time zone, you can use the java.util.Date object to hold a time (and date), and SimpleDateFormat to convert it into a string for ouput to the screen or to a file. e.g.

   java.util.Date d = new java.util.Date();
     SimpleDateFormat frm = new SimpleDateFormat("MM/dd/yyyy G hh:mm:ss aa z");
     outputField.setText(frm.format(d));

To create a Date object based on data input from a user or text file or to deal with the components of a date (day of year, day of month, day of week), use the GregorianCalendar object. Note, this is useful if you want to calculate the time it would be N days in the future/past. e.g.

GregorianCalendar cal = new GregorianCalendar(2004,2,24,12,30,3); // create a calendar date Feb 24, 2004 at 12:30:03
GregorianCalendar checkoutdate = new GregorianCalendar(); // set the date checked out to today's date and time
GregorianCalendar duedate = new GregorianCalendar(); // set due date to today's date
duedate.add(GregorianCalendar.DAY_OF_YEAR,14); // add 14 days to due date
Date due = duedate.getTime(); // due date in Date format

If you are formatting strings to be inserted into and out of a database using SQL statement commands, then you may want to use the java.sql.Date, java.sql.Time, and java.sql.Timestamp objects. All these objects are based on the java.util.Date object (so they can be used anywhere java.util.Date can be used), but each has its own toString function that will produce an output compatible with SQL INSERT INTO and UPDATE functions. Also use these forms when you are setting/getting date/time information from PreparedStatements and ResultSets.

Note: the setDate, setTime, setTimestamp methods of PreparedStatements handle taking the date and formatting it in the proper way to get it into the database. Alternatively you could give the user just one JTextfield to type in date information, then put a # before and after the date they entered and pass the whole thing off to SQL. This assumes the user can be trusted to type everything in just right.

Example: Retrieve a date field from the result set and enter the date onto JTextFields (month, day, year)

     try{
        PreparedStatement prep = con.prepareStatement("SELECT * FROM orders WHERE ordernumber = ?");
        prep.setInt(1, number);
        ResultSet rs = prep.executeQuery();
        if(rs.next()) // was at least one record found?
        {
         // get record data from result set into local variables
         number = rs.getInt(1);
         String phone = rs.getString(2);
         String product = rs.getString(3);
         short quantity = rs.getShort(4);
         double price = rs.getDouble(5);
         java.sql.Timestamp orderdate = rs.getTimestamp(6);

         GregorianCalendar cal = new GregorianCalendar();
         cal.setTime(orderdate);
         //
         // display data onto screen
         //
         orderNumberField.setText(""+number);
         orderPhoneField.setText(phone);
         orderProductField.setSelectedItem(product);
         orderQuantityField.setText(""+quantity);
         orderPriceField.setText(""+price);
         orderMonthField.setText(""+(cal.get(GregorianCalendar.MONTH)+1)); // add one to make month 1 relative
         orderYearField.setText(""+cal.get(GregorianCalendar.YEAR));
         orderDayField.setText(""+cal.get(GregorianCalendar.DAY_OF_MONTH));
         messageLabel.setText(""); // clear out message label
        }
        else
          messageLabel.setText(number+" not found in Orders table");
        prep.close();
       }
       catch(SQLException sqle)
       {
        messageLabel.setText("Error during lookup : "+sqle.getMessage());
       }

Example: Add a record to the database from information on the screen. Month, day, year are JTextFields.

     //
        // retrieve and convert data into local variables
        //
        String product = (String)orderProductField.getSelectedItem();
        String strquantity = orderQuantityField.getText();
        String strprice = orderPriceField.getText();
        String phone = orderPhoneField.getText();
        String monthstr = orderMonthField.getText();
        String yearstr = orderYearField.getText();
        String daystr = orderDayField.getText();
        int month, day, year;
        short quantity = 0;;
        double price = 0;

        try{
          quantity = Short.parseShort(strquantity);
        }
        catch(NumberFormatException e)
        {
         messageLabel.setText("Invalid entry in quantity field, must be a number");
         return;
        }
        try{
          price = Double.parseDouble(strprice);
        }
        catch(NumberFormatException e)
        {
         messageLabel.setText("Invalid entry in price field, must be a number");
         return;
        }

        try{
          month = Integer.parseInt(monthstr)-1; // make 0 relative
          day = Integer.parseInt(daystr);
          year = Integer.parseInt(yearstr);
        }
        catch(NumberFormatException e)
        {
         messageLabel.setText("Invalid entry date field");
         return;
        }
        //
        // Create an SQL date object, first create a Gregorian Calendar, then the date
        //
        GregorianCalendar caldate = new GregorianCalendar(year, month, day, 0, 0, 0);
        java.sql.Date date = new java.sql.Date(caldate.getTimeInMillis());
        //
        // test data for consistency and accuracy
        //
        if(price < 0)
        {
         messageLabel.setText("Price must be greater than or equal to zero");
         return;
        }
        if(quantity < 0)
        {
         messageLabel.setText("Quantity must be greater than or equal to zero");
         return;
        }
        if(product.length() <= 0)
        {
         messageLabel.setText("Product name cannot be blank");
         return;
        }
        if(phone.length() <= 0)
        {
         messageLabel.setText("Customer phone cannot be blank");
         return;
        }
        //
        // create and execute a prepared statement
        //
        try{
          PreparedStatement prep = con.prepareStatement("INSERT INTO orders (CustomerPhone, ProductName, Quantity, PriceEach, OrderDate) Values(?, ?, ?, ?, ?)");
          prep.setString(1, phone);
          prep.setString(2,product);
          prep.setShort(3,quantity);
          prep.setDouble(4,price);
          prep.setDate(5,date);
          int result = prep.executeUpdate();
          if(result == 1)
             messageLabel.setText("New record added to the order table");
          else
             messageLabel.setText("Unable to add to the order table");
          prep.close(); // close the PreparedStatement
         }
         catch (SQLException e)
         {
          messageLabel.setText("Unable to order table : "+e.getMessage());
         }

Pattern letter	Time component	Example output:
`G`	Era designator	`AD`
`y`	Year	`1996`; `96`
`M`	Month in year	`July`; `Jul`; `07`
`w`	Week in year	`27`
`W`	Week in month	`2`
`D`	Day in year	`189`
`d`	Day in month	`10`
`F`	Day of week in month	`2`
`E`	Day in week	`Tuesday`; `Tue`
`a`	Am/pm marker	`PM`
`H`	Hour in day (0-23)	`0`
`k`	Hour in day (1-24)	`24`
`K`	Hour in am/pm (0-11)	`0`
`h`	Hour in am/pm (1-12)	`12`
`m`	Minute in hour	`30`
`s`	Second in minute	`55`
`S`	Millisecond	`978`
`z`	Time zone	`Pacific Standard Time`; `PST`; `GMT-08:00`
`Z`	Time zone	`-0800`