All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class java.text.DateFormat

java.lang.Object
   |
   +----java.text.Format
           |
           +----java.text.DateFormat

public class DateFormat
extends Format
implements Cloneable

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 formatting (i.e., millis -> text), parsing (text -> millis), and normalization. Formats/Parses a date or time, which is the standard millis since 24:00 GMT, Jan 1, 1970

DateFormat provides many class methods for obtaining default date-time formatters based on the default or a given loacle and a number of formatting styles. The formatting styles include FULL, LONG, DEFAULT, and SHORT. More detail and examples of using these styles are provided in the method descriptions.

See Also:: Format, NumberFormat, SimpleDateFormat, Calendar, GregorianCalendar, TimeZone

AMPM_FIELD: Useful constant for AMPM field alignment.
calendar: The calendar that DateFormat uses to produce the time field values needed to implement date-time formatting.
DATE_FIELD: Useful constant for DATE field alignment.
DAYOFWEEK_FIELD: Useful constant for DAYOFWEEK field alignment.
DAYOFWEEKINMONTH_FIELD: Useful constant for DAYOFWEEKINMONTH field alignment.
DAYOFYEAR_FIELD: Useful constant for DAYOFYEAR field alignment.
DEFAULT: Constant for medium/default style pattern.
ERA_FIELD: Useful constant for ERA field alignment.
FULL: Constant for full style pattern.
HOUR0_FIELD: Useful constant for zero-based HOUR field alignment.
HOUR1_FIELD: Useful constant for one-based HOUR field alignment.
HOUROFDAY0_FIELD: Useful constant for zero-based HOUROFDAY field alignment.
HOUROFDAY1_FIELD: Useful constant for one-based HOUROFDAY field alignment.
LONG: Constant for long style pattern.
MILLISECOND_FIELD: Useful constant for MILLISECOND field alignment.
MINUTE_FIELD: Useful constant for MINUTE field alignment.
MONTH_FIELD: Useful constant for MONTH field alignment.
numberFormat: The number formatter that DateFormat uses to implement date-time formatting.
SECOND_FIELD: Useful constant for SECOND field alignment.
SHORT: Constant for short style pattern.
TIMEZONE_FIELD: Useful constant for TIMEZONE field alignment.
WEEKOFMONTH_FIELD: Useful constant for WEEKOFMONTH field alignment.
WEEKOFYEAR_FIELD: Useful constant for WEEKOFYEAR field alignment.
YEAR_FIELD: Useful constant for YEAR field alignment.

DateFormat()

clone(): Overrides Cloneable
format(Date): Formats a Date into a date-time string.
format(Date, StringBuffer, FormatStatus): Formats a Date into a date-time string.
format(Object, StringBuffer, FormatStatus): Overrides Format.
getAvailableLocales(): Gets the set of locales for which DateFormats are installed.
getCalendar(): Gets the calendar associated with this date-time formatter.
getDateFormat(): Gets the date formatter with the default formatting style for the default locale.
getDateFormat(int): Gets the date formatter with the given formatting style for the default locale.
getDateFormat(int, Locale): Gets the date formatter with the given formatting style for the given locale.
getDateTimeFormat(): Gets the date-time formatter with the default formatting style for the default locale.
getDateTimeFormat(int, int): Gets the date-time formatter with the given date and time formatting styles for the default locale.
getDateTimeFormat(int, int, Locale): Gets the date-time formatter with the given formatting styles for the given locale.
getDisplayName(Locale): Get name of the object for the desired Locale, in the langauge of the default locale.
getDisplayName(Locale, Locale): Get name of the object for the desired Locale, in the desired langauge.
getNumberFormat(): Gets the number formatter which this date-time formatter uses to format and parse a time.
getTimeFormat(): Gets the time formatter with the default formatting style for the default locale.
getTimeFormat(int): Gets the time formatter with the given formatting style for the default locale.
getTimeFormat(int, Locale): Gets the time formatter with the given formatting style for the given locale.
getTimeZone(): Gets the time zone.
getValidationMode(): Gets the validation mode.
parse(String): Parses a date-time string.
parse(String, ParseStatus): Parses a date-time string according to the given parsing status.
parseObject(String, ParseStatus): Parse the date-time text into the date in milliseconds.
setCalendar(Calendar): Allows you to set the calendar.
setNumberFormat(NumberFormat): Allows you to set the number formatter.
setTimeZone(TimeZone): Sets the time zone for the calendar of this DateFormat object.
setValidationMode(boolean): Sets the validation mode which controls the parsing behavior of DateFormat.

