com.webobjects.foundation
Class NSTimeZone

java.lang.Object
  |
  +--java.util.TimeZone
        |
        +--com.webobjects.foundation.NSTimeZone

All Implemented Interfaces:

Cloneable, NSCoding, Serializable

public class NSTimeZone

extends TimeZone

implements Cloneable, Serializable, NSCoding

NSTimeZone defines the behavior of time zones for different geopolitical regions. Consequently, these objects have names (and abbreviations, such as "PST") for these regions. NSTimeZone objects also represent a temporal offset, either plus or minus, from Greenwich Mean Time (GMT).

NSTimeZone provides several ways to instantiate time zones. The class also permits you to set the default time zone within your application (setDefault). You can access this default time zone at any time with the getDefault static method. With the localTimeZone static method, you can get a relative time zone object that decodes itself to become the default time zone for any locale in which it finds itself.

Because NSTimeZone is a subclass of java.util.TimeZone, you can also use the java.util.TimeZone API with NSTimeZones.

WARNING: NSTimeZone is only intended to be used with NSTimestamp and NSTimestampFormatter. It produces incorrect results when used with Java's date-related classes.

Some NSTimestamp methods return date objects that are automatically bound to time zone objects. These date objects use the functionality of NSTimeZone to adjust dates for the proper locale. Unless you specify otherwise, objects returned from NSTimestamp are bound to the default time zone for the current locale.

See Also:

abbreviation(), getDefault(), getID(), localTimeZone(), setDefault(java.util.TimeZone aTZ), NSTimestamp, NSTimestampFormatter, Serialized Form

Inner classes inherited from class com.webobjects.foundation.NSCoding

NSCoding.Support

Field Summary

static String

SystemTimeZoneDidChangeNotification The name for the notification posted during any invocation of NSTimeZone's resetSystemTimeZone method.

Fields inherited from class java.util.TimeZone

LONG, SHORT

Constructor Summary

	NSTimeZone() Required internally to implement the java.io.Serializable interface and should be considered private.
protected	NSTimeZone(String aName, NSData aData) Used internally by NSTimeZone and should be considered private.

Method Summary

String	abbreviation() Returns the abbreviation for the NSTimeZone at the current instant, such as "EDT" (Eastern Daylight Time).
static NSDictionary	abbreviationDictionary() Provides the mappings of time zone abbreviations to time zone names.
String	abbreviationForTimestamp(NSTimestamp aTimestamp) Provides the abbreviation for the NSTimeZone at the instant specified by aTimestamp.
Class	classForCoder() Allows the receiver, before being encoded, to substitute a class other than its own in a coder.
Object	clone() Since NSTimeZones are immutable, there's no need to make an actual clone.
NSData	data() Provides an opaque object representing the behavior for this NSTimeZone.
static Object	decodeObject(NSCoder aDecoder) Provided for compliance with com.webobjects.foundation.NSCoding.
static NSTimeZone	defaultTimeZone() Deprecated. Use getDefault instead.
void	encodeWithCoder(NSCoder aCoder) Encodes the receiver using coder.
boolean	equals(Object anObject) Indicates whether this NSTimeZone has the same data as that of anObject.
static String[]	getAvailableIDs() Provides a list of all of the names and abbreviations known to NSTimeZone.
static TimeZone	getDefault() Provides the last object given to NSTimeZone via setDefault.
String	getDisplayName(boolean inDaylightSavingTime, int aTZStyle, Locale aLocale)
String	getID()
int	getOffset(int anEra, int aYear, int aMonth, int aDayOfMonth, int aDayOfWeek, int milliseconds)
int	getRawOffset() Provides the generic difference between the NSTimeZone and Greenwich Mean Time (the offset).
int	hashCode()
boolean	hasSameRules(TimeZone aTZ) Invokes equals with aTZ.
boolean	inDaylightTime(Date aDate) Indicates whether this NSTimeZone uses daylight savings time at aDate.
boolean	isDaylightSavingTime() Indicates whether this NSTimeZone currently uses daylight savings time.
boolean	isDaylightSavingTimeForTimestamp(NSTimestamp aTimestamp) Indicates whether this NSTimeZone uses daylight savings time at aTimestamp.
boolean	isEqualToTimeZone(NSTimeZone aTimeZone) Deprecated. Use equals.
static NSArray	knownTimeZoneNames() Provides a list of all of the names and abbreviations known to NSTimeZone.
static NSTimeZone	localTimeZone() Provides an object that forwards all messages to the default time zone in the current locale for the application.
String	name() Deprecated. Use getID.
protected Object	readResolve()
static void	resetSystemTimeZone() Clears any previously determined system time zone.
int	secondsFromGMT() Indicates the difference between the NSTimeZone and Greenwich Mean Time (the offset) at the current instant.
int	secondsFromGMTForTimestamp(NSTimestamp aTimestamp) Indicates the difference between the NSTimeZone and Greenwich Mean Time (the offset) at the instant specified by aTimestamp.
static void	setDefault(TimeZone aTZ) Changes the time zone provided by getDefault for the application.
static void	setDefaultTimeZone(NSTimeZone aTZ) Deprecated. Use setDefault instead.
void	setID(String anID) Irrelevant for NSTimeZone objects, which are not mutable.
void	setRawOffset(int offsetMillis) Irrelevant for NSTimeZone objects, which are not mutable.
static NSTimeZone	systemTimeZone() Provides the time zone object representing the system's time zone.
static NSTimeZone	timeZoneForSecondsFromGMT(int secondsOffsetFromGMT) Provides an NSTimeZone object with seconds offset from Greenwich Mean Time.
static NSTimeZone	timeZoneWithName(String aName, boolean tryAbbreviation) Provides an NSTimeZone object corresponding to aName.
static NSTimeZone	timeZoneWithNameAndData(String aName, NSData aData) Use timeZoneWithName instead of calling this method directly.
String	toString()
boolean	useDaylightTime() Indicates whether the NSTimeZone ever uses or has used daylight savings time.

