OpenACS

gustafn
committed
oacs-5-9:gustafn:20160622081932
on 22 Jun 16
- modernize HTML
openacs-4/.../www/doc/design.adp (+79 -77)
4 4 <master>
5 5 <h2>ACS Events Design Documentation</h2>
6 6
7 7 by <a href="mailto:smeeks\@arsdigita.com">W. Scott Meeks</a>
8 8 <hr>
9 9 <h3>I. Essentials</h3>
10 10 <ul>
11 11 <li>Tcl script directory (link to the API browser page for the
12 12 package)</li><li>PL/SQL file (link to the API browser page for the package)</li><li>Data model: <a href="/doc/sql/display-sql?url=acs-events-create.sql&amp;package_key=acs-events">
13 13 acs-events-create.sql</a>
14 14 </li><li><a href="requirements">Requirements document</a></li><li>ER diagram</li><li>Transaction flow diagram</li>
15 15 </ul>
16 16 <h3>II. Introduction</h3>
17 17 <p>The ACS events service is primarily intended for use by writers
18 18 of application packages and other service packages. The service
19 19 allows developers to specify and manipulate relationships (possibly
20 20 recurring) between a <em>set of intervals in time</em>, an
21 21 <em>activity</em>, and an arbitrary number of <em>parties</em>. An
22 22 activity can be associated with an arbitrary number of ACS
23 23 <em>objects</em>.</p>
24   <p>The package doesn't provide for any interpretation of events,
25   leaving that up to the applications that use the service. In
26   particular, the package assumes that permissioning, and the related
27   concept of approval, will be handled by the application. Similarly,
28   notification is also the responsibility of the application (but
29   probably via another service package.) Likewise, the package
30   provides no UI support.</p>
  24 <p>The package doesn't provide for any interpretation of
  25 events, leaving that up to the applications that use the service.
  26 In particular, the package assumes that permissioning, and the
  27 related concept of approval, will be handled by the application.
  28 Similarly, notification is also the responsibility of the
  29 application (but probably via another service package.) Likewise,
  30 the package provides no UI support.</p>
31 31 <p>Possible application domains include include calendaring, room
32 32 reservation, scheduling, project management, and event
33 33 registration.</p>
34 34 <p>The requirements break the functionality into four main areas:
35 35 events, time intervals, activities, and recurrences. The package
36 36 meets the requirements for each of these areas in the following
37 37 ways:</p>
38 38 <p>
39   <strong>Events:</strong> The service creates a new subtype of acs_object:
40   acs_event. It creates an auxiliary table for mapping events to
41   parties. It provides an API for manipulating and querying events
42   and their associated time interval sets, activities, recurrences,
43   and parties.</p>
  39 <strong>Events:</strong> The service creates a new subtype of
  40 acs_object: acs_event. It creates an auxiliary table for mapping
  41 events to parties. It provides an API for manipulating and querying
  42 events and their associated time interval sets, activities,
  43 recurrences, and parties.</p>
44 44 <p>
45   <strong>Time Intervals:</strong> The service creates tables for storing
46   time intervals and sets of time intervals. It provides an API for
47   manipulating and querying time intervals and time interval
  45 <strong>Time Intervals:</strong> The service creates tables for
  46 storing time intervals and sets of time intervals. It provides an
  47 API for manipulating and querying time intervals and time interval
48 48 sets.</p>
49 49 <p>
50   <strong>Activities:</strong> The service creates a new subtype of
51   acs_object: acs_activity. It creates an auxiliary table for mapping
52   activities to objects. It provides an API for manipulating
  50 <strong>Activities:</strong> The service creates a new subtype
  51 of acs_object: acs_activity. It creates an auxiliary table for
  52 mapping activities to objects. It provides an API for manipulating
