001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (https://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: https://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: https://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
116        /** January */
117        JANUARY,
118        /** February */
119        FEBRUARY,
120        /** March */
121        MARCH,
122        /** April */
123        APRIL,
124        /** May */
125        MAY,
126        /** June */
127        JUNE,
128        /** July */
129        JULY,
130        /** August */
131        AUGUST,
132        /** September */
133        SEPTEMBER,
134        /** October */
135        OCTOBER,
136        /** November */
137        NOVEMBER,
138        /** December */
139        DECEMBER;
140
141        /**
142         * Returns the (maximal) number of days the month can have.
143         * I.e., for February 29 and for the other months either 30 or 31 depending on the month.
144         * @return the (maximal) number of days the month can have.
145         */
146        public int getMaximalDay() {
147
148            switch (this) {
149                case JANUARY:
150                    return 31;
151                case FEBRUARY:
152                    return 29;
153                case MARCH:
154                    return 31;
155                case APRIL:
156                    return 30;
157                case MAY:
158                    return 31;
159                case JUNE:
160                    return 30;
161                case JULY:
162                    return 31;
163                case AUGUST:
164                    return 31;
165                case SEPTEMBER:
166                    return 30;
167                case OCTOBER:
168                    return 31;
169                case NOVEMBER:
170                    return 30;
171                case DECEMBER:
172                    return 31;
173                default:
174                    throw new IllegalArgumentException();
175            }
176        }
177    }
178
179    /** Type of the series. E.g., daily, weekly, etc. */
180    public enum PatternType {
181        /** No series at all. */
182        NONE,
183        /** Series is specified on a daily base. */
184        DAILY,
185        /** Series is specified on a weekly base. */
186        WEEKLY,
187        /** Series is specified on a monthly base. */
188        MONTHLY,
189        /** Series is specified on a yearly base. */
190        YEARLY,
191        /** Series is specified by individual dates. */
192        INDIVIDUAL;
193    }
194
195    /** Enumeration representing the week days. */
196    public enum WeekDay {
197
198        /** Sunday */
199        SUNDAY,
200        /** Monday */
201        MONDAY,
202        /** Tuesday */
203        TUESDAY,
204        /** Wednesday */
205        WEDNESDAY,
206        /** Thursday */
207        THURSDAY,
208        /** Friday */
209        FRIDAY,
210        /** Saturday */
211        SATURDAY;
212
213        /** Conversion of integers to weekdays. The conversion is NOT the inverse of the ordinals.
214         * The enumeration here starts with 1, i.e., fromInt(i).ordinal() == i-1.
215         * The shift is added to get the numbers as used in {@link java.util.Calendar}.
216         * @param i the number of the weekday (starting with 1 for Sunday)
217         * @return the {@link WeekDay} that corresponds to the given number.
218         */
219        public static WeekDay fromInt(int i) {
220
221            switch (i) {
222                case 1:
223                    return WeekDay.SUNDAY;
224                case 2:
225                    return WeekDay.MONDAY;
226                case 3:
227                    return WeekDay.TUESDAY;
228                case 4:
229                    return WeekDay.WEDNESDAY;
230                case 5:
231                    return WeekDay.THURSDAY;
232                case 6:
233                    return WeekDay.FRIDAY;
234                case 7:
235                    return WeekDay.SATURDAY;
236                default:
237                    throw new IllegalArgumentException();
238            }
239        }
240
241        /**Object
242         * Converts the {@link WeekDay} to it's corresponding number, i.e. it's ordinal plus 1.
243         * The numbers correspond to the numbers for weekdays used by {@link java.util.Calendar}.
244         *
245         * @return the number corresponding to the weekday.
246         */
247        public int toInt() {
248
249            return this.ordinal() + 1;
250        }
251    }
252
253    /** Possible weeks of a month. */
254    public enum WeekOfMonth {
255        /** The first week of a month. */
256        FIRST,
257        /** The second week of a month. */
258        SECOND,
259        /** The third week of a month. */
260        THIRD,
261        /** The fourth week of a month. */
262        FOURTH,
263        /** The last week of a month. */
264        LAST
265    }
266
267    /** Constant for the milliseconds of a day. */
268    static final long DAY_IN_MILLIS = 1000 * 60 * 60 * 24;
269
270    /** The number of weekdays (seven). */
271    static final int NUM_OF_WEEKDAYS = 7;
272
273    /**
274     * Returns a flag, indicating if the event ends at midnight.
275     * @return a flag, indicating if the event ends at midnight.
276     */
277    boolean endsAtMidNight();
278
279    /**
280     * Returns the type of the specified date.
281     * @return the type of the specified date.
282     */
283    DateType getDateType();
284
285    /**
286     * Returns the day of the month, the events should take place.
287     * @return the day of the month, the events should take place.
288     */
289    int getDayOfMonth();
290
291    /**
292     * Returns the end time of the events.
293     * @return the end time of the events.
294     */
295    Date getEnd();
296
297    /**
298     * Returns the end type of the event series.
299     * @return the end type of the event series.
300     */
301    EndType getEndType();
302
303    /**
304     * Returns the dates, where the event should not take place.
305     * @return the dates, where the event should not take place.
306     */
307    SortedSet<Date> getExceptions();
308
309    /**
310     * Returns the dates of an individual date series.
311     * @return the dates of an individual date series.
312     */
313    SortedSet<Date> getIndividualDates();
314
315    /**
316     * Returns the pattern type specific interval of the event.
317     * @return the pattern type specific interval of the event.
318     */
319    int getInterval();
320
321    /**
322     * Returns the month in which the events take place.
323     * @return the month in which the events take place.
324     */
325    Month getMonth();
326
327    /**
328     * Returns the number of occurrences of the event.
329     * @return the number of occurrences of the event.
330     */
331    int getOccurrences();
332
333    /**
334     * Returns the uuid of the content that holds the series, the current event was extracted from.
335     * Or <code>null</code> if the current event series was not extracted from another one.
336     * @return the uuid of the original series' content,
337     *         or <code>null<code>, if the event is not extracted from another event series.
338     */
339    CmsUUID getParentSeriesId();
340
341    /**
342     * Returns the pattern type of the event series.
343     * @return the pattern type of the event series.
344     */
345    PatternType getPatternType();
346
347    /**
348     * Returns the date of the last day, events of the series should take place.
349     * @return the date of the last day, events of the series should take place.
350     */
351    Date getSeriesEndDate();
352
353    /**
354     * Returns the start time of the events.
355     * @return the start time of the events.
356     */
357    Date getStart();
358
359    /**
360     * Returns the week day where the event should take place.
361     * @return the week day where the event should take place.
362     */
363    WeekDay getWeekDay();
364
365    /**
366     * Returns the week days where the event should take place.
367     * @return the week days where the event should take place.
368     */
369    SortedSet<WeekDay> getWeekDays();
370
371    /**
372     * Returns the week of the month, the event should take place.
373     * @return the week of the month, the event should take place.
374     */
375    WeekOfMonth getWeekOfMonth();
376
377    /**
378     * Returns the weeks of the month, the event should take place.
379     * @return the weeks of the month, the event should take place.
380     */
381    SortedSet<WeekOfMonth> getWeeksOfMonth();
382
383    /**
384     * Returns a flag, indicating if the events should be treated as "current" till they end (or only till they start).
385     * @return <code>true</code> if the event is "current" till it ends, <code>false</code> if it is current till it starts.
386     */
387    boolean isCurrentTillEnd();
388
389    /**
390     * Returns a flag, indicating if the event should take place every working day.
391     * @return a flag, indicating if the event should take place every working day.
392     */
393    boolean isEveryWorkingDay();
394
395    /**
396     * Returns a flag, indicating if the event is extracted from another series.
397     * @return a flag, indicating if the event is extracted from another series.
398     */
399    boolean isFromOtherSeries();
400
401    /**
402     * Returns a flag, indicating if the value specifies a valid date (series).
403     * @return a flag, indicating if the value specifies a valid date (series).
404     */
405    boolean isValid();
406
407    /**
408     * Returns a flag, indicating if the event last the whole day/whole days.
409     * @return a flag, indicating if the event last the whole day/whole days.
410     */
411    boolean isWholeDay();
412
413}