public abstract class

TimeZone

extends Object
implements Serializable Cloneable
java.lang.Object
   ↳ java.util.TimeZone
Known Direct Subclasses

Class Overview

TimeZone represents a time zone offset, taking into account 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 the following: 

 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 you can create a custom time zone ID with the following syntax: 
 GMT[+|-]hh[[:]mm]
For example, you might specify GMT+14:00 as a custom time zone ID. The TimeZone that is returned when you specify a custom time zone ID does not include daylight savings time.

For compatibility with JDK 1.1.x, some other three-letter time zone IDs (such as "PST", "CTT", "AST") are also supported. However, their use 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.

Please note the type returned by factory methods, i.e. getDefault() and getTimeZone(String), is implementation dependent, so it may introduce serialization incompatibility issues between different implementations. Android returns instances of SimpleTimeZone so that the bytes serialized by Android can be deserialized successfully on other implementations, but the reverse compatibility cannot be guaranteed.

See Also

Summary

Constants
int LONG The LONG display name style.
int SHORT The SHORT display name style.
Public Constructors
TimeZone()
Constructs a new instance of this class.
Public Methods
Object clone()
Returns a new TimeZone with the same ID, rawOffset and daylight savings time rules as this TimeZone.
synchronized static String[] getAvailableIDs()
Gets the available time zone IDs.
synchronized static String[] getAvailableIDs(int offset)
Gets the available time zone IDs which match the specified offset from GMT.
int getDSTSavings()
Gets the daylight savings offset in milliseconds for this TimeZone.
synchronized static TimeZone getDefault()
Gets the default time zone.
final String getDisplayName()
Gets the LONG name for this TimeZone for the default Locale in standard time.
final String getDisplayName(boolean daylightTime, int style)
Gets the specified style of name (LONG or SHORT) for this TimeZone for the default Locale in either standard or daylight time as specified.
final String getDisplayName(Locale locale)
Gets the LONG name for this TimeZone for the specified Locale in standard time.
String getDisplayName(boolean daylightTime, int style, Locale locale)
Gets the specified style of name (LONG or SHORT) for this TimeZone for the specified Locale in either standard or daylight time as specified.
String getID()
Gets the ID of this TimeZone.
abstract int getOffset(int era, int year, int month, int day, int dayOfWeek, int time)
Gets the offset from GMT of this TimeZone for the specified date and time.
int getOffset(long time)
Gets the offset from GMT of this TimeZone for the specified date.
abstract int getRawOffset()
Gets the offset for standard time from GMT for this TimeZone.
synchronized static TimeZone getTimeZone(String name)
Gets the TimeZone with the specified ID.
boolean hasSameRules(TimeZone zone)
Returns whether the specified TimeZone has the same raw offset as this TimeZone.
abstract boolean inDaylightTime(Date time)
Returns whether the specified Date is in the daylight savings time period for this TimeZone.
synchronized static void setDefault(TimeZone timezone)
Sets the default time zone.
void setID(String name)
Sets the ID of this TimeZone.
abstract void setRawOffset(int offset)
Sets the offset for standard time from GMT for this TimeZone.
abstract boolean useDaylightTime()
Returns whether this TimeZone has a daylight savings time period.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int LONG

Since: API Level 1

The LONG display name style.

Constant Value: 1 (0x00000001)

public static final int SHORT

Since: API Level 1

The SHORT display name style.

Constant Value: 0 (0x00000000)

Public Constructors

public TimeZone ()

Since: API Level 1

Constructs a new instance of this class.

Public Methods

public Object clone ()

Since: API Level 1

Returns a new TimeZone with the same ID, rawOffset and daylight savings time rules as this TimeZone.

Returns
  • a shallow copy of this TimeZone.
See Also

public static synchronized String[] getAvailableIDs ()

Since: API Level 1

Gets the available time zone IDs. Any one of these IDs can be passed to get() to create the corresponding TimeZone instance.

Returns
  • an array of time zone ID strings.

public static synchronized String[] getAvailableIDs (int offset)

Since: API Level 1

Gets the available time zone IDs which match the specified offset from GMT. Any one of these IDs can be passed to get() to create the corresponding TimeZone instance.

Parameters
offset the offset from GMT in milliseconds.
Returns
  • an array of time zone ID strings.

public int getDSTSavings ()

Since: API Level 1

Gets the daylight savings offset in milliseconds for this TimeZone.

This implementation returns 3600000 (1 hour), or 0 if the time zone does not observe daylight savings.

Subclasses may override to return daylight savings values other than 1 hour.

Note that this method doesn't tell you whether or not to apply the offset: you need to call inDaylightTime for the specific time you're interested in. If this method returns a non-zero offset, that only tells you that this TimeZone sometimes observes daylight savings.

