001package biweekly.property;
002
003import java.util.Date;
004import java.util.List;
005
006import biweekly.ICalVersion;
007import biweekly.Warning;
008import biweekly.component.ICalComponent;
009import biweekly.parameter.Related;
010import biweekly.util.Duration;
011
012/*
013 Copyright (c) 2013-2015, Michael Angstadt
014 All rights reserved.
015
016 Redistribution and use in source and binary forms, with or without
017 modification, are permitted provided that the following conditions are met: 
018
019 1. Redistributions of source code must retain the above copyright notice, this
020 list of conditions and the following disclaimer. 
021 2. Redistributions in binary form must reproduce the above copyright notice,
022 this list of conditions and the following disclaimer in the documentation
023 and/or other materials provided with the distribution. 
024
025 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
026 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
027 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
028 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
029 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
030 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
031 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
032 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
033 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
034 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
035 */
036
037/**
038 * <p>
039 * Defines when to trigger an alarm.
040 * </p>
041 * <p>
042 * <b>Code sample:</b>
043 * 
044 * <pre class="brush:java">
045 * //15 minutes before the start time
046 * Duration duration = Duration.builder().prior(true).minutes(15).build();
047 * Trigger trigger = new Trigger(duration, Related.START);
048 * VAlarm alarm = VAlarm.display(trigger, &quot;Meeting in 15 minutes&quot;);
049 * </pre>
050 * 
051 * </p>
052 * @author Michael Angstadt
053 * @see <a href="http://tools.ietf.org/html/rfc5545#page-133">RFC 5545
054 * p.133-6</a>
055 * @see <a href="http://tools.ietf.org/html/rfc2445#page-127">RFC 2445
056 * p.127-9</a>
057 */
058public class Trigger extends ICalProperty {
059        private Duration duration;
060        private Date date;
061
062        /**
063         * Creates a trigger property.
064         * @param duration the relative time
065         * @param related the date-time field that the duration is relative to
066         */
067        public Trigger(Duration duration, Related related) {
068                setDuration(duration, related);
069        }
070
071        /**
072         * Creates a trigger property.
073         * @param date the date-time the alarm will trigger.
074         */
075        public Trigger(Date date) {
076                setDate(date);
077        }
078
079        /**
080         * Gets the relative time at which the alarm will trigger.
081         * @return the relative time or null if an absolute time is set
082         */
083        public Duration getDuration() {
084                return duration;
085        }
086
087        /**
088         * Sets a relative time at which the alarm will trigger.
089         * @param duration the relative time
090         * @param related the date-time field that the duration is relative to
091         */
092        public void setDuration(Duration duration, Related related) {
093                this.date = null;
094                this.duration = duration;
095                setRelated(related);
096        }
097
098        /**
099         * Gets the date-time that the alarm will trigger.
100         * @return the date-time or null if a relative duration is set
101         */
102        public Date getDate() {
103                return date;
104        }
105
106        /**
107         * Sets the date-time that the alarm will trigger.
108         * @param date the date-time the alarm will trigger.
109         */
110        public void setDate(Date date) {
111                this.date = date;
112                this.duration = null;
113                setRelated(null);
114        }
115
116        /**
117         * Gets the date-time field that the duration is relative to.
118         * @return the field or null if not set
119         * @see <a href="http://tools.ietf.org/html/rfc5545#page-24">RFC 5545
120         * p.24</a>
121         */
122        public Related getRelated() {
123                return parameters.getRelated();
124        }
125
126        /**
127         * Sets the date-time field that the duration is relative to.
128         * @param related the field or null to remove
129         * @see <a href="http://tools.ietf.org/html/rfc5545#page-24">RFC 5545
130         * p.24</a>
131         */
132        public void setRelated(Related related) {
133                parameters.setRelated(related);
134        }
135
136        @Override
137        protected void validate(List<ICalComponent> components, ICalVersion version, List<Warning> warnings) {
138                if (duration == null && date == null) {
139                        warnings.add(Warning.validate(33));
140                }
141
142                Related related = getRelated();
143                if (duration != null && related == null) {
144                        warnings.add(Warning.validate(10));
145                }
146        }
147}