DELTA 195 0 16016
SVN  ‚­4‚Âe‚þ<€G _€•> ~ˆs †}Šp€y L„€3  ‘l€‚ ‚4•€: F—{€‚E Fš}€”Q B° €D iÀj€ DÒ@€= ~ã@ ä= åR tæY€„, Oï3€ƒ& Oï3€6 Dñ<® ƒò% ˆDõ* ‚)ým )€ 5=€Ž# ƒ@‘€ƒf ‚h—m€E _œ-€ƒg I {€B {¢€P ‡I¤Wº ˆ¬\€I µ<€ ·[ ‚¸r€I »M€ œ½^€G ®jÚ? Ž!‚‰* ’i‚—L L‚ª6 ‚1‚«\documentclass[11pt,letterpaper]{report}

\usepackage[margin=1in]{geometry}
\usepackage{graphicx}
\usepackage{hyperref}

\newcommand{\lab}{\ensuremath{\langle}}
\newcommand{\rab}{\ensuremath{\rangle}$ $
}
\date{SVN $ $Date$ $}

\begin{document}

\maketitle
\tableofcontents

\chapter{Background}

\section{Introduction}
The Import/Export Module is part of the calendaring component of a 
larger Campus Life Management System, responsible for providing 
calendaring, course management, and course evaluation features to 
members of a university community.  This system will automatically 
present academic information (such as class meetings, course work, and 
group schedules) on personal calendars.  The components and their 
dependencies are shown in the following diagrams.
\begin{center}
\includegraphics*[trim=36 360 144 60,width=3in]{TopLevelComponents} \qquad
\includegraphics*[trim=30 280 60 20,width=3in]{ApplicationServerComponents}
\end{center}

The calendaring component contains several relevant classes.
\begin{description}
\item[EventSeries] a calendar event, which has a short name, a longer 
description, a lifepsan interval during which it occurs, a priority, and 
a Pattern object that describes its recurrence pattern.  EventSeries can 
either be ``busy,'' meaning that they occupy time, or not busy (this 
concept of transparent events is borrowed from RFC 2445).
\item[Calendar] a collection of EventSeries, along with a short name and 
a longer description.  The calendar also contains a notion of whether it 
is editable or not---a published calendar of holidays is an example of a 
read-only calendar.  A single user may have multiple calendars.
\item[Pattern] a representation of when the event described by the 
EventSeries recurs.  Every EventSeries has a Pattern, even if it is just 
a one-time event.
\item[TodoItem] a specific task that needs to be done.  This task has a 
short name, a longer description, and due date, a current status, and a 
priority.  TodoItems are not recurring.
\item[TodoList] a collection of TodoItems grouped into a list.  This 
list has a short name and a longer description.  A user might have 
multiple TodoLists for different sorts of tasks.
\end{description}
These classes are shown in the following diagram.  Notice that many of 
these classes also contain a Reminder, which controls notification about 
the event or todo item.  Reminders are not currently supported by the 
import/export module.
\begin{center}
\includegraphics*[trim=10 10 80 10,width=6.5in]{CalendaringClassDiagram}
\end{center}

The Pattern class is not shown.  Different recurrence patterns are 
represented using different derived classes, such as the OneTimePattern, 
the DailyPattern, the WeeklyPattern, the MonthlyPattern and the 
MWFPattern.  The classes in the Pattern module are shown in the 
following figure.
\begin{center}
\includegraphics*[trim=20 210 80 10,width=6in]{PatternClassDiagram}
\end{center}
\section{Suggested Review Order}
This document has been prepared in the suggested review order---a reader
is advised to start with the Background and known issues, then proceed
to the module design, and finally to consider the test cases designed to
and Scheduling Core Object Specification (iCalendar)}.

\chapter{Module Design}
Derived from \texttt{/tags/proj3/architecture/import\_export/DESIGN} r137.

\section{Introduction} (see
\S\ref{sec:UML}).  This diagram was generated using StarUML from the
file diagrams.uml.  Private data members are not defined in this
section because they are more concisely represented using the UML
diagram.  Instead, this section focuses on documentation and method
UML Diagram\label{sec:UML}}
\begin{center}
\includegraphics*[trim=20 15 60 25,width=6.5in]{UMLDiagram}
\end{center}

\section{Documentation and Pseudocode}
\subsection{CalendarImporter}
the supported external formats.

It is the context component of the Strategy pattern.

\begin{description}
\item[CalendarImporter(target: CalendarImportFormat)]
    construct a CalendarImporter object for the target format