Methods inherited from class java.util.TimeZone

getAvailableIDs, getDisplayName, getDisplayName, getDisplayName, getTimeZone

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SystemTimeZoneDidChangeNotification

public static final String SystemTimeZoneDidChangeNotification

The name for the notification posted during any invocation of NSTimeZone's resetSystemTimeZone method.

See Also:

resetSystemTimeZone(), NSNotification

Constructor Detail

NSTimeZone

public NSTimeZone()

Required internally to implement the java.io.Serializable interface and should be considered private.

Use the following methods to get NSTimeZone objects:

• timeZoneForSecondsFromGMT
• timeZoneWithName

See Also:

timeZoneWithName(String aName, boolean tryAbbreviation), timeZoneForSecondsFromGMT(int secondsOffsetFromGMT), Serializable

NSTimeZone

protected NSTimeZone(String aName,
                     NSData aData)

Used internally by NSTimeZone and should be considered private.

Use the following methods to get NSTimeZone objects:

• timeZoneForSecondsFromGMT
• timeZoneWithName

Parameters:

aName - the proposed name for the newly instantiated NSTimeZone object

aData - the proposed behavior for the newly instantiated NSTimeZone object (represented by raw binary data)

See Also:

timeZoneWithName(String aName, boolean tryAbbreviation), timeZoneForSecondsFromGMT(int secondsOffsetFromGMT)

Method Detail

abbreviation

public String abbreviation()

Returns the abbreviation for the NSTimeZone at the current instant, such as "EDT" (Eastern Daylight Time). Invokes abbreviationForTimestamp with an NSTimestamp representing the current instant.

Invoked by toString.

Returns:

the abbreviation for the time zone at the current instant.

See Also:

abbreviationDictionary(), abbreviationForTimestamp(NSTimestamp aTimestamp), toString()

abbreviationDictionary

public static NSDictionary abbreviationDictionary()

Provides the mappings of time zone abbreviations to time zone names.

Any given name may be represented by several abbreviations. Conversely, more than one time zone may have the same abbreviation. For example, US/Pacific and Canada/Pacific both use the abbreviation "PST." In these cases, this method always chooses a single name to which to map the abbreviation.

Returns:

the mappings of abbreviations to names. Never null.

See Also:

getID(), abbreviation(), abbreviationForTimestamp(NSTimestamp aTimestamp)

abbreviationForTimestamp

public String abbreviationForTimestamp(NSTimestamp aTimestamp)

Provides the abbreviation for the NSTimeZone at the instant specified by aTimestamp.

Note that the abbreviation may be different at different instants. For example, during daylight savings time, the US/Eastern time zone has an abbreviation of "EDT". At other times, its abbreviation is "EST".

Invoked by abbreviation.

Parameters:

