java.util
Class TimeZone

java.lang.Object
  |
  +--java.util.TimeZone

public abstract class TimeZone
extends Object

TimeZone represents a time zone offset, and also figures out daylight savings.

Typically, you get a TimeZone using getDefault which creates a TimeZone based on the time zone where the program is running. For example, for a program running in Japan, getDefault creates a TimeZone object based on Japanese Standard Time.

You can also get a TimeZone using getTimeZone along with a time zone ID. For instance, the time zone ID for the Pacific Standard Time zone is "PST". So, you can get a PST TimeZone object with:

 TimeZone tz = TimeZone.getTimeZone("PST");
 

This class is a pure subset of the java.util.TimeZone class in J2SE.

The only time zone ID that is required to be supported is "GMT".

Apart from the methods and variables being subset, the semantics of the getTimeZone() method may also be subset.

You can create custom time zones that represent a general GMT offset value by using getTimeZone with an ID created with the following syntax:

ID:

Sign: one of:

Hours:

Minutes:

Digit: one of:

When creating a custom time zone, the ID is normalized as GMT Sign Hours (two digit version) : Minutes

e.g. TimeZone tz = TimeZone.getTimeZone("GMT-8").getID() returns GMT-08:00.

See Also:
Calendar

Constructor Summary
TimeZone()
           
 
Method Summary
static String[] getAvailableIDs()
          Gets all the available IDs supported.
static TimeZone getDefault()
          Gets the default TimeZone for this host.
 String getID()
          Gets the ID of this time zone.
abstract  int getOffset(int era, int year, int month, int day, int dayOfWeek, int millis)
          Gets offset, for current date, modified in case of daylight savings.
abstract  int getRawOffset()
          Gets the GMT offset for this time zone.
static TimeZone getTimeZone(String ID)
          Gets the TimeZone for the given ID.
abstract  boolean useDaylightTime()
          Queries if this time zone uses Daylight Savings Time.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TimeZone

public TimeZone()
Method Detail

getAvailableIDs

public static String[] getAvailableIDs()
Gets all the available IDs supported.
Returns:
an array of IDs.

getDefault

public static TimeZone getDefault()
Gets the default TimeZone for this host. The source of the default TimeZone may vary with implementation.
Returns:
a default TimeZone.

getID

public String getID()
Gets the ID of this time zone.
Returns:
the ID of this time zone.

getOffset

public abstract int getOffset(int era,
                              int year,
                              int month,
                              int day,
                              int dayOfWeek,
                              int millis)
Gets offset, for current date, modified in case of daylight savings. This is the offset to add *to* GMT to get local time. Gets the time zone offset, for current date, modified in case of daylight savings. This is the offset to add *to* GMT to get local time. Assume that the start and end month are distinct. This method may return incorrect results for rules that start at the end of February (e.g., last Sunday in February) or the beginning of March (e.g., March 1).
Parameters:
era - The era of the given date (0 = BC, 1 = AD).
year - The year in the given date.
month - The month in the given date. Month is 0-based. e.g., 0 for January.
day - The day-in-month of the given date.
dayOfWeek - The day-of-week of the given date.
millis - The milliseconds in day in standard local time.
Returns:
The offset to add *to* GMT to get local time.
Throws:
IllegalArgumentException - the era, month, day, dayOfWeek, or millis parameters are out of range

getRawOffset

public abstract int getRawOffset()
Gets the GMT offset for this time zone.
Returns:
the GMT offset for this time zone.

getTimeZone

public static TimeZone getTimeZone(String ID)
Gets the TimeZone for the given ID.
Parameters:
ID - the ID for a TimeZone, either an abbreviation such as "GMT", or a full name such as "America/Los_Angeles".

The only time zone ID that is required to be supported is "GMT".

The following is information for implementers. Applications should not need to be aware of this or rely on it, because each implementation may do it differently:

The Calendar will look up a class the name of which includes the platform name. The class name will take the form:

{classRoot}.util.{platform}.CalendarImpl

The classRoot is derived from the system by looking up the system property "microedition.implpath" If this property key is not found or the associated class is not present then "com.sun.cldc" is used.

The platform name is derived from the system by looking for the system property "microedition.platform". If this property key is not found or the associated class is not present then one of two default directories are used. These are called "j2me" and "j2se". If the property "microedition.configuration" is non-null then "j2me" is used, otherwise "j2se" is assumed.

UPDATE: Timezone implemenation has changed. Instead of a giant static array of zones (i.e. lots of objects list is controlled at compile time) a new interface for manipulating zones has been created. Therefore, getTimeZone has been updated to use this interface.

Returns:
the specified TimeZone, or the GMT zone if the given ID cannot be understood.

useDaylightTime

public abstract boolean useDaylightTime()
Queries if this time zone uses Daylight Savings Time.
Returns:
if this time zone uses Daylight Savings Time.



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.