DELTA 195 0 16016 SVN‚­4‚­W‚è%€G_€wr‚z€L„€ŠˆZ€‚‚4•€(F—{€‚EFš}€”QB°€DiÀj€DÒ@€=~ã@ä=åRtæY€„,Oï3€ƒ&Oï3€6Dñ<®ƒò%ˆDõ*‚)ým)€5=€Ž#ƒ@‘€ƒ*‚h—m€E_œ-€ƒgI {€B{¢€P‡I¤Wºˆ¬\€Iµ<€ ·[‚¸r€I»M€ œ½^€G®jÚ?Ž!‚‰*’i‚—LL‚ª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 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 (see \S\ref{sec:UML}). This diagram was generated using StarUML from the file diagrams.uml. Private data members are not defined in this chapter because they are more concisely represented using the UML diagram. Instead, this chapter focuses on documentation and method UML Diagram\label{sec:UML}} \begin{center} \includegraphics[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 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.r198/13659 type: file pred: 26.0.r196/129 count: 2 text: 198 0 13634 38615 218b7a8fff431e16cd5ceab8af2b5b09 props: 196 72 44 0 3a3bbe6cafaf8696993f107a07a056dd cpath: /trunk/review/reviewPackages/brett/ReviewPackage.tex copyroot: 0 / PLAIN K 17 ReviewPackage.tex V 20 file 26.0.r198/13659 K 14 UMLDiagram.pdf V 15 file r.y.r197/0 END ENDREP id: 25.0.r198/14010 type: dir pred: 25.0.r197/407 count: 3 text: 198 13903 94 94 119f015660dce0fc2023d99df46ec9b7 cpath: /trunk/review/reviewPackages/brett copyroot: 0 / PLAIN K 5 brett V 19 dir 25.0.r198/14010 K 4 mike V 18 dir 1j.0.r192/4057 END ENDREP id: 1i.0.r198/14266 type: dir pred: 1i.0.r197/657 count: 18 text: 198 14181 72 72 d9bba2f1d7168845e01713c37672819e 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.r198/14266 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.r198/14604 type: dir pred: 1g.0.r197/989 count: 21 text: 198 14432 159 159 27252d4074f24ef4abf84ac20dac6e16 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.r198/14604 K 7 testing V 16 dir 15.0.r176/84 END ENDREP id: 3.0.r198/14926 type: dir pred: 3.0.r197/1306 count: 181 text: 198 14757 156 156 7c37199dd75ebed8216a59a391a9e7f7 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.r198/14926 END ENDREP id: 0.0.r198/15190 type: dir pred: 0.0.r197/1567 count: 198 text: 198 15072 105 105 115c8144723425af266ca8253dd0d119 cpath: / copyroot: 0 / 26.0.t197-1 modify true false /trunk/review/reviewPackages/brett/ReviewPackage.tex 15190 15331