epubjs
Version:
Render ePub documents in the browser, across many devices
272 lines (263 loc) • 47.2 kB
HTML
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Dates and Times</title><link rel="stylesheet" href="core.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"/></head><body><div class="sect1" title="Dates and Times"><div class="titlepage"><div><div><h1 class="title"><a id="learnjava3-CHP-11-SECT-2"/>Dates and Times</h1></div></div></div><p>Working with dates and times without the proper tools can be a
chore. Fortunately, Java has three classes that handle most of the work
for you. The <a id="I_indexterm11_id738307" class="indexterm"/><code class="literal">java.util.Date</code> class
encapsulates a point in time. The <a id="I_indexterm11_id738318" class="indexterm"/><code class="literal">java.util.GregorianCalendar</code> class, which extends
the abstract <a id="I_indexterm11_id738329" class="indexterm"/><code class="literal">java.util.Calendar</code>,
translates between a point in time and calendar fields like month, day,
and year. Finally, the <code class="literal">java.text.DateFormat</code> class knows how to generate
and parse string representations of dates and times in many
languages.<sup>[<a id="learnjava3-CHP-11-FN-2" href="#ftn.learnjava3-CHP-11-FN-2" class="footnote">32</a>]</sup></p><p>The separation of the <code class="literal">Date</code> and
<code class="literal">Calendar</code> classes is analogous to having
a class representing temperature and a class that translates that
temperature to Celsius units. A <code class="literal">Date</code>
represents an absolute point in time as defined by a number of
milliseconds from the reference point: midnight, Jan 1, 1970, GMT. This is
the same frame of reference used by the <a id="I_indexterm11_id738386" class="indexterm"/><code class="literal">System.currentTimeMillis()</code> call. A <code class="literal">Calendar</code> encapsulates a point in time and maps
it to higher-level (and messier) notions like years, months, weeks, and
days, and deals with discontinuities like leap years. Conceivably, we
could define subclasses of <code class="literal">Calendar</code>
other than the default <code class="literal">GregorianCalendar</code>, say <code class="literal">JulianCalendar</code> or <code class="literal">LunarCalendar</code>, that map time using other
sociological or cultural conventions.<sup>[<a id="learnjava3-CHP-11-FN-3" href="#ftn.learnjava3-CHP-11-FN-3" class="footnote">33</a>]</sup></p><div class="sect2" title="Working with Calendars"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-11-SECT-2.1"/>Working with Calendars</h2></div></div></div><p><a id="idx10596" class="indexterm"/> <a id="idx10619" class="indexterm"/> <a id="idx10638" class="indexterm"/>The default <code class="literal">GregorianCalendar</code> constructor creates a
calendar initialized to the current time, in the current time
zone:</p><a id="I_11_tt687"/><pre class="programlisting"> <code class="n">GregorianCalendar</code> <code class="n">now</code> <code class="o">=</code> <code class="k">new</code> <code class="n">GregorianCalendar</code><code class="o">();</code></pre><p>However, more generally we can just ask the <code class="literal">Calendar</code> class for an appropriate calendar
instance without worrying about what type of calendar system the world
is using this century:</p><a id="I_11_tt688"/><pre class="programlisting"> <code class="n">Calendar</code> <code class="n">now</code> <code class="o">=</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">getInstance</code><code class="o">();</code></pre><p>In either case, all the real work is done through the main
<a id="I_indexterm11_id738531" class="indexterm"/><code class="literal">set()</code> and <a id="I_indexterm11_id738541" class="indexterm"/><code class="literal">get()</code> methods of
<code class="literal">Calendar</code>. These methods use static
identifiers to refer to calendar fields and values. For example:</p><a id="I_11_tt689"/><pre class="programlisting"> <code class="n">Calendar</code> <code class="n">birthday</code> <code class="o">=</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">getInstance</code><code class="o">();</code>
<code class="n">birthday</code><code class="o">.</code><code class="na">set</code><code class="o">(</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">YEAR</code><code class="o">,</code> <code class="mi">1972</code> <code class="o">);</code>
<code class="n">birthday</code><code class="o">.</code><code class="na">set</code><code class="o">(</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">MONTH</code><code class="o">,</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">MAY</code> <code class="o">);</code>
<code class="n">birthday</code><code class="o">.</code><code class="na">set</code><code class="o">(</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">DATE</code><code class="o">,</code> <code class="mi">20</code> <code class="o">);</code></pre><p>Here, we set the year, month, and day values on the calendar,
altering the internal <code class="literal">Date</code> of the
<code class="literal">Calendar</code> object. Any remaining fields
that we did not set are left as they were initialized (to the current
date and time when it was constructed). In this case, we did not really
specify a full date and time; we simply overrode individual fields in
the calendar.</p><p>The <code class="literal">Calendar</code> class contains
identifiers for all of the standard date and time fields, as well as
values such as days of the week and months of the year. The following
are the most common identifiers:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><a id="I_indexterm11_id738604" class="indexterm"/> <a id="I_indexterm11_id738610" class="indexterm"/> <code class="literal">YEAR</code>, <code class="literal">MONTH</code></p></li><li class="listitem"><p><a id="I_indexterm11_id738628" class="indexterm"/> <a id="I_indexterm11_id738634" class="indexterm"/> <code class="literal">WEEK_OF_YEAR</code>,
<code class="literal">WEEK_OF_MONTH</code></p></li><li class="listitem"><p><a id="I_indexterm11_id738652" class="indexterm"/> <code class="literal">DATE</code>, <a id="I_indexterm11_id738664" class="indexterm"/><code class="literal">DAY_OF_YEAR</code>,
<a id="I_indexterm11_id738675" class="indexterm"/><a id="I_indexterm11_id738680" class="indexterm"/><code class="literal">DAY_OF_MONTH</code>,
<code class="literal">DAY_OF_WEEK</code></p></li><li class="listitem"><p><a id="I_indexterm11_id738697" class="indexterm"/> <code class="literal">HOUR</code>, <a id="I_indexterm11_id738708" class="indexterm"/><a id="I_indexterm11_id738714" class="indexterm"/><code class="literal">HOUR_OF_DAY</code>,
<code class="literal">AM_PM</code></p></li><li class="listitem"><p><a id="I_indexterm11_id738731" class="indexterm"/> <code class="literal">MINUTE</code>, <a id="I_indexterm11_id738742" class="indexterm"/><a id="I_indexterm11_id738748" class="indexterm"/><code class="literal">SECOND</code>, <code class="literal">MILLISECOND</code></p></li><li class="listitem"><p><a id="I_indexterm11_id738764" class="indexterm"/> <a id="I_indexterm11_id738771" class="indexterm"/> <code class="literal">ZONE_OFFSET</code>,
<code class="literal">DST_OFFSET</code></p></li></ul></div><p><code class="literal">DATE</code> and <code class="literal">DAY_OF_MONTH</code> are synonymous. <code class="literal">HOUR</code> is a 12-hour clock that can be combined
with <code class="literal">AM_PM</code>. The values are just what
you would expect, as shown in the following:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p><code class="literal">SUNDAY</code>, <code class="literal">MONDAY</code>, <code class="literal">TUESDAY</code>...</p></li><li class="listitem"><p><code class="literal">JANUARY</code>, <code class="literal">FEBRUARY</code>, <code class="literal">MARCH</code>...</p></li><li class="listitem"><p><code class="literal">AM</code>, <code class="literal">PM</code></p></li></ul></div><p>In addition to the <code class="literal">set()</code> method
for changing field values, the <code class="literal">Calendar</code> class has two additional methods for
performing date math, <a id="I_indexterm11_id738872" class="indexterm"/><code class="literal">add()</code> and <a id="I_indexterm11_id738885" class="indexterm"/><code class="literal">roll()</code>. Using <code class="literal">add()</code>, you can move a calendar forward or
backward in any unit of time easily, without having to calculate the
other fields. For example, we can move our calendar forward four
weeks:</p><a id="I_11_tt690"/><pre class="programlisting"> <code class="n">Calendar</code> <code class="n">cal</code> <code class="o">=</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">getInstance</code><code class="o">();</code>
<code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">println</code><code class="o">(</code> <code class="n">cal</code><code class="o">.</code><code class="na">getTime</code><code class="o">()</code> <code class="o">);</code>
<code class="c1">// Thu Nov 04 16:39:06 CST 2004</code>
<code class="err"> </code>
<code class="n">cal</code><code class="o">.</code><code class="na">add</code><code class="o">(</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">WEEK_OF_YEAR</code><code class="o">,</code> <code class="mi">4</code> <code class="o">);</code>
<code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">println</code><code class="o">(</code> <code class="n">cal</code><code class="o">.</code><code class="na">getTime</code><code class="o">()</code> <code class="o">);</code>
<code class="c1">// Thu Dec 02 16:39:06 CST 2004</code></pre><p>The <code class="literal">roll()</code> method, by contrast,
does not alter the other fields of the calendar, but arbitrarily adjusts
individual fields. See the <code class="literal">Spinner</code>
example in <a class="xref" href="ch17.html" title="Chapter 17. Using Swing Components">Chapter 17</a> for additional
information about adding and subtracting time periods using the <code class="literal">add()</code> method.</p><p>Finally, you can always get the internal <code class="literal">Date</code> of the <code class="literal">Calendar</code> object or reinitialize the calendar
to a specific <code class="literal">Date</code> using the
<a id="I_indexterm11_id738958" class="indexterm"/><code class="literal">getTime()</code> and
<a id="I_indexterm11_id738969" class="indexterm"/><code class="literal">setTime()</code>
method:<a id="I_indexterm11_id738980" class="indexterm"/><a id="I_indexterm11_id738987" class="indexterm"/><a id="I_indexterm11_id738994" class="indexterm"/></p><a id="I_11_tt691"/><pre class="programlisting"> <code class="c1">// Get the absolute time the Calendar references</code>
<code class="n">Date</code> <code class="n">date</code> <code class="o">=</code> <code class="n">calendar</code><code class="o">.</code><code class="na">getTime</code><code class="o">();</code>
<code class="err"> </code>
<code class="c1">// Reinitialize this calendar to the current date and time</code>
<code class="n">Date</code> <code class="n">now</code> <code class="o">=</code> <code class="k">new</code> <code class="n">Date</code><code class="o">();</code>
<code class="n">calendar</code><code class="o">.</code><code class="na">setTime</code><code class="o">(</code> <code class="n">now</code> <code class="o">);</code></pre></div><div class="sect2" title="Time Zones"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-11-SECT-2.2"/>Time Zones</h2></div></div></div><p><a id="idx10622" class="indexterm"/> <a id="idx10641" class="indexterm"/> <a id="idx10673" class="indexterm"/>An instance of the <a id="I_indexterm11_id739057" class="indexterm"/><code class="literal">TimeZone</code> class
represents a time zone and the knowledge of daylight savings time at
that location. You can construct a time zone from a string specifier in
a number of ways. The most general approach is to use an offset from
GMT, but many human-readable formats are included. (For a list, use
<a id="I_indexterm11_id739070" class="indexterm"/><code class="literal">TimeZone.getAvailableIDs()</code>.)</p><a id="I_11_tt692"/><pre class="programlisting"> <code class="n">TimeZone</code><code class="o">.</code><code class="na">getTimeZone</code><code class="o">(</code><code class="s">"US/Central"</code><code class="o">);</code> <code class="c1">// CST</code>
<code class="n">TimeZone</code><code class="o">.</code><code class="na">getTimeZone</code><code class="o">(</code><code class="s">"GMT-06"</code><code class="o">);</code> <code class="c1">// CST</code>
<code class="n">TimeZone</code><code class="o">.</code><code class="na">getTimeZone</code><code class="o">(</code><code class="s">"America/Chicago"</code><code class="o">);</code> <code class="c1">// CST</code></pre><p>A <code class="literal">Calendar</code> inherits the default
time zone from the platform on which it was created. You can set a
different time zone with the <a id="I_indexterm11_id739099" class="indexterm"/><code class="literal">setTimeZone()</code>
method:</p><a id="I_11_tt693"/><pre class="programlisting"> <code class="n">GregorianCalendar</code> <code class="n">smokey</code> <code class="o">=</code> <code class="k">new</code>
<code class="n">GregorianCalendar</code><code class="o">();</code>
<code class="n">smokey</code><code class="o">.</code><code class="na">setTimeZone</code><code class="o">(</code> <code class="n">TimeZone</code><code class="o">.</code><code class="na">getTimeZone</code><code class="o">(</code><code class="s">"US/Mountain"</code><code class="o">)</code> <code class="o">);</code></pre><p>It’s important to think about dates and time zones in the right
way. Remember that a <a id="I_indexterm11_id739123" class="indexterm"/><code class="literal">Date</code> is an absolute
point in time, while a <a id="I_indexterm11_id739134" class="indexterm"/><code class="literal">Calendar</code> translates
that <code class="literal">Date</code> into localized fields that
may depend on where you are. In a sense, it is meaningless to talk about
the date “Nov 1, 2004,” without specifying a time zone because at any
given moment on earth, “now” could be one of two different calendar
days. Even specifying a date and time such as “Nov 1, 2004, 9:01 pm” is
ambiguous, because that particular combination of calendar and time
fields occurs at 24 separate times over the span of a day as the world
turns (see <a class="xref" href="ch11s02.html#learnjava3-CHP-11-FIG-1" title="Figure 11-1. Calendars translate an absolute point in time to a localized data and time">Figure 11-1</a>). Only a complete
date, time, and time zone specifies an absolute point in time, such as
“Nov 1, 2004, 9:01 pm EST.” So it’s important to remember that the
<code class="literal">Calendar</code> class defaults all of these
fields for you even if you haven’t set them.</p><div class="figure"><a id="learnjava3-CHP-11-FIG-1"/><div class="figure-contents"><div class="mediaobject"><a id="I_11_tt694"/><img src="httpatomoreillycomsourceoreillyimages1707635.png" alt="Calendars translate an absolute point in time to a localized data and time"/></div></div><p class="title">Figure 11-1. Calendars translate an absolute point in time to a localized
data and time</p></div><p>The following example prints the day of the week for the same
<code class="literal">Date</code> object in two different time
zones:</p><a id="I_11_tt695"/><pre class="programlisting"> <code class="n">Date</code> <code class="n">date</code> <code class="o">=</code> <code class="k">new</code> <code class="n">Date</code><code class="o">();</code> <code class="c1">// point in time</code>
<code class="err"> </code>
<code class="n">TimeZone</code> <code class="n">CST</code> <code class="o">=</code> <code class="n">TimeZone</code><code class="o">.</code><code class="na">getTimeZone</code><code class="o">(</code> <code class="s">"America/Chicago"</code> <code class="o">);</code>
<code class="n">Calendar</code> <code class="n">usa</code> <code class="o">=</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">getInstance</code><code class="o">(</code> <code class="n">CST</code> <code class="o">);</code>
<code class="n">usa</code><code class="o">.</code><code class="na">setTime</code><code class="o">(</code> <code class="n">date</code> <code class="o">);</code>
<code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">println</code><code class="o">(</code> <code class="n">usa</code><code class="o">.</code><code class="na">get</code><code class="o">(</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">DAY_OF_WEEK</code> <code class="o">)</code> <code class="o">);</code> <code class="c1">// 1</code>
<code class="err"> </code>
<code class="n">TimeZone</code> <code class="n">GMT8</code> <code class="o">=</code> <code class="n">TimeZone</code><code class="o">.</code><code class="na">getTimeZone</code><code class="o">(</code> <code class="s">"GMT+08"</code><code class="o">);</code> <code class="c1">// Beijing</code>
<code class="n">Calendar</code> <code class="n">china</code> <code class="o">=</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">getInstance</code><code class="o">(</code> <code class="n">GMT8</code> <code class="o">);</code>
<code class="n">china</code><code class="o">.</code><code class="na">setTime</code><code class="o">(</code> <code class="n">date</code> <code class="o">);</code>
<code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">println</code><code class="o">(</code> <code class="n">china</code><code class="o">.</code><code class="na">get</code><code class="o">(</code> <code class="n">Calendar</code><code class="o">.</code><code class="na">DAY_OF_WEEK</code> <code class="o">)</code> <code class="o">);</code> <code class="c1">// 2</code></pre><p>In this example, we could also have simply changed the time zone
on the calendar <code class="literal">usa</code> using the
<code class="literal">setTimeZone()</code> method. Unlike the
field <code class="literal">set()</code> methods, setting the time
zone does not change the underlying <code class="literal">Date</code> value of the calendar, only the
interpretation of the fields.</p><p>The meaning of the <a id="I_indexterm11_id739242" class="indexterm"/><code class="literal">Date</code> object and its
relationship to <a id="I_indexterm11_id739253" class="indexterm"/><code class="literal">Calendar</code> become
particularly important when dealing with APIs for things such as
databases that construct dates from incomplete date and time fields. If,
as is entirely possible, you end up sending your <code class="literal">Date</code> object from a client application in one
part of the world to a server in another, you may be surprised that the
calendar fields have changed. In these situations, it’s important to
work with <code class="literal">Calendar</code>s to translate the
date fields and avoid the temptation to “fix” the problem by adding or
subtracting real time from the date.</p><div class="sect3" title="Locale"><div class="titlepage"><div><div><h3 class="title"><a id="learnjava3-CHP-11-SECT-2.2.1"/>Locale</h3></div></div></div><p><a id="I_indexterm11_id739288" class="indexterm"/>It should be clear now that <code class="literal">Calendar</code> is not just a fancy <code class="literal">Date</code>, but rather is something in between a
time-keeping device and a time-formatting device. This point is
brought home by the fact that the <code class="literal">Calendar</code> class is also locale-sensitive. In
addition to the notion of a time zone, a <code class="literal">Calendar</code> has a <code class="literal">Locale</code> that governs conventions such as on
which day the week begins and ends. You can specify an alternate
locale with the <code class="literal">setLocale()</code> method.
Most locale-specific details, however, are handled by the <code class="literal">DateFormat</code> class, which we’ll discuss
next.<a id="I_indexterm11_id739337" class="indexterm"/><a id="I_indexterm11_id739344" class="indexterm"/><a id="I_indexterm11_id739351" class="indexterm"/></p></div></div><div class="sect2" title="Parsing and Formatting with DateFormat"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-11-SECT-2.3"/>Parsing and Formatting with DateFormat</h2></div></div></div><p><a id="idx10620" class="indexterm"/> <a id="idx10637" class="indexterm"/> <a id="idx10639" class="indexterm"/> <a id="idx10664" class="indexterm"/>As its name suggests, the <code class="literal">DateFormat</code> class formats <code class="literal">Date</code> objects and not <code class="literal">Calendars</code>, so the first step in formatting
dates and times from a <code class="literal">Calendar</code> is to
get back to a <code class="literal">Date</code> with the <code class="literal">getTime()</code> method:</p><a id="I_11_tt696"/><pre class="programlisting"> <code class="n">Date</code> <code class="n">birthDate</code> <code class="o">=</code> <code class="n">calendar</code><code class="o">.</code><code class="na">getTime</code><code class="o">();</code></pre><p>To create string representations of dates and times, create a
<code class="literal">DateFormat</code> object and apply its
<a id="I_indexterm11_id739468" class="indexterm"/><code class="literal">format()</code> method to a
<code class="literal">Date</code> object. Like the <code class="literal">NumberFormat</code> object we looked at in the
previous chapter, <code class="literal">DateFormat</code> itself
is abstract, but it has several static (“factory”) methods that return
useful <code class="literal">DateFormat</code> subclass instances.
To get a default <code class="literal">DateFormat</code>, simply
call <code class="literal">getInstance()</code>:</p><a id="I_11_tt697"/><pre class="programlisting"> <code class="n">DateFormat</code> <code class="n">simple</code> <code class="o">=</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">getInstance</code><code class="o">();</code>
<code class="n">String</code> <code class="n">now</code> <code class="o">=</code> <code class="n">simple</code><code class="o">.</code><code class="na">format</code><code class="o">(</code> <code class="k">new</code> <code class="n">Date</code><code class="o">()</code> <code class="o">);</code> <code class="c1">// 4/12/06 6:06 AM</code></pre><p>You can generate a date string or a time string, or both, using
the <a id="I_indexterm11_id739525" class="indexterm"/><code class="literal">getDateInstance()</code>,
<a id="I_indexterm11_id739536" class="indexterm"/><code class="literal">getTimeInstance()</code>, and
<a id="I_indexterm11_id739547" class="indexterm"/><code class="literal">getDateTimeInstance()</code>
factory methods. The argument to these methods describes what level of
detail you’d like to see. <code class="literal">DateFormat</code>
defines four constants representing detail levels: they are <a id="I_indexterm11_id739566" class="indexterm"/><code class="literal">SHORT</code>, <a id="I_indexterm11_id739577" class="indexterm"/><code class="literal">MEDIUM</code>, <a id="I_indexterm11_id739587" class="indexterm"/><code class="literal">LONG</code>, and <a id="I_indexterm11_id739598" class="indexterm"/><code class="literal">FULL</code>. There is also a
<a id="I_indexterm11_id739608" class="indexterm"/><code class="literal">DEFAULT</code>, which is the
same as <code class="literal">MEDIUM</code>. The following code
creates three <code class="literal">DateFormat</code> instances:
one to format a date, one to format a time, and one to format a date and
time together. <a id="I_indexterm11_id739631" class="indexterm"/><code class="literal">getDateTimeInstance()</code>
requires two arguments: the first specifies how to format the date, the
second how to format the time:</p><a id="I_11_tt698"/><pre class="programlisting"> <code class="c1">// 12-Apr-06</code>
<code class="n">DateFormat</code> <code class="n">df</code> <code class="o">=</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateInstance</code><code class="o">(</code><code class="n">DateFormat</code><code class="o">.</code><code class="na">DEFAULT</code><code class="o">);</code>
<code class="c1">// 9:18:27 AM</code>
<code class="n">DateFormat</code> <code class="n">tf</code> <code class="o">=</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">getTimeInstance</code><code class="o">(</code><code class="n">DateFormat</code><code class="o">.</code><code class="na">DEFAULT</code><code class="o">);</code>
<code class="c1">// Wednesday, April 12, 2006 9:18:27 o'clock AM EDT</code>
<code class="n">DateFormat</code> <code class="n">dtf</code> <code class="o">=</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateTimeInstance</code><code class="o">(</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">FULL</code><code class="o">,</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">FULL</code> <code class="o">);</code></pre><p>We’re showing only how to create the <code class="literal">DateFormat</code> objects here. In order to actually
generate a <code class="literal">String</code> from a date, you’ll
need to call the <code class="literal">format()</code> method of
these objects, passing a <code class="literal">Date</code> as an
argument.</p><p>Formatting dates and times for other countries is just as easy.
Overloaded factory methods accept a <code class="literal">Locale</code> argument:</p><a id="I_11_tt699"/><pre class="programlisting"> <code class="c1">// 12 avr. 06</code>
<code class="n">DateFormat</code> <code class="n">df</code> <code class="o">=</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateInstance</code><code class="o">(</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">DEFAULT</code><code class="o">,</code> <code class="n">Locale</code><code class="o">.</code><code class="na">FRANCE</code> <code class="o">);</code>
<code class="c1">// 9:27:49</code>
<code class="n">DateFormat</code> <code class="n">tf</code> <code class="o">=</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">getTimeInstance</code><code class="o">(</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">DEFAULT</code><code class="o">,</code> <code class="n">Locale</code><code class="o">.</code><code class="na">GERMANY</code> <code class="o">);</code>
<code class="c1">// mercoledi 12 aprile 2006 9.27.49 GMT-04:00</code>
<code class="n">DateFormat</code> <code class="n">dtf</code> <code class="o">=</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateTimeInstance</code><code class="o">(</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">FULL</code><code class="o">,</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">FULL</code><code class="o">,</code> <code class="n">Locale</code><code class="o">.</code><code class="na">ITALY</code> <code class="o">);</code></pre><p>To parse a string representing a date, we use the <code class="literal">parse()</code> method of the <code class="literal">DateFormat</code> class. The result is a <code class="literal">Date</code> object. The parsing algorithms are
finicky, so it’s safest to parse dates and times that are in the same
format produced by the <code class="literal">DateFormat</code>.
The <a id="I_indexterm11_id739727" class="indexterm"/><code class="literal">parse()</code> method throws a
<a id="I_indexterm11_id739737" class="indexterm"/><code class="literal">ParseException</code> if it
doesn’t understand the string you give it. All of the following calls to
<code class="literal">parse()</code> succeed except the last; we
don’t supply a time zone, but the format for the time is <code class="literal">LONG</code>. Other exceptions are occasionally thrown
from the <code class="literal">parse()</code> method. To cover all
the bases, catch <a id="I_indexterm11_id739768" class="indexterm"/><code class="literal">NullPointerExceptions</code>
and <a id="I_indexterm11_id739779" class="indexterm"/><code class="literal">StringIndexOutOfBoundsExceptions</code>
also:<a id="I_indexterm11_id739790" class="indexterm"/><a id="I_indexterm11_id739797" class="indexterm"/><a id="I_indexterm11_id739804" class="indexterm"/><a id="I_indexterm11_id739811" class="indexterm"/></p><a id="I_11_tt700"/><pre class="programlisting"> <code class="k">try</code> <code class="o">{</code>
<code class="n">Date</code> <code class="n">d</code><code class="o">;</code>
<code class="n">DateFormat</code> <code class="n">df</code><code class="o">;</code>
<code class="n">df</code> <code class="o">=</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateTimeInstance</code><code class="o">(</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">FULL</code><code class="o">,</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">FULL</code><code class="o">);</code>
<code class="n">d</code> <code class="o">=</code> <code class="n">df</code><code class="o">.</code><code class="na">parse</code><code class="o">(</code><code class="s">"Wednesday, April 12, 2006 2:22:22 o'clock PM EDT"</code><code class="o">);</code>
<code class="n">df</code> <code class="o">=</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateTimeInstance</code><code class="o">(</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">MEDIUM</code><code class="o">,</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">MEDIUM</code><code class="o">);</code>
<code class="n">d</code> <code class="o">=</code> <code class="n">df</code><code class="o">.</code><code class="na">parse</code><code class="o">(</code><code class="s">"12-Apr-06 2:22:22 PM"</code><code class="o">);</code>
<code class="n">df</code> <code class="o">=</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">getDateTimeInstance</code><code class="o">(</code>
<code class="n">DateFormat</code><code class="o">.</code><code class="na">LONG</code><code class="o">,</code> <code class="n">DateFormat</code><code class="o">.</code><code class="na">LONG</code><code class="o">);</code>
<code class="n">d</code> <code class="o">=</code> <code class="n">df</code><code class="o">.</code><code class="na">parse</code><code class="o">(</code><code class="s">"April 12, 2006 2:22:22 PM EDT"</code><code class="o">);</code>
<code class="c1">// throws a ParseException; detail level mismatch</code>
<code class="n">d</code> <code class="o">=</code> <code class="n">df</code><code class="o">.</code><code class="na">parse</code><code class="o">(</code><code class="s">"12-Apr-06 2:22:22 PM"</code><code class="o">);</code>
<code class="o">}</code>
<code class="k">catch</code> <code class="o">(</code><code class="n">Exception</code> <code class="n">e</code><code class="o">)</code> <code class="o">{</code> <code class="o">...</code> <code class="o">}</code></pre></div><div class="sect2" title="Printf-Style Date and Time Formatting"><div class="titlepage"><div><div><h2 class="title"><a id="learnjava3-CHP-11-SECT-2.4"/>Printf-Style Date and Time Formatting</h2></div></div></div><p><a id="idx10621" class="indexterm"/> <a id="idx10640" class="indexterm"/> <a id="idx10666" class="indexterm"/>The printf-style formatting covered in <a class="xref" href="ch10.html" title="Chapter 10. Working with Text">Chapter 10</a> can render dates and times to strings in
completely arbitrary ways, without having to resort to <code class="literal">Calendar</code> methods to get components.</p><p>All date and time format strings use the same conversion
character, <a id="I_indexterm11_id739894" class="indexterm"/><code class="literal">t</code> or <a id="I_indexterm11_id739904" class="indexterm"/><code class="literal">T</code>, followed by a suffix
character that identifies the actual format or date/time component to be
generated. For example, the format string <code class="literal">%tc</code> turns a <code class="literal">Date</code> argument into the string equivalent of
what you get with the standard <code class="literal">Date
toString()</code> method:</p><a id="I_11_tt701"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code> <code class="s">"The date is %tc\n"</code><code class="o">,</code> <code class="k">new</code> <code class="n">Date</code><code class="o">()</code> <code class="o">);</code>
<code class="c1">// The date is Thu Nov 04 22:32:00 CST 2004</code></pre><p>As with other conversion characters, the only difference between
<code class="literal">t</code> and <code class="literal">T</code> is that the latter forces all of the output
to uppercase. All time and date formatting is locale-sensitive,
including the names of days and months and the A.M./P.M. identifier. To
format a <code class="literal">Date</code> for another language,
simply pass the <code class="literal">Locale</code> as the first
argument:</p><a id="I_11_tt702"/><pre class="programlisting"> <code class="n">System</code><code class="o">.</code><code class="na">out</code><code class="o">.</code><code class="na">printf</code><code class="o">(</code> <code class="n">Locale</code><code class="o">.</code><code class="na">ITALIAN</code><code class="o">,</code> <code class="s">"The date is %tc\n"</code><code class="o">,</code> <code class="k">new</code> <code class="n">Date</code><code class="o">()</code> <code class="o">);</code>
<code class="c1">// The date is gio nov 04 22:32:00 CST 2004</code></pre><p>There are two additional composite, date-only formats and three
composite time-only formats, as shown in the following table. The format
string description in the third column of <a class="xref" href="ch11s02.html#learnjava3-CHP-11-TABLE-4" title="Table 11-4. Composite date and time formats">Table 11-4</a> refers to date and time component
formats discussed in Tables <a class="xref" href="ch11s02.html#learnjava3-CHP-11-TABLE-5" title="Table 11-5. Date component formats">11-5</a> and <a class="xref" href="ch11s02.html#learnjava3-CHP-11-TABLE-6" title="Table 11-6. Time component formats">11-6</a>.</p><div class="table"><a id="learnjava3-CHP-11-TABLE-4"/><p class="title">Table 11-4. Composite date and time formats</p><div class="table-contents"><table summary="Composite date and time formats" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Format suffix</p></th><th style="text-align: left"><p>Example</p></th><th style="text-align: left"><p>Components</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740056" class="indexterm"/> <code class="literal">c</code>
</p></td><td style="text-align: left"><p>Thu Nov 04 22:32:00 CST
2004</p></td><td style="text-align: left"><p> <code class="literal">%ta %tb %td
%tT %tZ %tY</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740090" class="indexterm"/> <code class="literal">D</code>
</p></td><td style="text-align: left"><p>11/04/04</p></td><td style="text-align: left"><p> <code class="literal">%tm/%td/%ty</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740124" class="indexterm"/> <code class="literal">F</code>
</p></td><td style="text-align: left"><p>2004-11-04</p></td><td style="text-align: left"><p> <code class="literal">%tY-%tm-%td</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740157" class="indexterm"/> <code class="literal">r</code>
</p></td><td style="text-align: left"><p>10:32:00 PM</p></td><td style="text-align: left"><p> <code class="literal">%tI:%tM:%tS
%Tp</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740191" class="indexterm"/> <code class="literal">R</code>
</p></td><td style="text-align: left"><p>22:32</p></td><td style="text-align: left"><p> <code class="literal">%tH:%tM</code> </p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740224" class="indexterm"/> <code class="literal">T</code>
</p></td><td style="text-align: left"><p>22:32:00</p></td><td style="text-align: left"><p> <code class="literal">%tH:%tM:%tS</code> </p></td></tr></tbody></table></div></div><p><a class="xref" href="ch11s02.html#learnjava3-CHP-11-TABLE-5" title="Table 11-5. Date component formats">Table 11-5</a> lists formats for
accessing date components.</p><div class="table"><a id="learnjava3-CHP-11-TABLE-5"/><p class="title">Table 11-5. Date component formats</p><div class="table-contents"><table summary="Date component formats" style="border-collapse: collapse;border-top: 0.5pt solid ; border-bottom: 0.5pt solid ; "><colgroup><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Format suffix</p></th><th style="text-align: left"><p>Examples</p></th><th style="text-align: left"><p>Description</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740312" class="indexterm"/> <code class="literal">a</code>
</p></td><td style="text-align: left"><p>Sun, Mon, Tue...</p></td><td style="text-align: left"><p>Abbreviated day of week</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740341" class="indexterm"/> <code class="literal">A</code>
</p></td><td style="text-align: left"><p>Sunday, Monday...</p></td><td style="text-align: left"><p>Full day of week</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740370" class="indexterm"/> <code class="literal">b</code>
</p></td><td style="text-align: left"><p>Jan, Feb, Mar, ...</p></td><td style="text-align: left"><p>Abbreviated month</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740398" class="indexterm"/> <code class="literal">B</code>
</p></td><td style="text-align: left"><p>January, February, ...</p></td><td style="text-align: left"><p>Full month</p></td></tr><tr><td style="text-align: left"><p> Y </p></td><td style="text-align: left"><p>1999, 2004</p></td><td style="text-align: left"><p>Four-digit year</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740444" class="indexterm"/> <code class="literal">C</code>
</p></td><td style="text-align: left"><p>2004 = 20</p></td><td style="text-align: left"><p>High two digits of year</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740472" class="indexterm"/> <code class="literal">y</code>
</p></td><td style="text-align: left"><p>1999 = 99</p></td><td style="text-align: left"><p>Low two digits of year</p></td></tr><tr><td style="text-align: left"><p> <code class="literal">j</code>
</p></td><td style="text-align: left"><p>001 ... 366</p></td><td style="text-align: left"><p>Day of year</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740522" class="indexterm"/> <code class="literal">m</code>
</p></td><td style="text-align: left"><p>01 ... 13</p></td><td style="text-align: left"><p>Month of year</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740550" class="indexterm"/> <code class="literal">d</code>
</p></td><td style="text-align: left"><p>01 ... 31</p></td><td style="text-align: left"><p>Day of month</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740578" class="indexterm"/> <code class="literal">e</code>
</p></td><td style="text-align: left"><p>1 ... 31</p></td><td style="text-align: left"><p>Day of month, no leading
zeros</p></td></tr></tbody></table></div></div><p><a class="xref" href="ch11s02.html#learnjava3-CHP-11-TABLE-6" title="Table 11-6. Time component formats">Table 11-6</a> lists formats for
accessing time components.</p><div class="table"><a id="learnjava3-CHP-11-TABLE-6"/><p class="title">Table 11-6. Time component formats</p><div class="table-contents"><table summary="Time component formats" style="border-collapse: collapse;border-top: 0.5pt solid ; "><colgroup><col/><col/><col/></colgroup><thead><tr><th style="text-align: left"><p>Format suffix</p></th><th style="text-align: left"><p>Examples</p></th><th style="text-align: left"><p>Description</p></th></tr></thead><tbody><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740662" class="indexterm"/> <code class="literal">H</code>
</p></td><td style="text-align: left"><p>00 ... 23</p></td><td style="text-align: left"><p>24-hour clock</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740690" class="indexterm"/> <code class="literal">k</code>
</p></td><td style="text-align: left"><p>0 ... 23</p></td><td style="text-align: left"><p>24-hour clock, no leading
zeros</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740719" class="indexterm"/> <code class="literal">I</code>
</p></td><td style="text-align: left"><p>01 ... 12</p></td><td style="text-align: left"><p>12-hour clock</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740747" class="indexterm"/> <code class="literal">l</code>
</p></td><td style="text-align: left"><p>1 ... 12</p></td><td style="text-align: left"><p>12-hour clock, no leading
zeros</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740776" class="indexterm"/> <code class="literal">M</code>
</p></td><td style="text-align: left"><p>00 ... 59</p></td><td style="text-align: left"><p>Minute</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740804" class="indexterm"/> <code class="literal">S</code>
</p></td><td style="text-align: left"><p>00 ... 60<sup>[<a id="id1602617" href="#ftn.id1602617" class="footnote">a</a>]</sup></p></td><td style="text-align: left"><p>Second</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740841" class="indexterm"/> <code class="literal">L</code>
</p></td><td style="text-align: left"><p>000 ... 999</p></td><td style="text-align: left"><p>Millisecond</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740870" class="indexterm"/> <code class="literal">p</code>
</p></td><td style="text-align: left"><p>am, pm</p></td><td style="text-align: left"><p>Morning or afternoon
designator</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740898" class="indexterm"/> <code class="literal">Z</code>
</p></td><td style="text-align: left"><p>CST, EST</p></td><td style="text-align: left"><p>Time zone name</p></td></tr><tr><td style="text-align: left"><p> <a id="I_indexterm11_id740926" class="indexterm"/> <code class="literal">z</code>
</p></td><td style="text-align: left"><p>-0600</p></td><td style="text-align: left"><p>Time zone GMT offset<a id="I_indexterm11_id740948" class="indexterm"/><a id="I_indexterm11_id740956" class="indexterm"/><a id="I_indexterm11_id740963" class="indexterm"/></p></td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div class="footnote"><p><sup>[<a id="ftn.id1602617" href="#id1602617" class="para">a</a>] </sup>The second value (<code class="literal">60</code>) is a convention used to
support leap seconds.</p></div></td></tr></tbody></table></div></div></div><div class="footnotes"><br/><hr/><div class="footnote"><p><sup>[<a id="ftn.learnjava3-CHP-11-FN-2" href="#learnjava3-CHP-11-FN-2" class="para">32</a>] </sup>Prior to Java 1.1, the <code class="literal">Date</code>
class handled some of the functions of a calendar as well. Most of
these methods have now been deprecated. Today, the only purpose of the
<code class="literal">Date</code> class is to represent a point
in time.</p></div><div class="footnote"><p><sup>[<a id="ftn.learnjava3-CHP-11-FN-3" href="#learnjava3-CHP-11-FN-3" class="para">33</a>] </sup>Java’s <a id="I_indexterm11_id738433" class="indexterm"/><code class="literal">GregorianCalendar</code>
class is actually both a Julian and Gregorian calendar with a
programmable cut-over date. For a wealth of information about time and
world time-keeping conventions, see the <a class="ulink" href="http://tycho.usno.navy.mil">U.S. Navy Directorate of
Time</a>.</p></div></div></div></body></html>