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

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