Working with Dates

The utilities provided by Java are by no means limited to data containers. Part of the Java API consists of a number of classes useful for creating and manipulating dates. When Java's support for internationalization was introduced with the 1.1 release, the date- related classes in the language were obviously impacted significantly. For this reason, most of the discussion of dates is held until Chapter 24, "Using Internationalization." However, this section covers the Date class in particular, which provides some useful functionality for representing a specific instant in time and comparing two such values.

The Date Class

The Date class represents a specific date and time. It is centered around the Epoch, which is midnight GMT on January 1, 1970. If you look at the API documentation for this class, you will see that the majority of its constructors and methods are deprecated. Prior to the Java 1.1 release, Date provided functionality for formatting dates and separating them out into year, month, day, hour , and so on. The existing functionality did not support the need for internationalization, so these responsibilities were transferred to the Calendar and DateFormat classes introduced later in Chapter 24. This section instead focuses on the nondeprecated operations of the class.

You can create a Date object that represents the current date and time by calling its no- argument constructor:

 public Date() 

You can also create a Date object using the number of milliseconds from the Epoch, which is the same kind of value returned by System.currentTimeMillis():

 public Date(long millis) 

Comparing Dates

The nondeprecated methods of Date, other than clone and toString, relate to comparing two Date instances. As is true with all classes, you can compare two dates for object equality with the equals method. The Date class also provides methods for determining whether one date comes before or after another. The after method returns true if a date instance comes after the date passed to the method as an argument:

 public boolean after(Date when) 

Similarly, the before method tells whether a date instance occurs before a date passed to the method:

 public boolean before(Date when) 

Date also provides two overloaded implementations of compareTo whose signatures differ only in the type of the method parameter. Date implements Comparable so one of these methods is declared to accept a parameter of type Object. The other specifically declares its parameter to be a Date. These methods function equivalently, except that the second version throws a ClassCastException if the method argument is not a Date instance:

 public int compareTo(Date otherDate) public int compareTo(Object o) 

Converting Dates to Strings

Date was originally created with several methods for returning a string representation, but all other than toString have been deprecated. This method converts a Date to a String of the form:

 dow mon dd hh:mm:ss zzz yyyy 

See Chapter 24, "Using Internationalization."

Changing Date Attributes

You can change the date and time represented by a Date instance by calling the setTime method and passing a new offset from the Epoch:

 public void setTime(long time)