com.webobjects.foundation
Class NSTimestampFormatter

java.lang.Object
  java.text.Format
      com.webobjects.foundation.NSTimestampFormatter

All Implemented Interfaces:

Cloneable, Serializable

public class NSTimestampFormatter

extends Format

implements Serializable

Instances of NSTimestampFormatter format NSTimestamps into their textual representations and convert textual representations of dates and times into NSTimestamps. You have a great degree flexibility when expressing dates and times: "Thu 22 Dec 1994" is just as acceptable as "12/22/94".

You can associate a timestamp pattern with a WOString or WOTextField dynamic element. WebObjects uses an NSTimestampFormatter object to perform the appropriate conversions.

You can also create an NSTimestampFormatter with the constructor, provide a timestamp pattern string, and use the format and parseObject methods of java.text.Format to convert between NSTimestamps and their textual representations:

 NSTimestampFormatter formatter=new NSTimestampFormatter("%m/%d/%y");
 String description=formatter.format(myNSTimestamp);

 NSTimestampFormatter formatter=new NSTimestampFormatter("%m/%d/%y");
 NSTimestamp myNSTimestamp=(NSTimestamp)formatter.parseObject(myTimestampString);
 

The default pattern for NSTimestampFormatter is %Y-%m-%d %H:%M:%S %Z. You can specify a pattern whenever you create a NSTimestampFormatter. This pattern is a string that contains specifiers that are very similar to those used in the standard C library function strftime(). When NSTimestampFormatter converts a date to a string, it uses this pattern.

The date conversion specifiers cover a range of date conventions.

Conversion Specifiers

Specifier	Description
%%	a '%' character
%a	abbreviated weekday name
%A	full weekday name
%b	abbreviated month name
%B	full month name
%c	shorthand for "%X %x", the locale format for date and time
%d	day of the month as a decimal number (01-31)
%e	same as %d but does not print the leading 0 for days 1 through 9
%F	milliseconds as a decimal number (000-999)
%H	hour based on a 24-hour clock as a decimal number (00-23)
%I	hour based on a 12-hour clock as a decimal number (01-12)
%j	day of the year as a decimal number (001-366)
%m	month as a decimal number (01-12)
%M	minute as a decimal number (00-59)
%p	AM/PM designation for the locale
%S	second as a decimal number (00-59)
%w	weekday as a decimal number (0-6), where Sunday is 0
%x	date using the date representation for the locale
%X	time using the time representation for the locale
%y	year without century (00-99)
%Y	year with century (such as 1990)
%Z	time zone name (such as "Europe/Paris" or "PST")
%z	time zone offset from GMT in hours and minutes (such as "+0200" or "-1200")

Note that time zone names can not contain spaces. For example, "Pacific Daylight Time" is not a valid time zone name, but "America/Los_Angeles" and "PDT" are both valid.

Alternatively, you can specify the pattern using Sun's date pattern specifiers. See Sun's documentation for the java.text.SimpleDateFormat class for more information.

When you convert a string without a time zone specification to an NSTimestamp, the formatter assumes the time zone is the default parse time zone. An analogous time zone, called the default format time zone, is used when converting an NSTimestamp to a string.

Sometimes you need to give the user a choice of time zones. For example, you might put the time zones in a pop-up list. In such cases, you can use the parseObjectInUTC method to parse a date string for the UTC time zone. The following code shows how you can compute the offset from UTC for the particular time zone the user chooses and add it to the parsed timestamp:

 NSTimestamp date = (NSTimestamp)myFormatter.parseInUTC(myString);
 NSTimeZone tz = NSTimeZone.timeZoneWithName(myTimeZoneName);
 int offset = tz.secondsFromGMTForTimestamp(date);
 long milliseconds = date.getTime() - offset * 1000;
 NSTimestamp dateWithTimeZone = new NSTimestamp(milliseconds);

See Also:

format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition), parseObject(java.lang.String, java.text.ParsePosition), defaultParseTimeZone(), setDefaultParseTimeZone(com.webobjects.foundation.NSTimeZone), parseObjectInUTC(java.lang.String, java.text.ParsePosition), Serialized Form

Nested Class Summary

Nested classes inherited from class java.text.Format

Format.Field

Constructor Summary

NSTimestampFormatter()
Creates an NSTimestampFormatter with the default pattern.

NSTimestampFormatter(String aPattern)
Creates an NSTimestampFormatter with the pattern string aPattern.

NSTimestampFormatter(String aPattern, DateFormatSymbols symbols)
Creates an NSTimestampFormatter with the specified pattern using the specified date format symbols.

Method Summary

DateFormatSymbols	defaultDateFormatSymbols() Returns the default set of date format symbols.
NSTimeZone	defaultFormatTimeZone() Returns the default time zone this NSTimestampFormatter uses for formatting -- converting an NSTimestamp to a string.
NSTimeZone	defaultParseTimeZone() Returns the default time zone this NSTimestampFormatter uses for parsing -- converting a string to an NSTimestamp.
StringBuffer	format(Object obj, StringBuffer toAppendTo, FieldPosition pos) Formats obj to produce a string, appends the string to toAppendTo, and returns the resulting string.
Object	parseObject(String text, ParsePosition pos) Parses a string to produce an object.
Object	parseObjectInUTC(String text, ParsePosition pos) Parses a string to produce an object using UTC as the time zone.
String	pattern() Returns this NSTimestampFormatter's pattern.
void	setDefaultFormatTimeZone(NSTimeZone zone) Sets the default time zone this NSTimestampFormatter uses for formatting -- converting an NSTimestamp into a string -- to zone.
void	setDefaultParseTimeZone(NSTimeZone zone) Sets the default time zone this NSTimestampFormatter uses for parsing -- converting a string to an NSTimestamp -- to zone.
void	setPattern(String pattern) Sets this NSTimestampFormatter's pattern to pattern.
String	toString() Returns a string representation of this NSTimestampFormatter that includes the default format time zone, the default parse time zone, and the pattern.