\item[import(input: InputStream)]
    read the external calendar from the provided InputStream.  This
   specified import format.  If not, this method will throw an
    InvalidCalendarStream exception.  Calling this function more
    than once will cause the imported calendars to be merged
    together.  The name of the first imported calendar will
    determine the name and description of the calendar returned by
    \texttt{getCalendar()}.
\item[getCalendar(): Calendar]
    returns the Calendar object produced by reading the imported
    calendar data.  If this function is called before any data has
    been imported, it will return an empty Calendar.  Since this
    Calendar has not yet been stored, it will not have a valid
    CalendarID.
\item[getUnreadableEvents(): List\lab EventSeries\rab]
    returns a list of all the events that could not be completely
    converted into EventSeries objects.  These EventSeries objects
    will be populated with as much information as possible, but they
    will not appear in the calendar returned by \texttt{getCalendar()}.
\item[getTodoList(): TodoList]
    returns the TodoList object produced by reading the imported
    calendar data.  If this function is called before any data has
    been imported, it will return an empty TodoList.  Since this
    TodoList has not yet been stored, it will not have a valid
    TodoListID.
\item[getUnreadableTodoItems(): List\lab TodoItem\rab]
    returns a list of all the todo items that could not be
    completely converted into TodoItem objects.  These TodoItem
    objects will be populated with as much information as possible,
    but they will not appear in the TodoList returned by
    \texttt{getTodoList()}.
\end{description}

\subsection{Importer}
Importer is an abstract class that determines the necessary behavior
of an importer.  It is the strategy component of the Strategy
pattern.

Proper usage would call \texttt{import()} a number of times, then call
\texttt{getEvents()} and \texttt{getTodoItems()} to obtain the imported 
data.  Errors could then be detected using 
\texttt{getUnreadableEvents()} and \texttt{getUnreadableTodoItems()}.

\begin{description}
\item[import(input: InputStream)]
    reads calendar data from the provided stream
\item[getEvents(): List\lab EventSeries\rab]
    returns a list of the read events
\item[getUnreadableEvents(): List\lab EventSeries\rab]
    returns a list of the events that could not be properly processed
\item[getTodoItems(): List\lab TodoItem\rab]

    returns a list of the read todo items
\item[getUnreadableTodoItems(): List\lab TodoItem\rab]
    returns a list of the todo items that could not be properly
    processed
\end{description}

\subsection{ICalendarImporter}
2445).  Its public interface matches that required by Importer.

\begin{description}
\item[import(input: InputString)]
    reads calendar data from the provided stream
\item[getEvents(): List\lab EventSeries\rab]
    returns a list of the read events
\item[getUnreadableEvents(): List\lab EventSeries\rab]
    returns a list of the events that could not be properly processed
\item[getTodoItems(): List\lab TodoItem\rab]
    returns a list of the read todo items
\item[getUnreadableTodoItems(): List\lab TodoItem\rab]
    returns a list of the todo items that could not be properly
    processed
\item[-mapPriority(priority: String): Priority]
    converts iCalendar priority strings to Priority objects
\item[-mapStatus(status: String): TodoStatus]
    converts iCalendar status strings to TodoStatus objects
\end{description}

\subsection{ICalendarPatternImporter}
ICalendarPatternImporter is responsible for converting iCalendar
recurrence strings to Pattern objects.  Since iCalendar recurrences
are more expressive than our internal Pattern objects, it is not
necessarily possible to convert a recurrence string to a single
Pattern object or even to a finite set of Pattern objects.
Nevertheless, while it is not always guaranteed to succeed, any set
of patterns returned by the ICalendarPatternImporter is guaranteed
to be equivalent to the iCalendar recurrence.

Since it maintains no state information, this class can be static.

\begin{description}
\item[import(date: Date, recurrence: String): List\lab Pattern\rab]
    returns a list of Pattern objects that are equivalent to the
    given iCalendar recurrence string.  Since Patterns contain date
    information but iCalendar recurrence strings do not, the
    provided date is that of the first occurrence of the event.  The
    returned set of Patterns is only guaranteed to be the minimal
    possible set if the recurrence can be represented by a single
    Pattern object.  If the recurrence cannot be represented with a
    finite number of Pattern objects, an UnrepresentableRecurrence
    exception is thrown.
\end{description}

\begin{verbatim}\end{verbatim}

\subsection{CalendarDateTimeConverter}
CalendarDateTimeConverter is responsible for converting Date, Time,
and DateTime objects to and from the iCalendar string representation.
It is a concrete strategy component of the Strategy pattern.

