java.util
Class SimpleTimeZone

java.lang.Object
  extended by java.util.TimeZone
      extended by java.util.SimpleTimeZone
All Implemented Interfaces:
Serializable, Cloneable

public class SimpleTimeZone
extends TimeZone

This class represents a simple time zone offset and handles daylight savings. It can only handle one daylight savings rule, so it can't represent historical changes. This object is tightly bound to the Gregorian calendar. It assumes a regular seven days week, and the month lengths are that of the Gregorian Calendar. It can only handle daylight savings for years lying in the AD era.

See Also:
Calendar, GregorianCalendar, Serialized Form

Field Summary
static int STANDARD_TIME
          Constant to indicate that start and end times are specified in standard time, without adjusting for daylight savings.
static int UTC_TIME
          Constant to indicate that start and end times are specified in UTC.
static int WALL_TIME
          Constant to indicate that start and end times are specified in wall time, adjusting for daylight savings.
 
Fields inherited from class java.util.TimeZone
LONG, SHORT
 
Constructor Summary
SimpleTimeZone(int rawOffset, String id)
          Create a SimpleTimeZone with the given time offset from GMT and without daylight savings.
SimpleTimeZone(int rawOffset, String id, int startMonth, int startDayOfWeekInMonth, int startDayOfWeek, int startTime, int endMonth, int endDayOfWeekInMonth, int endDayOfWeek, int endTime)
          Create a SimpleTimeZone with the given time offset from GMT and with daylight savings.
SimpleTimeZone(int rawOffset, String id, int startMonth, int startDayOfWeekInMonth, int startDayOfWeek, int startTime, int endMonth, int endDayOfWeekInMonth, int endDayOfWeek, int endTime, int dstSavings)
          This constructs a new SimpleTimeZone that supports a daylight savings rule.
SimpleTimeZone(int rawOffset, String id, int startMonth, int startDayOfWeekInMonth, int startDayOfWeek, int startTime, int startTimeMode, int endMonth, int endDayOfWeekInMonth, int endDayOfWeek, int endTime, int endTimeMode, int dstSavings)
          This constructs a new SimpleTimeZone that supports a daylight savings rule.
 
Method Summary
 boolean equals(Object o)
          Determine whether this Object is semantically equal to another Object.
 int getDSTSavings()
          Gets the daylight savings offset.
 int getOffset(int era, int year, int month, int day, int dayOfWeek, int millis)
          Gets the time zone offset, for current date, modified in case of daylight savings.
 int getRawOffset()
          Returns the time zone offset to GMT in milliseconds, ignoring day light savings.
 int hashCode()
          Generates the hashCode for the SimpleDateFormat object.
 boolean hasSameRules(TimeZone other)
          Test if the other time zone uses the same rule and only possibly differs in ID.
 boolean inDaylightTime(Date date)
          Determines if the given date is in daylight savings time.
 void setDSTSavings(int dstSavings)
          Sets the daylight savings offset.
 void setEndRule(int month, int day, int time)
          Sets the daylight savings end rule.
 void setEndRule(int month, int day, int dayOfWeek, int time)
          Sets the daylight savings end rule.
 void setEndRule(int month, int day, int dayOfWeek, int time, boolean after)
          Sets the daylight savings end rule.
 void setRawOffset(int rawOffset)
          Sets the standard time zone offset to GMT.
 void setStartRule(int month, int day, int time)
          Sets the daylight savings start rule.
 void setStartRule(int month, int day, int dayOfWeek, int time)
          Sets the daylight savings start rule.
 void setStartRule(int month, int day, int dayOfWeek, int time, boolean after)
          Sets the daylight savings start rule.
 void setStartYear(int year)
          Sets the first year, where daylight savings applies.
 String toString()
          Returns a string representation of this SimpleTimeZone object.
 boolean useDaylightTime()
          Returns if this time zone uses daylight savings time.
 
Methods inherited from class java.util.TimeZone
clone, getAvailableIDs, getAvailableIDs, getDefault, getDisplayName, getDisplayName, getDisplayName, getDisplayName, getID, getOffset, getTimeZone, setDefault, setID
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

STANDARD_TIME

public static final int STANDARD_TIME
Constant to indicate that start and end times are specified in standard time, without adjusting for daylight savings.

See Also:
Constant Field Values

