jars/icu4j-4_8_1_1/main/classes/core/src/com/ibm/icu/util/TimeZoneRule.java

   1 /*
   2  *******************************************************************************
   3  * Copyright (C) 2007-2010, International Business Machines Corporation and    *
   4  * others. All Rights Reserved.                                                *
   5  *******************************************************************************
   6  */
   7 package com.ibm.icu.util;
   8
   9 import java.io.Serializable;
  10 import java.util.Date;
  11
  12 /**
  13  * <code>TimeZoneRule</code> is an abstract class representing a rule for time zone.
  14  * <code>TimeZoneRule</code> has a set of time zone attributes, such as zone name,
  15  * raw offset (UTC offset for standard time) and daylight saving time offset.
  16  *
  17  * @see com.ibm.icu.util.TimeZoneTransition
  18  * @see com.ibm.icu.util.RuleBasedTimeZone
  19  *
  20  * @stable ICU 3.8
  21  */
  22 public abstract class TimeZoneRule implements Serializable {
  23
  24     private static final long serialVersionUID = 6374143828553768100L;
  25
  26     private final String name;
  27     private final int rawOffset;
  28     private final int dstSavings;
  29
  30     /**
  31      * Constructs a <code>TimeZoneRule</code> with the name, the GMT offset of its
  32      * standard time and the amount of daylight saving offset adjustment.
  33      *
  34      * @param name          The time zone name.
  35      * @param rawOffset     The UTC offset of its standard time in milliseconds.
  36      * @param dstSavings    The amount of daylight saving offset adjustment in milliseconds.
  37      *                      If this is a rule for standard time, the value of this argument is 0.
  38      *
  39      * @stable ICU 3.8
  40      */
  41     public TimeZoneRule(String name, int rawOffset, int dstSavings) {
  42         this.name = name;
  43         this.rawOffset = rawOffset;
  44         this.dstSavings = dstSavings;
  45     }
  46
  47     /**
  48      * Gets the name of this time zone.
  49      *
  50      * @return The name of this time zone.
  51      *
  52      * @stable ICU 3.8
  53      */
  54     public String getName() {
  55         return name;
  56     }
  57
  58     /**
  59      * Gets the standard time offset.
  60      *
  61      * @return The standard time offset from UTC in milliseconds.
  62      *
  63      * @stable ICU 3.8
  64      */
  65     public int getRawOffset() {
  66         return rawOffset;
  67     }
  68
  69     /**
  70      * Gets the amount of daylight saving delta time from the standard time.
  71      *
  72      * @return  The amount of daylight saving offset used by this rule
  73      *          in milliseconds.
  74      *
  75      * @stable ICU 3.8
  76      */
  77     public int getDSTSavings() {
  78         return dstSavings;
  79     }
  80
  81     /**
  82      * Returns if this rule represents the same rule and offsets as another.
  83      * When two <code>TimeZoneRule</code> objects differ only its names, this method returns
  84      * true.
  85      *
  86      * @param other The <code>TimeZoneRule</code> object to be compared with.
  87      * @return true if the other <code>TimeZoneRule</code> is the same as this one.
  88      *
  89      * @stable ICU 3.8
  90      */
  91     public boolean isEquivalentTo(TimeZoneRule other) {
  92         if (rawOffset == other.rawOffset && dstSavings == other.dstSavings) {
  93             return true;
  94         }
  95         return false;
  96     }
  97
  98     /**
  99      * Gets the very first time when this rule takes effect.
 100      *
 101      * @param prevRawOffset     The standard time offset from UTC before this rule
 102      *                          takes effect in milliseconds.
 103      * @param prevDSTSavings    The amount of daylight saving offset from the
 104      *                          standard time.
 105      *
 106      * @return  The very first time when this rule takes effect.
 107      *
 108      * @stable ICU 3.8
 109      */
 110     public abstract Date getFirstStart(int prevRawOffset, int prevDSTSavings);
 111
 112     /**
 113      * Gets the final time when this rule takes effect.
 114      *
 115      * @param prevRawOffset     The standard time offset from UTC before this rule
 116      *                          takes effect in milliseconds.
 117      * @param prevDSTSavings    The amount of daylight saving offset from the
 118      *                          standard time.
 119      *
 120      * @return  The very last time when this rule takes effect,
 121      *          or null if this rule is applied for future dates infinitely.
 122      *
 123      * @stable ICU 3.8
 124      */
 125     public abstract Date getFinalStart(int prevRawOffset, int prevDSTSavings);
 126
 127     /**
 128      * Gets the first time when this rule takes effect after the specified time.
 129      *
 130      * @param base              The first time after this time is returned.
 131      * @param prevRawOffset     The standard time offset from UTC before this rule
 132      *                          takes effect in milliseconds.
 133      * @param prevDSTSavings    The amount of daylight saving offset from the
 134      *                          standard time.
 135      * @param inclusive         Whether the base time is inclusive or not.
 136      *
 137      * @return  The first time when this rule takes effect after the specified time,
 138      *          or null when this rule never takes effect after the specified time.
 139      *
 140      * @stable ICU 3.8
 141      */
 142     public abstract Date getNextStart(long base, int prevRawOffset, int prevDSTSavings, boolean inclusive);
 143
 144     /**
 145      * Gets the most recent time when this rule takes effect before the specified time.
 146      *
 147      * @param base              The most recent time when this rule takes effect before
 148      *                          this time is returned.
 149      * @param prevRawOffset     The standard time offset from UTC before this rule
 150      *                          takes effect in milliseconds.
 151      * @param prevDSTSavings    The amount of daylight saving offset from the
 152      *                          standard time.
 153      * @param inclusive         Whether the base time is inclusive or not.
 154      *
 155      * @return  The most recent time when this rule takes effect before the specified time,
 156      *          or null when this rule never takes effect before the specified time.
 157      *
 158      * @stable ICU 3.8
 159      */
 160     public abstract Date getPreviousStart(long base, int prevRawOffset, int prevDSTSavings, boolean inclusive);
 161
 162     /**
 163      * Returns if this <code>TimeZoneRule</code> has one or more start times.
 164      *
 165      * @return true if this <TimeZoneRule</code> has one or more start times.
 166      *
 167      * @stable ICU 3.8
 168      */
 169     public abstract boolean isTransitionRule();
 170
 171     /**
 172      * Returns a <code>String</code> representation of this <code>TimeZoneRule</code> object.
 173      * This method is used for debugging purpose only.  The string representation can be changed
 174      * in future version of ICU without any notice.
 175      * @stable ICU 3.8
 176      */
 177     public String toString() {
 178         StringBuilder buf = new StringBuilder();
 179         buf.append("name=" + name);
 180         buf.append(", stdOffset=" + rawOffset);
 181         buf.append(", dstSaving=" + dstSavings);
 182         return buf.toString();
 183     }
 184 }