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 U.S. Pacific Time zone is "America/Los_Angeles". So, you can get a U.S. Pacific Time TimeZone object with:

 TimeZone tz = TimeZone.getTimeZone("America/Los_Angeles");
 

You can use the getAvailableIDs method to iterate through all the supported time zone IDs. You can then choose a supported ID to get a TimeZone. If the time zone you want is not represented by one of the supported IDs, then a custom time zone ID can be specified to produce a TimeZone. The syntax of a custom time zone ID is:

 CustomID:
         GMT Sign Hours : Minutes
         GMT Sign Hours Minutes
         GMT Sign Hours
 Sign: one of
         + -
 Hours:
         Digit
         Digit Digit
 Minutes:
         Digit Digit
 Digit: one of
         0 1 2 3 4 5 6 7 8 9
 

Hours must be between 0 to 23 and Minutes must be between 00 to 59. For example, "GMT+10" and "GMT+0010" mean ten hours and ten minutes ahead of GMT, respectively.

The format is locale independent and digits must be taken from the Basic Latin block of the Unicode standard. No daylight saving time transition schedule can be specified with a custom time zone ID. If the specified string doesn't match the syntax, "GMT" is used.

When creating a TimeZone, the specified custom time zone ID is normalized in the following syntax:

 NormalizedCustomID:
         GMT Sign TwoDigitHours : Minutes
 Sign: one of
         + -
 TwoDigitHours:
         Digit Digit
 Minutes:
         Digit Digit
 Digit: one of
         0 1 2 3 4 5 6 7 8 9
 

For example, TimeZone.getTimeZone("GMT-8").getID() returns "GMT-08:00".

Three-letter time zone IDs

The use of three-letter time zones is deprecated because the same abbreviation is often used for multiple time zones (for example, "CST" could be U.S. "Central Standard Time" and "China Standard Time"), and the Java platform can then only recognize one of them.

CLDC

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: custom IDs such as "GMT-8:00" are not required to be supported.

Sun SPOT and Squawk Details

For Sun SPOTs the following additional time zones are supported:

     HST, AST, PST, MST, CST & EST and "GMT+hh:mm"
 

plus we allow other timezones to be user defined via system properties passed in to Squawk on the command line.

The default time zone is "PST". It can be changed to another supported time zone by setting the system property com.sun.cldc.util.j2me.TimeZoneImpl.timezone E.g. to make the default be "EST" include the following in the command line to start Squawk:

    -Dcom.sun.cldc.util.j2me.TimeZoneImpl.timezone=EST
 

To add additional time zones use the system property com.sun.cldc.util.j2me.TimeZoneImpl.additionaltimezones, where its value is a list of the time zones to add in the format:

     tzname1={+-}hh{:mm}{,daylight_savings_spec};tzname2=...;
 

where

     daylight_savings_spec =
           start_month,start_day,start_day_of_week,start_time,
           end_month,end_day,end_day_of_week,end_time,hh{:mm}
 

To specify the last Sunday of the month set the day_of_week to Calendar.SUNDAY and the day to -1, i.e. day is interpreted then to be which Sunday (1 = first, 2 = second, -2 = second last, etc.).

It is also possible to specify a date such as the first Sunday before/after a given day of the month by setting the day_of_week to be negative. If the day value is negative then the day_of_week before that day is specified.

For example an Australian might define:

    -Dcom.sun.cldc.util.j2me.TimeZoneImpl.additionaltimezones=
          Australia/Perth=8;Australia/Darwin=9:30;Australia/Adelaide=9:30,9,-1,1,2,2,-1,1,2,1;
          Australia/Brisbane=10;Australia/Sydney=10,9,-1,1,2,2,-1,1,3,1;
          Australia/Lord_Howe=10:30,9,-1,1,2,2,-1,1,3,0:30;
 

Version:

1.0 (J2ME MIDP)

Author:

Mark Davis, David Goldsmith, Chen-Lieh Huang, Alan Liu, Brian Modra

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.

Sun SPOT and Squawk Details

To add additional time zones use the system property com.sun.cldc.util.j2me.TimeZoneImpl.additionaltimezones. See TimeZone for details.

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.

Sun SPOT and Squawk Details

The default time zone is "PST". It can be changed to another supported time zone by setting the system property com.sun.cldc.util.j2me.TimeZoneImpl.timezone.

See TimeZone for details.

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".

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.