001 package biweekly.component;
002
003 import java.util.Date;
004 import java.util.List;
005
006 import biweekly.property.Comment;
007 import biweekly.property.DateStart;
008 import biweekly.property.ExceptionDates;
009 import biweekly.property.RecurrenceDates;
010 import biweekly.property.RecurrenceRule;
011 import biweekly.property.TimezoneName;
012 import biweekly.property.TimezoneOffsetFrom;
013 import biweekly.property.TimezoneOffsetTo;
014
015 /*
016 Copyright (c) 2013, Michael Angstadt
017 All rights reserved.
018
019 Redistribution and use in source and binary forms, with or without
020 modification, are permitted provided that the following conditions are met:
021
022 1. Redistributions of source code must retain the above copyright notice, this
023 list of conditions and the following disclaimer.
024 2. Redistributions in binary form must reproduce the above copyright notice,
025 this list of conditions and the following disclaimer in the documentation
026 and/or other materials provided with the distribution.
027
028 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
029 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
030 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
031 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
032 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
033 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
034 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
035 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
036 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
037 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
038 */
039
040 /**
041 * Parent class for the "daylight" and "standard" timezone observances.
042 * @author Michael Angstadt
043 * @see DaylightSavingsTime
044 * @see StandardTime
045 * @see <a href="http://tools.ietf.org/html/rfc5545#page-62">RFC 5545
046 * p.62-71</a>
047 */
048 public abstract class Observance extends ICalComponent {
049 /**
050 * Gets the date that the timezone starts.
051 * @return the start date or null if not set
052 * @see <a href="http://tools.ietf.org/html/rfc5545#page-97">RFC 5545
053 * p.97-8</a>
054 */
055 public DateStart getDateStart() {
056 return getProperty(DateStart.class);
057 }
058
059 /**
060 * Sets the date that the timezone starts.
061 * @param dateStart the start date or null to remove
062 * @see <a href="http://tools.ietf.org/html/rfc5545#page-97">RFC 5545
063 * p.97-8</a>
064 */
065 public void setDateStart(DateStart dateStart) {
066 setProperty(DateStart.class, dateStart);
067 }
068
069 /**
070 * Sets the date that the timezone starts.
071 * @param dateStart the start date or null to remove
072 * @return the property that was created
073 * @see <a href="http://tools.ietf.org/html/rfc5545#page-97">RFC 5545
074 * p.97-8</a>
075 */
076 public DateStart setDateStart(Date dateStart) {
077 DateStart prop = (dateStart == null) ? null : new DateStart(dateStart);
078 setDateStart(prop);
079 return prop;
080 }
081
082 /**
083 * Gets the timezone offset that is currently in use in the timezone
084 * observance.
085 * @return the timezone offset or null if not set
086 * @see <a href="http://tools.ietf.org/html/rfc5545#page-105">RFC 5545
087 * p.105-6</a>
088 */
089 public TimezoneOffsetTo getTimezoneOffsetTo() {
090 return getProperty(TimezoneOffsetTo.class);
091 }
092
093 /**
094 * Sets the timezone offset that is currently in use in the timezone
095 * observance.
096 * @param timezoneOffsetTo the timezone offset or null to remove
097 * @see <a href="http://tools.ietf.org/html/rfc5545#page-105">RFC 5545
098 * p.105-6</a>
099 */
100 public void setTimezoneOffsetTo(TimezoneOffsetTo timezoneOffsetTo) {
101 setProperty(TimezoneOffsetTo.class, timezoneOffsetTo);
102 }
103
104 /**
105 * Sets the timezone offset that is currently in use in the timezone
106 * observance.
107 * @param hour the hour offset (e.g. "-5")
108 * @param minute the minute offset (e.g. "0")
109 * @return the property that was created
110 * @see <a href="http://tools.ietf.org/html/rfc5545#page-105">RFC 5545
111 * p.105-6</a>
112 */
113 public TimezoneOffsetTo setTimezoneOffsetTo(Integer hour, Integer minute) {
114 TimezoneOffsetTo prop = new TimezoneOffsetTo(hour, minute);
115 setTimezoneOffsetTo(prop);
116 return prop;
117 }
118
119 /**
120 * Gets the timezone offset that was in use before the timezone observance.
121 * @return the timezone offset or null if not set
122 * @see <a href="http://tools.ietf.org/html/rfc5545#page-104">RFC 5545
123 * p.104-5</a>
124 */
125 public TimezoneOffsetFrom getTimezoneOffsetFrom() {
126 return getProperty(TimezoneOffsetFrom.class);
127 }
128
129 /**
130 * Sets the timezone offset that was in use before the timezone observance.
131 * @param timezoneOffsetFrom the timezone offset or null to remove
132 * @see <a href="http://tools.ietf.org/html/rfc5545#page-104">RFC 5545
133 * p.104-5</a>
134 */
135 public void setTimezoneOffsetFrom(TimezoneOffsetFrom timezoneOffsetFrom) {
136 setProperty(TimezoneOffsetFrom.class, timezoneOffsetFrom);
137 }
138
139 /**
140 * Sets the timezone offset that was in use before the timezone observance.
141 * @param hour the hour offset (e.g. "-5")
142 * @param minute the minute offset (e.g. "0")
143 * @return the property that was created
144 * @see <a href="http://tools.ietf.org/html/rfc5545#page-104">RFC 5545
145 * p.104-5</a>
146 */
147 public TimezoneOffsetFrom setTimezoneOffsetFrom(Integer hour, Integer minute) {
148 TimezoneOffsetFrom prop = new TimezoneOffsetFrom(hour, minute);
149 setTimezoneOffsetFrom(prop);
150 return prop;
151 }
152
153 /**
154 * Gets how often the observance repeats.
155 * @return the recurrence rule or null if not set
156 * @see <a href="http://tools.ietf.org/html/rfc5545#page-122">RFC 5545
157 * p.122-32</a>
158 */
159 public RecurrenceRule getRecurrenceRule() {
160 return getProperty(RecurrenceRule.class);
161 }
162
163 /**
164 * Sets how often the observance repeats.
165 * @param recurrenceRule the recurrence rule or null to remove
166 * @see <a href="http://tools.ietf.org/html/rfc5545#page-122">RFC 5545
167 * p.122-32</a>
168 */
169 public void setRecurrenceRule(RecurrenceRule recurrenceRule) {
170 setProperty(RecurrenceRule.class, recurrenceRule);
171 }
172
173 //
174 //zero or more
175 // private List<Comment> comments;
176 // private List<RDate> rdates;
177 // private List<TimezoneName> timezoneName;
178
179 /**
180 * Gets the comments attached to the timezone.
181 * @return the comments
182 * @see <a href="http://tools.ietf.org/html/rfc5545#page-83">RFC 5545
183 * p.83-4</a>
184 */
185 public List<Comment> getComments() {
186 return getProperties(Comment.class);
187 }
188
189 /**
190 * Adds a comment to the timezone.
191 * @param comment the comment to add
192 * @see <a href="http://tools.ietf.org/html/rfc5545#page-83">RFC 5545
193 * p.83-4</a>
194 */
195 public void addComment(Comment comment) {
196 addProperty(comment);
197 }
198
199 /**
200 * Adds a comment to the timezone.
201 * @param comment the comment to add
202 * @return the property that was created
203 * @see <a href="http://tools.ietf.org/html/rfc5545#page-83">RFC 5545
204 * p.83-4</a>
205 */
206 public Comment addComment(String comment) {
207 Comment prop = new Comment(comment);
208 addComment(prop);
209 return prop;
210 }
211
212 /**
213 * Gets the list of dates/periods that help define the recurrence rule of
214 * this observance (if one is defined).
215 * @return the recurrence dates
216 * @see <a href="http://tools.ietf.org/html/rfc5545#page-120">RFC 5545
217 * p.120-2</a>
218 */
219 public List<RecurrenceDates> getRecurrenceDates() {
220 return getProperties(RecurrenceDates.class);
221 }
222
223 /**
224 * Adds a list of dates/periods that help define the recurrence rule of this
225 * observance (if one is defined).
226 * @param recurrenceDates the recurrence dates
227 * @see <a href="http://tools.ietf.org/html/rfc5545#page-120">RFC 5545
228 * p.120-2</a>
229 */
230 public void addRecurrenceDates(RecurrenceDates recurrenceDates) {
231 addProperty(recurrenceDates);
232 }
233
234 /**
235 * Gets the traditional, non-standard names for the timezone.
236 * @return the timezone names
237 * @see <a href="http://tools.ietf.org/html/rfc5545#page-103">RFC 5545
238 * p.103-4</a>
239 */
240 public List<TimezoneName> getTimezoneNames() {
241 return getProperties(TimezoneName.class);
242 }
243
244 /**
245 * Adds a traditional, non-standard name for the timezone.
246 * @param timezoneName the timezone name
247 * @see <a href="http://tools.ietf.org/html/rfc5545#page-103">RFC 5545
248 * p.103-4</a>
249 */
250 public void addTimezoneName(TimezoneName timezoneName) {
251 addProperty(timezoneName);
252 }
253
254 /**
255 * Adds a traditional, non-standard name for the timezone.
256 * @param timezoneName the timezone name (e.g. "EST")
257 * @return the property that was created
258 * @see <a href="http://tools.ietf.org/html/rfc5545#page-103">RFC 5545
259 * p.103-4</a>
260 */
261 public TimezoneName addTimezoneName(String timezoneName) {
262 TimezoneName prop = new TimezoneName(timezoneName);
263 addTimezoneName(prop);
264 return prop;
265 }
266
267 /**
268 * Gets the list of exceptions to the observance.
269 * @return the list of exceptions
270 * @see <a href="http://tools.ietf.org/html/rfc5545#page-118">RFC 5545
271 * p.118-20</a>
272 */
273 public List<ExceptionDates> getExceptionDates() {
274 return getProperties(ExceptionDates.class);
275 }
276
277 /**
278 * Adds a list of exceptions to the observance. Note that this property can
279 * contain multiple dates.
280 * @param exceptionDates the list of exceptions
281 * @see <a href="http://tools.ietf.org/html/rfc5545#page-118">RFC 5545
282 * p.118-20</a>
283 */
284 public void addExceptionDates(ExceptionDates exceptionDates) {
285 addProperty(exceptionDates);
286 }
287
288 @SuppressWarnings("unchecked")
289 @Override
290 protected void validate(List<ICalComponent> components, List<String> warnings) {
291 checkRequiredCardinality(warnings, DateStart.class, TimezoneOffsetTo.class, TimezoneOffsetFrom.class);
292 }
293 }