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

• 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.
• also note,  when storing dates in a database, its usually best to have the server store its own date/time, rather than relying on the user's machine to be set correctly.  Every DBMS has a different function to do this,  in SQLServer, use GetDate(), e.g.