imip-agent

Annotated docs/wiki/EventRecurrences

1021:a04c967b2d8e
2015-11-06 Paul Boddie Removed the complicated "old" lock directory mechanism since the active lock directory should be protected by the "outside-in" attempts to create it while the dismantling operation occurs "inside-out".
paul@933 1
= Event Recurrences =
paul@933 2
paul@934 3
Events defined by iCalendar objects may recur when
paul@934 4
[[http://tools.ietf.org/html/rfc5545#section-3.8.5|recurrence component properties]]
paul@934 5
such as `RDATE` and `RRULE` are employed. Each recurrence of an event may then
paul@934 6
be referenced using
paul@934 7
[[http://tools.ietf.org/html/rfc5545#section-3.8.4.4|recurrence identifiers]],
paul@934 8
and such identifiers indicate the originally-specified start point of a
paul@934 9
particular recurrence (either implicitly specified by `RRULE` properties or
paul@934 10
explicitly specified by `RDATE` properties).
paul@933 11
paul@933 12
== Recurrence Identifier Stability ==
paul@933 13
paul@934 14
A recurrence retains the same identifier throughout its lifetime. Even if a
paul@934 15
recurrence's start date or time changes, it will still retain the same
paul@934 16
identifier in its `RECURRENCE-ID` property which will no longer reflect the
paul@934 17
currently-specified start point of the recurrence. Such identifier stability
paul@934 18
is intended to provide a means of identifying the original recurrence so that
paul@934 19
it can be hidden from any calendar or event descriptions and replaced with the
paul@934 20
modified version.
paul@933 21
paul@933 22
== Recurrences and Time Zones ==
paul@933 23
paul@934 24
Since recurrence identifiers may be defined using time zone information,
paul@934 25
imip-agent normalises the specified recurrence identifiers to UTC-based
paul@934 26
datetimes to minimise ambiguity. For example:
paul@934 27
paul@934 28
|| '''iCalendar Property'''                         || '''Normalised Value''' || '''UTC Datetime?''' ||
paul@934 29
|| `RECURRENCE-ID:20141114`                         || `20141114`             || No                  ||
paul@934 30
|| `RECURRENCE-ID:20141114T000000`                  || `20141114T000000`      || No                  ||
paul@934 31
|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114`        || `20141113T230000Z`     || Yes                 ||
paul@934 32
|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114T000000` || `20141113T230000Z`     || Yes                 ||
paul@934 33
|| `RECURRENCE-ID:20141114T000000Z`                 || `20141114T000000Z`     || Yes                 ||
paul@933 34
paul@934 35
Identifiers without time zone information are not in themselves sufficient to
paul@934 36
unambiguously define points in time, and thus additional time zone information
paul@934 37
must be provided to obtain such time periods for such purposes as detecting
paul@934 38
conflicts with other events. In the above examples, those normalised values
paul@934 39
not providing a UTC datetime representation need further conversion to be
paul@934 40
usable for period comparisons. Such further conversion would be done by
paul@934 41
nominating a disambiguating time zone, such as the user's configured time
paul@934 42
zone.
paul@933 43
paul@934 44
By normalising identifiers using any object-resident time zone information,
paul@934 45
imip-agent can use the resulting values without needing to consult the object
paul@934 46
providing any redefined recurrence, knowing that any time zone information has
paul@934 47
already been taken into consideration. Thus, all UTC-based datetimes used as
paul@934 48
recurrence identifiers are readily usable for comparison purposes, whereas any
paul@934 49
floating date or datetime values used as recurrence identifiers must need
paul@934 50
additional conversion using the user's time zone to be usable.
paul@933 51
paul@934 52
It might be thought that there would be correspondence between a recurrence
paul@934 53
identifier and the time zone details employed by the original object
paul@934 54
describing the redefined recurrence (such as the `TZID` attribute specified on
paul@934 55
an object's `DTSTART` property), and so any unqualified recurrence identifier
paul@934 56
might be converted to a UTC-based datetime using such time zone details.
paul@934 57
However, an assumption could equally be made that the recurrence identifier
paul@934 58
should inherit time zone details from the redefined recurrence instead. The
paul@934 59
only reasonable choice to be made when confronted with such ambiguity is to
paul@934 60
treat any unqualified identifier as a genuine floating date or datetime, and
paul@934 61
the normalisation process facilitates this strategy.
paul@933 62
paul@933 63
== Recurrences and Free/Busy Information ==
paul@933 64
paul@934 65
Events employing recurrences on fixed occasions can be readily recorded in the
paul@934 66
free/busy information for a calendar user. However, iCalendar also permits
paul@934 67
recurrences that may potentially continue forever, and yet providing free/busy
paul@934 68
information for arbitrary periods in the future may either result in
paul@934 69
substantial computation or substantial demands on storage resources.
paul@934 70
Consequently, free/busy information may only be generated for a period ending
paul@934 71
at a certain point in the future defined in terms of days from the present.
paul@934 72
Within this period scheduling would make sense, and attempts to schedule
paul@934 73
events outside this period would succeed at the participant's own risk.
paul@933 74
paul@934 75
Such a period where participant availability is known must be necessarily
paul@934 76
expanded as time progresses. One-off events, once recorded in the free/busy
paul@934 77
records, will not contribute further to expansions of those records. Recurring
paul@934 78
events, however, may provide additional periods of interest as the
paul@934 79
availability window moves forward in time.
paul@933 80
paul@934 81
To determine which events contribute recurrences, a list of objects (initially
paul@934 82
all objects known to a user that have not been cancelled) is consulted and
paul@934 83
their recurrence properties inspected. With such knowledge of recurring
paul@934 84
events, upon expanding the availability window, only these "known recurring"
paul@934 85
events need to be inspected for further contributions to the free/busy
paul@934 86
records, and those no longer contributing after a given point can be discarded
paul@934 87
from the list for future expansion of the window. Meanwhile, new events would
paul@934 88
need to be added to the list, at least if they were defined as providing
paul@934 89
recurrences that may occur in future availability periods.
paul@933 90
paul@933 91
=== Updating Free/Busy Records ===
paul@933 92
paul@934 93
To update and thus expand availability information, it is suggested that a
paul@934 94
regularly scheduled task be used to consult the events known (or thought) to
paul@934 95
provide additional free/busy periods and to record such additional periods for
paul@934 96
each user. This can be done using a system's `cron` daemon and a suitable
paul@955 97
script in `/etc/cron.daily` or equivalent. Such a script is
paul@955 98
[[../CronIntegration|provided]] in the imip-agent distribution along with a
paul@955 99
program that can expand availability information for all known recipients of
paul@955 100
calendar information.