WebObjects 5.2.3

com.webobjects.foundation
Class NSTimeZone

java.lang.Object
  extended byjava.util.TimeZone
      extended bycom.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:

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:

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:

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:

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:

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:

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)

Last updated Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.