SimpleTimeZone JDK 1.6)

Description

public class SimpleTimeZone

SimpleTimeZone is a concrete subclass of TimeZone that represents a time zone for use with a Gregorian calendar.

SimpleTimeZone is a concrete subclass of TimeZone that represents a time zone for use with a Gregorian calendar. The class holds an offset from GMT, called raw offset, and start and end rules for a daylight saving time schedule. Since it only holds single values for each, it cannot handle historical changes in the offset from GMT and the daylight saving schedule, except that the setStartYear method can specify the year when the daylight saving time schedule starts in effect.

To construct a SimpleTimeZone with a daylight saving time schedule, the schedule can be described with a set of rules, start-rule and end-rule. A day when daylight saving time starts or ends is specified by a combination of month, day-of-month, and day-of-week values. The month value is represented by a Calendar MONTH field value, such as Calendar.MARCH. The day-of-week value is represented by a Calendar DAY_OF_WEEK value, such as SUNDAY. The meanings of value combinations are as follows.

Exact day of month
To specify an exact day of month, set the month and day-of-month to an exact value, and day-of-week to zero. For example, to specify March 1, set the month to MARCH, day-of-month to 1, and day-of-week to 0.
Day of week on or after day of month
To specify a day of week on or after an exact day of month, set the month to an exact month value, day-of-month to the day on or after which the rule is applied, and day-of-week to a negative DAY_OF_WEEK field value. For example, to specify the second Sunday of April, set month to APRIL, day-of-month to 8, and day-of-week to -SUNDAY.
Day of week on or before day of month
To specify a day of the week on or before an exact day of the month, set day-of-month and day-of-week to a negative value. For example, to specify the last Wednesday on or before the 21st of March, set month to MARCH, day-of-month is -21 and day-of-week is -WEDNESDAY.
Last day-of-week of month
To specify, the last day-of-week of the month, set day-of-week to a DAY_OF_WEEK value and day-of-month to -1. For example, to specify the last Sunday of October, set month to OCTOBER, day-of-week to SUNDAY and day-of-month to -1.

The time of the day at which daylight saving time starts or ends is specified by a millisecond value within the day. There are three kinds of modes to specify the time: SimpleTimeZone.WALL_TIME, SimpleTimeZone.STANDARD_TIME and SimpleTimeZone.UTC_TIME. For example, if daylight saving time ends at 2:00 am in the wall clock time, it can be specified by 7200000 milliseconds in the SimpleTimeZone.WALL_TIME mode. In this case, the wall clock time for an end-rule means the same thing as the daylight time.

The following are examples of parameters for constructing time zone objects.


      // Base GMT offset: -8:00
      // DST starts:      at 2:00am in standard time
      //                  on the first Sunday in April
      // DST ends:        at 2:00am in daylight time
      //                  on the last Sunday in October
      // Save:            1 hour
      SimpleTimeZone(-28800000,
                     "America/Los_Angeles",
                     Calendar.APRIL, 1, -Calendar.SUNDAY,
                     7200000,
                     Calendar.OCTOBER, -1, Calendar.SUNDAY,
                     7200000,
                     3600000)

      // Base GMT offset: +1:00
      // DST starts:      at 1:00am in UTC time
      //                  on the last Sunday in March
      // DST ends:        at 1:00am in UTC time
      //                  on the last Sunday in October
      // Save:            1 hour
      SimpleTimeZone(3600000,
                     "Europe/Paris",
                     Calendar.MARCH, -1, Calendar.SUNDAY,
                     3600000, SimpleTimeZone.UTC_TIME,
                     Calendar.OCTOBER, -1, Calendar.SUNDAY,
                     3600000, SimpleTimeZone.UTC_TIME,
                     3600000)

These parameter rules are also applicable to the set rule methods, such as setStartRule.

See also: Calendar GregorianCalendar TimeZone

Constructors

public SimpleTimeZone (int rawOffset, String ID)

Constructs a SimpleTimeZone with the given base time zone offset from GMT and time zone ID with no daylight saving time schedule.

public SimpleTimeZone (int rawOffset, String ID, int startMonth, int startDay, int startDayOfWeek, int startTime, int endMonth, int endDay, int endDayOfWeek, int endTime)

