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