1 /*
2 * ==================================================================== The
3 * Apache Software License, Version 1.1
4 *
5 * Copyright (c) 2003 Digital Clash LLC. All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met: 1.
9 * Redistributions of source code must retain the above copyright notice, this
10 * list of conditions and the following disclaimer. 2. Redistributions in
11 * binary form must reproduce the above copyright notice, this list of
12 * conditions and the following disclaimer in the documentation and/or other
13 * materials provided with the distribution. 3. The end-user documentation
14 * included with the redistribution, if any, must include the following
15 * acknowledgment: "This product includes software developed by the ChronicJ
16 * team (http://www.chronicj.org/)." Alternately, this acknowledgment may
17 * appear in the software itself, if and wherever such third-party
18 * acknowledgments normally appear. 4. The names "ChronicJ" and "Digital Clash"
19 * not be used to endorse or promote products derived from this software
20 * without prior written permission. For written permission, please contact
21 * info@digitalclash.com. 5. Products derived from this software may not be
22 * called "ChronicJ", "Digital Clash", nor may "ChronicJ" or "Digital Clash"
23 * appear in their name, without prior written permission of Digital Clash LLC.
24 *
25 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
26 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
27 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
28 * APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
29 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
30 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
31 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
32 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
34 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
35 * ==================================================================== This
36 * product includes software developed by the by the Apache Software Foundation
37 * (http://www.apache.org/).
38 * ====================================================================
39 */
40 package org.chronicj;
41
42 import java.util.List;
43
44 /***
45 * <p>
46 * Represents a coherent collection of logical events that are expected to
47 * occur over the course of time. A <code>Schedule</code> is composed of zero
48 * or more {@link org.chronicj.ScheduleElement ScheduleElement}s which are
49 * queried to handle requests for schedule information.
50 * </p>
51 *
52 * <p>
53 * Schedule also provides the public API for adding, editing and removing
54 * scheduled events for a given entity.
55 * </p>
56 *
57 * <p>
58 * This class is based directly on patterns described in a paper by Martin
59 * Fowler which can be found <a
60 * href="http://martinfowler.com/apsupp/recurring.pdf">here</a>.
61 * </p>
62 *
63 * @author <a href="mlipper@US-ABP.com">Matthew Lipper</a>
64 *
65 * @see <a href="http://martinfowler.com/apsupp/recurring.pdf">Recurring
66 * Events for Calendars</a>
67 */
68 public interface Schedule
69 {
70 /***
71 * Determines if a given event occurs during a particular instant in time.
72 *
73 * @param anEvent
74 * the Event whose schedule is being queried
75 * @param aTimePoint
76 * the moment in time
77 *
78 * @return a boolean value indicating whether the event occurs during the
79 * specified TimePoint
80 */
81 public boolean isOccuring(Event anEvent, TimePoint aTimePoint);
82
83 /***
84 * Determines if a given event occurs within a particular date range for
85 * this schedule.
86 *
87 * @param anEvent
88 * the Event whose schedule is being queried
89 * @param aDateRange
90 * the time period in which to check schedule information
91 *
92 * @return a boolean value indicating whether the event occurs within the
93 * specified DateRange
94 */
95 public boolean isOccuring(Event anEvent, DateRange aDateRange);
96
97 /***
98 * Returns a {@link java.util.List List}of
99 * {@link org.chronicj.TimePoint TimePoint}s on which the supplied event
100 * occurs given the specified {@link DateRange}.
101 *
102 * @param anEvent
103 * the Event whose schedule is being queried
104 * @param aDateRange
105 * the time period in which to check schedule information
106 *
107 * @return a boolean value indicating whether the event occurs within the
108 * specified DateRange
109 */
110 public List dates(Event anEvent, DateRange during);
111
112 /***
113 * Returns a {@link TimePoint}indicating the next occurence of the
114 * supplied {@link Event}on or after the given point in time.
115 *
116 * @param anEvent
117 * the Event whose schedule is being queried
118 * @param aTimePoint
119 * point in time after which to check the Event's next
120 * occurrence.
121 *
122 * @return a boolean value indicating whether the event occurs within the
123 * specified DateRange
124 */
125 public TimePoint nextOccurence(Event anEvent, TimePoint aTimePoint);
126
127 /***
128 * Adds an {@link Event Event}whose occurance is determined by the given
129 * {@link TemporalExpression}.
130 *
131 * @param anEvent
132 * the Event to add
133 * @param aTemporalExpression
134 * the date/time(s) when this Event occurs.
135 */
136 public void add(Event anEvent, TemporalExpression aTemporalExpression);
137 }
This page was automatically generated by Maven