Constructs a SimpleTimeZone with the given base time zone offset from GMT, time zone ID, and rules for starting and ending the daylight time.

Constructs a SimpleTimeZone with the given base time zone offset from
GMT, time zone ID, and rules for starting and ending the daylight
time.
Both startTime and endTime are specified to be
represented in the wall clock time. The amount of daylight saving is
assumed to be 3600000 milliseconds (i.e., one hour). This constructor is
equivalent to:


     SimpleTimeZone(rawOffset,
                    ID,
                    startMonth,
                    startDay,
                    startDayOfWeek,
                    startTime,
                    SimpleTimeZone.SimpleTimeZone.WALL_TIME,
                    endMonth,
                    endDay,
                    endDayOfWeek,
                    endTime,
                    SimpleTimeZone.SimpleTimeZone.WALL_TIME,
                    3600000)

Parameters:
- rawOffset - The given base time zone offset from GMT.
- ID - The time zone ID which is given to this object.
- startMonth - The daylight saving time starting month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 0 for January).
- startDay - The day of the month on which the daylight saving time starts. See the class description for the special cases of this parameter.
- startDayOfWeek - The daylight saving time starting day-of-week. See the class description for the special cases of this parameter.
- startTime - The daylight saving time starting time in local wall clock time (in milliseconds within the day), which is local standard time in this case.
- endMonth - The daylight saving time ending month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 9 for October).
- endDay - The day of the month on which the daylight saving time ends. See the class description for the special cases of this parameter.
- endDayOfWeek - The daylight saving time ending day-of-week. See the class description for the special cases of this parameter.
- endTime - The daylight saving ending time in local wall clock time, (in milliseconds within the day) which is local daylight time in this case.
Throws:
- IllegalArgumentException - if the month, day, dayOfWeek, or time parameters are out of range for the start or end rule

public SimpleTimeZone (int rawOffset, String ID, int startMonth, int startDay, int startDayOfWeek, int startTime, int endMonth, int endDay, int endDayOfWeek, int endTime, int dstSavings)

Constructs a SimpleTimeZone with the given base time zone offset from GMT, time zone ID, and rules for starting and ending the daylight time.

Constructs a SimpleTimeZone with the given base time zone offset from
GMT, time zone ID, and rules for starting and ending the daylight
time.
Both startTime and endTime are assumed to be
represented in the wall clock time. This constructor is equivalent to:


     SimpleTimeZone(rawOffset,
                    ID,
                    startMonth,
                    startDay,
                    startDayOfWeek,
                    startTime,
                    SimpleTimeZone.SimpleTimeZone.WALL_TIME,
                    endMonth,
                    endDay,
                    endDayOfWeek,
                    endTime,
                    SimpleTimeZone.SimpleTimeZone.WALL_TIME,
                    dstSavings)

Parameters:
- rawOffset - The given base time zone offset from GMT.
- ID - The time zone ID which is given to this object.
- startMonth - The daylight saving time starting month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 0 for January).
- startDay - The day of the month on which the daylight saving time starts. See the class description for the special cases of this parameter.
- startDayOfWeek - The daylight saving time starting day-of-week. See the class description for the special cases of this parameter.
- startTime - The daylight saving time starting time in local wall clock time, which is local standard time in this case.
- endMonth - The daylight saving time ending month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 9 for October).
- endDay - The day of the month on which the daylight saving time ends. See the class description for the special cases of this parameter.
- endDayOfWeek - The daylight saving time ending day-of-week. See the class description for the special cases of this parameter.
- endTime - The daylight saving ending time in local wall clock time, which is local daylight time in this case.
- dstSavings - The amount of time in milliseconds saved during daylight saving time.
Throws:
- IllegalArgumentException - if the month, day, dayOfWeek, or time parameters are out of range for the start or end rule
Since: 1.2

public SimpleTimeZone (int rawOffset, String ID, int startMonth, int startDay, int startDayOfWeek, int startTime, int startTimeMode, int endMonth, int endDay, int endDayOfWeek, int endTime, int endTimeMode, int dstSavings)

