home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Java Fundamental Classes Reference

Previous Chapter 17
The java.util Package
Next
 

Date

Name

Date

Synopsis

Class Name:

java.util.Date

Superclass:

java.lang.Object

Immediate Subclasses:

None

Interfaces Implemented:

java.lang.Cloneable, java.io.Serializable

Availability:

JDK 1.0 or later

Description

The Date class encapsulates a point in time with millisecond precision. The value of a Date is represented internally by a long value that contains the number of milliseconds since midnight, January 1, 1970 GMT.

Prior to JDK 1.1, the Date class was used for two purposes that are now encapsulated by other classes. First, the Date class included methods for calculating calendar values, like months and days of the week. This functionality is now embedded in the Calendar class. Second, the Date class included methods for generating and parsing a string representation of a date. This functionality is now provided by java.text.DateFormat. Thus, as of JDK 1.1, most of the methods of Date are deprecated; the class is used only to represent a point in time.

The accurate measurement of time is a subject of considerable complexity and multifarious acronyms. There are two main methods of measuring time, atomic and astronomical. The U.S. Naval Observatory (http://tycho.usno.navy.mil) maintains a set of atomic clocks that provide the basis for Coordinated Universal Time (UTC). These clocks adhere to precise definitions of the second based on atomic decay.

Outside of the U.S. Navy, people tend to measure time in terms of Greenwich Mean Time (GMT). In the scientific community, GMT is called UT, which is a system of time predicated on the assumption that each rotation of the earth is exactly 24 * 60 * 60 seconds long. Because the earth's rotation is gradually slowing down, the seconds in UT are a little bit longer than the seconds in UTC. Now and then a "leap second" is added in UTC to keep it close to UT. Because the Date class simply measures milliseconds since a point in time, without regard for leap seconds, it is a good representation of UT or GMT.

Class Summary

public class java.util.Date extends java.lang.Object
             implements java.lang.Cloneable, java.io.Serializable {
  // Constructors
  public Date();
  public Date(long date);
  public Date(int year, int month, int date);       // Deprecated in 1.1
  public Date(int year, int month, int date, 
              int hrs, int min);                    // Deprecated in 1.1
  public Date(int year, int month, int date, 
              int hrs, int min, int sec);           // Deprecated in 1.1
  public Date(String s);                            // Deprecated in 1.1
  // Class Methods
  public static long parse(String s);               // Deprecated in 1.1
  public static long UTC(int year, int month, 
                         int date, int hrs, 
                         int min, int sec);         // Deprecated in 1.1
  // Instance Methods
  public boolean after(Date when);
  public boolean before(Date when);
  public boolean equals(Object obj); 
  public int getDate();                             // Deprecated in 1.1
  public int getDay();                              // Deprecated in 1.1
  public int getHours();                            // Deprecated in 1.1
  public int getMinutes();                          // Deprecated in 1.1
  public int getMonth();                            // Deprecated in 1.1
  public int getSeconds();                          // Deprecated in 1.1
  public long getTime();
  public int getTimezoneOffset();                   // Deprecated in 1.1
  public int getYear();                             // Deprecated in 1.1
  public int hashCode();
  public void setDate(int date);                    // Deprecated in 1.1
  public void setHours(int hours);                  // Deprecated in 1.1
  public void setMinutes(int minutes);              // Deprecated in 1.1
  public void setMonth(int month);                  // Deprecated in 1.1
  public void setSeconds(int seconds);              // Deprecated in 1.1
  public void setTime(long time);
  public void setYear(int year);                    // Deprecated in 1.1
  public String toGMTString();                      // Deprecated in 1.1
  public String toLocaleString();                   // Deprecated in 1.1
  public String toString();
}

Constructors

Date

public Date()

Description

This constructor creates a Date object that is initialized to the current time.

public Date(long date)

Parameters

date

A time value, measured as the number of milliseconds since midnight, January 1, 1970 GMT.

Description

This constructor creates a Date object that represents the given time.

public Date(int year, int month, int day)

Availability

Deprecated as of JDK 1.1

Parameters

year

The year specified as a value that is added to 1900 to get the actual year.

month

The month specified in the range 0 to 11.

day

The day of the month specified in the range 1 to 31.

Description

This constructor creates a Date that represents midnight local time on the specified date.

public Date(int year, int month, int day, int hrs, int min)

Availability

Deprecated as of JDK 1.1

Parameters

year

The year specified as a value that is added to 1900 to get the actual year.

month

The month specified in the range 0 to 11.

day

The day of the month specified in the range 1 to 31.

hrs

The hours specified in the range 0 to 23.

min

The minutes specified in the range 0 to 59.

Description

This constructor creates a Date that represents the given date and time.

 public Date(int year, int month, int day, int hrs, int min, int sec) 

Availability

Deprecated as of JDK 1.1

Parameters

year

The year specified as a value that is added to 1900 to get the actual year.

month

The month specified in the range 0 to 11.

day

The day of the month specified in the range 1 to 31.

hrs

The hours specified in the range 0 to 23.

min

The minutes specified in the range 0 to 59.

sec

The seconds specified in the range 0 to 59.

Description

This constructor creates a Date that represents the given date and time.

public Date(String s)

Availability

Deprecated as of JDK 1.1

Parameters

s

The string to parse.

Description

This constructor creates a Date that represents the date and time specified by the given string. The syntax of the date in the string must satisfy the requirements of the parse() method. The following is an example of a string that this constructor can understand:

Sat, 8 Feb 1997 13:30:00 GMT

Class Methods

parse

public static long parse(String s)

Availability

Deprecated as of JDK 1.1

Parameters

s

The string to parse.

Returns

A time value represented as the number of milliseconds since midnight, January 1, 1970 GMT.

Throws

IllegalArgumentException

If the string cannot be parsed.

Description

This method returns the raw time value specified by the given string. This method understands a number of different formats. The following are examples of strings that this method can understand:

Sat, 8 Feb 1997 13:30:00 GMT
4/6/97
4/6/1997
January 5, 1997
2/4/97 11:03 AM
2/4/97 10:25 PM
2/4/97 17:03 GMT-6
2/4/97 17:03:24
March 16, 97 17:03 EST
March (comment)16, 97 (comment) 17:03 EST
16 march 1996 17:03 pdt
Sat 16 march 97 17:03 cst

The JDK 1.0.2 implementation of parse() has a serious bug. It incorrectly interprets date formats that specify the month as a number by making the month one greater than it should be. So 2/4/97 is incorrectly interpreted as March 4, 1997.

For the purposes of this method, UTC and GMT are considered equivalent.

UTC

 public static long UTC(int year, int month, int date, int hrs, int min, int sec) 

Availability

Deprecated as of JDK 1.1

Parameters

year

The year specified as a value that is added to 1900 to get the actual year.

month

The month specified in the range 0 to 11.

day

The day of the month specified in the range 1 to 31.

hrs

The hours specified in the range 0 to 23.

min

The minutes specified in the range 0 to 59.

sec

The seconds specified in the range 0 to 59.

Returns

A time value represented as the number of milliseconds since midnight, January 1, 1970 GMT.

Description

This method returns a raw time value that corresponds to the given parameters. Computations are based on GMT, not the local time zone.

Instance Methods

after

public boolean after(Date when)

Parameters

when

The object to compare to this Date.

Returns

true if this object is after when; false otherwise.

Description

This method returns true if the value of when falls before the value of this Date.

before

public boolean before(Date when)

Parameters

when

The object to compare to this Date.

Returns

true if this object is before when; false otherwise.

Description

This method returns true if the value of when falls after the value of this Date.

equals

public boolean equals(Object obj)

Parameters

obj

The object to be compared with this object.

Returns

true if the objects are equal; false if they are not.

Overrides

Object.equals()

Description

This method returns true if when is an instance of Date and it contains the same value as the object this method is associated with. In other words, the two Date objects are equal only if they both represent the same point in time, to the millisecond.

getDate

public int getDate()

Availability

Deprecated as of JDK 1.1

Returns

The day of the month of this Date.

Description

This method returns the day of the month represented by this Date object. The value is in the range 1 to 31.

getDay

public int getDay()

Availability

Deprecated as of JDK 1.1

Returns

The day of the week of this Date.

Description

This method returns the day of the week represented by this Date object. The value is in the range 0 to 6, where 0 means Sunday.

getHours

public int getHours()

Availability

Deprecated as of JDK 1.1

Returns

The hour value of this Date.

Description

This method returns the hour represented by this Date object. The value is in the range 0 to 23, where 0 means midnight.

getMinutes

public int getMinutes()

Availability

Deprecated as of JDK 1.1

Returns

The minute value of this Date.

Description

This method returns the number of minutes after the hour represented by this Date object. The value is in the range 0 to 59.

getMonth

public int getMonth()

Availability

Deprecated as of JDK 1.1

Returns

The month of this Date.

Description

This method returns the month represented by this Date object. The value is in the range 0 to 11, where 0 means January.

getSeconds

public int getSeconds()

Availability

Deprecated as of JDK 1.1

Returns

The second value of this Date.

Description

This method returns the number of seconds after the minute represented by this Date object. The value is in the range 0 to 59.

getTime

public long getTime()

Returns

The raw time value of this Date.

Description

This method returns the date and time of this Date as the number of milliseconds since midnight, January 1, 1970 GMT.

getTimezoneOffset

public int getTimezoneOffset()

Availability

Deprecated as of JDK 1.1

Returns

The time zone offset for this Date.

Description

This method returns the number of minutes between the local time zone and GMT for this Date object.

getYear

public int getYear()

Availability

Deprecated as of JDK 1.1

Returns

The year of this Date.

Description

This method returns the year represented by this Date object. The value is the number of years since 1990.

hashCode

public int hashCode()

Returns

The hashcode for this Date.

Overrides

Object.hashCode()

Description

This method returns a hashcode for this object.

setDate

public void setDate(int date)

Availability

Deprecated as of JDK 1.1

Parameters

date

The day of the month specified in the range 1 to 31.

Description

This method sets the day of the month of this Date object.

setHours

public void setHours(int hours)

Availability

Deprecated as of JDK 1.1

Parameters

hours

The hours specified in the range 0 to 23.

Description

This method sets the hour of this Date object.

setMinutes

public void setMinutes(int minutes)

Availability

Deprecated as of JDK 1.1

Parameters

minutes

The minutes specified in the range 0 to 59.

Description

This method sets the minute value of this Date object.

setMonth

public void setMonth(int month)

Availability

Deprecated as of JDK 1.1

Parameters

month

The month specified in the range 0 to 11.

Description

This method sets the month of this Date object

setSeconds

public void setSeconds(int seconds)

Availability

Deprecated as of JDK 1.1

Parameters

seconds

The seconds specified in the range 0 to 59.

Description

This method sets the second value of this Date object.

setTime

public void setTime(long time)

Parameters

time

A time value specified as the number of milliseconds since midnight, January 1, 1970 GMT.

Description

This method sets the date and time represented by this Date to the given raw time value.

setYear

public void setYear(int year)

Availability

Deprecated as of JDK 1.1

Parameters

year

The year specified as a value that is added to 1900 to get the actual year.

Description

This method sets the year of this Date object.

toGMTString

public String toGMTString()

Availability

Deprecated as of JDK 1.1

Returns

A string that represents this Date.

Description

The method returns a string representation of this Date object based on Internet GMT conventions. The string is of the form:

Sat, 8 Feb 1997 13:30:00 GMT

The date is the string is either one or two digits; the rest of the fields always have the width shown. The time zone is always GMT.

toLocaleString

public String toLocaleString()

Availability

Deprecated as of JDK 1.1

Returns

A string that represents this Date.

Description

The method returns a string representation of this Date based on the conventions of the current locale.

toString

public String toString()

Returns

A string that represents this Date.

Overrides

Object.toString()

Description

This method returns a string representation of this Date. The string is of the form:

Sat Feb 8 2:30:00 MST 1997

Inherited Methods

Method

Inherited From

Method

Inherited From

clone()

Object

finalize()

Object

getClass()

Object

notify()

Object

notifyAll()

Object

wait()

Object

wait(long)

Object

wait(long, int)

Object

See Also

Calendar, Cloneable, DateFormat, GregorianCalendar, IllegalArgumentException, Serializable, TimeZone


Previous Home Next
Calendar Book Index Dictionary

Java in a Nutshell Java Language Reference Java AWT Java Fundamental Classes Exploring Java