001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.acacia.shared;
029
030import org.opencms.util.CmsUUID;
031
032import java.util.Date;
033import java.util.SortedSet;
034
035/** Interface to access serial date values easily. Used on client and server. */
036public interface I_CmsSerialDateValue {
037
038    /** Different types of serial dates. */
039    public enum DateType {
040        /** Only a single date is specified, which is not extracted from a series. */
041        SINGLE,
042        /** The date was extracted from a series. */
043        EXTRACTED,
044        /** A whole series of dates is specified. */
045        SERIES;
046    }
047
048    /** Different types of conditions how serial dates can end. */
049    public enum EndType {
050        /** There is no end type, all dates are specified explicitly */
051        SINGLE,
052        /** An explicit end date is specified. */
053        DATE,
054        /** A number of occurrences for the event is specified */
055        TIMES;
056    }
057
058    /** The JSON keys used in the JSON representation of serial date specifications. */
059    static final class JsonKey {
060
061        /** Start time of the first event. */
062        public static final String START = "from";
063
064        /** End time of the first event. */
065        public static final String END = "to";
066
067        /** Flag, indicating if the event last the whole day/whole days, or not. */
068        public static final String WHOLE_DAY = "wholeday";
069
070        /** Sub-object with the pattern related information. */
071        public static final String PATTERN = "pattern";
072
073        /** The pattern type. */
074        public static final String PATTERN_TYPE = "type";
075
076        /** The pattern specific interval. */
077        public static final String PATTERN_INTERVAL = "interval";
078
079        /** Flag, indicating if the event takes place every working day. */
080        public static final String PATTERN_EVERYWORKINGDAY = "everyworkingday";
081
082        /** Array with the weekdays, the event takes place. */
083        public static final String PATTERN_WEEKDAYS = "weekdays";
084
085        /** The day of the month where the event takes place. */
086        public static final String PATTERN_DAY_OF_MONTH = "day";
087
088        /** Array with the weeks of the month where the event takes place. */
089        public static final String PATTERN_WEEKS_OF_MONTH = "weeks";
090
091        /** Array with individual dates where the event takes place. */
092        public static final String PATTERN_DATES = "dates";
093
094        /** The month where the event takes place. */
095        public static final String PATTERN_MONTH = "month";
096
097        /** Array with dates where the event does not take place. */
098        public static final String EXCEPTIONS = "exceptions";
099
100        /** The last day the event can potentially take place. */
101        public static final String SERIES_ENDDATE = "enddate";
102
103        /** The maximal number of occurrences of the event. */
104        public static final String SERIES_OCCURRENCES = "occurrences";
105
106        /** The uuid of the series content, the event originally belonged to. */
107        public static final String PARENT_SERIES = "parentseries";
108
109        /** Flag, indicating if events are "current" events till the end, or only till the beginning. */
110        public static final String CURRENT_TILL_END = "currenttillend";
111    }
112
113    /** Months as enumeration. */
114    public enum Month {
115        /** January */
116        JANUARY,
117        /** February */
118        FEBRUARY,
119        /** March */
120        MARCH,
121        /** April */
122        APRIL,
123        /** May */
124        MAY,
125        /** June */
126        JUNE,
127        /** July */
128        JULY,
129        /** August */
130        AUGUST,
131        /** September */
132        SEPTEMBER,
133        /** October */
134        OCTOBER,
135        /** November */
136        NOVEMBER,
137        /** December */
138        DECEMBER;
139
140        /**
141         * Returns the (maximal) number of days the month can have.
142         * I.e., for February 29 and for the other months either 30 or 31 depending on the month.
143         * @return the (maximal) number of days the month can have.
144         */
145        public int getMaximalDay() {
146
147            switch (this) {
148                case JANUARY:
149                    return 31;
150                case FEBRUARY:
151                    return 29;
152                case MARCH:
153                    return 31;
154                case APRIL:
155                    return 30;
156                case MAY:
157                    return 31;
158                case JUNE:
159                    return 30;
160                case JULY:
161                    return 31;
162                case AUGUST:
163                    return 31;
164                case SEPTEMBER:
165                    return 30;
166                case OCTOBER:
167                    return 31;
168                case NOVEMBER:
169                    return 30;
170                case DECEMBER:
171                    return 31;
172                default:
173                    throw new IllegalArgumentException();
174            }
175        }
176    }
177
178    /** Type of the series. E.g., daily, weekly, etc. */
179    public enum PatternType {
180        /** No series at all. */
181        NONE,
182        /** Series is specified on a daily base. */
183        DAILY,
184        /** Series is specified on a weekly base. */
185        WEEKLY,
186        /** Series is specified on a monthly base. */
187        MONTHLY,
188        /** Series is specified on a yearly base. */
189        YEARLY,
190        /** Series is specified by individual dates. */
191        INDIVIDUAL;
192    }
193
194    /** Enumeration representing the week days. */
195    public enum WeekDay {
196        /** Sunday */
197        SUNDAY,
198        /** Monday */
199        MONDAY,
200        /** Tuesday */
201        TUESDAY,
202        /** Wednesday */
203        WEDNESDAY,
204        /** Thursday */
205        THURSDAY,
206        /** Friday */
207        FRIDAY,
208        /** Saturday */
209        SATURDAY;
210
211        /** Conversion of integers to weekdays. The conversion is NOT the inverse of the ordinals.
212         * The enumeration here starts with 1, i.e., fromInt(i).ordinal() == i-1.
213         * The shift is added to get the numbers as used in {@link java.util.Calendar}.
214         * @param i the number of the weekday (starting with 1 for Sunday)
215         * @return the {@link WeekDay} that corresponds to the given number.
216         */
217        public static WeekDay fromInt(int i) {
218
219            switch (i) {
220                case 1:
221                    return WeekDay.SUNDAY;
222                case 2:
223                    return WeekDay.MONDAY;
224                case 3:
225                    return WeekDay.TUESDAY;
226                case 4:
227                    return WeekDay.WEDNESDAY;
228                case 5:
229                    return WeekDay.THURSDAY;
230                case 6:
231                    return WeekDay.FRIDAY;
232                case 7:
233                    return WeekDay.SATURDAY;
234                default:
235                    throw new IllegalArgumentException();
236            }
237        }
238
239        /**Object
240         * Converts the {@link WeekDay} to it's corresponding number, i.e. it's ordinal plus 1.
241         * The numbers correspond to the numbers for weekdays used by {@link java.util.Calendar}.
242         *
243         * @return the number corresponding to the weekday.
244         */
245        public int toInt() {
246
247            return this.ordinal() + 1;
248        }
249    }
250
251    /** Possible weeks of a month. */
252    public enum WeekOfMonth {
253        /** The first week of a month. */
254        FIRST,
255        /** The second week of a month. */
256        SECOND,
257        /** The third week of a month. */
258        THIRD,
259        /** The fourth week of a month. */
260        FOURTH,
261        /** The last week of a month. */
262        LAST
263    }
264
265    /** Constant for the milliseconds of a day. */
266    static final long DAY_IN_MILLIS = 1000 * 60 * 60 * 24;
267
268    /** The number of weekdays (seven). */
269    static final int NUM_OF_WEEKDAYS = 7;
270
271    /**
272     * Returns a flag, indicating if the event ends at midnight.
273     * @return a flag, indicating if the event ends at midnight.
274     */
275    boolean endsAtMidNight();
276
277    /**
278     * Returns the type of the specified date.
279     * @return the type of the specified date.
280     */
281    DateType getDateType();
282
283    /**
284     * Returns the day of the month, the events should take place.
285     * @return the day of the month, the events should take place.
286     */
287    int getDayOfMonth();
288
289    /**
290     * Returns the end time of the events.
291     * @return the end time of the events.
292     */
293    Date getEnd();
294
295    /**
296     * Returns the end type of the event series.
297     * @return the end type of the event series.
298     */
299    EndType getEndType();
300
301    /**
302     * Returns the dates, where the event should not take place.
303     * @return the dates, where the event should not take place.
304     */
305    SortedSet<Date> getExceptions();
306
307    /**
308     * Returns the dates of an individual date series.
309     * @return the dates of an individual date series.
310     */
311    SortedSet<Date> getIndividualDates();
312
313    /**
314     * Returns the pattern type specific interval of the event.
315     * @return the pattern type specific interval of the event.
316     */
317    int getInterval();
318
319    /**
320     * Returns the month in which the events take place.
321     * @return the month in which the events take place.
322     */
323    Month getMonth();
324
325    /**
326     * Returns the number of occurrences of the event.
327     * @return the number of occurrences of the event.
328     */
329    int getOccurrences();
330
331    /**
332     * Returns the uuid of the content that holds the series, the current event was extracted from.
333     * Or <code>null</code> if the current event series was not extracted from another one.
334     * @return the uuid of the original series' content,
335     *         or <code>null<code>, if the event is not extracted from another event series.
336     */
337    CmsUUID getParentSeriesId();
338
339    /**
340     * Returns the pattern type of the event series.
341     * @return the pattern type of the event series.
342     */
343    PatternType getPatternType();
344
345    /**
346     * Returns the date of the last day, events of the series should take place.
347     * @return the date of the last day, events of the series should take place.
348     */
349    Date getSeriesEndDate();
350
351    /**
352     * Returns the start time of the events.
353     * @return the start time of the events.
354     */
355    Date getStart();
356
357    /**
358     * Returns the week day where the event should take place.
359     * @return the week day where the event should take place.
360     */
361    WeekDay getWeekDay();
362
363    /**
364     * Returns the week days where the event should take place.
365     * @return the week days where the event should take place.
366     */
367    SortedSet<WeekDay> getWeekDays();
368
369    /**
370     * Returns the week of the month, the event should take place.
371     * @return the week of the month, the event should take place.
372     */
373    WeekOfMonth getWeekOfMonth();
374
375    /**
376     * Returns the weeks of the month, the event should take place.
377     * @return the weeks of the month, the event should take place.
378     */
379    SortedSet<WeekOfMonth> getWeeksOfMonth();
380
381    /**
382     * Returns a flag, indicating if the events should be treated as "current" till they end (or only till they start).
383     * @return <code>true</code> if the event is "current" till it ends, <code>false</code> if it is current till it starts.
384     */
385    boolean isCurrentTillEnd();
386
387    /**
388     * Returns a flag, indicating if the event should take place every working day.
389     * @return a flag, indicating if the event should take place every working day.
390     */
391    boolean isEveryWorkingDay();
392
393    /**
394     * Returns a flag, indicating if the event is extracted from another series.
395     * @return a flag, indicating if the event is extracted from another series.
396     */
397    boolean isFromOtherSeries();
398
399    /**
400     * Returns a flag, indicating if the value specifies a valid date (series).
401     * @return a flag, indicating if the value specifies a valid date (series).
402     */
403    boolean isValid();
404
405    /**
406     * Returns a flag, indicating if the event last the whole day/whole days.
407     * @return a flag, indicating if the event last the whole day/whole days.
408     */
409    boolean isWholeDay();
410
411}