calendar

  protected Calendar calendar

The calendar that DateFormat uses to produce the time field values needed to implement date-time formatting.

numberFormat

  protected NumberFormat numberFormat

The number formatter that DateFormat uses to implement date-time formatting.

ERA_FIELD

  public final static byte ERA_FIELD

Useful constant for ERA field alignment. Used in FormatStatus of date-time formatting.

YEAR_FIELD

  public final static byte YEAR_FIELD

Useful constant for YEAR field alignment. Used in FormatStatus of date-time formatting.

MONTH_FIELD

  public final static byte MONTH_FIELD

Useful constant for MONTH field alignment. Used in FormatStatus of date-time formatting.

DATE_FIELD

  public final static byte DATE_FIELD

Useful constant for DATE field alignment. Used in FormatStatus of date-time formatting.

HOUROFDAY1_FIELD

  public final static byte HOUROFDAY1_FIELD

Useful constant for one-based HOUROFDAY field alignment. Used in FormatStatus of date-time formatting. HOUROFDAY1_FIELD is used for the one-based 24-hour clock. For example, 23:59 + 01:00 results in 24:59.

HOUROFDAY0_FIELD

  public final static byte HOUROFDAY0_FIELD

Useful constant for zero-based HOUROFDAY field alignment. Used in FormatStatus of date-time formatting. HOUROFDAY0_FIELD is used for the zero-based 24-hour clock. For example, 23:59 + 01:00 results in 00:59.

MINUTE_FIELD

  public final static byte MINUTE_FIELD

Useful constant for MINUTE field alignment. Used in FormatStatus of date-time formatting.

SECOND_FIELD

  public final static byte SECOND_FIELD

Useful constant for SECOND field alignment. Used in FormatStatus of date-time formatting.

MILLISECOND_FIELD

  public final static byte MILLISECOND_FIELD

Useful constant for MILLISECOND field alignment. Used in FormatStatus of date-time formatting.

DAYOFWEEK_FIELD

  public final static byte DAYOFWEEK_FIELD

Useful constant for DAYOFWEEK field alignment. Used in FormatStatus of date-time formatting.

DAYOFYEAR_FIELD

  public final static byte DAYOFYEAR_FIELD

Useful constant for DAYOFYEAR field alignment. Used in FormatStatus of date-time formatting.

DAYOFWEEKINMONTH_FIELD

  public final static byte DAYOFWEEKINMONTH_FIELD

Useful constant for DAYOFWEEKINMONTH field alignment. Used in FormatStatus of date-time formatting.

WEEKOFYEAR_FIELD

  public final static byte WEEKOFYEAR_FIELD

Useful constant for WEEKOFYEAR field alignment. Used in FormatStatus of date-time formatting.

WEEKOFMONTH_FIELD

  public final static byte WEEKOFMONTH_FIELD

Useful constant for WEEKOFMONTH field alignment. Used in FormatStatus of date-time formatting.

AMPM_FIELD

  public final static byte AMPM_FIELD

Useful constant for AMPM field alignment. Used in FormatStatus of date-time formatting.

HOUR1_FIELD

  public final static byte HOUR1_FIELD

Useful constant for one-based HOUR field alignment. Used in FormatStatus of date-time formatting. HOUR1_FIELD is used for the one-based 12-hour clock. For example, 11:30 PM + 1 hour results in 12:30 AM.

HOUR0_FIELD

  public final static byte HOUR0_FIELD

Useful constant for zero-based HOUR field alignment. Used in FormatStatus of date-time formatting. HOUR0_FIELD is used for the zero-based 12-hour clock. For example, 11:30 PM + 1 hour results in 00:30 AM.

TIMEZONE_FIELD

  public final static byte TIMEZONE_FIELD

