Module java.base
Package java.util

Class SimpleTimeZone

  • All Implemented Interfaces:
    Serializable,Cloneable
    public classSimpleTimeZoneextendsTimeZone
    SimpleTimeZone is a concrete subclass ofTimeZone that represents a time zone for use with a Gregorian calendar. The class holds an offset from GMT, calledraw 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 thesetStartYear method can specify the year when the daylight saving time schedule starts in effect.

    To construct aSimpleTimeZone with a daylight saving time schedule, the schedule can be described with a set of rules,start-rule andend-rule. A day when daylight saving time starts or ends is specified by a combination ofmonth,day-of-month, andday-of-week values. Themonth value is represented by a CalendarMONTH field value, such asCalendar.MARCH. Theday-of-week value is represented by a CalendarDAY_OF_WEEK value, such asSUNDAY. The meanings of value combinations are as follows.

    • Exact day of month
      To specify an exact day of month, set themonth andday-of-month to an exact value, andday-of-week to zero. For example, to specify March 1, set themonth toMARCH,day-of-month to 1, andday-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 themonth to an exact month value,day-of-month to the day on or after which the rule is applied, andday-of-week to a negativeDAY_OF_WEEK field value. For example, to specify the second Sunday of April, setmonth toAPRIL,day-of-month to 8, andday-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, setday-of-month andday-of-week to a negative value. For example, to specify the last Wednesday on or before the 21st of March, setmonth toMARCH,day-of-month is -21 andday-of-week is-WEDNESDAY.
    • Last day-of-week of month
      To specify, the last day-of-week of the month, setday-of-week to aDAY_OF_WEEK value andday-of-month to -1. For example, to specify the last Sunday of October, setmonth toOCTOBER,day-of-week toSUNDAY andday-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 ofmodes to specify the time:WALL_TIME,STANDARD_TIME andUTC_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 theWALL_TIME mode. In this case, the wall clock time for anend-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 assetStartRule.

    Since:
    1.1
    See Also:
    Calendar,GregorianCalendar,TimeZone,Serialized Form

    • Field Summary

      Fields 
      Modifier and TypeFieldDescription
      static intSTANDARD_TIME
      Constant for a mode of start or end time specified as standard time.
      static intUTC_TIME
      Constant for a mode of start or end time specified as UTC.
      static intWALL_TIME
      Constant for a mode of start or end time specified as wall clock time.

    • Constructor Summary

      Constructors 
      ConstructorDescription
      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.
      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.
      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.
      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.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and TypeMethodDescription
      Objectclone()
      Returns a clone of thisSimpleTimeZone instance.
      booleanequals​(Object obj)
      Compares the equality of twoSimpleTimeZone objects.
      intgetDSTSavings()
      Returns the amount of time in milliseconds that the clock is advanced during daylight saving time.
      intgetOffset​(int era, int year, int month, int day, int dayOfWeek, int millis)
      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.
      intgetOffset​(long date)
      Returns the offset of this time zone from UTC at the given time.
      intgetRawOffset()
      Gets the GMT offset for this time zone.
      inthashCode()
      Generates the hash code for the SimpleDateFormat object.
      booleanhasSameRules​(TimeZone other)
      Returnstrue if this zone has the same rules and offset as another zone.
      booleaninDaylightTime​(Date date)
      Queries if the given date is in daylight saving time.
      booleanobservesDaylightTime()
      Returnstrue if thisSimpleTimeZone observes Daylight Saving Time.
      voidsetDSTSavings​(int millisSavedDuringDST)
      Sets the amount of time in milliseconds that the clock is advanced during daylight saving time.
      voidsetEndRule​(int endMonth, int endDay, int endTime)
      Sets the daylight saving time end rule to a fixed date within a month.
      voidsetEndRule​(int endMonth, int endDay, int endDayOfWeek, int endTime)
      Sets the daylight saving time end rule.
      voidsetEndRule​(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.
      voidsetRawOffset​(int offsetMillis)
      Sets the base time zone offset to GMT.
      voidsetStartRule​(int startMonth, int startDay, int startTime)
      Sets the daylight saving time start rule to a fixed date within a month.
      voidsetStartRule​(int startMonth, int startDay, int startDayOfWeek, int startTime)
      Sets the daylight saving time start rule.
      voidsetStartRule​(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.
      voidsetStartYear​(int year)
      Sets the daylight saving time starting year.
      StringtoString()
      Returns a string representation of this time zone.
      booleanuseDaylightTime()
      Queries if this time zone uses daylight saving time.

    • Field Detail

      • WALL_TIME

        public static final int WALL_TIME
        Constant for a mode of start or end time specified as wall clock time. Wall clock time is standard time for the onset rule, and daylight time for the end rule.
        Since:
        1.4
        See Also:
        Constant Field Values

      • STANDARD_TIME

        public static final int STANDARD_TIME
        Constant for a mode of start or end time specified as standard time.
        Since:
        1.4
        See Also:
        Constant Field Values

      • UTC_TIME

        public static final int UTC_TIME
        Constant for a mode of start or end time specified as UTC. European Union rules are specified as UTC time, for example.
        Since:
        1.4
        See Also:
        Constant Field Values

    • Constructor Detail

      • SimpleTimeZone

        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.
        Parameters:
        rawOffset - The base time zone offset in milliseconds to GMT.
        ID - The time zone name that is given to this instance.

      • SimpleTimeZone

        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. BothstartTime andendTime 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.WALL_TIME,                    endMonth,                    endDay,                    endDayOfWeek,                    endTime,                    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 aMONTH 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 aMONTH 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

      • SimpleTimeZone

        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. BothstartTime andendTime are assumed to be represented in the wall clock time. This constructor is equivalent to:
             SimpleTimeZone(rawOffset,                    ID,                    startMonth,                    startDay,                    startDayOfWeek,                    startTime,                    SimpleTimeZone.WALL_TIME,                    endMonth,                    endDay,                    endDayOfWeek,                    endTime,                    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 aMONTH 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 aMONTH 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

      • SimpleTimeZone

        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. This constructor takes the full set of the start and end rules parameters, including modes ofstartTime andendTime. The mode specifies eitherwall time orstandard time orUTC 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 aMONTH 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 bystartTimeMode.
        startTimeMode - The mode of the start time specified by startTime.
        endMonth - The daylight saving time ending month. Month is aMONTH 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 byendTimeMode.
        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:
        WALL_TIME,STANDARD_TIME,UTC_TIME

    • Method Detail

      • setStartYear

        public void setStartYear​(int year)
        Sets the daylight saving time starting year.
        Parameters:
        year - The daylight saving starting year.

      • setStartRule

        public void setStartRule​(int startMonth,                         int startDay,                         int startDayOfWeek,                         int startTime)
        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 aMONTH 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 thestartMonth,startDay,startDayOfWeek, orstartTime parameters are out of range

      • setStartRule

        public void setStartRule​(int startMonth,                         int startDay,                         int startTime)
        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 aMONTH 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 thestartMonth,startDayOfMonth, orstartTime parameters are out of range
        Since:
        1.2

      • setStartRule

        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.
        Parameters:
        startMonth - The daylight saving time starting month. Month is aMONTH 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 firstdayOfWeek on orafterdayOfMonth. If false, this rule selects the lastdayOfWeek on orbeforedayOfMonth.
        Throws:
        IllegalArgumentException - if thestartMonth,startDay,startDayOfWeek, orstartTime parameters are out of range
        Since:
        1.2

      • setEndRule

        public void setEndRule​(int endMonth,                       int endDay,                       int endDayOfWeek,                       int endTime)
        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 aMONTH 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 theendMonth,endDay,endDayOfWeek, orendTime parameters are out of range

      • setEndRule

        public void setEndRule​(int endMonth,                       int endDay,                       int endTime)
        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 aMONTH 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 - theendMonth,endDay, orendTime parameters are out of range
        Since:
        1.2

      • setEndRule

        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.
        Parameters:
        endMonth - The daylight saving time ending month. Month is aMONTH 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 firstendDayOfWeek on orafterendDay. If false, this rule selects the lastendDayOfWeek on or beforeendDay of the month.
        Throws:
        IllegalArgumentException - theendMonth,endDay,endDayOfWeek, orendTime parameters are out of range
        Since:
        1.2

      • getOffset

        public int getOffset​(long date)
        Returns the offset of this time zone from UTC at the given time. If daylight saving time is in effect at the given time, the offset value is adjusted with the amount of daylight saving.
        Overrides:
        getOffset in class TimeZone
        Parameters:
        date - the time at which the time zone offset is found
        Returns:
        the amount of time in milliseconds to add to UTC to get local time.
        Since:
        1.4
        See Also:
        Calendar.ZONE_OFFSET,Calendar.DST_OFFSET

      • getOffset

        public int getOffset​(int era,                     int year,                     int month,                     int day,                     int dayOfWeek,                     int millis)
        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 defaultGregorianCalendar 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 defaultGregorianCalendar.

        Note: In general, clients should useCalendar.get(ZONE_OFFSET) + Calendar.get(DST_OFFSET) instead of calling this method.

        Specified by:
        getOffset in class TimeZone
        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 instandard local time.
        Returns:
        The milliseconds to add to UTC to get local time.
        Throws:
        IllegalArgumentException - theera,month,day,dayOfWeek, ormillis parameters are out of range
        See Also:
        Calendar.ZONE_OFFSET,Calendar.DST_OFFSET

      • getRawOffset

        public int getRawOffset()
        Gets the GMT offset for this time zone.
        Specified by:
        getRawOffset in class TimeZone
        Returns:
        the GMT offset value in milliseconds
        See Also:
        setRawOffset(int)

      • setRawOffset

        public void setRawOffset​(int offsetMillis)
        Sets the base time zone offset to GMT. This is the offset to add to UTC to get local time.
        Specified by:
        setRawOffset in class TimeZone
        Parameters:
        offsetMillis - the given base time zone offset to GMT.
        See Also:
        getRawOffset()

      • setDSTSavings

        public void setDSTSavings​(int millisSavedDuringDST)
        Sets the amount of time in milliseconds that the clock is advanced during daylight saving time.
        Parameters:
        millisSavedDuringDST - the number of milliseconds the time is advanced with respect to standard time when the daylight saving time rules are in effect. A positive number, typically one hour (3600000).
        Since:
        1.2
        See Also:
        getDSTSavings()

      • getDSTSavings

        public int getDSTSavings()
        Returns the amount of time in milliseconds that the clock is advanced during daylight saving time.
        Overrides:
        getDSTSavings in class TimeZone
        Returns:
        the number of milliseconds the time is advanced with respect to standard time when the daylight saving rules are in effect, or 0 (zero) if this time zone doesn't observe daylight saving time.
        Since:
        1.2
        See Also:
        setDSTSavings(int)

      • inDaylightTime

        public boolean inDaylightTime​(Date date)
        Queries if the given date is in daylight saving time.
        Specified by:
        inDaylightTime in class TimeZone
        Parameters:
        date - the given Date.
        Returns:
        true if daylight saving time is in effective at the given date; false otherwise.

      • clone

        public Object clone()
        Returns a clone of thisSimpleTimeZone instance.
        Overrides:
        clone in class TimeZone
        Returns:
        a clone of this instance.
        See Also:
        Cloneable

      • equals

        public boolean equals​(Object obj)
        Compares the equality of twoSimpleTimeZone objects.
        Overrides:
        equals in class Object
        Parameters:
        obj - TheSimpleTimeZone object to be compared with.
        Returns:
        True if the givenobj is the same as thisSimpleTimeZone object; false otherwise.
        See Also:
        Object.hashCode(),HashMap

      • hasSameRules

        public boolean hasSameRules​(TimeZone other)
        Returnstrue if this zone has the same rules and offset as another zone.
        Overrides:
        hasSameRules in class TimeZone
        Parameters:
        other - the TimeZone object to be compared with
        Returns:
        true if the given zone is a SimpleTimeZone and has the same rules and offset as this one
        Since:
        1.2

      • toString

        public String toString()
        Returns a string representation of this time zone.
        Overrides:
        toString in class Object
        Returns:
        a string representation of this time zone.