53 53 activities, their properties, and their associated objects.</p>
54 54 <p>
55   <strong>Recurrences:</strong> The service creates a table for storing
56   information on how an event recurs, including how the event recurs
57   and when it stops recurring. It provides an API for manipulating
58   recurrence information and recurring events. This includes a
59   function to insert event recurrences in such a way as to reasonably
60   limit the amount of information stored in the DB for a particular
61   event. This is done by only partially populating the recurrences
62   for certain events. The service also provides a view which
63   simplifies querying to find partially populated recurring events
64   that need recurrences added to the DB.</p>
  55 <strong>Recurrences:</strong> The service creates a table for
  56 storing information on how an event recurs, including how the event
  57 recurs and when it stops recurring. It provides an API for
  58 manipulating recurrence information and recurring events. This
  59 includes a function to insert event recurrences in such a way as to
  60 reasonably limit the amount of information stored in the DB for a
  61 particular event. This is done by only partially populating the
  62 recurrences for certain events. The service also provides a view
  63 which simplifies querying to find partially populated recurring
  64 events that need recurrences added to the DB.</p>
65 65 <h3>III. Historical Considerations</h3>
66 66 <p>There are number of historical considerations surrounding the
67 67 design of recurring events. Much of the current design can be
68 68 traced pack to the original <a href="http://www.arsdigita.com/doc/calendar/design.html">ACS 3.4
69 69 Calendar Package design</a>, though the design has been cleaned up,
70 70 modified to fit with the new events data model and slightly
71 71 expanded.</p>
72 72 <p>One key consideration is exactly how recurring events are
73 73 supported. There are two main choices. One choice is to insert only
74 74 a single row for each recurring event, regardless of the number of
75 75 times it will recur. This row contains all the information
76 76 necessary to compute whether or not that event would recur on a
77 77 particular day. The alternative is to insert a row for each
78 78 recurrence.</p>
79 79 <p>I favored the second approach for the following reasons. First,
80 80 one tradeoff is time vs. space. Computation, particularly if it
81 81 might need to be done in Tcl and not solely in the database, is
82 82 relatively expensive compared to storing additional information in
83 83 the database. In many cases, the only information that will need to
84 84 be stored for recurrences is the date and time of the
85 85 recurrence.</p>
86 86 <p>I think it may be faster in Oracle even with a stored proc, at
87 87 least with the month view and possibly the week view as well. This
88 88 is because with 1 row per recurrence, the month and week view
89 89 queries can pull all the relevant items out at once and can take
90 90 advantage of the index on the start_date column to optimize the
91 91 query. With the stored proc, it would be necessary to iterate over
92 92 each day (up to 42 in the month view), calling the check repeat
93   proc for each base repeating item who's repeat_until date was still
94   relevant, and then effectively constructing the item to be
  93 proc for each base repeating item who's repeat_until date was
  94 still relevant, and then effectively constructing the item to be
95 95 displayed.</p>
96 96 <p>Another reason is that the first approach, to insert only a
97 97 single row, seems to require a significantly more complex design.
98 98 Thus the design, implementation and eventual maintenance time would
99 99 be greater. It becomes even more complex when you allow exceptions.
100 100 Now you need to maintain a separate table of exceptions and it
101 101 becomes necessary to check through the exceptions table every time
102 102 the check repeat proc is called. It the worst case, every
103   recurrence is an exception, so you're essentially back to 1 row per
104   recurrence, plus all the added complexity of using the check repeat
105   proc.</p>
  103 recurrence is an exception, so you're essentially back to 1 row
  104 per recurrence, plus all the added complexity of using the check
  105 repeat proc.</p>
106 106 <p>This is not an unreasonable possibility and is in fact how Sloan
107 107 operates. Each class is represented as a recurring item and it is
108 108 very common for each instance to have a different set of files
109 109 attached to it.</p>
110 110 <p>However, there are drawbacks to this approach. First, it will be
111 111 more difficult to handle events that recur indefinitely. Second
112 112 (but related) is that safeguards will need to be put in place to
113 113 prevent pathological (accidental or intentional) cases from
114 114 swamping the database.</p>
115 115 <p>In the ACS 3.4 Calendar Package, this was partially resolved in
116 116 the following way. Users are limited to looking no more than 10
117 117 years in the past or 10 years in the future. (Actually, this is a
118 118 system parameter and can be set more or less restrictive, but the
119 119 default is 10 years.) This seemed reasonable given that other
120 120 systems seem to have arbitrary, implementation driven limits. Yahoo
121 121 and Excite have arbitrary limits between about 1970 and 2030. Palm
122 122 seems to have no lower limit, but an upper limit of 2031.</p>
123   <p>The 4.0 ACS Events service doesn't enforce a particular policy
124   to prevent problems, but it does provide mechanisms that a
  123 <p>The 4.0 ACS Events service doesn't enforce a particular
  124 policy to prevent problems, but it does provide mechanisms that a