Constructs a SimpleTimeZone with the given base time zone offset from GMT, time zone ID, and rules for starting and ending the daylight time.

Constructs a SimpleTimeZone with the given base time zone offset from
GMT, time zone ID, and rules for starting and ending the daylight
time.
This constructor takes the full set of the start and end rules
parameters, including modes of startTime and
endTime. The mode specifies either

wall
 time

or standard time or

UTC
 time

.
Parameters:
- rawOffset - The given base time zone offset from GMT.
- ID - The time zone ID which is given to this object.
- startMonth - The daylight saving time starting month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 0 for January).
- startDay - The day of the month on which the daylight saving time starts. See the class description for the special cases of this parameter.
- startDayOfWeek - The daylight saving time starting day-of-week. See the class description for the special cases of this parameter.
- startTime - The daylight saving time starting time in the time mode specified by startTimeMode.
- startTimeMode - The mode of the start time specified by startTime.
- endMonth - The daylight saving time ending month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 9 for October).
- endDay - The day of the month on which the daylight saving time ends. See the class description for the special cases of this parameter.
- endDayOfWeek - The daylight saving time ending day-of-week. See the class description for the special cases of this parameter.
- endTime - The daylight saving ending time in time time mode specified by endTimeMode.
- endTimeMode - The mode of the end time specified by endTime
- dstSavings - The amount of time in milliseconds saved during daylight saving time.
Throws:
- IllegalArgumentException - if the month, day, dayOfWeek, time more, or time parameters are out of range for the start or end rule, or if a time mode value is invalid.
Since: 1.4
See Also: SimpleTimeZone.WALL_TIME, SimpleTimeZone.STANDARD_TIME, SimpleTimeZone.UTC_TIME,

Methods

Hide/Show inherited methods

public Object clone () [Overrides TimeZone]

Returns a clone of this SimpleTimeZone instance.

Returns a clone of this SimpleTimeZone instance.
Returns: a clone of this instance.

public boolean equals (Object obj)

Compares the equality of two SimpleTimeZone objects.

Compares the equality of two SimpleTimeZone objects.
Returns: True if the given obj is the same as this SimpleTimeZone object; false otherwise.
Parameters:
- obj - The SimpleTimeZone object to be compared with.

publicstaticsynchronized String getAvailableIDs () [Inherited From TimeZone]

Gets all the available IDs supported.

publicstaticsynchronized String getAvailableIDs (int rawOffset) [Inherited From TimeZone]

Gets the available IDs according to the given time zone offset in milliseconds.

publicstatic TimeZone getDefault () [Inherited From TimeZone]

Gets the default TimeZone for this host.

Gets the default TimeZone for this host.
The source of the default TimeZone
may vary with implementation.
Returns: a default TimeZone.
See Also: TimeZone.setDefault(java.util.TimeZone),

pack-privatestatic TimeZone getDefaultRef () [Inherited From TimeZone]

Returns the reference to the default TimeZone object.

publicfinal String getDisplayName () [Inherited From TimeZone]

Returns a name of this time zone suitable for presentation to the user in the default locale.

publicfinal String getDisplayName (boolean daylight, int style) [Inherited From TimeZone]

Returns a name of this time zone suitable for presentation to the user in the default locale.

Returns a name of this time zone suitable for presentation to the user
in the default locale.
If the display name is not available for the locale, then this
method returns a string in the
normalized custom ID format.
Returns: the human-readable name of this time zone in the default locale.
Parameters:
- daylight - if true, return the daylight savings name.
- style - either LONG or SHORT
Since: 1.2

public String getDisplayName (boolean daylight, int style, Locale locale) [Inherited From TimeZone]

Returns a name of this time zone suitable for presentation to the user in the specified locale.

Returns a name of this time zone suitable for presentation to the user
in the specified locale.
If the display name is not available for the locale,
then this method returns a string in the
normalized custom ID format.
Returns: the human-readable name of this time zone in the given locale.
Parameters:
- daylight - if true, return the daylight savings name.
- style - either LONG or SHORT
- locale - the locale in which to supply the display name.
Throws:
- IllegalArgumentException - style is invalid.
Since: 1.2