Useful constant for TIMEZONE field alignment. Used in FormatStatus of date-time formatting.

FULL

  public final static int FULL

Constant for full style pattern.

LONG

  public final static int LONG

Constant for long style pattern.

DEFAULT

  public final static int DEFAULT

Constant for medium/default style pattern.

SHORT

  public final static int SHORT

Constant for short style pattern.

DateFormat

  public DateFormat()

format

  public final StringBuffer format(Object obj,
                                   StringBuffer toAppendTo,
                                   FormatStatus status)

Overrides Format. Formats a time object into a time string. Examples of time objects are a time value expressed in milliseconds and a Date object.

Parameters:: obj - must be a Number or a Date.; toAppendTo - the string buffer for the returning time string.; status - the formatting status. On input: an alignment field, if desired. On output: the offsets of the alignment field.
Returns:: the formatted time string.
Overrides:: format in class Format
See Also:: Format

format

  public abstract StringBuffer format(Date date,
                                      StringBuffer toAppendTo,
                                      FormatStatus status)

Formats a Date into a date-time string.

Parameters:: date - a Date to be formatted into a date-time string.; toAppendTo - the string buffer for the returning date-time string.; status - the formatting status. On input: an alignment field, if desired. On output: the offsets of the alignment field. For example, given a time text "1996.07.10 AD at 15:08:56 PDT", if the given status.alignField is DateFormat.YEAR_FIELD, the offsets status.alignStart and status.alignEnd will be set to 0 and 4, respectively. Notice that if the same time field appears more than once in a pattern, the status will be set for the first occurence of that time field. For instance, formatting a Date to the time string "1 PM PDT (Pacific Daylight Time)" using the pattern "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD, the offsets status.alignStart and status.alignEnd will be set to 5 and 8, respectively, for the first occurence of the timezone pattern character 'z'.
Returns:: the formatted date-time string.

format

  public final String format(Date date)

Formats a Date into a date-time string.

Parameters:: date - the time value to be formatted into a time string.
Returns:: the formatted time string.

parse

  public Date parse(String text) throws FormatException

Parses a date-time string.

If there is no match when parsing, FormatException is thrown. For example: A time text "07/10/96 4:5 PM, PDT" will be parsed into a Date which is equivalent to Date(837039928046), if status.startAt is set at the beginning (0) of the given time text.

Parameters:: text - the time string to be parsed.
Returns:: a Date. Throws a FormatException if failed.

parse

  public abstract Date parse(String text,
                             ParseStatus status)

Parses a date-time string according to the given parsing status. For example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date that is equivalent to Date(837039928046), when status.startAt is set at the beginning offset of the given time text. Clients can set the validation mode using setValidationMode to control the parsing behavior. When the mode is true, the parse will throw FormatException if the given time text isn't reasonable. When the mode is false, and there is no match when parsing, the ParseStatus.startAt will be set at where the parse failed.

Parameters:: text - the date-time string to be parsed.; status - the parsing status.
Returns:: a Date. Returns null if failed.

parseObject

  public Object parseObject(String source,
                            ParseStatus status)

Parse the date-time text into the date in milliseconds. For example: A time text "07/10/96 4:5 PM, PDT" will be parsed into a Date which is equivalent to Date(837039928046), if status.startAt is set at the beginning (0) of the given time text.

Parameters:: source - the time string to be parsed.; status - the parsing status.
Returns:: a Date. Returns null if failed.
Overrides:: parseObject in class Format

getTimeFormat

  public final static synchronized DateFormat getTimeFormat()

Gets the time formatter with the default formatting style for the default locale.

Returns:: a time formatter.

getTimeFormat

  public final static synchronized DateFormat getTimeFormat(int style)

Gets the time formatter with the given formatting style for the default locale.

Parameters:: style - the given formatting style. For example, SHORT for "h:mm a" in the US locale.
Returns:: a time formatter.

getTimeFormat

  public final static synchronized DateFormat getTimeFormat(int style,
                                                            Locale aLocale)

Gets the time formatter with the given formatting style for the given locale.

Parameters:: style - the given formatting style. For example, SHORT for "h:mm a" in the US locale.; inLocale - the given locale.
Returns:: a time formatter.