125 125 well-designed application can use. The keys are the
126 126 <strong>event_recurrence.insert_events</strong> procedure and the
127 127 <strong>partially_populated_events</strong> view.</p>
128 128 <p>
129   <strong>insert_events</strong> takes either an event_id or a recurrence_id
130   and a cutoff date. It either uses the recurrence_id, or gets it
131   from the event_id, to retrieve the information needed to generate
132   the dates of the recurrences. When inserting a recurring event for
133   the first time, the application will need to call
134   <strong>insert_events</strong> with a reasonable populate_until date. For
135   calendar, for example, this could be sysdate + the lookahead
136   limit.</p>
  129 <strong>insert_events</strong> takes either an event_id or a
  130 recurrence_id and a cutoff date. It either uses the recurrence_id,
  131 or gets it from the event_id, to retrieve the information needed to
  132 generate the dates of the recurrences. When inserting a recurring
  133 event for the first time, the application will need to call
  134 <strong>insert_events</strong> with a reasonable populate_until
  135 date. For calendar, for example, this could be sysdate + the
  136 lookahead limit.</p>
137 137 <p>It is the application's responsibility to determine if
138 138 additional events need to be inserted into the DB to support the
139 139 date being used in a query to view events. The application can do
140 140 this by querying on partially_populated_events, using the date in
141 141 question and any other limiting conditions to determine if there
142 142 are any recurrences that might recur on the date in question which
143 143 have not been populated up to that date. To insure reasonable
144 144 performance, the application needs to be clever about tracking the
145 145 current date viewed and the maximum date viewed so as to minimize
146 146 the number of times this query is performed. The application should
147 147 also pick a date reasonably far in the future for insert additional
148 148 instances.</p>
149 149 <p>Another historical consideration is the choice of values for
150 150 event_recurrence.interval_type. The original choice for the 3.4
151 151 calendar was based on the Palm DateBook which seemed fairly
152 152 inclusive (covering both Yahoo Calendar and Excite Planner) though
153 153 it didn't capture some of the more esoteric cases covered by
154 154 Outlook or (particuarly) Lotus Notes. The Events service maintains
155   the original choices, but adds an additional choice, 'custom',
156   which, when combined with the custom_func column, allows an
157   application to generate an arbitrary recurrence function. The
158   function must take a date and a number of intervals as arguments
159   and return a new date greater than the given date. The number of
160   intervals is guaranteed to be a positive integer.</p>
  155 the original choices, but adds an additional choice,
  156 'custom', which, when combined with the custom_func column,
  157 allows an application to generate an arbitrary recurrence function.
  158 The function must take a date and a number of intervals as
  159 arguments and return a new date greater than the given date. The
  160 number of intervals is guaranteed to be a positive integer.</p>
161 161 <p>For the days_of_week column, the representation chosen, a
162 162 space-delimited list of integers, has a number of advantages.
163 163 First, it is easy and reasonably efficient to generate the set of
164   dates corresponding to the recurrences. <strong>insert_events</strong> takes
165   each number in the list in turn and adds it to the date of the
166   beginning of the week. Second, the Tcl and Oracle representations
167   are equivalent and the translations to and from UI are
168   straightforward. In particular, the set of checkboxes corresponding
169   to days of the week are converted directly into a Tcl list which
170   can be stored directly into the DB.</p>
  164 dates corresponding to the recurrences.
  165 <strong>insert_events</strong> takes each number in the list in
  166 turn and adds it to the date of the beginning of the week. Second,
  167 the Tcl and Oracle representations are equivalent and the
  168 translations to and from UI are straightforward. In particular, the
  169 set of checkboxes corresponding to days of the week are converted
  170 directly into a Tcl list which can be stored directly into the
  171 DB.</p>