WALL_TIME

public static final int WALL_TIME
Constant to indicate that start and end times are specified in wall time, adjusting for daylight savings. This is the default.

See Also:
Constant Field Values

UTC_TIME

public static final int UTC_TIME
Constant to indicate that start and end times are specified in UTC.

See Also:
Constant Field Values
Constructor Detail

SimpleTimeZone

public SimpleTimeZone(int rawOffset,
                      String id)
Create a SimpleTimeZone with the given time offset from GMT and without daylight savings.

Parameters:
rawOffset - the time offset from GMT in milliseconds.
id - The identifier of this time zone.

SimpleTimeZone

public SimpleTimeZone(int rawOffset,
                      String id,
                      int startMonth,
                      int startDayOfWeekInMonth,
                      int startDayOfWeek,
                      int startTime,
                      int endMonth,
                      int endDayOfWeekInMonth,
                      int endDayOfWeek,
                      int endTime)
Create a SimpleTimeZone with the given time offset from GMT and with daylight savings. The start/end parameters can have different meaning (replace WEEKDAY with a real day of week). Only the first two meanings were supported by earlier versions of jdk.
day > 0, dayOfWeek = Calendar.WEEKDAY
The start/end of daylight savings is on the day-th WEEKDAY in the given month.
day < 0, dayOfWeek = Calendar.WEEKDAY
The start/end of daylight savings is on the -day-th WEEKDAY counted from the end of the month.
day > 0, dayOfWeek = 0
The start/end of daylight is on the day-th day of the month.
day > 0, dayOfWeek = -Calendar.WEEKDAY
The start/end of daylight is on the first WEEKDAY on or after the day-th day of the month. You must make sure that this day lies in the same month.
day < 0, dayOfWeek = -Calendar.WEEKDAY
The start/end of daylight is on the first WEEKDAY on or before the -day-th day of the month. You must make sure that this day lies in the same month.
If you give a non existing month, a day that is zero, or too big, or a dayOfWeek that is too big, the result is undefined. The start rule must have a different month than the end rule. This restriction shouldn't hurt for all possible time zones.

Parameters:
rawOffset - The time offset from GMT in milliseconds.
id - The identifier of this time zone.
startMonth - The start month of daylight savings; use the constants in Calendar.
startDayOfWeekInMonth - A day in month or a day of week number, as described above.
startDayOfWeek - The start rule day of week; see above.
startTime - A time in millis in standard time.
endMonth - The end month of daylight savings; use the constants in Calendar.
endDayOfWeekInMonth - A day in month or a day of week number, as described above.
endDayOfWeek - The end rule day of week; see above.
endTime - A time in millis in standard time.
Throws:
IllegalArgumentException - if parameters are invalid or out of range.

SimpleTimeZone

public SimpleTimeZone(int rawOffset,
                      String id,
                      int startMonth,
                      int startDayOfWeekInMonth,
                      int startDayOfWeek,
                      int startTime,
                      int endMonth,
                      int endDayOfWeekInMonth,
                      int endDayOfWeek,
                      int endTime,
                      int dstSavings)
This constructs a new SimpleTimeZone that supports a daylight savings rule. The parameter are the same as for the constructor above, except there is the additional dstSavaings parameter.

Parameters:
dstSavings - the amount of savings for daylight savings time in milliseconds. This must be positive.
Since:
1.2

SimpleTimeZone

public SimpleTimeZone(int rawOffset,
                      String id,
                      int startMonth,
                      int startDayOfWeekInMonth,
                      int startDayOfWeek,
                      int startTime,
                      int startTimeMode,
                      int endMonth,
                      int endDayOfWeekInMonth,
                      int endDayOfWeek,
                      int endTime,
                      int endTimeMode,
                      int dstSavings)
This constructs a new SimpleTimeZone that supports a daylight savings rule. The parameter are the same as for the constructor above, except there are the additional startTimeMode, endTimeMode, and dstSavings parameters.

Parameters:
startTimeMode - the mode that start times are specified in. One of WALL_TIME, STANDARD_TIME, or UTC_TIME.
endTimeMode - the mode that end times are specified in. One of WALL_TIME, STANDARD_TIME, or UTC_TIME.
dstSavings - the amount of savings for daylight savings time in milliseconds. This must be positive.
Throws:
IllegalArgumentException - if parameters are invalid or out of range.
Since:
1.4
Method Detail