aTimestamp - the specified instant

Returns:

the abbreviation for the NSTimeZone at aTimestamp. Never null.

See Also:

abbreviation(), abbreviationDictionary()

classForCoder

public Class classForCoder()

Description copied from interface: NSCoding

Allows the receiver, before being encoded, to substitute a class other than its own in a coder. For example, private subclasses can substitute the name of a public superclass when being encoded.

Specified by:

classForCoder in interface NSCoding

Following copied from interface: com.webobjects.foundation.NSCoding

Returns:

the class a coder should record

clone

public Object clone()

Since NSTimeZones are immutable, there's no need to make an actual clone.

Overrides:

clone in class TimeZone

Returns:

a reference to this same NSTimeZone object

data

public NSData data()

Provides an opaque object representing the behavior for this NSTimeZone. Invoked by equals.

Returns:

raw binary data that represents the NSTimeZone's behavior. Never null.

See Also:

equals(Object anObject)

decodeObject

public static Object decodeObject(NSCoder aDecoder)

Provided for compliance with com.webobjects.foundation.NSCoding. Provides an NSTimeZone object for the decoded data. Attempts to avoid creating duplicate objects.

Parameters:

aDecoder - the NSCoder object used to decode this NSTimeZone object

Returns:

the decoded NSTimeZone object

See Also:

encodeWithCoder(com.webobjects.foundation.NSCoder aCoder), NSCoding

defaultTimeZone

public static NSTimeZone defaultTimeZone()

Deprecated. Use getDefault instead.

Invokes getDefault.

See Also:

getDefault()

encodeWithCoder

public void encodeWithCoder(NSCoder aCoder)

Description copied from interface: NSCoding

Encodes the receiver using coder. Object type information along with an object's data is stored.

Specified by:

encodeWithCoder in interface NSCoding

Following copied from interface: com.webobjects.foundation.NSCoding

Parameters:

coder - an NSCoder object that will be used to encode object of classes that implement this interface

See Also:

NSCoder

equals

public boolean equals(Object anObject)

Indicates whether this NSTimeZone has the same data as that of anObject. Invoked by:

• hasSameRules
• isEqualToTimeZone

Overrides:

equals in class Object

Parameters:

anObject - another NSTimeZone object against which to compare this NSTimeZone.

Returns:

false if they have different data or if anObject is not an instance of NSTimeZone, true otherwise

See Also:

data(), hasSameRules(java.util.TimeZone aTZ), isEqualToTimeZone(NSTimeZone aTimeZone)

getAvailableIDs

public static String[] getAvailableIDs()

Provides a list of all of the names and abbreviations known to NSTimeZone.

Returns:

the Java array of all names and abbreviations. Never null.

See Also:

knownTimeZoneNames()

getDefault

public static TimeZone getDefault()

Provides the last object given to NSTimeZone via setDefault. This is not the same thing as the localTimeZone.

Unless this behavior is changed using setDefaultTimeZone, this method returns systemTimeZone.

Invoked by defaultTimeZone.

Returns:

the default time zone. Never null.

See Also:

defaultTimeZone(), localTimeZone(), setDefault(java.util.TimeZone aTZ), systemTimeZone()

getDisplayName

public String getDisplayName(boolean inDaylightSavingTime,
                             int aTZStyle,
                             Locale aLocale)

Overrides:

getDisplayName in class TimeZone

getID

public String getID()

Overrides:

getID in class TimeZone

getOffset

public int getOffset(int anEra,
                     int aYear,
                     int aMonth,
                     int aDayOfMonth,
                     int aDayOfWeek,
                     int milliseconds)

Overrides:

getOffset in class TimeZone

getRawOffset

public int getRawOffset()

Provides the generic difference between the NSTimeZone and Greenwich Mean Time (the offset).

Because NSTimeZones represent geopolitical regions, many timezones don't have one, generic offset. The offset can change over time for reasons other than daylight saving purposes. Consequently, this method will return zero except for generic, apolitical time zones of the form GMT+/-hrs, like those generated by timeZoneForSecondsFromGMT.

Overrides:

getRawOffset in class TimeZone

Returns:

the offset in milliseconds for apolitical time zones, zero otherwise

See Also:

timeZoneForSecondsFromGMT(int secondsOffsetFromGMT)

hasSameRules

public boolean hasSameRules(TimeZone aTZ)

Invokes equals with aTZ.

Overrides:

hasSameRules in class TimeZone

Parameters:

aTZ - another NSTimeZone object against which to compare this NSTimeZone

Returns:

true if aTimeZone and this NSTimeZone have the same data, false otherwise

See Also:

data(), equals(Object anObject)

hashCode

public int hashCode()

Overrides:

hashCode in class Object

inDaylightTime

public boolean inDaylightTime(Date aDate)

Indicates whether this NSTimeZone uses daylight savings time at aDate.

Invokes isDaylightSavingTimeForTimestamp with an NSTimestamp representing aDate.

Overrides:

inDaylightTime in class TimeZone

Parameters:

aDate - the specified instant

Returns:

true if the NSTimeZone uses daylight savings time at the specified instant, false otherwise

See Also:

isDaylightSavingTime(), isDaylightSavingTimeForTimestamp(NSTimestamp aTimestamp)

isDaylightSavingTime

public boolean isDaylightSavingTime()

Indicates whether this NSTimeZone currently uses daylight savings time. Invokes isDaylightSavingTimeForTimestamp with an NSTimestamp representing the current instant.

Returns:

true if the NSTimeZone is currently using daylight savings time, false otherwise

See Also:

inDaylightTime(java.util.Date aDate), isDaylightSavingTimeForTimestamp(NSTimestamp aTimestamp)

isDaylightSavingTimeForTimestamp

public boolean isDaylightSavingTimeForTimestamp(NSTimestamp aTimestamp)

Indicates whether this NSTimeZone uses daylight savings time at aTimestamp.

Invoked by:

• inDaylightTime
• isDaylightSavingTime

Parameters:

aTimestamp - the specified instant

Returns:

true if the NSTimeZone uses daylight savings time at the specified instant, false otherwise

See Also:

inDaylightTime(java.util.Date aDate), isDaylightSavingTime()

isEqualToTimeZone

public boolean isEqualToTimeZone(NSTimeZone aTimeZone)

Deprecated. Use equals.

Invokes equals with aTimeZone.

Parameters:

aTimeZone - another NSTimeZone object against which to compare this NSTimeZone

Returns:

true if aTimeZone and this NSTimeZone have the same data, false otherwise

See Also:

data(), equals(Object anObject)

knownTimeZoneNames

public static NSArray knownTimeZoneNames()

Provides a list of all of the names and abbreviations known to NSTimeZone.

Returns:

the NSArray of Strings representing all of the names and abbreviations

See Also:

getAvailableIDs()

localTimeZone

public static NSTimeZone localTimeZone()

Provides an object that forwards all messages to the default time zone in the current locale for the application. This behavior is particularly useful for NSTimestamp objects that are archived or distributed across a network. Such objects may be used in different locales than the one in which they were created.

Returns:

a special object that forwards all messages to the time zone provided by getDefault. Never null.

See Also:

defaultTimeZone()

name

public String name()

Deprecated. Use getID.

Invokes getID.

Returns:

the name that identifies the geopolitical region that the NSTimeZone represents

See Also:

getID()

readResolve

protected Object readResolve()
                      throws ObjectStreamException

resetSystemTimeZone

public static void resetSystemTimeZone()

Clears any previously determined system time zone. Subsequent calls to systemTimeZone will redetermine the system time zone.

Also posts an NSTimeZone.SystemTimeZoneDidChangeNotification.

See Also:

systemTimeZone()

secondsFromGMT

public int secondsFromGMT()

Indicates the difference between the NSTimeZone and Greenwich Mean Time (the offset) at the current instant.

Returns:

current offset in seconds

secondsFromGMTForTimestamp

public int secondsFromGMTForTimestamp(NSTimestamp aTimestamp)

Indicates the difference between the NSTimeZone and Greenwich Mean Time (the offset) at the instant specified by aTimestamp.

The NSTimeZone object may change its offset from GMT at different points in the year. For example, the U.S. time zones change offsets with daylight savings time.

Because NSTimeZone objects represent geopolitical regions, offsets such as those for daylight savings time may change across different spans. For example, the organization which governs a region may abolish daylight savings time, though daylight savings time would be relevant for moments preceding the abolition.

Parameters:

aTimestamp - an instant in time

Returns:

offset in seconds at the instant specified by aTimestamp

setDefault

public static void setDefault(TimeZone aTZ)

Changes the time zone provided by getDefault for the application. This is not the same as the localTimeZone, which cannot be substituted.