171 172 <h3>IV. Competitive Analysis</h3>
172 173 <p>Since this is a low level service package, there is no direct
173 174 competition.</p>
174 175 <h3>V. Design Tradeoffs</h3>
175 176 <p>Because this is a service package, tradeoffs were made only in
176 177 areas of interest to developers. Indeed, the main design tradeoff
177 178 was made at the very beginning, namely that this would be a
178 179 narrowly-focussed service package. This had consequences in the
179 180 following areas:</p>
180 181 <h4>Maintainability</h4>
181 182 <p>To simplify the package as much as possible, a number of
182 183 possible features were left to be handled by other services or by
183 184 the applications using the events package. This includes
184 185 controlling access to events via permissions, providing an approval
185 186 process, and providing support for notification. permissions app
186 187 dependent, approval via workflow, separate notification service
187 188 package</p>
188 189 <p>There was one significant, fairly complex feature that was
189 190 included, namely the support for recurrences. It could have been
190 191 left to the application developers or another service package.
 
193 194 model for the rest of the events data model. The advantage of this
194 195 is that this code is now in one place with no need for applications
195 196 to reinvent the wheel. It also means that there is a consistent
196 197 model across the toolkit.</p>
197 198 <h4>Reusability</h4>
198 199 <p>Much thought was given to the needs of applications most likely
199 200 to use this service, such as calendar, events, and room
200 201 reservations. This has led to a well defined API which should be
201 202 reusable by most applications that are concerned by events.</p>
202 203 <h4>Testability</h4>
203 204 <p>Because the API consists of well defined PL/SQL functions, it
204 205 should be fairly easy to build a test suite using the PL/SQL
205 206 testing tools.</p>
206 207 <h3>VI. Data Model and API Discussion</h3>
207 208 <p>The data model and PL/SQL API encapsulate the four main
208 209 abstractions defined in the ACS Events service: events, time
209 210 interval sets, activities, and recurrences. At present, there is no
210 211 Tcl API, but if desired one could be added consisting primarily of
211 212 wrappers around PL/SQL functions and procedures.</p>
212 213 <h4>Events</h4>
213   <p>This is the main abstraction in the package. <tt>acs_event</tt>
214   is a subtype of <tt>acs_object</tt>. In addition to the
215   <tt>acs_events</tt> table, there is an <tt>acs_event_party_map</tt>
216   table which maps between parties and events. The <tt>acs_event</tt>
217   package defines <tt>new</tt>, <tt>delete</tt>, various procedures
218   to set attributes and <tt>recurs_p</tt> indicating whether or not a
219   particular event recurs.</p>
  214 <p>This is the main abstraction in the package.
  215 <kbd>acs_event</kbd> is a subtype of <kbd>acs_object</kbd>. In
  216 addition to the <kbd>acs_events</kbd> table, there is an
  217 <kbd>acs_event_party_map</kbd> table which maps between parties and
  218 events. The <kbd>acs_event</kbd> package defines <kbd>new</kbd>,
  219 <kbd>delete</kbd>, various procedures to set attributes and
  220 <kbd>recurs_p</kbd> indicating whether or not a particular event
  221 recurs.</p>
220 222 <h4>Time Interval Sets</h4>
221 223 <p>Because time interval sets are so simple, there is no need to
222   make them a subtype of <tt>acs_object</tt>. Interval sets are
  224 make them a subtype of <kbd>acs_object</kbd>. Interval sets are
223 225 represented with one table to represent time intervals, and a
224 226 second table which groups intervals into sets, with corresponding
225   PL/SQL packages defining <tt>new</tt>, <tt>delete</tt>, and
  227 PL/SQL packages defining <kbd>new</kbd>, <kbd>delete</kbd>, and
226 228 additional manipulation functions.</p>
227 229 <h4>Activities</h4>
228 230 <p>This is the secondary abstraction in the package.
229   <tt>acs_activity</tt> is a subtype of <tt>acs_object</tt>. In
230   addition to the <tt>acs_activities</tt> table, there is an
231   <tt>acs_activity_object_map</tt> table which maps between objects
232   and activities. The <tt>acs_activity</tt> package defines
233   <tt>new</tt>, <tt>delete</tt>, and various procedures to set
  231 <kbd>acs_activity</kbd> is a subtype of <kbd>acs_object</kbd>. In
  232 addition to the <kbd>acs_activities</kbd> table, there is an
  233 <kbd>acs_activity_object_map</kbd> table which maps between objects
  234 and activities. The <kbd>acs_activity</kbd> package defines
  235 <kbd>new</kbd>, <kbd>delete</kbd>, and various procedures to set