setStartYear

public void setStartYear(int year)
Sets the first year, where daylight savings applies. The daylight savings rule never apply for years in the BC era. Note that this is gregorian calendar specific.

Parameters:
year - the start year.

setStartRule

public void setStartRule(int month,
                         int day,
                         int dayOfWeek,
                         int time)
Sets the daylight savings start rule. You must also set the end rule with setEndRule or the result of getOffset is undefined. For the parameters see the ten-argument constructor above.

Parameters:
month - The month where daylight savings start, zero based. You should use the constants in Calendar.
day - A day of month or day of week in month.
dayOfWeek - The day of week where daylight savings start.
time - The time in milliseconds standard time where daylight savings start.
Throws:
IllegalArgumentException - if parameters are out of range.
See Also:
SimpleTimeZone

setStartRule

public void setStartRule(int month,
                         int day,
                         int dayOfWeek,
                         int time,
                         boolean after)
Sets the daylight savings start rule. You must also set the end rule with setEndRule or the result of getOffset is undefined. For the parameters see the ten-argument constructor above. Note that this API isn't incredibly well specified. It appears that the after flag must override the parameters, since normally, the day and dayofweek can select this. I.e., if day < 0 and dayOfWeek < 0, on or before mode is chosen. But if after == true, this implementation overrides the signs of the other arguments. And if dayOfWeek == 0, it falls back to the behavior in the other APIs. I guess this should be checked against Sun's implementation.

Parameters:
month - The month where daylight savings start, zero based. You should use the constants in Calendar.
day - A day of month or day of week in month.
dayOfWeek - The day of week where daylight savings start.
time - The time in milliseconds standard time where daylight savings start.
after - If true, day and dayOfWeek specify first day of week on or after day, else first day of week on or before.
Since:
1.2
See Also:
SimpleTimeZone

setStartRule

public void setStartRule(int month,
                         int day,
                         int time)
Sets the daylight savings start rule. You must also set the end rule with setEndRule or the result of getOffset is undefined. For the parameters see the ten-argument constructor above.

Parameters:
month - The month where daylight savings start, zero based. You should use the constants in Calendar.
day - A day of month or day of week in month.
time - The time in milliseconds standard time where daylight savings start.
Since:
1.2
See Also:
SimpleTimeZone

setEndRule

public void setEndRule(int month,
                       int day,
                       int dayOfWeek,
                       int time)
Sets the daylight savings end rule. You must also set the start rule with setStartRule or the result of getOffset is undefined. For the parameters see the ten-argument constructor above.

Parameters:
month - The end month of daylight savings.
day - A day in month, or a day of week in month.
dayOfWeek - A day of week, when daylight savings ends.
time - A time in millis in standard time.
See Also:
setStartRule(int, int, int, int)

setEndRule

public void setEndRule(int month,
                       int day,
                       int dayOfWeek,
                       int time,
                       boolean after)
Sets the daylight savings end rule. You must also set the start rule with setStartRule or the result of getOffset is undefined. For the parameters see the ten-argument constructor above. Note that this API isn't incredibly well specified. It appears that the after flag must override the parameters, since normally, the day and dayofweek can select this. I.e., if day < 0 and dayOfWeek < 0, on or before mode is chosen. But if after == true, this implementation overrides the signs of the other arguments. And if dayOfWeek == 0, it falls back to the behavior in the other APIs. I guess this should be checked against Sun's implementation.

Parameters:
month - The end month of daylight savings.
day - A day in month, or a day of week in month.
dayOfWeek - A day of week, when daylight savings ends.
time - A time in millis in standard time.
after - If true, day and dayOfWeek specify first day of week on or after day, else first day of week on or before.
Since:
1.2
See Also:
setStartRule(int, int, int, int, boolean)

setEndRule

public void setEndRule(int month,
                       int day,
                       int time)
Sets the daylight savings end rule. You must also set the start rule with setStartRule or the result of getOffset is undefined. For the parameters see the ten-argument constructor above.

Parameters:
month - The end month of daylight savings.
day - A day in month, or a day of week in month.
time - A time in millis in standard time.
See Also:
setStartRule(int, int, int)

getOffset

