+The ACS events service is primarily intended for use by writers of +application packages and other service packages. The service allows +developers to specify and manipulate relationships (possibly +recurring) between a set of intervals in time, an +activity, and an arbitrary number of parties. An +activity can be associated with an arbitrary number of ACS +objects. +
+The package doesn't provide for any interpretation of events, leaving +that up to the applications that use the service. In particular, the +package assumes that permissioning, and the related concept of +approval, will be handled by the application. Similarly, notification +is also the responsibility of the application (but probably via +another service package.) Likewise, the package provides no UI support. +
+Possible application domains include include calendaring, room +reservation, scheduling, project management, and event registration. +
+The requirements break the functionality into four main areas: events, +time intervals, activities, and recurrences. The package meets the +requirements for each of these areas in the following ways: +
+Events: The service creates a new subtype of acs_object: +acs_event. It creates an auxiliary table for mapping events to +parties. It provides an API for manipulating and querying events and their +associated time interval sets, activities, recurrences, and parties. +
+Time Intervals: The service creates tables for storing time +intervals and sets of time intervals. It provides an API for +manipulating and querying time intervals and time interval sets. +
+Activities: The service creates a new subtype of acs_object: +acs_activity. It creates an auxiliary table for mapping activities to +objects. It provides an API for manipulating activities, their +properties, and their associated objects. +
+Recurrences: The service creates a table for storing +information on how an event recurs, including how the event recurs and +when it stops recurring. It provides an API for manipulating +recurrence information and recurring events. This includes a function +to insert event recurrences in such a way as to reasonably limit the +amount of information stored in the DB for a particular event. This +is done by only partially populating the recurrences for certain +events. The service also provides a view which simplifies querying to +find partially populated recurring events that need recurrences added +to the DB. +
+ ++There are number of historical considerations surrounding the +design of recurring events. Much of the current design can be traced +pack to the original ACS 3.4 +Calendar Package design, though the design has been +cleaned up, modified to fit with the new events data model and slightly +expanded. +
+One key consideration is exactly how recurring events are supported. +There are two main choices. One +choice is to insert only a single row for each recurring event, +regardless of the number of times it will recur. This row contains +all the information necessary to compute whether or not that event +would recur on a particular day. The alternative is to insert a row +for each recurrence. +
+I favored the second approach for the following reasons. First, one +tradeoff is time vs. space. Computation, particularly if it might +need to be done in Tcl and not solely in the database, is relatively +expensive compared to storing additional information in the database. +In many cases, the only information that will need to be stored for +recurrences is the date and time of the recurrence. +
+I think it may be faster in Oracle even with a stored proc, at least +with the month view and possibly the week view as well. This is +because with 1 row per recurrence, the month and week view queries can +pull all the relevant items out at once and can take advantage of the +index on the start_date column to optimize the query. With the stored +proc, it would be necessary to iterate over each day (up to 42 in the +month view), calling the check repeat proc for each base repeating +item who's repeat_until date was still relevant, and then effectively +constructing the item to be displayed. +
+Another reason is that the first approach, to insert only a single +row, seems to require a significantly more complex design. Thus the +design, implementation and eventual maintenance time would be greater. +It becomes even more complex when you allow exceptions. Now you need to +maintain a separate table of exceptions and it becomes necessary to check +through the exceptions table every time the check repeat proc is called. +It the worst case, every recurrence is an exception, so you're +essentially back to 1 row per recurrence, plus all the added complexity +of using the check repeat proc. +
+This is not an unreasonable possibility and is in fact how Sloan +operates. Each class is represented as a recurring item and it is very +common for each instance to have a different set of files attached to it. +
+However, there are drawbacks to this approach. First, it will be more +difficult to handle events that recur indefinitely. Second (but +related) is that safeguards will need to be put in place to prevent +pathological (accidental or intentional) cases from swamping the +database. +
+In the ACS 3.4 Calendar Package, this was partially resolved in the +following way. Users are limited to looking no more than 10 years in +the past or 10 years in the future. (Actually, this is a system +parameter and can be set more or less restrictive, but the default is +10 years.) This seemed reasonable given that other systems seem to +have arbitrary, implementation driven limits. Yahoo and Excite have +arbitrary limits between about 1970 and 2030. Palm seems to have no +lower limit, but an upper limit of 2031. +
+The 4.0 ACS Events service doesn't enforce a particular policy to +prevent problems, but it does provide mechanisms that a well-designed +application can use. The keys are the event_recurrence.insert_events +procedure and the partially_populated_events view. +
+insert_events takes either an event_id or a recurrence_id and a +cutoff date. It either uses the recurrence_id, or gets it from the +event_id, to retrieve the information needed to generate the dates of +the recurrences. When inserting a recurring event for the first time, +the application will need to call insert_events with a +reasonable populate_until date. For calendar, for example, this could +be sysdate + the lookahead limit. +
+It is the application's responsibility to determine if additional +events need to be inserted into the DB to support the date being used +in a query to view events. The application can do this by querying on +partially_populated_events, using the date in question and any other +limiting conditions to determine if there are any recurrences that +might recur on the date in question which have not been populated up +to that date. To insure reasonable performance, the application needs +to be clever about tracking the current date viewed and the maximum +date viewed so as to minimize the number of times this query is +performed. The application should also pick a date reasonably far in +the future for insert additional instances. +
+Another historical consideration is the choice of values for +event_recurrence.interval_type. The original choice for the 3.4 +calendar was based on the Palm DateBook which seemed fairly inclusive +(covering both Yahoo Calendar and Excite Planner) though it didn't +capture some of the more esoteric cases covered by Outlook or +(particuarly) Lotus Notes. The Events service maintains the original +choices, but adds an additional choice, 'custom', which, when combined +with the custom_func column, allows an application to generate an +arbitrary recurrence function. The function must take a date and a +number of intervals as arguments and return a new date greater than +the given date. The number of intervals is guaranteed to be a +positive integer. +
+For the days_of_week column, the representation chosen, a +space-delimited list of integers, has a number of advantages. First, +it is easy and reasonably efficient to generate the set of dates +corresponding to the recurrences. insert_events takes each +number in the list in turn and adds it to the date of the beginning of +the week. Second, the Tcl and Oracle representations are equivalent +and the translations to and from UI are straightforward. In +particular, the set of checkboxes corresponding to days of the week +are converted directly into a Tcl list which can be stored directly +into the DB. +
+Since this is a low level service package, there is no direct competition. +
+Because this is a service package, tradeoffs were made only in areas +of interest to developers. Indeed, the main design tradeoff was made at the +very beginning, namely that this would be a narrowly-focussed service +package. This had consequences in the following areas: +
+To simplify the package as much as possible, a number of possible +features were left to be handled by other services or by the +applications using the events package. This includes controlling +access to events via permissions, providing an approval process, and +providing support for notification. permissions app dependent, +approval via workflow, separate notification service package +
+There was one significant, fairly complex feature that was +included, namely the support for recurrences. It could have been left +to the application developers or another service package. However, +because the 3.4 Calendar package already had a model for recurring +calendar items, it was straightforward to adapt this model for the +rest of the events data model. The advantage of this is that this +code is now in one place with no need for applications to reinvent +the wheel. It also means that there is a consistent model across the +toolkit. +
+Much thought was given to the needs of applications most likely to use +this service, such as calendar, events, and room reservations. This +has led to a well defined API which should be reusable by most +applications that are concerned by events. +
+Because the API consists of well defined PL/SQL functions, it should +be fairly easy to build a test suite using the PL/SQL testing tools. +
+The data model and PL/SQL API encapsulate the four main abstractions +defined in the ACS Events service: events, time interval sets, +activities, and recurrences. At present, there is no Tcl API, but if +desired one could be added consisting primarily of wrappers around +PL/SQL functions and procedures. +
+This is the main abstraction in the package. acs_event is a +subtype of acs_object. In addition to the +acs_events table, there is an acs_event_party_map +table which maps between parties and events. The acs_event +package defines new, delete, various procedures to +set attributes and recurs_p indicating whether or not a +particular event recurs. +
+Because time interval sets are so simple, there is no need to make +them a subtype of acs_object. Interval sets are represented +with one table to represent time intervals, and a second table which +groups intervals into sets, with corresponding PL/SQL packages +defining new, delete, and additional manipulation functions. +
+This is the secondary abstraction in the package. acs_activity is a +subtype of acs_object. In addition to the +acs_activities table, there is an acs_activity_object_map +table which maps between objects and activities. The acs_activity +package defines new, delete, and various procedures to +set attributes and mappings. +
+Since recurrences are always associated with events, there seemed to +be no need to make them objects. The information that determines how +an event recurs is stored in the event_recurrences table. +
+The event_recurrence package defines new, +delete, and other procedures related to recurrences. The key +procedure is insert_events. +
+A view, partially_populated_events, is created which hides +some of the details of retrieving recurrences that need to populated further. +
+This package does not provide a UI. +
+There are no parameters for this package. +
+If the system presently lacks useful/desirable features, note details +here. You could also comment on non-functional improvements to the +package, such as usability. +
+Note that a careful treatment of the earlier "competitive analysis" +section can greatly facilitate the documenting of this section. +
| Document Revision # | Action Taken, Notes | When? | By Whom? | +
|---|---|---|---|
| 0.1 | Creation | 11/20/2000 | W. Scott Meeks | +