where y is year, m is month, d is day, T is a separator, H is hour, M
in minute, S is second, and Z is a time zone indicator.  In the
future, however, functionality may be added to support the "floating"
time format (for a definition of this format, see RFC 2445).

Since it has no state information, this class can be static.

\begin{description}
\item[stringFromDate(date: Date): String]
    convert the given Date object to an iCalendar date-time string
\item[dateFromString(date: String): Date]
    convert the given iCalendar date-time string into a Date object
\item[stringFromTime(time: Time): String]
    convert the given Time object to an iCalendar date-time string
\item[timeFromString(time: String): Time]
    convert the given iCalendar date-time string into a Time object
\item[stringFromDateTime(time: DateTime): String]
    convert the given DateTime object to an iCalendar date-time
    string
\item[dateTimeFromString(time: String): DateTime]
    convert the given iCalendar date-time string into a DateTime
    object
\end{description}

\subsection{CalendarExporter}
CalendarExporter is a common interface to export the internal
calendar representation to one of the supported export formats.
It is the context component of the Strategy pattern.

\begin{description}
\item[CalendarExporter(target: CalendarExportFormat)]
     construct a CalendarExporter object for the target format
\item[addCalendar(calendar: Calendar)]
     adds the given calendar to the data that will be exported.
     Multiple calls to this function will cause multiple calendars to
     be merged before they are exported.
\item[addTodoList(list: TodoList)]
     adds the given todo list to the data that will be exported.
     Multiple calls to this function will cause multiple todo lists
     to be merged before they are exported.
\item[export(output: OutputStream)]
     prints the added calendar and todo list information to the
     provided output stream.  If no data has been added, the
     equivalent of an empty calendar in the specified format will be
     produced.
\end{description}

\begin{verbatim}\end{verbatim}

\subsection{Exporter}
Exporter is an abstract class that determines the necessary behavior
of an exporter class.  It is the strategy component of the Strategy
pattern.

Proper usage would call \texttt{addTodoItem()} and \texttt{addEvent()} a 
number of times, then call \texttt{export()} to cause the information to 
be written.

\begin{description}
\item[addTodoItem(item: TodoItem)]
    add a "todo" to the exported calendar
\item[addEvent(item: EventSeries)]
    add an event to the exported calendar
\item[export(output: OutputStream)]
\end{description}

\subsection{ICalendarExporter}
ICalendarExporter is an Exporter for writing ICalendar files (RFC 2445).
See the Exporter documentation for a description of the purpose of each 
public method.

\begin{description}
\item[addTodoItem(item: TodoItem)]
    add a "todo" to the exported calendar
\item[addEvent(item: EventSeries)]
    add an event to the exported calendar
\item[export(output: OutputStream)]
\item[-mapPriority(priority: Priority): String]
    convert a Priority object to the corresponding VTODO or VEVENT
    PRIORITY keyword
\item[-mapStatus(status: TodoStatus): String]
   keyword
\end{description}

\begin{verbatim}\end{verbatim}

\subsection{ICalendarPatternExporter}
ICalendarPatternExporter is responsible for converting a Pattern
object into a faithful iCalendar representation.

