diff --git a/src/share/classes/java/text/DateFormat.java b/src/share/classes/java/text/DateFormat.java
index 51a43435638c7263a476491a29dc35bdebdb39e9..5445678d8dc0d84e1eb4d599706801060139885f 100644
--- a/src/share/classes/java/text/DateFormat.java
+++ b/src/share/classes/java/text/DateFormat.java
@@ -53,20 +53,20 @@ import java.util.spi.LocaleServiceProvider;
import sun.util.LocaleServiceProviderPool;
/**
- * DateFormat is an abstract class for date/time formatting subclasses which
+ * {@code DateFormat} is an abstract class for date/time formatting subclasses which
* formats and parses dates or time in a language-independent manner.
- * The date/time formatting subclass, such as SimpleDateFormat, allows for
+ * The date/time formatting subclass, such as {@link SimpleDateFormat}, allows for
* formatting (i.e., date -> text), parsing (text -> date), and
* normalization. The date is represented as a Date
object or
* as the milliseconds since January 1, 1970, 00:00:00 GMT.
*
- *
DateFormat provides many class methods for obtaining default date/time + *
{@code DateFormat} provides many class methods for obtaining default date/time * formatters based on the default or a given locale and a number of formatting - * styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More + * styles. The formatting styles include {@link #FULL}, {@link #LONG}, {@link #MEDIUM}, and {@link #SHORT}. More * detail and examples of using these styles are provided in the method * descriptions. * - *
DateFormat helps you to format and parse dates for any locale. + *
{@code DateFormat} helps you to format and parse dates for any locale. * Your code can be completely independent of the locale conventions for * months, days of the week, or even the calendar format: lunar vs. solar. * @@ -86,7 +86,7 @@ import sun.util.LocaleServiceProviderPool; * } * *
To format a date for a different Locale, specify it in the - * call to getDateInstance(). + * call to {@link #getDateInstance(int, Locale) getDateInstance()}. *
* DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE); *@@ -94,30 +94,30 @@ import sun.util.LocaleServiceProviderPool; *
* myDate = df.parse(myString); *- *
Use getDateInstance to get the normal date format for that country. + *
Use {@code getDateInstance} to get the normal date format for that country. * There are other static factory methods available. - * Use getTimeInstance to get the time format for that country. - * Use getDateTimeInstance to get a date and time format. You can pass in + * Use {@code getTimeInstance} to get the time format for that country. + * Use {@code getDateTimeInstance} to get a date and time format. You can pass in * different options to these factory methods to control the length of the - * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends + * result; from {@link #SHORT} to {@link #MEDIUM} to {@link #LONG} to {@link #FULL}. The exact result depends * on the locale, but generally: - *
You can also set the time zone on the format if you wish. * If you want even more control over the format or parsing, * (or want to give your users more control), - * you can try casting the DateFormat you get from the factory methods - * to a SimpleDateFormat. This will work for the majority - * of countries; just remember to put it in a try block in case you + * you can try casting the {@code DateFormat} you get from the factory methods + * to a {@link SimpleDateFormat}. This will work for the majority + * of countries; just remember to put it in a {@code try} block in case you * encounter an unusual one. * *
You can also use forms of the parse and format methods with - * ParsePosition and FieldPosition to + * {@link ParsePosition} and {@link FieldPosition} to * allow you to *
DateFormat
uses to produce the time field
- * values needed to implement date and time formatting. Subclasses should
- * initialize this to a calendar appropriate for the locale associated with
- * this DateFormat
.
+ * The {@link Calendar} instance used for calculating the date-time fields
+ * and the instant of time. This field is used for both formatting and
+ * parsing.
+ *
+ * Subclasses should initialize this field to a {@link Calendar}
+ * appropriate for the {@link Locale} associated with this
+ * DateFormat
.
* @serial
*/
protected Calendar calendar;
@@ -358,15 +361,21 @@ public abstract class DateFormat extends Format {
/**
* Parse a date/time string according to the given parse position. For
- * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
- * that is equivalent to Date(837039928046).
+ * example, a time text {@code "07/10/96 4:5 PM, PDT"} will be parsed into a {@code Date}
+ * that is equivalent to {@code Date(837039900000L)}.
*
*
By default, parsing is lenient: If the input is not in the form used * by this object's format method but can still be parsed as a date, then * the parse succeeds. Clients may insist on strict adherence to the - * format by calling setLenient(false). + * format by calling {@link #setLenient(boolean) setLenient(false)}. * - * @see java.text.DateFormat#setLenient(boolean) + *
This parsing operation uses the {@link #calendar} to produce + * a {@code Date}. As a result, the {@code calendar}'s date-time + * fields and the {@code TimeZone} value may have been + * overwritten, depending on subclass implementations. Any {@code + * TimeZone} value that has previously been set by a call to + * {@link #setTimeZone(java.util.TimeZone) setTimeZone} may need + * to be restored for further operations. * * @param source The date/time string to be parsed * @@ -374,7 +383,7 @@ public abstract class DateFormat extends Format { * output, the position at which parsing terminated, or the * start position if the parse failed. * - * @return A Date, or null if the input could not be parsed + * @return A {@code Date}, or {@code null} if the input could not be parsed */ public abstract Date parse(String source, ParsePosition pos); @@ -569,7 +578,12 @@ public abstract class DateFormat extends Format { /** * Set the calendar to be used by this date format. Initially, the default * calendar for the specified or default locale is used. - * @param newCalendar the new Calendar to be used by the date format + * + *
Any {@link java.util.TimeZone TimeZone} and {@linkplain + * #isLenient() leniency} values that have previously been set are + * overwritten by {@code newCalendar}'s values. + * + * @param newCalendar the new {@code Calendar} to be used by the date format */ public void setCalendar(Calendar newCalendar) { @@ -578,6 +592,7 @@ public abstract class DateFormat extends Format { /** * Gets the calendar associated with this date/time formatter. + * * @return the calendar associated with this date/time formatter. */ public Calendar getCalendar() @@ -605,7 +620,18 @@ public abstract class DateFormat extends Format { } /** - * Sets the time zone for the calendar of this DateFormat object. + * Sets the time zone for the calendar of this {@code DateFormat} object. + * This method is equivalent to the following call. + *
+ * + *+ * getCalendar().setTimeZone(zone) + *
The {@code TimeZone} set by this method is overwritten by a + * {@link #setCalendar(java.util.Calendar) setCalendar} call. + * + *
The {@code TimeZone} set by this method may be overwritten as + * a result of a call to the parse method. + * * @param zone the given new time zone. */ public void setTimeZone(TimeZone zone) @@ -615,6 +641,11 @@ public abstract class DateFormat extends Format { /** * Gets the time zone. + * This method is equivalent to the following call. + *
+ * * @return the time zone associated with the calendar of DateFormat. */ public TimeZone getTimeZone() @@ -627,8 +658,17 @@ public abstract class DateFormat extends Format { * lenient parsing, the parser may use heuristics to interpret inputs that * do not precisely match this object's format. With strict parsing, * inputs must match this object's format. - * @param lenient when true, parsing is lenient - * @see java.util.Calendar#setLenient + * + *+ * getCalendar().getTimeZone() + *
This method is equivalent to the following call. + *
+ * + *+ * getCalendar().setLenient(lenient) + *
This leniency value is overwritten by a call to {@link + * #setCalendar(java.util.Calendar) setCalendar()}. + * + * @param lenient when {@code true}, parsing is lenient + * @see java.util.Calendar#setLenient(boolean) */ public void setLenient(boolean lenient) { @@ -637,6 +677,14 @@ public abstract class DateFormat extends Format { /** * Tell whether date/time parsing is to be lenient. + * This method is equivalent to the following call. + *
+ * + * @return {@code true} if the {@link #calendar} is lenient; + * {@code false} otherwise. + * @see java.util.Calendar#isLenient() */ public boolean isLenient() { diff --git a/src/share/classes/java/text/SimpleDateFormat.java b/src/share/classes/java/text/SimpleDateFormat.java index 1dfa42ea5f2d2c369a828d4e1cd3cfc54cf169f0..eacfbddfe6b3e9e96032894262df5e1430fc83fe 100644 --- a/src/share/classes/java/text/SimpleDateFormat.java +++ b/src/share/classes/java/text/SimpleDateFormat.java @@ -1235,6 +1235,20 @@ public class SimpleDateFormat extends DateFormat { * changed, the error index of+ * getCalendar().isLenient() + *
pos
is set to the index of
* the character where the error occurred, and null is returned.
*
+ * This parsing operation uses the {@link DateFormat#calendar
+ * calendar} to produce a {@code Date}. All of the {@code
+ * calendar}'s date-time fields are {@linkplain Calendar#clear()
+ * cleared} before parsing, and the {@code calendar}'s default
+ * values of the date-time fields are used for any missing
+ * date-time information. For example, the year value of the
+ * parsed {@code Date} is 1970 with {@link GregorianCalendar} if
+ * no year value is given from the parsing operation. The {@code
+ * TimeZone} value may be overwritten, depending on the given
+ * pattern and the time zone value in {@code text}. Any {@code
+ * TimeZone} value that has previously been set by a call to
+ * {@link #setTimeZone(java.util.TimeZone) setTimeZone} may need
+ * to be restored for further operations.
+ *
* @param text A String
, part of which should be parsed.
* @param pos A ParsePosition
object with index and error
* index information as described above.