Returns
  • the daylight savings offset in milliseconds if this TimeZone observes daylight savings, zero otherwise.

public static synchronized TimeZone getDefault ()

Since: API Level 1

Gets the default time zone.

Returns
  • the default time zone.

public final String getDisplayName ()

Since: API Level 1

Gets the LONG name for this TimeZone for the default Locale in standard time. If the name is not available, the result is in the format GMT[+-]hh:mm.

Returns
  • the TimeZone name.

public final String getDisplayName (boolean daylightTime, int style)

Since: API Level 1

Gets the specified style of name (LONG or SHORT) for this TimeZone for the default Locale in either standard or daylight time as specified. If the name is not available, the result is in the format GMT[+-]hh:mm.

Parameters
daylightTime true for daylight time, false for standard time.
style either LONG or SHORT.
Returns
  • the TimeZone name.

public final String getDisplayName (Locale locale)

Since: API Level 1

Gets the LONG name for this TimeZone for the specified Locale in standard time. If the name is not available, the result is in the format GMT[+-]hh:mm.

Parameters
locale the Locale.
Returns
  • the TimeZone name.

public String getDisplayName (boolean daylightTime, int style, Locale locale)

Since: API Level 1

Gets the specified style of name (LONG or SHORT) for this TimeZone for the specified Locale in either standard or daylight time as specified. If the name is not available, the result is in the format GMT[+-]hh:mm.

Parameters
daylightTime true for daylight time, false for standard time.
style either LONG or SHORT.
locale either LONG or SHORT.
Returns
  • the TimeZone name.

public String getID ()

Since: API Level 1

Gets the ID of this TimeZone.

Returns
  • the time zone ID string.

public abstract int getOffset (int era, int year, int month, int day, int dayOfWeek, int time)

Since: API Level 1

Gets the offset from GMT of this TimeZone for the specified date and time. The offset includes daylight savings time if the specified date and time are within the daylight savings time period.

Parameters
era the GregorianCalendar era, either GregorianCalendar.BC or GregorianCalendar.AD.
year the year.
month the Calendar month.
day the day of the month.
dayOfWeek the Calendar day of the week.
time the time of day in milliseconds.
Returns
  • the offset from GMT in milliseconds.

public int getOffset (long time)

Since: API Level 1

Gets the offset from GMT of this TimeZone for the specified date. The offset includes daylight savings time if the specified date is within the daylight savings time period.

Parameters
time the date in milliseconds since January 1, 1970 00:00:00 GMT
Returns
  • the offset from GMT in milliseconds.

public abstract int getRawOffset ()

Since: API Level 1

Gets the offset for standard time from GMT for this TimeZone.

Returns
  • the offset from GMT in milliseconds.

public static synchronized TimeZone getTimeZone (String name)

Since: API Level 1

Gets the TimeZone with the specified ID.

Parameters
name a time zone string ID.
Returns
  • the TimeZone with the specified ID or null if no TimeZone with the specified ID exists.

public boolean hasSameRules (TimeZone zone)

Since: API Level 1

Returns whether the specified TimeZone has the same raw offset as this TimeZone.

Parameters
zone a TimeZone.
Returns
  • true when the TimeZone have the same raw offset, false otherwise.

public abstract boolean inDaylightTime (Date time)

Since: API Level 1

Returns whether the specified Date is in the daylight savings time period for this TimeZone.

Parameters
time a Date.
Returns
  • true when the Date is in the daylight savings time period, false otherwise.

public static synchronized void setDefault (TimeZone timezone)

Since: API Level 1

Sets the default time zone. If passed null, then the next time getDefault() is called, the default time zone will be determined. This behavior is slightly different than the canonical description of this method, but it follows the spirit of it.

Parameters
timezone a TimeZone object.

public void setID (String name)

Since: API Level 1

Sets the ID of this TimeZone.

Parameters
name a string which is the time zone ID.

public abstract void setRawOffset (int offset)

Since: API Level 1

Sets the offset for standard time from GMT for this TimeZone.

Parameters
offset the offset from GMT in milliseconds.

public abstract boolean useDaylightTime ()

Since: API Level 1

Returns whether this TimeZone has a daylight savings time period.

If this method returns true, that only tells you that this TimeZone sometimes observes daylight savings. You need to call inDaylightTime to find out whether daylight savings is in effect.

More specifically, this method returns true to indicate that there's at least one known future transition to or from daylight savings. This means that, say, Taiwan will return false because its historical use of daylight savings doesn't count. A hypothetical country that has never observed daylight savings before but plans to start next year would return true.

Returns
  • true if this TimeZone has a daylight savings time period, false otherwise.