publicfinal String getDisplayName (Locale locale) [Inherited From TimeZone]

Returns a name of this time zone suitable for presentation to the user in the specified locale.

public int getDSTSavings () [Overrides TimeZone]

Returns the amount of time in milliseconds that the clock is advanced during daylight saving time.

public String getID () [Inherited From TimeZone]

Gets the ID of this time zone.

public int getOffset (int era, int year, int month, int day, int dayOfWeek, int millis) [Specified in TimeZone]

Returns the difference in milliseconds between local time and UTC, taking into account both the raw offset and the effect of daylight saving, for the specified date and time.

Returns the difference in milliseconds between local time and UTC, taking into account both the raw offset and the effect of daylight saving, for the specified date and time. This method assumes that the start and end month are distinct. It also uses a default GregorianCalendar object as its underlying calendar, such as for determining leap years. Do not use the result of this method with a calendar other than a default GregorianCalendar.

Note: In general, clients should use Calendar.get(ZONE_OFFSET) + Calendar.get(DST_OFFSET) instead of calling this method.
Returns: The milliseconds to add to UTC to get local time.
Parameters:
- era - The era of the given date.
- 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.
Throws:
- IllegalArgumentException - the era, month, day, dayOfWeek, or millis parameters are out of range

public int getOffset (long date) [Overrides TimeZone]

Returns the offset of this time zone from UTC at the given time.

pack-private int getOffsets (long date, int[] offsets) [Overrides TimeZone]

public int getRawOffset () [Specified in TimeZone]

Gets the GMT offset for this time zone.

publicstaticsynchronized TimeZone getTimeZone (String ID) [Inherited From TimeZone]

Gets the TimeZone for the given ID.

Gets the TimeZone for the given ID.
Returns: the specified TimeZone, or the GMT zone if the given ID cannot be understood.
Parameters:
- ID - the ID for a TimeZone, either an abbreviation such as "PST", a full name such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". Note that the support of abbreviations is for JDK 1.1.x compatibility only and full names should be used.

publicsynchronized int hashCode ()

Generates the hash code for the SimpleDateFormat object.

public boolean hasSameRules (TimeZone other) [Overrides TimeZone]

Returns true if this zone has the same rules and offset as another zone.

Returns true if this zone has the same rules and offset as another zone.
Returns: true if the given zone is a SimpleTimeZone and has the same rules and offset as this one
Parameters:
- other - the TimeZone object to be compared with
Since: 1.2

public boolean inDaylightTime (Date date) [Specified in TimeZone]

Queries if the given date is in daylight saving time.

publicstatic void setDefault (TimeZone zone) [Inherited From TimeZone]

Sets the TimeZone that is returned by the getDefault method.

Sets the TimeZone that is
returned by the getDefault method. If zone
is null, reset the default to the value it had originally when the
VM first started.
Parameters:
- zone - the new default time zone
See Also: TimeZone.getDefault(),

public void setDSTSavings (int millisSavedDuringDST)

Sets the amount of time in milliseconds that the clock is advanced during daylight saving time.

public void setEndRule (int endMonth, int endDay, int endTime)

Sets the daylight saving time end rule to a fixed date within a month.

Sets the daylight saving time end rule to a fixed date within a month.
This method is equivalent to:

setEndRule(endMonth, endDay, 0, endTime)

Parameters:
- endMonth - The daylight saving time ending month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 9 for October).
- endDay - The day of the month on which the daylight saving time ends.
- endTime - The daylight saving ending time in local wall clock time, (in milliseconds within the day) which is local daylight time in this case.
Throws:
- IllegalArgumentException - the endMonth, endDay, or endTime parameters are out of range
Since: 1.2

public void setEndRule (int endMonth, int endDay, int endDayOfWeek, int endTime)

Sets the daylight saving time end rule.