public int getOffset(int era,
                     int year,
                     int month,
                     int day,
                     int dayOfWeek,
                     int millis)
Gets the time zone offset, for current date, modified in case of daylight savings. This is the offset to add to UTC to get the local time. In the standard JDK the results given by this method may result in inaccurate results at the end of February or the beginning of March. To avoid this, you should use Calendar instead: offset = cal.get(Calendar.ZONE_OFFSET) + cal.get(Calendar.DST_OFFSET); This version doesn't suffer this inaccuracy. The arguments don't follow the approach for setting start and end rules. The day must be a positive number and dayOfWeek must be a positive value from Calendar. dayOfWeek is redundant, but must match the other values or an inaccurate result may be returned.

Specified by:
getOffset in class TimeZone
Parameters:
era - the era of the given date
year - the year of the given date
month - the month of the given date, 0 for January.
day - the day of month
dayOfWeek - the day of week; this must match the other fields.
millis - the millis in the day (in local standard time)
Returns:
the time zone offset in milliseconds.
Throws:
IllegalArgumentException - if arguments are incorrect.

getRawOffset

public int getRawOffset()
Returns the time zone offset to GMT in milliseconds, ignoring day light savings.

Specified by:
getRawOffset in class TimeZone
Returns:
the time zone offset.

setRawOffset

public void setRawOffset(int rawOffset)
Sets the standard time zone offset to GMT.

Specified by:
setRawOffset in class TimeZone
Parameters:
rawOffset - The time offset from GMT in milliseconds.

getDSTSavings

public int getDSTSavings()
Gets the daylight savings offset. This is a positive offset in milliseconds with respect to standard time. Typically this is one hour, but for some time zones this may be half an our.

Overrides:
getDSTSavings in class TimeZone
Returns:
the daylight savings offset in milliseconds.
Since:
1.2

setDSTSavings

public void setDSTSavings(int dstSavings)
Sets the daylight savings offset. This is a positive offset in milliseconds with respect to standard time.

Parameters:
dstSavings - the daylight savings offset in milliseconds.
Since:
1.2

useDaylightTime

public boolean useDaylightTime()
Returns if this time zone uses daylight savings time.

Specified by:
useDaylightTime in class TimeZone
Returns:
true, if we use daylight savings time, false otherwise.

inDaylightTime

public boolean inDaylightTime(Date date)
Determines if the given date is in daylight savings time.

Specified by:
inDaylightTime in class TimeZone
Parameters:
date - the given Date.
Returns:
true, if it is in daylight savings time, false otherwise.

hashCode

public int hashCode()
Generates the hashCode for the SimpleDateFormat object. It is the rawOffset, possibly, if useDaylightSavings is true, xored with startYear, startMonth, startDayOfWeekInMonth, ..., endTime.

Overrides:
hashCode in class Object
Returns:
the hash code for this Object
See Also:
Object.equals(Object), System.identityHashCode(Object)

equals

public boolean equals(Object o)
Description copied from class: Object
Determine whether this Object is semantically equal to another Object.

There are some fairly strict requirements on this method which subclasses must follow:

This is typically overridden to throw a ClassCastException if the argument is not comparable to the class performing the comparison, but that is not a requirement. It is legal for a.equals(b) to be true even though a.getClass() != b.getClass(). Also, it is typical to never cause a NullPointerException.

In general, the Collections API (java.util) use the equals method rather than the == operator to compare objects. However, IdentityHashMap is an exception to this rule, for its own good reasons.

The default implementation returns this == o.

Overrides:
equals in class Object
Parameters:
o - the Object to compare to
Returns:
whether this Object is semantically equal to another
See Also:
Object.hashCode()

hasSameRules

public boolean hasSameRules(TimeZone other)
Test if the other time zone uses the same rule and only possibly differs in ID. This implementation for this particular class will return true if the other object is a SimpleTimeZone, the raw offsets and useDaylight are identical and if useDaylight is true, also the start and end datas are identical.

Overrides:
hasSameRules in class TimeZone
Returns:
true if this zone uses the same rule.

toString

public String toString()
Returns a string representation of this SimpleTimeZone object.

Overrides:
toString in class Object
Returns:
a string representation of this SimpleTimeZone object.
See Also:
Object.getClass(), Object.hashCode(), Class.getName(), Integer.toHexString(int)