getDateFormat

  public final static synchronized DateFormat getDateFormat()

Gets the date formatter with the default formatting style for the default locale.

Returns:: a date formatter.

getDateFormat

  public final static synchronized DateFormat getDateFormat(int style)

Gets the date formatter with the given formatting style for the default locale.

Parameters:: style - the given formatting style. For example, SHORT for "M/d/yy" in the US locale.
Returns:: a date formatter.

getDateFormat

  public final static synchronized DateFormat getDateFormat(int style,
                                                            Locale aLocale)

Gets the date formatter with the given formatting style for the given locale.

Parameters:: style - the given formatting style. For example, SHORT for "M/d/yy" in the US locale.; inLocale - the given locale.
Returns:: a date formatter.

getDateTimeFormat

  public final static synchronized DateFormat getDateTimeFormat()

Gets the date-time formatter with the default formatting style for the default locale.

Returns:: a date-time formatter.

getDateTimeFormat

  public final static synchronized DateFormat getDateTimeFormat(int dateStyle,
                                                                int timeStyle)

Gets the date-time formatter with the given date and time formatting styles for the default locale.

Parameters:: dateStyle - the given date formatting style. For example, SHORT for "M/d/yy" in the US locale.; timeStyle - the given time formatting style. For example, SHORT for "h:mm a" in the US locale.
Returns:: a date-time formatter.

getDateTimeFormat

  public final static synchronized DateFormat getDateTimeFormat(int dateStyle,
                                                                int timeStyle,
                                                                Locale aLocale)

Gets the date-time formatter with the given formatting styles for the given locale.

Parameters:: dateStyle - the given date formatting style.; timeStyle - the given time formatting style.; inLocale - the given locale.
Returns:: a date-time formatter.

getAvailableLocales

  public static synchronized Locale[] getAvailableLocales()

Gets the set of locales for which DateFormats are installed.

Returns:: the set of locales for which DateFormats are installed.

getDisplayName

  public static synchronized String getDisplayName(Locale objectLocale,
                                                   Locale displayLocale)

Get name of the object for the desired Locale, in the desired langauge.

Parameters:: objectLocale - must be from getAvailableLocales.; displayLocale - specifies the desired locale for output. Uses best match.
Returns:: user-displayable name
See Also:: ResourceBundle

getDisplayName

  public final static String getDisplayName(Locale objectLocale)

Get name of the object for the desired Locale, in the langauge of the default locale.

Parameters:: objectLocale - must be from getMatchingLocales
Returns:: user-displayable name
See Also:: ResourceBundle

setCalendar

  public void setCalendar(Calendar newCalendar)

Allows you to set the calendar. Default uses GregorianCalendar.

Parameters:: newCalendar - the given new calendar.

getCalendar

  public Calendar getCalendar()

Gets the calendar associated with this date-time formatter.

Returns:: the calendar associated with this date-time formatter.

setNumberFormat

  public void setNumberFormat(NumberFormat newNumberFormat)

Allows you to set the number formatter.

Parameters:: newNumberFormat - the given new NumberFormat.

getNumberFormat

  public NumberFormat getNumberFormat()

Gets the number formatter which this date-time formatter uses to format and parse a time.

Returns:: the number formatter which this date-time formatter uses.

setTimeZone

  public void setTimeZone(TimeZone zone)

Sets the time zone for the calendar of this DateFormat object.

Parameters:: zone - the given new time zone.

getTimeZone

  public TimeZone getTimeZone()

Gets the time zone.

Returns:: the time zone associated with the calendar of DateFormat.

setValidationMode

  public void setValidationMode(boolean mode)

Sets the validation mode which controls the parsing behavior of DateFormat.

Parameters:: mode - when true, the parse will throw FormatException if the given time text to be parsed isn't reasonable. When the mode is false, the parse will return the best result it can.
See Also:: setValidationMode

getValidationMode

  public boolean getValidationMode()

Gets the validation mode.

Returns:: the state of the validation mode.
See Also:: setValidationMode

clone

  public Object clone()

Overrides Cloneable

Overrides:: clone in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index