Parameters:

aTZ - the proposed default time zone. Must be an instance of NSTimeZone.

See Also:

getDefault(), localTimeZone()

setDefaultTimeZone

public static void setDefaultTimeZone(NSTimeZone aTZ)

Deprecated. Use setDefault instead.

Invokes setDefault.

See Also:

setDefault(java.util.TimeZone aTZ)

setID

public void setID(String anID)

Irrelevant for NSTimeZone objects, which are not mutable.

Overrides:

setID in class TimeZone

setRawOffset

public void setRawOffset(int offsetMillis)

Irrelevant for NSTimeZone objects, which are not mutable.

Overrides:

setRawOffset in class TimeZone

systemTimeZone

public static NSTimeZone systemTimeZone()

Provides the time zone object representing the system's time zone. This is different from localTimeZone and may be different from the time zone object returned by getDefault.

Returns:

the time zone currently used by the system or the GMT time zone if the current time zone can't be determined

See Also:

getDefault(), localTimeZone(), resetSystemTimeZone()

timeZoneForSecondsFromGMT

public static NSTimeZone timeZoneForSecondsFromGMT(int secondsOffsetFromGMT)

Provides an NSTimeZone object with seconds offset from Greenwich Mean Time. The name of the new time zone is GMT +/- the offset, in hours and minutes.

If the secondsOffsetFromGMT correspond evenly to a whole hour between 12 and -12, this method attempts to reuse an existing, well-known NSTimeZone objects for that offset. Otherwise, creates a new NSTimeZone instance for the specified offset.

These time zones are always apolitical. They never use daylight savings time, and their offset is constant.

The name and abbreviation for these time zones do NOT follow the POSIX convention of minutes-west.

Parameters:

secondsOffsetFromGMT - the specified offset in seconds to use in creating a new or finding an existing, apolitical NSTimeZone object

Returns:

the corresponding time zone object. May be null if secondsOffsetFromGMT correspond evenly to hours and the corresponding NSTimeZone object can't be found.

See Also:

timeZoneWithName(String aName, boolean tryAbbreviation), getID()

timeZoneWithName

public static NSTimeZone timeZoneWithName(String aName,
                                          boolean tryAbbreviation)

Provides an NSTimeZone object corresponding to aName. Avoids creating duplicate NSTimeZone objects as much as possible. This method is the recommended way for you to create or retrieve NSTimeZone objects.

Invoked by:

• decodeObject
• readResolve
• systemTimeZone
• timeZoneForSecondsFromGMT

Parameters:

aName - the name or abbreviation used to search for an existing NSTimeZone object. Should never be null.

tryAbbreviation - true to match aName against the abbreviationDictionary, false otherwise

Returns:

an NSTimeZone object identified by aName, null if there is no match

See Also:

abbreviation(), abbreviationDictionary(), abbreviationForTimestamp(NSTimestamp aTimestamp), decodeObject(NSCoder aDecoder), getID(), knownTimeZoneNames(), readResolve(), systemTimeZone(), timeZoneForSecondsFromGMT(int secondsOffsetFromGMT)

timeZoneWithNameAndData

public static NSTimeZone timeZoneWithNameAndData(String aName,
                                                 NSData aData)

Use timeZoneWithName instead of calling this method directly.

Invoked by:

• decodeObject
• readResolve
• timeZoneForSecondsFromGMT

Parameters:

aName - the proposed name of the new NSTimeZone object. Should never be null. May be coerced into another name, if there's a preferred name for the time zone identified.

aData - the proposed behavior (represented by raw binary data) for the new NSTimeZone object. Should never be null.

Returns:

a new NSTimeZone object, which may be a duplicate of an existing NSTimeZone object

See Also:

data(), decodeObject(NSCoder aDecoder), getID(), readResolve(), timeZoneForSecondsFromGMT(int secondsOffsetFromGMT), timeZoneWithName(String aName, boolean tryAbbreviation)

toString

public String toString()

Overrides:

toString in class Object

useDaylightTime

public boolean useDaylightTime()

Indicates whether the NSTimeZone ever uses or has used daylight savings time. Only ever true for objects that represent geopolitical regions.

Overrides:

useDaylightTime in class TimeZone

Returns:

true if the time zone ever uses or has used daylight savings time, false otherwise

See Also:

timeZoneForSecondsFromGMT(int secondsOffsetFromGMT)