1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/net/fortuna/ical4j/model/component/VAlarm.java Tue Feb 10 18:12:00 2015 +0100
1.3 @@ -0,0 +1,468 @@
1.4 +/**
1.5 + * Copyright (c) 2012, Ben Fortuna
1.6 + * All rights reserved.
1.7 + *
1.8 + * Redistribution and use in source and binary forms, with or without
1.9 + * modification, are permitted provided that the following conditions
1.10 + * are met:
1.11 + *
1.12 + * o Redistributions of source code must retain the above copyright
1.13 + * notice, this list of conditions and the following disclaimer.
1.14 + *
1.15 + * o Redistributions in binary form must reproduce the above copyright
1.16 + * notice, this list of conditions and the following disclaimer in the
1.17 + * documentation and/or other materials provided with the distribution.
1.18 + *
1.19 + * o Neither the name of Ben Fortuna nor the names of any other contributors
1.20 + * may be used to endorse or promote products derived from this software
1.21 + * without specific prior written permission.
1.22 + *
1.23 + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
1.24 + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1.25 + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1.26 + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
1.27 + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
1.28 + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
1.29 + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
1.30 + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1.31 + * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1.32 + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
1.33 + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.34 + */
1.35 +package net.fortuna.ical4j.model.component;
1.36 +
1.37 +import java.util.HashMap;
1.38 +import java.util.Map;
1.39 +
1.40 +import net.fortuna.ical4j.model.DateTime;
1.41 +import net.fortuna.ical4j.model.Dur;
1.42 +import net.fortuna.ical4j.model.Property;
1.43 +import net.fortuna.ical4j.model.PropertyList;
1.44 +import net.fortuna.ical4j.model.ValidationException;
1.45 +import net.fortuna.ical4j.model.Validator;
1.46 +import net.fortuna.ical4j.model.property.Action;
1.47 +import net.fortuna.ical4j.model.property.Attach;
1.48 +import net.fortuna.ical4j.model.property.Description;
1.49 +import net.fortuna.ical4j.model.property.Duration;
1.50 +import net.fortuna.ical4j.model.property.Method;
1.51 +import net.fortuna.ical4j.model.property.Repeat;
1.52 +import net.fortuna.ical4j.model.property.Summary;
1.53 +import net.fortuna.ical4j.model.property.Trigger;
1.54 +import net.fortuna.ical4j.util.PropertyValidator;
1.55 +
1.56 +/**
1.57 + * $Id$ [Apr 5, 2004]
1.58 + *
1.59 + * Defines an iCalendar VALARM component.
1.60 + *
1.61 + * <pre>
1.62 + * 4.6.6 Alarm Component
1.63 + *
1.64 + * Component Name: VALARM
1.65 + *
1.66 + * Purpose: Provide a grouping of component properties that define an
1.67 + * alarm.
1.68 + *
1.69 + * Formal Definition: A "VALARM" calendar component is defined by the
1.70 + * following notation:
1.71 + *
1.72 + * alarmc = "BEGIN" ":" "VALARM" CRLF
1.73 + * (audioprop / dispprop / emailprop / procprop)
1.74 + * "END" ":" "VALARM" CRLF
1.75 + *
1.76 + * audioprop = 2*(
1.77 + *
1.78 + * ; 'action' and 'trigger' are both REQUIRED,
1.79 + * ; but MUST NOT occur more than once
1.80 + *
1.81 + * action / trigger /
1.82 + *
1.83 + * ; 'duration' and 'repeat' are both optional,
1.84 + * ; and MUST NOT occur more than once each,
1.85 + * ; but if one occurs, so MUST the other
1.86 + *
1.87 + * duration / repeat /
1.88 + *
1.89 + * ; the following is optional,
1.90 + * ; but MUST NOT occur more than once
1.91 + *
1.92 + * attach /
1.93 + *
1.94 + * ; the following is optional,
1.95 + * ; and MAY occur more than once
1.96 + *
1.97 + * x-prop
1.98 + *
1.99 + * )
1.100 + *
1.101 + *
1.102 + *
1.103 + * dispprop = 3*(
1.104 + *
1.105 + * ; the following are all REQUIRED,
1.106 + * ; but MUST NOT occur more than once
1.107 + *
1.108 + * action / description / trigger /
1.109 + *
1.110 + * ; 'duration' and 'repeat' are both optional,
1.111 + * ; and MUST NOT occur more than once each,
1.112 + * ; but if one occurs, so MUST the other
1.113 + *
1.114 + * duration / repeat /
1.115 + *
1.116 + * ; the following is optional,
1.117 + * ; and MAY occur more than once
1.118 + *
1.119 + * *x-prop
1.120 + *
1.121 + * )
1.122 + *
1.123 + *
1.124 + *
1.125 + * emailprop = 5*(
1.126 + *
1.127 + * ; the following are all REQUIRED,
1.128 + * ; but MUST NOT occur more than once
1.129 + *
1.130 + * action / description / trigger / summary
1.131 + *
1.132 + * ; the following is REQUIRED,
1.133 + * ; and MAY occur more than once
1.134 + *
1.135 + * attendee /
1.136 + *
1.137 + * ; 'duration' and 'repeat' are both optional,
1.138 + * ; and MUST NOT occur more than once each,
1.139 + * ; but if one occurs, so MUST the other
1.140 + *
1.141 + * duration / repeat /
1.142 + *
1.143 + * ; the following are optional,
1.144 + * ; and MAY occur more than once
1.145 + *
1.146 + * attach / x-prop
1.147 + *
1.148 + * )
1.149 + *
1.150 + *
1.151 + *
1.152 + * procprop = 3*(
1.153 + *
1.154 + * ; the following are all REQUIRED,
1.155 + * ; but MUST NOT occur more than once
1.156 + *
1.157 + * action / attach / trigger /
1.158 + *
1.159 + * ; 'duration' and 'repeat' are both optional,
1.160 + * ; and MUST NOT occur more than once each,
1.161 + * ; but if one occurs, so MUST the other
1.162 + *
1.163 + * duration / repeat /
1.164 + *
1.165 + * ; 'description' is optional,
1.166 + * ; and MUST NOT occur more than once
1.167 + *
1.168 + * description /
1.169 + *
1.170 + * ; the following is optional,
1.171 + * ; and MAY occur more than once
1.172 + *
1.173 + * x-prop
1.174 + *
1.175 + * )
1.176 + * </pre>
1.177 + *
1.178 + * Example 1 - Creating an alarm to trigger at a specific time:
1.179 + *
1.180 + * <pre><code>
1.181 + * java.util.Calendar cal = java.util.Calendar.getInstance();
1.182 + * cal.set(java.util.Calendar.MONTH, java.util.Calendar.DECEMBER);
1.183 + * cal.set(java.util.Calendar.DAY_OF_MONTH, 25);
1.184 + *
1.185 + * VAlarm christmas = new VAlarm(cal.getTime());
1.186 + * </code></pre>
1.187 + *
1.188 + * Example 2 - Creating an alarm to trigger one (1) hour before the scheduled start of the parent event/the parent todo
1.189 + * is due:
1.190 + *
1.191 + * <pre><code>
1.192 + * VAlarm reminder = new VAlarm(new Dur(0, -1, 0, 0));
1.193 + *
1.194 + * // repeat reminder four (4) more times every fifteen (15) minutes..
1.195 + * reminder.getProperties().add(new Repeat(4));
1.196 + * reminder.getProperties().add(new Duration(new Dur(0, 0, 15, 0)));
1.197 + *
1.198 + * // display a message..
1.199 + * reminder.getProperties().add(Action.DISPLAY);
1.200 + * reminder.getProperties().add(new Description("Progress Meeting at 9:30am"));
1.201 + * </code></pre>
1.202 + *
1.203 + * @author Ben Fortuna
1.204 + */
1.205 +public class VAlarm extends CalendarComponent {
1.206 +
1.207 + private static final long serialVersionUID = -8193965477414653802L;
1.208 +
1.209 + private final Map actionValidators = new HashMap();
1.210 + {
1.211 + actionValidators.put(Action.AUDIO, new AudioValidator());
1.212 + actionValidators.put(Action.DISPLAY, new DisplayValidator());
1.213 + actionValidators.put(Action.EMAIL, new EmailValidator());
1.214 + actionValidators.put(Action.PROCEDURE, new ProcedureValidator());
1.215 + }
1.216 +
1.217 + private final Validator itipValidator = new ITIPValidator();
1.218 +
1.219 + /**
1.220 + * Default constructor.
1.221 + */
1.222 + public VAlarm() {
1.223 + super(VALARM);
1.224 + }
1.225 +
1.226 + /**
1.227 + * Constructor.
1.228 + * @param properties a list of properties
1.229 + */
1.230 + public VAlarm(final PropertyList properties) {
1.231 + super(VALARM, properties);
1.232 + }
1.233 +
1.234 + /**
1.235 + * Constructs a new VALARM instance that will trigger at the specified time.
1.236 + * @param trigger the time the alarm will trigger
1.237 + */
1.238 + public VAlarm(final DateTime trigger) {
1.239 + this();
1.240 + getProperties().add(new Trigger(trigger));
1.241 + }
1.242 +
1.243 + /**
1.244 + * Constructs a new VALARM instance that will trigger at the specified time relative to the event/todo component.
1.245 + * @param trigger a duration of time relative to the parent component that the alarm will trigger at
1.246 + */
1.247 + public VAlarm(final Dur trigger) {
1.248 + this();
1.249 + getProperties().add(new Trigger(trigger));
1.250 + }
1.251 +
1.252 + /**
1.253 + * {@inheritDoc}
1.254 + */
1.255 + public final void validate(final boolean recurse)
1.256 + throws ValidationException {
1.257 +
1.258 + /*
1.259 + * ; 'action' and 'trigger' are both REQUIRED, ; but MUST NOT occur more than once action / trigger /
1.260 + */
1.261 + PropertyValidator.getInstance().assertOne(Property.ACTION, getProperties());
1.262 + PropertyValidator.getInstance().assertOne(Property.TRIGGER, getProperties());
1.263 +
1.264 + /*
1.265 + * ; 'duration' and 'repeat' are both optional, ; and MUST NOT occur more than once each, ; but if one occurs,
1.266 + * so MUST the other duration / repeat /
1.267 + */
1.268 + PropertyValidator.getInstance().assertOneOrLess(Property.DURATION, getProperties());
1.269 + PropertyValidator.getInstance().assertOneOrLess(Property.REPEAT, getProperties());
1.270 +
1.271 + try {
1.272 + PropertyValidator.getInstance().assertNone(Property.DURATION, getProperties());
1.273 + PropertyValidator.getInstance().assertNone(Property.REPEAT, getProperties());
1.274 + }
1.275 + catch (ValidationException ve) {
1.276 + PropertyValidator.getInstance().assertOne(Property.DURATION, getProperties());
1.277 + PropertyValidator.getInstance().assertOne(Property.REPEAT, getProperties());
1.278 + }
1.279 +
1.280 + /*
1.281 + * ; the following is optional, ; and MAY occur more than once x-prop
1.282 + */
1.283 +
1.284 + final Validator actionValidator = (Validator) actionValidators.get(getAction());
1.285 + if (actionValidator != null) {
1.286 + actionValidator.validate();
1.287 + }
1.288 +
1.289 + if (recurse) {
1.290 + validateProperties();
1.291 + }
1.292 + }
1.293 +
1.294 + /**
1.295 + * {@inheritDoc}
1.296 + */
1.297 + protected Validator getValidator(Method method) {
1.298 + return itipValidator;
1.299 + }
1.300 +
1.301 + private class AudioValidator implements Validator {
1.302 +
1.303 + private static final long serialVersionUID = 1L;
1.304 +
1.305 + /**
1.306 + * {@inheritDoc}
1.307 + */
1.308 + public void validate() throws ValidationException {
1.309 + /*
1.310 + * ; the following is optional, ; but MUST NOT occur more than once attach /
1.311 + */
1.312 + PropertyValidator.getInstance().assertOneOrLess(Property.ATTACH, getProperties());
1.313 + }
1.314 + }
1.315 +
1.316 + private class DisplayValidator implements Validator {
1.317 +
1.318 + private static final long serialVersionUID = 1L;
1.319 +
1.320 + /**
1.321 + * {@inheritDoc}
1.322 + */
1.323 + public void validate() throws ValidationException {
1.324 + /*
1.325 + * ; the following are all REQUIRED, ; but MUST NOT occur more than once action / description / trigger /
1.326 + */
1.327 + PropertyValidator.getInstance().assertOne(Property.DESCRIPTION, getProperties());
1.328 + }
1.329 + }
1.330 +
1.331 + private class EmailValidator implements Validator {
1.332 +
1.333 + private static final long serialVersionUID = 1L;
1.334 +
1.335 + /**
1.336 + * {@inheritDoc}
1.337 + */
1.338 + public void validate() throws ValidationException {
1.339 + /*
1.340 + * ; the following are all REQUIRED,
1.341 + * ; but MUST NOT occur more than once action / description / trigger / summary
1.342 + * ; the following is REQUIRED,
1.343 + * ; and MAY occur more than once attendee /
1.344 + * ; 'duration' and 'repeat' are both optional,
1.345 + * ; and MUST NOT occur more than once each,
1.346 + * ; but if one occurs, so MUST the other duration / repeat /
1.347 + * ; the following are optional,
1.348 + * ; and MAY occur more than once attach / x-prop
1.349 + */
1.350 + PropertyValidator.getInstance().assertOne(Property.DESCRIPTION, getProperties());
1.351 + PropertyValidator.getInstance().assertOne(Property.SUMMARY, getProperties());
1.352 +
1.353 + PropertyValidator.getInstance().assertOneOrMore(Property.ATTENDEE, getProperties());
1.354 + }
1.355 + }
1.356 +
1.357 + private class ProcedureValidator implements Validator {
1.358 +
1.359 + private static final long serialVersionUID = 1L;
1.360 +
1.361 + /**
1.362 + * {@inheritDoc}
1.363 + */
1.364 + public void validate() throws ValidationException {
1.365 + /*
1.366 + * ; the following are all REQUIRED,
1.367 + * ; but MUST NOT occur more than once action / attach / trigger /
1.368 + * ; 'duration' and 'repeat' are both optional,
1.369 + * ; and MUST NOT occur more than once each,
1.370 + * ; but if one occurs, so MUST the other duration / repeat /
1.371 + * ; 'description' is optional,
1.372 + * ; and MUST NOT occur more than once description /
1.373 + * ; the following is optional, ; and MAY occur more than once x-prop
1.374 + */
1.375 + PropertyValidator.getInstance().assertOne(Property.ATTACH, getProperties());
1.376 +
1.377 + PropertyValidator.getInstance().assertOneOrLess(Property.DESCRIPTION, getProperties());
1.378 + }
1.379 + }
1.380 +
1.381 + /**
1.382 + * Common validation for all iTIP methods.
1.383 + *
1.384 + * <pre>
1.385 + * Component/Property Presence
1.386 + * ------------------- ----------------------------------------------
1.387 + * VALARM 0+
1.388 + * ACTION 1
1.389 + * ATTACH 0+
1.390 + * DESCRIPTION 0 or 1
1.391 + * DURATION 0 or 1 if present REPEAT MUST be present
1.392 + * REPEAT 0 or 1 if present DURATION MUST be present
1.393 + * SUMMARY 0 or 1
1.394 + * TRIGGER 1
1.395 + * X-PROPERTY 0+
1.396 + * </pre>
1.397 + */
1.398 + private class ITIPValidator implements Validator {
1.399 +
1.400 + private static final long serialVersionUID = 1L;
1.401 +
1.402 + /**
1.403 + * {@inheritDoc}
1.404 + */
1.405 + public void validate() throws ValidationException {
1.406 + PropertyValidator.getInstance().assertOne(Property.ACTION, getProperties());
1.407 + PropertyValidator.getInstance().assertOne(Property.TRIGGER, getProperties());
1.408 +
1.409 + PropertyValidator.getInstance().assertOneOrLess(Property.DESCRIPTION, getProperties());
1.410 + PropertyValidator.getInstance().assertOneOrLess(Property.DURATION, getProperties());
1.411 + PropertyValidator.getInstance().assertOneOrLess(Property.REPEAT, getProperties());
1.412 + PropertyValidator.getInstance().assertOneOrLess(Property.SUMMARY, getProperties());
1.413 + }
1.414 + }
1.415 +
1.416 + /**
1.417 + * Returns the mandatory action property.
1.418 + * @return the ACTION property or null if not specified
1.419 + */
1.420 + public final Action getAction() {
1.421 + return (Action) getProperty(Property.ACTION);
1.422 + }
1.423 +
1.424 + /**
1.425 + * Returns the mandatory trigger property.
1.426 + * @return the TRIGGER property or null if not specified
1.427 + */
1.428 + public final Trigger getTrigger() {
1.429 + return (Trigger) getProperty(Property.TRIGGER);
1.430 + }
1.431 +
1.432 + /**
1.433 + * Returns the optional duration property.
1.434 + * @return the DURATION property or null if not specified
1.435 + */
1.436 + public final Duration getDuration() {
1.437 + return (Duration) getProperty(Property.DURATION);
1.438 + }
1.439 +
1.440 + /**
1.441 + * Returns the optional repeat property.
1.442 + * @return the REPEAT property or null if not specified
1.443 + */
1.444 + public final Repeat getRepeat() {
1.445 + return (Repeat) getProperty(Property.REPEAT);
1.446 + }
1.447 +
1.448 + /**
1.449 + * Returns the optional attachment property.
1.450 + * @return the ATTACH property or null if not specified
1.451 + */
1.452 + public final Attach getAttachment() {
1.453 + return (Attach) getProperty(Property.ATTACH);
1.454 + }
1.455 +
1.456 + /**
1.457 + * Returns the optional description property.
1.458 + * @return the DESCRIPTION property or null if not specified
1.459 + */
1.460 + public final Description getDescription() {
1.461 + return (Description) getProperty(Property.DESCRIPTION);
1.462 + }
1.463 +
1.464 + /**
1.465 + * Returns the optional summary property.
1.466 + * @return the SUMMARY property or null if not specified
1.467 + */
1.468 + public final Summary getSummary() {
1.469 + return (Summary) getProperty(Property.SUMMARY);
1.470 + }
1.471 +}