Methods inherited from class java.text.Format

clone, format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

NSTimestampFormatter

public NSTimestampFormatter()

Creates an NSTimestampFormatter with the default pattern.

NSTimestampFormatter

public NSTimestampFormatter(String aPattern)

Creates an NSTimestampFormatter with the pattern string aPattern. If aPattern is null, this constructor uses the default pattern. See the Calendar Specifiers table in the NSTimestampFormatter class description for more information on specifying the pattern string.

Parameters:

aPattern - the pattern string

NSTimestampFormatter

public NSTimestampFormatter(String aPattern,
                            DateFormatSymbols symbols)

Creates an NSTimestampFormatter with the specified pattern using the specified date format symbols. If aPattern is null, this constructor uses the default pattern with the slashes replaced by the appropriate date symbol.

See the Calendar Specifiers table in the NSTimestampFormatter class description for more information on specifying the pattern string.

Note If you use this constructor, you must ensure that the Strings in the symbols zone strings contain no spaces.

Parameters:

aPattern - the pattern specified

symbols - the date format symbols

Method Detail

defaultDateFormatSymbols

public DateFormatSymbols defaultDateFormatSymbols()

Returns the default set of date format symbols.

Returns:

the default set of date format symbols

defaultFormatTimeZone

public NSTimeZone defaultFormatTimeZone()

Returns the default time zone this NSTimestampFormatter uses for formatting -- converting an NSTimestamp to a string. The default format time zone itself defaults to the time zone specified by NSTimeZone defaultTimeZone.

Returns:

the default time zone this NSTimestampFormatter uses for formatting

See Also:

defaultParseTimeZone(), NSTimestamp

defaultParseTimeZone

public NSTimeZone defaultParseTimeZone()

Returns the default time zone this NSTimestampFormatter uses for parsing -- converting a string to an NSTimestamp. The default parse time zone itself defaults to the time zone specified by NSTimeZone defaultTimeZone.

Returns:

the default time zone the receiver uses for parsing

See Also:

defaultFormatTimeZone(), NSTimestamp.timeZone()

format

public StringBuffer format(Object obj,
                           StringBuffer toAppendTo,
                           FieldPosition pos)

Formats obj to produce a string, appends the string to toAppendTo, and returns the resulting string. The pos parameter specifies an alignment field to place the formatted object. When the method returns, this parameter contains the position of the alignment field.

Parameters:

obj - the object that is formatted to produce a string

toAppendTo - StringBuffer to which the string is appended

pos - the position parameter

Returns:

the resulting string

Throws:

IllegalArgumentException - if obj is not an NSTimestamp

parseObject

public Object parseObject(String text,
                          ParsePosition pos)

Parses a string to produce an object. If the string does not specify a time zone, uses the default parse time zone.

Parameters:

text - the string that is to be parsed to produce an object

pos - the position parameter indicating where in text to begin parsing

Returns:

the object produced by parsing the input string

See Also:

defaultParseTimeZone()

parseObjectInUTC

public Object parseObjectInUTC(String text,
                               ParsePosition pos)

Parses a string to produce an object using UTC as the time zone. This method ignores the time zone specified by the string and the value of the parse time zone.

Parameters:

text - the string that is to be parsed to produce an object

pos - the position parameter indicating where in text to begin parsing

Returns:

the object produced by parsing the input string

See Also:

parseObject(java.lang.String, java.text.ParsePosition)

pattern

public String pattern()

Returns this NSTimestampFormatter's pattern. See the Calendar Specifiers table in the NSTimestampFormatter class description for more information on specifying the pattern string.

Returns:

the receivers's pattern

setDefaultFormatTimeZone

public void setDefaultFormatTimeZone(NSTimeZone zone)

Sets the default time zone this NSTimestampFormatter uses for formatting -- converting an NSTimestamp into a string -- to zone.

Parameters:

zone - the default time zone this NSTimestampFormatter uses for formatting

See Also:

setDefaultParseTimeZone(com.webobjects.foundation.NSTimeZone), NSTimestamp

setDefaultParseTimeZone

public void setDefaultParseTimeZone(NSTimeZone zone)

Sets the default time zone this NSTimestampFormatter uses for parsing -- converting a string to an NSTimestamp -- to zone.

Parameters:

zone - default time zone this NSTimestampFormatter uses for parsing

See Also:

setDefaultFormatTimeZone(com.webobjects.foundation.NSTimeZone), NSTimestamp

setPattern

public void setPattern(String pattern)

Sets this NSTimestampFormatter's pattern to pattern. See the Calendar Specifiers table in the NSTimestampFormatter class description for more information on specifying the pattern string.

Parameters:

pattern - new pattern String

toString

public String toString()

Returns a string representation of this NSTimestampFormatter that includes the default format time zone, the default parse time zone, and the pattern.

Returns:

String representation of the receiver

See Also:

defaultFormatTimeZone(), defaultParseTimeZone(), pattern()