Caldavsync Sources / file revision
src/net/fortuna/ical4j/model/property/Trigger.java@fb9019fb1bf7
src/net/fortuna/ical4j/model/property/Trigger.java
Tue, 10 Feb 2015 18:12:00 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Tue, 10 Feb 2015 18:12:00 +0100
- changeset 0
- fb9019fb1bf7
- permissions
- -rw-r--r--
Import initial revisions of existing project AndroidCaldavSyncAdapater,
forked from upstream repository at 27e8a0f8495c92e0780d450bdf0c7cec77a03a55.
1 /**
2 * Copyright (c) 2012, Ben Fortuna
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * o Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * o Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * o Neither the name of Ben Fortuna nor the names of any other contributors
17 * may be used to endorse or promote products derived from this software
18 * without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32 package net.fortuna.ical4j.model.property;
34 import java.text.ParseException;
36 import net.fortuna.ical4j.model.DateTime;
37 import net.fortuna.ical4j.model.Dur;
38 import net.fortuna.ical4j.model.Parameter;
39 import net.fortuna.ical4j.model.ParameterList;
40 import net.fortuna.ical4j.model.PropertyFactoryImpl;
41 import net.fortuna.ical4j.model.ValidationException;
42 import net.fortuna.ical4j.model.parameter.Value;
43 import net.fortuna.ical4j.util.ParameterValidator;
45 /**
46 * $Id$
47 *
48 * Created: [Apr 6, 2004]
49 *
50 * Defines a TRIGGER iCalendar component property.
51 *
52 * <pre>
53 * 4.8.6.3 Trigger
54 *
55 * Property Name: TRIGGER
56 *
57 * Purpose: This property specifies when an alarm will trigger.
58 *
59 * Value Type: The default value type is DURATION. The value type can be
60 * set to a DATE-TIME value type, in which case the value MUST specify a
61 * UTC formatted DATE-TIME value.
62 *
63 * Property Parameters: Non-standard, value data type, time zone
64 * identifier or trigger relationship property parameters can be
65 * specified on this property. The trigger relationship property
66 * parameter MUST only be specified when the value type is DURATION.
67 *
68 * Conformance: This property MUST be specified in the "VALARM" calendar
69 * component.
70 *
71 * Description: Within the "VALARM" calendar component, this property
72 * defines when the alarm will trigger. The default value type is
73 * DURATION, specifying a relative time for the trigger of the alarm.
74 * The default duration is relative to the start of an event or to-do
75 * that the alarm is associated with. The duration can be explicitly set
76 *
77 * to trigger from either the end or the start of the associated event
78 * or to-do with the "RELATED" parameter. A value of START will set the
79 * alarm to trigger off the start of the associated event or to-do. A
80 * value of END will set the alarm to trigger off the end of the
81 * associated event or to-do.
82 *
83 * Either a positive or negative duration may be specified for the
84 * "TRIGGER" property. An alarm with a positive duration is triggered
85 * after the associated start or end of the event or to-do. An alarm
86 * with a negative duration is triggered before the associated start or
87 * end of the event or to-do.
88 *
89 * The "RELATED" property parameter is not valid if the value type of
90 * the property is set to DATE-TIME (i.e., for an absolute date and time
91 * alarm trigger). If a value type of DATE-TIME is specified, then the
92 * property value MUST be specified in the UTC time format. If an
93 * absolute trigger is specified on an alarm for a recurring event or
94 * to-do, then the alarm will only trigger for the specified absolute
95 * date/time, along with any specified repeating instances.
96 *
97 * If the trigger is set relative to START, then the "DTSTART" property
98 * MUST be present in the associated "VEVENT" or "VTODO" calendar
99 * component. If an alarm is specified for an event with the trigger set
100 * relative to the END, then the "DTEND" property or the "DSTART" and
101 * "DURATION' properties MUST be present in the associated "VEVENT"
102 * calendar component. If the alarm is specified for a to-do with a
103 * trigger set relative to the END, then either the "DUE" property or
104 * the "DSTART" and "DURATION' properties MUST be present in the
105 * associated "VTODO" calendar component.
106 *
107 * Alarms specified in an event or to-do which is defined in terms of a
108 * DATE value type will be triggered relative to 00:00:00 UTC on the
109 * specified date. For example, if "DTSTART:19980205, then the duration
110 * trigger will be relative to19980205T000000Z.
111 *
112 * Format Definition: The property is defined by the following notation:
113 *
114 * trigger = "TRIGGER" (trigrel / trigabs)
115 *
116 * trigrel = *(
117 *
118 * ; the following are optional,
119 * ; but MUST NOT occur more than once
120 *
121 * (";" "VALUE" "=" "DURATION") /
122 * (";" trigrelparam) /
123 *
124 * ; the following is optional,
125 * ; and MAY occur more than once
126 *
127 * (";" xparam)
128 * ) ":" dur-value
129 *
130 * trigabs = 1*(
131 *
132 * ; the following is REQUIRED,
133 * ; but MUST NOT occur more than once
134 *
135 * (";" "VALUE" "=" "DATE-TIME") /
136 *
137 * ; the following is optional,
138 * ; and MAY occur more than once
139 *
140 * (";" xparam)
141 *
142 * ) ":" date-time
143 * </pre>
144 *
145 * @author Ben Fortuna
146 */
147 public class Trigger extends UtcProperty {
149 private static final long serialVersionUID = 5049421499261722194L;
151 private Dur duration;
153 /**
154 * Default constructor.
155 */
156 public Trigger() {
157 super(TRIGGER, PropertyFactoryImpl.getInstance());
158 }
160 /**
161 * @param aList a list of parameters for this component
162 * @param aValue a value string for this component
163 */
164 public Trigger(final ParameterList aList, final String aValue) {
165 super(TRIGGER, aList, PropertyFactoryImpl.getInstance());
166 setValue(aValue);
167 }
169 /**
170 * @param duration a duration in milliseconds
171 */
172 public Trigger(final Dur duration) {
173 super(TRIGGER, PropertyFactoryImpl.getInstance());
174 setDuration(duration);
175 }
177 /**
178 * @param aList a list of parameters for this component
179 * @param duration a duration in milliseconds
180 */
181 public Trigger(final ParameterList aList, final Dur duration) {
182 super(TRIGGER, aList, PropertyFactoryImpl.getInstance());
183 setDuration(duration);
184 }
186 /**
187 * @param dateTime a date representation of a date-time
188 */
189 public Trigger(final DateTime dateTime) {
190 super(TRIGGER, PropertyFactoryImpl.getInstance());
191 setDateTime(dateTime);
192 }
194 /**
195 * @param aList a list of parameters for this component
196 * @param dateTime a date representation of a date-time
197 */
198 public Trigger(final ParameterList aList, final DateTime dateTime) {
199 super(TRIGGER, aList, PropertyFactoryImpl.getInstance());
200 setDateTime(dateTime);
201 }
203 /**
204 * {@inheritDoc}
205 */
206 public final void validate() throws ValidationException {
207 super.validate();
209 final Parameter relParam = getParameter(Parameter.RELATED);
210 final Parameter valueParam = getParameter(Parameter.VALUE);
212 if (relParam != null || !Value.DATE_TIME.equals(valueParam)) {
214 ParameterValidator.getInstance().assertOneOrLess(Parameter.RELATED,
215 getParameters());
217 ParameterValidator.getInstance().assertNullOrEqual(Value.DURATION,
218 getParameters());
220 if (getDuration() == null) {
221 throw new ValidationException("Duration value not specified");
222 }
223 }
224 else {
225 ParameterValidator.getInstance().assertOne(Parameter.VALUE,
226 getParameters());
228 ParameterValidator.getInstance().assertNullOrEqual(Value.DATE_TIME,
229 getParameters());
231 if (getDateTime() == null) {
232 throw new ValidationException("DATE-TIME value not specified");
233 }
234 }
235 }
237 /**
238 * @return Returns the duration.
239 */
240 public final Dur getDuration() {
241 return duration;
242 }
244 /**
245 * {@inheritDoc}
246 */
247 public final void setValue(final String aValue) {
248 try {
249 super.setValue(aValue);
250 duration = null;
251 }
252 catch (ParseException pe) {
253 duration = new Dur(aValue);
254 super.setDateTime(null);
255 }
256 }
258 /**
259 * {@inheritDoc}
260 */
261 public final String getValue() {
262 if (duration != null) {
263 return duration.toString();
264 }
265 return super.getValue();
266 }
268 /**
269 * @param dateTime The dateTime to set.
270 */
271 public final void setDateTime(final DateTime dateTime) {
272 super.setDateTime(dateTime);
273 duration = null;
274 getParameters().replace(Value.DATE_TIME);
275 }
277 /**
278 * @param duration The duration to set.
279 */
280 public final void setDuration(final Dur duration) {
281 this.duration = duration;
282 super.setDateTime(null);
283 // duration is the default value type for Trigger..
284 if (getParameter(Parameter.VALUE) != null) {
285 getParameters().replace(Value.DURATION);
286 }
287 }
288 }