234 236 attributes and mappings.</p>
235 237 <h4>Recurrences</h4>
236 238 <p>Since recurrences are always associated with events, there
237 239 seemed to be no need to make them objects. The information that
238 240 determines how an event recurs is stored in the
239   <tt>event_recurrences</tt> table.</p>
240   <p>The <tt>event_recurrence</tt> package defines <tt>new</tt>,
241   <tt>delete</tt>, and other procedures related to recurrences. The
242   key procedure is <tt>insert_events</tt>.</p>
243   <p>A view, <tt>partially_populated_events</tt>, is created which
  241 <kbd>event_recurrences</kbd> table.</p>
  242 <p>The <kbd>event_recurrence</kbd> package defines <kbd>new</kbd>,
  243 <kbd>delete</kbd>, and other procedures related to recurrences. The
  244 key procedure is <kbd>insert_events</kbd>.</p>
  245 <p>A view, <kbd>partially_populated_events</kbd>, is created which
244 246 hides some of the details of retrieving recurrences that need to
245 247 populated further.</p>
246 248 <!--
247 249     <li> Data management components: procedures that provide a stable
248 250     interface to database objects and legal transactions - the latter
249 251     often correspond to tasks. </li>
250 252
251 253 <p>
252 254 Remember that the correctness, completeness, and stability of the API
253 255 and interface are what experienced members of our audience are looking
254 256 for.  This is a cultural shift for us at aD (as of mid-year 2000), in
255 257 that we've previously always looked at the data models as key, and
256 258 seldom spent much effort on the API (e.g. putting raw SQL in pages to
257 259 handle transactions, instead of encapsulating them via procedures).
258 260 Experience has taught us that we need to focus on the API for
259 261 maintainability of our systems in the face of constant change.
260 262 </p>
261 263
262 264
263 265 <p>
 
281 283 mentioned. </li>
282 284
283 285     <h4>Transactions</h4>
284 286
285 287     <li> Discuss modifications which the database may undergo from
286 288     your package. Consider grouping legal transactions according to
287 289     the invoking user class, i.e. transactions by an ACS-admin, by
288 290     subsite-admin, by a user, by a developer, etc.  </li>
289 291
290 292 </ul>
291 293
292 294 --><h3>VIII. User Interface</h3>
293 295 <p>This package does not provide a UI.</p>
294 296 <h3>IX. Configuration/Parameters</h3>
295 297 <p>There are no parameters for this package.</p>
296 298 <h3>X. Future Improvements/Areas of Likely Change</h3>
297 299 <p>If the system presently lacks useful/desirable features, note
298 300 details here. You could also comment on non-functional improvements
299 301 to the package, such as usability.</p>
300 302 <p>Note that a careful treatment of the earlier "competitive
301   analysis" section can greatly facilitate the documenting of this
302   section.</p>
  303 analysis" section can greatly facilitate the documenting of
  304 this section.</p>
303 305 <h3>XI. Authors</h3>
304 306 <ul>
305 307 <li>System owner: <a href="mailto:smeeks\@arsdigita.com">W. Scott
306 308 Meeks</a>
307 309 </li><li>System creator: <a href="mailto:smeeks\@arsdigita.com">W. Scott
308 310 Meeks</a>
309 311 </li><li>Documentation author: <a href="mailto:smeeks\@arsdigita.com">W.
310 312 Scott Meeks</a>
311 313 </li>
312 314 </ul>
313 315 <h3>XII. Revision History</h3>
314 316 <table cellpadding="2" cellspacing="2" width="90%" bgcolor="#EFEFEF">
315 317 <tr bgcolor="#E0E0E0">
316 318 <th width="10%">Document Revision #</th><th width="50%">Action Taken, Notes</th><th>When?</th><th>By Whom?</th>
317 319 </tr><tr>
318 320 <td>0.1</td><td>Creation</td><td>11/20/2000</td><td>W. Scott Meeks</td>
319 321 </tr>
320 322 </table>