This process is significantly easier that the reverse process because
the iCalendar recurrence language is significantly more expressive than
the internal Pattern language.  However, there are different Pattern
subclasses for each recurrence pattern; it is necessary to write a
special function to convert each Pattern subclass (it is impossible to
use the common \texttt{getNextEvent()} interface because there is no way
to distinguish between infinitely recurring events and recurrences that
terminate in the very distance future.

As a result, the ICalendarPatternExporter class has a number of private
conversion functions of the form \texttt{-convert(pattern:
/PatternSubclass/): String}.  The general \texttt{export(Pattern):
String} method calls the proper function based on the type of the given
Pattern.  The Strategy pattern or subclasses are not used because the
\texttt{convert()} methods are more specific than the general
\texttt{export()} method and inheritance requires equivalent, not more
precise, subclasses.  There may be (and probably is) a better pattern to
use here; when we find one, we should be able to rewrite this section of
the code without any changes outside of this class.

This class requires no internal state, so it should be static.

\begin{description}
\item[export(pattern: Pattern, end: DateTime): String]
    convert the given recurrence Pattern with the given end to a
    iCalendar recurrence.  If the end DateTime object is the
    equivalent of 0/0/0, then the pattern repeats forever.  Excluded
    recurrence information will be maintained in the iCalendar
    representation.
\end{description}

\begin{verbatim}\end{verbatim}

The following private methods are used to convert a specific type of
Pattern to the correct iCalendar recurrence string.  In general,
these transformations require little more than printing of pattern
attributes in the proper format.  The pseudo code for the TThPattern
conversion is provided as an example.

More information on the recurrence rule can be found in 
\href{http://tools.ietf.org/html/rfc2445#section-4.3.10}{section 4.3.10 
of RFC 2445}.

\begin{verbatim}{Test Plan}
Derived from \texttt{/tags/proj4-brett/TestPlan.tex} r161
modules is to convert a known calendar into another format.  Existing
tools (either provided by other pieces of Calendaring or by external
libraries) are then used to iterate over both versions of the calendar
to compare the events and todo items in each.  The differences must then
be analyzed to determine whether the degree of lossiness is acceptable
given the particular conversion: some formats are inherently less
expressive than others, and so a lossless conversion is not always
discrepancies are unjustified; if they are, the test should fail.
identify the places at which information loss occurred.  This information
must be checked to confirm that all instances of data loss were
correctly flagged and that each instance is unavoidable---or at least
and TodoItem classes be implemented sufficiently to allow
effectively stubbed (any stub would have to implement most if not all of
the Calendaring Import/Export module\footnote{These requirements were
taken verbatim from the CalendarImporter and CalendarExporter sections
requirements rather than testable functional requirements; they are best
acceptance test cases.  From these two requirements, we obtain the
following tests to confirm that the component performs all the specified
of \texttt{/tags/proj3/architecture/import\_export/DESIGN}.} we deriveENDREP
id: 26.0.r202/16505
type: file
pred: 26.0.r199/2767
count: 4
text: 202 0 16480 41317 6a23f09dbe591d14602cfb9e44bae58f
props: 196 72 44 0 3a3bbe6cafaf8696993f107a07a056dd
cpath: /trunk/review/reviewPackages/brett/ReviewPackage.tex
copyroot: 0 /

PLAIN
K 31
ApplicationServerComponents.pdf
V 15
file w.z.r201/0
K 27
CalendaringClassDiagram.pdf
V 18
file y.10.r201/624
K 23
PatternClassDiagram.pdf
V 20
file 27.0.r200/23734
K 17
ReviewPackage.tex
V 20
file 26.0.r202/16505
K 22
TopLevelComponents.pdf
V 18
file x.11.r201/322
K 14
UMLDiagram.pdf
V 15
file r.y.r197/0
END
ENDREP
id: 25.0.r202/17079
type: dir
pred: 25.0.r201/1273
count: 7
text: 202 16750 316 316 acaf2307eb9268bd6b65ebd18f4259f8
cpath: /trunk/review/reviewPackages/brett
copyroot: 0 /

PLAIN
K 5
brett
V 19
dir 25.0.r202/17079
K 4
mike
V 18
dir 1j.0.r192/4057
END
ENDREP
id: 1i.0.r202/17338
type: dir
pred: 1i.0.r201/1529
count: 22
text: 202 17253 72 72 0daa4dc54df4a5c9a3c7ce8553f3578e
cpath: /trunk/review/reviewPackages
copyroot: 0 /

PLAIN
K 8
SCHEDULE
V 18
file 1h.0.r194/538
K 14
reviewPackages
V 19
dir 1i.0.r202/17338
K 7
reviews
V 17
dir 23.0.r194/404
K 8
toReview
V 19
dir 1q.0.r193/17234
END
ENDREP
id: 1g.0.r202/17677
type: dir
pred: 1g.0.r201/1866
count: 25
text: 202 17505 159 159 29e82627d8d58171fdac25646116c870
cpath: /trunk/review
copyroot: 0 /

PLAIN
K 12
architecture
V 18
dir m.0.r132/10273
K 12
requirements
V 16
dir j.0.r53/2435
K 6
review
V 19
dir 1g.0.r202/17677
K 7
testing
V 16
dir 15.0.r176/84
END
ENDREP
id: 3.0.r202/18000
type: dir
pred: 3.0.r201/2187
count: 185
text: 202 17831 156 156 dd4ef188408d1841f5962f84c6a20dc6
cpath: /trunk
copyroot: 0 /

PLAIN
K 8
branches
V 17
dir 1.0.r143/2096
K 4
tags
V 16
dir 2.0.r165/339
K 5
trunk
V 18
dir 3.0.r202/18000
END
ENDREP
id: 0.0.r202/18264
type: dir
pred: 0.0.r201/2449
count: 202
text: 202 18146 105 105 d5af240ac6dba306941611e22b9672ca
cpath: /
copyroot: 0 /

26.0.t201-1 modify true false /trunk/review/reviewPackages/brett/ReviewPackage.tex


18264 18405