/
VFreeBusy.java
625 lines (558 loc) · 24.2 KB
/
VFreeBusy.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
/**
* Copyright (c) 2012, Ben Fortuna
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* o Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* o Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* o Neither the name of Ben Fortuna nor the names of any other contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
package net.fortuna.ical4j.model.component;
import net.fortuna.ical4j.model.*;
import net.fortuna.ical4j.model.parameter.FbType;
import net.fortuna.ical4j.model.property.*;
import net.fortuna.ical4j.validate.ComponentValidator;
import net.fortuna.ical4j.validate.ValidationException;
import net.fortuna.ical4j.validate.ValidationRule;
import net.fortuna.ical4j.validate.Validator;
import net.fortuna.ical4j.validate.component.VFreeBusyValidator;
import org.threeten.extra.Interval;
import java.time.Instant;
import java.time.temporal.Temporal;
import java.time.temporal.TemporalAmount;
import java.util.*;
import static net.fortuna.ical4j.model.Property.*;
import static net.fortuna.ical4j.validate.ValidationRule.ValidationType.*;
/**
* $Id$ [Apr 5, 2004]
*
* Defines an iCalendar VFREEBUSY component.
*
* <pre>
* 4.6.4 Free/Busy Component
*
* Component Name: VFREEBUSY
*
* Purpose: Provide a grouping of component properties that describe
* either a request for free/busy time, describe a response to a request
* for free/busy time or describe a published set of busy time.
*
* Formal Definition: A "VFREEBUSY" calendar component is defined by the
* following notation:
*
* freebusyc = "BEGIN" ":" "VFREEBUSY" CRLF
* fbprop
* "END" ":" "VFREEBUSY" CRLF
*
* fbprop = *(
*
* ; the following are optional,
* ; but MUST NOT occur more than once
*
* contact / dtstart / dtend / duration / dtstamp /
* organizer / uid / url /
*
* ; the following are optional,
* ; and MAY occur more than once
*
* attendee / comment / freebusy / rstatus / x-prop
*
* )
*
* Description: A "VFREEBUSY" calendar component is a grouping of
* component properties that represents either a request for, a reply to
* a request for free or busy time information or a published set of
* busy time information.
*
* When used to request free/busy time information, the "ATTENDEE"
* property specifies the calendar users whose free/busy time is being
* requested; the "ORGANIZER" property specifies the calendar user who
* is requesting the free/busy time; the "DTSTART" and "DTEND"
* properties specify the window of time for which the free/busy time is
* being requested; the "UID" and "DTSTAMP" properties are specified to
* assist in proper sequencing of multiple free/busy time requests.
*
* When used to reply to a request for free/busy time, the "ATTENDEE"
* property specifies the calendar user responding to the free/busy time
* request; the "ORGANIZER" property specifies the calendar user that
* originally requested the free/busy time; the "FREEBUSY" property
* specifies the free/busy time information (if it exists); and the
* "UID" and "DTSTAMP" properties are specified to assist in proper
* sequencing of multiple free/busy time replies.
*
* When used to publish busy time, the "ORGANIZER" property specifies
* the calendar user associated with the published busy time; the
* "DTSTART" and "DTEND" properties specify an inclusive time window
* that surrounds the busy time information; the "FREEBUSY" property
* specifies the published busy time information; and the "DTSTAMP"
* property specifies the date/time that iCalendar object was created.
*
* The "VFREEBUSY" calendar component cannot be nested within another
* calendar component. Multiple "VFREEBUSY" calendar components can be
* specified within an iCalendar object. This permits the grouping of
* Free/Busy information into logical collections, such as monthly
* groups of busy time information.
*
* The "VFREEBUSY" calendar component is intended for use in iCalendar
* object methods involving requests for free time, requests for busy
* time, requests for both free and busy, and the associated replies.
*
* Free/Busy information is represented with the "FREEBUSY" property.
* This property provides a terse representation of time periods. One or
* more "FREEBUSY" properties can be specified in the "VFREEBUSY"
* calendar component.
*
* When present in a "VFREEBUSY" calendar component, the "DTSTART" and
* "DTEND" properties SHOULD be specified prior to any "FREEBUSY"
* properties. In a free time request, these properties can be used in
* combination with the "DURATION" property to represent a request for a
* duration of free time within a specified window of time.
*
* The recurrence properties ("RRULE", "EXRULE", "RDATE", "EXDATE") are
* not permitted within a "VFREEBUSY" calendar component. Any recurring
* events are resolved into their individual busy time periods using the
* "FREEBUSY" property.
*
* Example: The following is an example of a "VFREEBUSY" calendar
* component used to request free or busy time information:
*
* BEGIN:VFREEBUSY
* ORGANIZER:MAILTO:jane_doe@host1.com
* ATTENDEE:MAILTO:john_public@host2.com
* DTSTART:19971015T050000Z
* DTEND:19971016T050000Z
* DTSTAMP:19970901T083000Z
* END:VFREEBUSY
*
* The following is an example of a "VFREEBUSY" calendar component used
* to reply to the request with busy time information:
*
* BEGIN:VFREEBUSY
* ORGANIZER:MAILTO:jane_doe@host1.com
* ATTENDEE:MAILTO:john_public@host2.com
* DTSTAMP:19970901T100000Z
* FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M,
* 19971015T160000Z/PT5H30M,19971015T223000Z/PT6H30M
* URL:http://host2.com/pub/busy/jpublic-01.ifb
* COMMENT:This iCalendar file contains busy time information for
* the next three months.
* END:VFREEBUSY
*
* The following is an example of a "VFREEBUSY" calendar component used
* to publish busy time information.
*
* BEGIN:VFREEBUSY
* ORGANIZER:jsmith@host.com
* DTSTART:19980313T141711Z
* DTEND:19980410T141711Z
* FREEBUSY:19980314T233000Z/19980315T003000Z
* FREEBUSY:19980316T153000Z/19980316T163000Z
* FREEBUSY:19980318T030000Z/19980318T040000Z
* URL:http://www.host.com/calendar/busytime/jsmith.ifb
* END:VFREEBUSY
* </pre>
*
* Example 1 - Requesting all busy time slots for a given period:
*
* <pre><code>
* // request all busy times between today and 1 week from now..
* DateTime start = new DateTime();
* DateTime end = new DateTime(start.getTime() + 1000 * 60 * 60 * 24 * 7);
*
* VFreeBusy request = new VFreeBusy(start, end);
*
* VFreeBusy reply = new VFreeBusy(request, calendar.getComponents());
* </code></pre>
*
* Example 2 - Requesting all free time slots for a given period of at least the specified duration:
*
* <pre><code>
* // request all free time between today and 1 week from now of
* // duration 2 hours or more..
* DateTime start = new DateTime();
* DateTime end = new DateTime(start.getTime() + 1000 * 60 * 60 * 24 * 7);
*
* VFreeBusy request = new VFreeBusy(start, end, new Dur(0, 2, 0, 0));
*
* VFreeBusy response = new VFreeBusy(request, myCalendar.getComponents());
* </code></pre>
*
* @author Ben Fortuna
*/
public class VFreeBusy extends CalendarComponent implements ComponentContainer<Component> {
private static final long serialVersionUID = 1046534053331139832L;
private static final Map<Method, Validator<VFreeBusy>> methodValidators = new HashMap<>();
static {
methodValidators.put(Method.PUBLISH, new ComponentValidator<VFreeBusy>(new ValidationRule(OneOrMore, FREEBUSY),
new ValidationRule(One, DTSTAMP, DTSTART, DTEND, ORGANIZER, UID),
new ValidationRule(OneOrLess, URL),
new ValidationRule(None, ATTENDEE, DURATION, REQUEST_STATUS)));
methodValidators.put(Method.REPLY, new ComponentValidator(new ValidationRule(One, ATTENDEE, DTSTAMP, DTEND, DTSTART, ORGANIZER, UID),
new ValidationRule(OneOrLess, URL),
new ValidationRule(None, DURATION, SEQUENCE)));
methodValidators.put(Method.REQUEST, new ComponentValidator(new ValidationRule(OneOrMore, ATTENDEE),
new ValidationRule(One, DTEND, DTSTAMP, DTSTART, ORGANIZER, UID),
new ValidationRule(None, FREEBUSY, DURATION, REQUEST_STATUS, URL)));
}
private final Validator<VFreeBusy> validator = new ComponentValidator<>(
new ValidationRule<>(One, true, UID, DTSTAMP),
new ValidationRule<>(OneOrLess, CONTACT, DTSTART, DTEND, DURATION, DTSTAMP, ORGANIZER, UID, URL),
new ValidationRule<>(None, RRULE, EXRULE, RDATE, EXDATE)
);
/**
* Default constructor.
*/
public VFreeBusy() {
this(true);
}
public VFreeBusy(boolean initialise) {
super(VFREEBUSY);
if (initialise) {
add(new DtStamp());
}
}
/**
* Constructor.
* @param properties a list of properties
*/
public VFreeBusy(final PropertyList properties) {
super(VFREEBUSY, properties);
}
/**
* Constructs a new VFreeBusy instance with the specified start and end boundaries. This constructor should be used
* for requesting busy time for a specified period.
* @param start the starting boundary for the VFreeBusy
* @param end the ending boundary for the VFreeBusy
*/
public VFreeBusy(final Temporal start, final Temporal end) {
this();
// 4.8.2.4 Date/Time Start:
//
// Within the "VFREEBUSY" calendar component, this property defines the
// start date and time for the free or busy time information. The time
// MUST be specified in UTC time.
add(new DtStart<>(start));
// 4.8.2.2 Date/Time End
//
// Within the "VFREEBUSY" calendar component, this property defines the
// end date and time for the free or busy time information. The time
// MUST be specified in the UTC time format. The value MUST be later in
// time than the value of the "DTSTART" property.
add(new DtEnd<>(end));
}
/**
* Constructs a new VFreeBusy instance with the specified start and end boundaries. This constructor should be used
* for requesting free time for a specified duration in given period defined by the start date and end date.
* @param start the starting boundary for the VFreeBusy
* @param end the ending boundary for the VFreeBusy
* @param duration the length of the period being requested
*/
public VFreeBusy(final Instant start, final Instant end, final TemporalAmount duration) {
this();
// 4.8.2.4 Date/Time Start:
//
// Within the "VFREEBUSY" calendar component, this property defines the
// start date and time for the free or busy time information. The time
// MUST be specified in UTC time.
add(new DtStart<>(start));
// 4.8.2.2 Date/Time End
//
// Within the "VFREEBUSY" calendar component, this property defines the
// end date and time for the free or busy time information. The time
// MUST be specified in the UTC time format. The value MUST be later in
// time than the value of the "DTSTART" property.
add(new DtEnd<>(end));
add(new Duration(duration));
}
/**
* Constructs a new VFreeBusy instance representing a reply to the specified VFREEBUSY request according to the
* specified list of components.
* If the request argument has its duration set, then the result
* represents a list of <em>free</em> times (that is, parameter FBTYPE
* is set to FbType.FREE).
* If the request argument does not have its duration set, then the result
* represents a list of <em>busy</em> times.
* @param request a VFREEBUSY request
* @param components a component list used to initialise busy time
* @throws ValidationException
*/
public VFreeBusy(final VFreeBusy request, final List<CalendarComponent> components) {
this();
final DtStart<?> start;
final DtEnd<?> end;
start = request.getRequiredProperty(DTSTART);
end = request.getRequiredProperty(DTEND);
// ensure the request is valid..
request.validate();
final Optional<Duration> duration = request.getProperty(DURATION);
// 4.8.2.4 Date/Time Start:
//
// Within the "VFREEBUSY" calendar component, this property defines the
// start date and time for the free or busy time information. The time
// MUST be specified in UTC time.
add(new DtStart<>(start.getDate()));
// 4.8.2.2 Date/Time End
//
// Within the "VFREEBUSY" calendar component, this property defines the
// end date and time for the free or busy time information. The time
// MUST be specified in the UTC time format. The value MUST be later in
// time than the value of the "DTSTART" property.
add(new DtEnd<>(end.getDate()));
final Instant fbStart = Instant.from(start.getDate());
final Instant fbEnd = Instant.from(end.getDate());
FreeBusy fb;
if (duration.isPresent()) {
add(new Duration(duration.get().getDuration()));
// Initialise with all free time of at least the specified duration..
fb = new FreeTimeBuilder().start(fbStart).end(fbEnd).duration(duration.get().getDuration())
.components(components).build();
} else {
// initialise with all busy time for the specified period..
fb = new BusyTimeBuilder().start(fbStart).end(fbEnd)
.components(components).build();
}
if (!fb.getPeriods().isEmpty()) {
add(fb);
}
}
/**
* Create a FREEBUSY property representing the busy time for the specified component list. If the component is not
* applicable to FREEBUSY time, or if the component is outside the bounds of the start and end dates, null is
* returned. If no valid busy periods are identified in the component an empty FREEBUSY property is returned (i.e.
* empty period list).
*/
private static class BusyTimeBuilder {
private Instant start;
private Instant end;
private List<CalendarComponent> components;
public BusyTimeBuilder start(Instant start) {
this.start = start;
return this;
}
public BusyTimeBuilder end(Instant end) {
this.end = end;
return this;
}
public BusyTimeBuilder components(List<CalendarComponent> components) {
this.components = components;
return this;
}
public FreeBusy build() {
// periods must be in UTC time for freebusy..
final List<Period<Instant>> periods = getConsumedTime(components, new Period<>(start, end));
periods.removeIf(period -> {
// check if period outside bounds..
return !period.intersects(new Period<>(start, end));
});
return new FreeBusy(periods);
}
}
/**
* Create a FREEBUSY property representing the free time available of the specified duration for the given list of
* components. component. If the component is not applicable to FREEBUSY time, or if the component is outside the
* bounds of the start and end dates, null is returned. If no valid busy periods are identified in the component an
* empty FREEBUSY property is returned (i.e. empty period list).
*/
private static class FreeTimeBuilder {
private Instant start;
private Instant end;
private TemporalAmount duration;
private List<CalendarComponent> components;
public FreeTimeBuilder start(Instant start) {
this.start = start;
return this;
}
public FreeTimeBuilder end(Instant end) {
this.end = end;
return this;
}
private FreeTimeBuilder duration(TemporalAmount duration) {
this.duration = duration;
return this;
}
public FreeTimeBuilder components(List<CalendarComponent> components) {
this.components = components;
return this;
}
public FreeBusy build() {
final List<Period<Instant>> periods = getConsumedTime(components, new Period<>(start, end));
final Interval interval = Interval.of(start, end);
// Add final consumed time to avoid special-case end-of-list processing
periods.add(new Period<>(end, end));
Instant lastPeriodEnd = start;
List<Period<Instant>> freePeriods = new ArrayList<>();
// where no time is consumed set the last period end as the range start..
for (final Period<Instant> period : periods) {
// check if period outside bounds.. or period intersects with the end of the range..
if (interval.encloses(period.toInterval()) ||
(interval.overlaps(period.toInterval())
&& Instant.from(period.getStart()).isAfter(Instant.from(interval.getStart())))) {
// calculate duration between this period start and last period end..
final Duration freeDuration = new Duration(lastPeriodEnd, period.getStart());
if (new TemporalAmountComparator().compare(freeDuration.getDuration(), duration) >= 0) {
freePeriods.add(new Period<>(lastPeriodEnd, freeDuration.getDuration()));
}
}
if (Instant.from(period.getEnd()).isAfter(lastPeriodEnd)) {
lastPeriodEnd = Instant.from(period.getEnd());
}
}
ParameterList fbParams = new ParameterList(Collections.singletonList(FbType.FREE));
final FreeBusy fb = new FreeBusy(fbParams, freePeriods);
return fb;
}
}
/**
* Creates a list of periods representing the time consumed by the specified list of components.
* @param components
* @return
*/
private static <T extends Temporal> List<Period<T>> getConsumedTime(final List<CalendarComponent> components,
final Period<T> range) {
List<Period<T>> periods = new ArrayList<>();
// only events consume time..
components.stream().filter(c -> c.getName().equals(Component.VEVENT)).forEach(
c -> periods.addAll(((VEvent) c).getConsumedTime(range, false)));
return new ArrayList<>(new PeriodList(periods).normalise().getPeriods());
}
/**
* {@inheritDoc}
*/
@Override
public final void validate(final boolean recurse) throws ValidationException {
new VFreeBusyValidator().validate(this);
if (recurse) {
validateProperties();
}
}
/**
* Performs method-specific ITIP validation.
* @param method the applicable method
* @throws ValidationException where the component does not comply with RFC2446
*/
public void validate(Method method) throws ValidationException {
final Validator<VFreeBusy> validator = methodValidators.get(method);
if (validator != null) {
validator.validate(this);
}
else {
super.validate(method);
}
}
/**
*
* @return Returns the underlying component list.
*/
@Override
public ComponentList<Component> getComponentList() {
return (ComponentList<Component>) components;
}
@Override
public void setComponentList(ComponentList<Component> components) {
this.components = components;
}
/**
* @return the CONTACT property or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<Contact> getContact() {
return getProperty(CONTACT);
}
/**
* @return the DTSTART propery or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<DtStart<?>> getStartDate() {
return getProperty(DTSTART);
}
/**
* @return the DTEND property or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<DtEnd<?>> getEndDate() {
return getProperty(DTEND);
}
/**
* @return the DURATION property or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<Duration> getDuration() {
return getProperty(DURATION);
}
/**
* @return the DTSTAMP property or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<DtStamp> getDateStamp() {
return getProperty(DTSTAMP);
}
/**
* @return the ORGANIZER property or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<Organizer> getOrganizer() {
return getProperty(ORGANIZER);
}
/**
* @return the URL property or null if not specified
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<Url> getUrl() {
return getProperty(URL);
}
/**
* Returns the UID property of this component if available.
* @return a Uid instance, or null if no UID property exists
* @deprecated use {@link VFreeBusy#getProperty(String)}
*/
@Deprecated
public final Optional<Uid> getUid() {
return getProperty(UID);
}
@Override
protected ComponentFactory<VFreeBusy> newFactory() {
return new Factory();
}
public static class Factory extends Content.Factory implements ComponentFactory<VFreeBusy> {
public Factory() {
super(VFREEBUSY);
}
@Override
public VFreeBusy createComponent() {
return new VFreeBusy(false);
}
@Override
public VFreeBusy createComponent(PropertyList properties) {
return new VFreeBusy(properties);
}
}
}