Sets the daylight saving time end rule. For example, if daylight saving time
ends on the last Sunday in October at 2 am in wall clock time,
you can set the end rule by calling:
setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2*60*60*1000);
Parameters:
- endMonth - The daylight saving time ending month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 9 for October).
- endDay - The day of the month on which the daylight saving time ends. See the class description for the special cases of this parameter.
- endDayOfWeek - The daylight saving time ending day-of-week. See the class description for the special cases of this parameter.
- endTime - The daylight saving ending time in local wall clock time, (in milliseconds within the day) which is local daylight time in this case.
Throws:
- IllegalArgumentException - if the endMonth, endDay, endDayOfWeek, or endTime parameters are out of range

public void setEndRule (int endMonth, int endDay, int endDayOfWeek, int endTime, boolean after)

Sets the daylight saving time end rule to a weekday before or after the given date within a month, e.g., the first Monday on or after the 8th.

Sets the daylight saving time end rule to a weekday before or after the given date within
a month, e.g., the first Monday on or after the 8th.
Parameters:
- endMonth - The daylight saving time ending month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 9 for October).
- endDay - The day of the month on which the daylight saving time ends.
- endDayOfWeek - The daylight saving time ending day-of-week.
- endTime - The daylight saving ending time in local wall clock time, (in milliseconds within the day) which is local daylight time in this case.
- after - If true, this rule selects the first endDayOfWeek on or after endDay. If false, this rule selects the last endDayOfWeek on or before endDay of the month.
Throws:
- IllegalArgumentException - the endMonth, endDay, endDayOfWeek, or endTime parameters are out of range
Since: 1.2

public void setID (String ID) [Inherited From TimeZone]

Sets the time zone ID.

public void setRawOffset (int offsetMillis) [Specified in TimeZone]

Sets the base time zone offset to GMT.

public void setStartRule (int startMonth, int startDay, int startTime)

Sets the daylight saving time start rule to a fixed date within a month.

Sets the daylight saving time start rule to a fixed date within a month.
This method is equivalent to:

setStartRule(startMonth, startDay, 0, startTime)

Parameters:
- startMonth - The daylight saving time starting month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 0 for January).
- startDay - The day of the month on which the daylight saving time starts.
- startTime - The daylight saving time starting time in local wall clock time, which is local standard time in this case. See the class description for the special cases of this parameter.
Throws:
- IllegalArgumentException - if the startMonth, startDayOfMonth, or startTime parameters are out of range
Since: 1.2

public void setStartRule (int startMonth, int startDay, int startDayOfWeek, int startTime)

Sets the daylight saving time start rule.

Sets the daylight saving time start rule. For example, if daylight saving
time starts on the first Sunday in April at 2 am in local wall clock
time, you can set the start rule by calling:

setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2*60*60*1000);

Parameters:
- startMonth - The daylight saving time starting month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 0 for January).
- startDay - The day of the month on which the daylight saving time starts. See the class description for the special cases of this parameter.
- startDayOfWeek - The daylight saving time starting day-of-week. See the class description for the special cases of this parameter.
- startTime - The daylight saving time starting time in local wall clock time, which is local standard time in this case.
Throws:
- IllegalArgumentException - if the startMonth, startDay, startDayOfWeek, or startTime parameters are out of range

public void setStartRule (int startMonth, int startDay, int startDayOfWeek, int startTime, boolean after)

Sets the daylight saving time start rule to a weekday before or after the given date within a month, e.g., the first Monday on or after the 8th.

Sets the daylight saving time start rule to a weekday before or after the given date within
a month, e.g., the first Monday on or after the 8th.
Parameters:
- startMonth - The daylight saving time starting month. Month is a {@link Calendar#MONTH MONTH} field value (0-based. e.g., 0 for January).
- startDay - The day of the month on which the daylight saving time starts.
- startDayOfWeek - The daylight saving time starting day-of-week.
- startTime - The daylight saving time starting time in local wall clock time, which is local standard time in this case.
- after - If true, this rule selects the first dayOfWeek on or after dayOfMonth. If false, this rule selects the last dayOfWeek on or before dayOfMonth.
Throws:
- IllegalArgumentException - if the startMonth, startDay, startDayOfWeek, or startTime parameters are out of range
Since: 1.2

public void setStartYear (int year)

Sets the daylight saving time starting year.

public String toString ()

Returns a string representation of this time zone.

public boolean useDaylightTime () [Specified in TimeZone]

Queries if this time zone uses daylight saving time.