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 acts as a proxy for 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), NSTimestamp, NSTimestampFormatter, Serialized Form

Nested Class Summary

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

NSCoding.Support

Field Summary

static String

SystemTimeZoneDidChangeNotification Deprecated.

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() Provides the last object given to NSTimeZone via setDefault or setDefaultTimeZone.If no default time zone has been explicitly set, this method returns the system time zone.
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 or setDefaultTimeZone.
String	getDisplayName(boolean inDaylightSavingTime, int aTZStyle, Locale aLocale)
static NSTimeZone	getGMT() Returns an NSTimeZone object representing GMT.
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() Deprecated.
String	name() Deprecated. Use getID.
protected Object	readResolve()
static void	resetSystemTimeZone() Deprecated.
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 or defaultTimeZone for the application.
static void	setDefaultTimeZone(NSTimeZone aTZ) Changes the time zone provided by getDefault or defaultTimeZone for the application.
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 representing a fixed offset, specified in seconds, 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, getDSTSavings, getOffset, getTimeZone

Methods inherited from class java.lang.Object

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

Field Detail

SystemTimeZoneDidChangeNotification

public static final String SystemTimeZoneDidChangeNotification

Deprecated.

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(java.lang.String, boolean), timeZoneForSecondsFromGMT(int), 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(java.lang.String, boolean), timeZoneForSecondsFromGMT(int)

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(com.webobjects.foundation.NSTimestamp), 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(com.webobjects.foundation.NSTimestamp)

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

Returns:

the class a coder should record

clone

public Object clone()

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

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(java.lang.Object)

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), NSCoding

defaultTimeZone

public static NSTimeZone defaultTimeZone()

Provides the last object given to NSTimeZone via setDefault or setDefaultTimeZone.If no default time zone has been explicitly set, this method returns the system time zone. The default time zone returned by NSTimeZone may or may not be consistent with the default time zone returned by java.util.TimeZone.

Returns:

the default time zone.

See Also:

getDefault(), setDefault(java.util.TimeZone), setDefaultTimeZone(com.webobjects.foundation.NSTimeZone)

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

Parameters:

aCoder - 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

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), isEqualToTimeZone(com.webobjects.foundation.NSTimeZone)

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 or setDefaultTimeZone. If no default time zone has been explicitly set, this method returns the system time zone. The default time zone returned by NSTimeZone may or may not be consistent with the default time zone returned by java.util.TimeZone.

Returns:

the default time zone. Never null.

See Also:

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

getDisplayName

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

getGMT

public static NSTimeZone getGMT()

Returns an NSTimeZone object representing GMT.

Returns:

an instance of NSTimeZone representing the GMT time zone.

getID

public String getID()

getOffset

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

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 or Etc/GMT+/-hrs, like those generated by timeZoneForSecondsFromGMT.

Returns:

the offset in milliseconds for apolitical time zones, zero otherwise

See Also:

timeZoneForSecondsFromGMT(int)

hasSameRules

public boolean hasSameRules(TimeZone aTZ)

Invokes equals with aTZ.

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(java.lang.Object)

hashCode

public int hashCode()

inDaylightTime

public boolean inDaylightTime(Date aDate)

Indicates whether this NSTimeZone uses daylight savings time at aDate.

Invokes isDaylightSavingTimeForTimestamp with an NSTimestamp representing aDate.

Parameters:

aDate - the specified instant

Returns:

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

See Also:

isDaylightSavingTime(), isDaylightSavingTimeForTimestamp(com.webobjects.foundation.NSTimestamp)

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), isDaylightSavingTimeForTimestamp(com.webobjects.foundation.NSTimestamp)

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), 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(java.lang.Object)

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()

Deprecated.

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

Throws:

ObjectStreamException

resetSystemTimeZone

public static void resetSystemTimeZone()

Deprecated.

This method provided for backward compatibility only. Sets the system time zone to null and 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 or defaultTimeZone for the application. The default time zone 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)

Changes the time zone provided by getDefault or defaultTimeZone for the application. The default time zone 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:

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

setID

public void setID(String anID)

Irrelevant for NSTimeZone objects, which are not mutable.

setRawOffset

public void setRawOffset(int offsetMillis)

Irrelevant for NSTimeZone objects, which are not mutable.

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 representing a fixed offset, specified in seconds, from Greenwich Mean Time. If secondsOffsetFromGMT corresponds to a whole hour between 12 and -12, this method returns an existing, well-known NSTimeZone object that follows the POSIX convention. The time zone name is "Etc/GMT<+/->", where "hour" is a whole number 1-12 and the sign (plus or minus) is the opposite of the sign of the offset. An offset of zero is a special case, for which the time zone name is simply "Etc/GMT".

If secondsOffsetFromGMT does not correspond to a whole hour between 12 and -12, this method creates a new time zone for the specified offset, rounded to the nearest minute. In this case, the time zone name is consistent with the Java convention rather than the POSIX convention. The time zone name is "GMT<+/->:", where the hour is always represented by two digits, and where the sign (plus or minus) is the same as the sign of the offset. Time zones created from offsets are always apolitical. They never use daylight savings time, and their offsets are constant throughout the year, and throughout history.

Parameters:

secondsOffsetFromGMT - the offset from Greenwich Mean Time in seconds to use in finding an existing, or creating an new, apolitical NSTimeZone object.

Returns:

the corresponding time zone object.

See Also:

timeZoneWithName(java.lang.String, boolean), 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(com.webobjects.foundation.NSTimestamp), decodeObject(com.webobjects.foundation.NSCoder), getID(), knownTimeZoneNames(), readResolve(), systemTimeZone(), timeZoneForSecondsFromGMT(int)

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(com.webobjects.foundation.NSCoder), getID(), readResolve(), timeZoneForSecondsFromGMT(int), timeZoneWithName(java.lang.String, boolean)

toString

public String toString()

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.

Returns:

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

See Also:

timeZoneForSecondsFromGMT(int)