| -rw-r--r-- | development/pim/pimpaper/backend.tex | 22 | ||||
| -rw-r--r-- | development/pim/pimpaper/backendimplementation.tex | 53 | ||||
| -rw-r--r-- | development/pim/pimpaper/frontend.tex | 24 | ||||
| -rw-r--r-- | development/pim/pimpaper/gui_xref.tex | 44 | ||||
| -rw-r--r-- | development/pim/pimpaper/introduction.tex | 2 | ||||
| -rw-r--r-- | development/pim/pimpaper/opiepim.tex | 10 | ||||
| -rw-r--r-- | development/pim/pimpaper/seperation.tex | 91 |
7 files changed, 129 insertions, 117 deletions
diff --git a/development/pim/pimpaper/backend.tex b/development/pim/pimpaper/backend.tex index 2652b08..fcade7f 100644 --- a/development/pim/pimpaper/backend.tex +++ b/development/pim/pimpaper/backend.tex @@ -1,17 +1,17 @@ \section{The Backend Design} \subsection{The Template} -OPimAccessBackend is a template interface of the Backend. -It consists out of pure virtual functions to implement for -load, reload, save and clear. You will also need to implement -add, remove and replace. -Todo, Event and Address inherit from OPimAccessBackend to create -their Backend Type with additional functionality and also some -default implementation for some queries. +OPimAccessBackend is a template interface of the backend. +It consists out of pure virtual functions for +load, reload, save and clear, add, remove and replace. +Special inheritances from OPimAccessBackend for todo, calendar-event and conatact are available to +define the backend Type with additional functionality and some implementations for special queries. -\subsection{Read Ahead} -You may implement Read Ahead or Read Behind by implementing -the specific find function. First you need to give the Frontend +\subsection{Caching} +You may implement caching by implementing a specific find function. It is filling the cache +(located in the frontend) as read-ahed or read-behing, by giving a read direction. +\comment{ Das versteht an dieser Stelle keiner: First you need to give the Frontend a hint on how many items you want to cache and then you can call cache to cache items. -read Ahead returns the number of Records to read behind/ahead. +read-ahead returns the number of records to read behind/ahead.} +Caching is used automatically, if this function is implemented. diff --git a/development/pim/pimpaper/backendimplementation.tex b/development/pim/pimpaper/backendimplementation.tex index 272507a..a222be8 100644 --- a/development/pim/pimpaper/backendimplementation.tex +++ b/development/pim/pimpaper/backendimplementation.tex @@ -1,67 +1,70 @@ \section{Implementation of the Backends} -Opie Backends have implementations for XML, VCF and SQL. We can -group the VCF and XML Backend in the File Family. +Opie provides backend implementations for XML, VCF and SQL. XML and VCF are file based +implementations, while the SQL backend use a real database. \section{Locking, Journal and Visibility} Opie PIM encourages that all changes are made visible -immediately and are propagated by Qt Signals by the Frontend -but we recognize that not every Backend -- specially the File Family - is capable of making every -change physically available instantly or it would be too -complex to develop this is why this feature is nice to have -but not necessary implement by the Backend.\\ -By default changes may not be lost by concurrent access and two different -saves. The feature to implement is called Auto-Update the Backends -can utilize QCOP for the communication. When one Backend saves the data -it needs to lock the access (it can use API), check if external changes -occurred and reload the data if necessary and then save the merged changes -and finally to give up the lock. -The user may call reload() any time and the access needs to be locked -for that. The Backends can use the appropriate techniques to provide -fast and secure operation.\\ -The reload feature may be turned off for the Frontend so that a save() +immediately and are propagated via Qt Signals by the frontend. +Due to performance issues, we recognize that not every backend +implementation - especially the file based - is capable of making every +change physically available instantly, called ``Live Update''. It would be too complex to +implement this efficiently, thus we declare this as ``nice to have'' feature, +which may be implemented by the backend.\\ +By default changes should not be lost by concurrent access to the files. +The requested feature to avaoid this, is called ``Auto-Update''. +If one backend need to save the data, it has to lock the access (it can use API \comment{Was?}), check whether external changes +occurred since last save and reload and merge the data, if necessary. This merging guarantees to include all external changes +to the local dataset. Afterwards it saves all data and removes the lock. +\comment{ Was willst Du hier genau sagen? The user may call reload() at any time and the access needs to be locked +for that.} The backends has to use the appropriate technique to provide +fast and secure operations.\\ +\comment{Ich würde im Folgenden eher das vorschlagen: +The reload feature may be turned off by the frontend to disable automatic update. In this case, the +backend should work in ``read-only'' mode to prevent possible overwrite of changes} +The reload feature may be turned off by the frontend so that a save() might possible override changes that occurred. \subsubsection{Journal and Out Of Memory} -The Backend need to make sure that it is capable of surviving crashes +The backend need to make sure that it is capable of surviving crashes and storage out of memory situation without losing data and changes.\\ -The File Family is encouraged to use the journal on a per user basis +The file based backends is encouraged to use a journal-file on a per user basis to keep track of changes. The journal can be applied in case of a crash.\\ -In out of disk storage situation the user needs to be informed so it might -free space. +In out of disk storage situation the user needs to be informed, so he should get the chance to +free space before the operation is stopped. +Database based backends should use mechanisms which are provided or suggested for the database system, used. -\subsubsection{Features of the Backends} +\subsubsection{Features of the backends} \begin{center} \begin{tabular}{|l|l|l|l|l|} \hline -Backend & Live Update & Auto Update & Journal & Available\\ \hline +backend & Live Update & Auto Update & Journal & Available\\ \hline XML & no & yes & no but SQL & after save \\ \hline SQL & yes & yes & yes & immediately \\ \hline VCF & no & no & no & never \\ \hline \end{tabular} -\label{Feature of Backends} +\label{Feature of backends} \end{center} \subsection{Generic Implementation} \subsubsection{Recurrence} FIXME \subsubsection{OPimState} FIXME \subsubsection{Reminders and Alarms} \subsection{Todo} \subsubsection{XML} % supported attributes \begin{tabular}{|l|l|} \hline Key & Possible Values \\ \hline Categories & Comma separated list of Integers \\ \hline Uid & Unique negative Integer generated by timet \\ \hline HasDate & 0 for false and 1 for true \\ \hline Completed & 1 for completed and 0 for not completed \\ \hline Description & Escaped multi line Text \\ \hline Summary & One line summary \\ \hline Priority & Between 0 and 5, 5 high priority \\ \hline DateDay & The Day for the DueDate \\ \hline diff --git a/development/pim/pimpaper/frontend.tex b/development/pim/pimpaper/frontend.tex index 1ed41aa..9c46c07 100644 --- a/development/pim/pimpaper/frontend.tex +++ b/development/pim/pimpaper/frontend.tex @@ -1,24 +1,24 @@ \section{Frontend} \subsection{Low Level Frontend} -OPimBase is a low level not value based interface, to do basic queries -and record finding in a generic way. It is present to allow -generic access to all Frontends. +For general (typeless) operations, OPimBase provides a real low level, reference based, interface, for basic queries +and record finding. These operations are common to all frontends. \subsection{OTemplateBase} -Inherits from OPimBase and implements bits of the OPimBase Interface. +Inherited from OPimBase and implements bits \comment{bits? Teile ? Welche Teile ? Sollte es nicht eher vervollständigen heissen?} of the OPimBase Interface. This class is present to be used by the Backends ( OPimAccessBackend ) to set cache sizes and to cache items. \subsection{OPimAccessTemplate} Implements OTemplateBase and OPimBase. All low level functions are automatically implemented by the OPimAccessTemplate which does -additional type checking based on OPimRecord::rtti.\\ -This template is value based and utilizes the Backend. The Backend -can be set on the Constructor, when no Backend is specified -the default Backend Implementation will be used. -This AccessTemplate operates on OPimRecord based types and is meant -to be used by concrete Frontend implementations for Todo, Event, -Note and Address. The concrete Frontends can be used by applications. -Use this template to create your own PIM Type. +additional type checking, based on OPimRecord::rtti.\\ +This template is value based and utilizes the backend. The backend +can be set on instancing by the constructor. If no backend is specified, +the default implementation will be used (which one is defined by the config file +pimaccess.conf). +This AccessTemplate operates on types, based on OPimRecord and is meant +to be used by concrete frontend implementations for todo, datebook-event, +note and contact. The concrete frontends can be used by applications. +Use this template to create new PIM types. diff --git a/development/pim/pimpaper/gui_xref.tex b/development/pim/pimpaper/gui_xref.tex index d869c5f..f86e618 100644 --- a/development/pim/pimpaper/gui_xref.tex +++ b/development/pim/pimpaper/gui_xref.tex @@ -1,40 +1,44 @@ \section{GUI Classes} +GUI elements should be provided for modifying records in a general way. The next sections +shows suggested widgets for this purpose. \subsubsection{Recurrence Widget} -Opie PIM offers a recurrence Widget to let the user +Opie PIM offers a recurrence widget to let the user configure the recurrence. \subsubsection{Mainwindow} -The mainwindow implements a QCOP Interface for showing, +The mainwindow implements a QCOP interface for showing and editing records. It can handle alarms and reminder activation. \section{Cross Reference} \subsection{The idea} -Sometimes an Event or Todo is related to something else. -For example the Birthday Attribute of your children Record relate -to the Birthday Event in your Datebook and the ``Book clown'' -in your Todolist.\\ -We need a way to select the Record and the attribute if we want -that fine grained information. +Sometimes a datebook-event or todo is related to something else. +For example, the birthday attribute of a child record relate +to the birthday event in a datebook and to the entry ``Book clown'' +in your todolist.\\ +We need a way to interconnect information to describe such relations. \subsection{Selecting the Reference} \subsubsection{Out Of Process Selection} -For an Out of Process solution we could utilize the targeted -Application to request the selection of an record.\\ +For an out of process solution, we could utilize the targeted +application to request the selection of an record.\\ For that to work we need to know which application offers -Cross Referencing and the API needs to be able to find the +cross referencing. The API needs to be able to find the application and then call them via QCOP.\\ -Later for resolving the Cross Reference the same application\\ +Later, for resolving the cross-references, the same application\\ would be either asked to give a summary string or it could display the reference on demand. This requires the application -to start and a specific selection window, but more easily -allows to cross reference attributes. +to start a specific selection window, but more easily +allows to cross reference attributes. \comment{``, but..'' Das verstehe ich nicht!. Ich wuerde den Satz so uebersetzen: +Dies erfordert, dass die Application ein spezielles Auswahlfenster startet, aber viel einfacher die +Crossreferenzierung von Attributen erlaubt. +Meinst Du das ? } -\subsubsection{In Process Selection} -In Process Selection is possible with the usage of OPimBase +\subsubsection{In-Process-Selection} +In-process-selection is possible using OPimBase and OPimRecord. It allows to query and sort in a generic way. -This would allow to have a generic Selector widget which -can be used to select a Record and possible files as well. To -support new types one could dlopen the Frontends to allow -custom Frontends. +This would allow to have a generic selector widget, which +can be used to select a record and possible files as well. To +support new types it should be possible to use plugins (via dlopen) do load +and support custom frontends. diff --git a/development/pim/pimpaper/introduction.tex b/development/pim/pimpaper/introduction.tex index 24cf586..5241d5e 100644 --- a/development/pim/pimpaper/introduction.tex +++ b/development/pim/pimpaper/introduction.tex @@ -1,14 +1,14 @@ \section{Introduction} \subsection{This Document} This paper will describe the design decision, our specification and how it integrates into C++, Qt and Opie. It will examine the separation between Frontend and Backend, delayed loading of Records, the concrete XML, SQL and VCF implementation -of the Backend and finally we will built a new Frontend/Backend +of the Backend and finally, we will built a new Frontend/Backend to support a Note based API. \subsection{Copyright} Copyright notice \copyright 2004, Holger Hans Peter Freyther diff --git a/development/pim/pimpaper/opiepim.tex b/development/pim/pimpaper/opiepim.tex index 0b26083..89e6292 100644 --- a/development/pim/pimpaper/opiepim.tex +++ b/development/pim/pimpaper/opiepim.tex @@ -1,52 +1,58 @@ \documentclass [12pt,a4paper]{article} \usepackage{german} \usepackage[latin1]{inputenc} \pagestyle{headings} \usepackage{epsfig} \usepackage{graphicx} +\newcommand{\comment}[1]{} + \begin{document} \begin{titlepage} \begin{center} \Huge{Opie PIM Design and Implementation} \Large{\\pre beta\\} \Large{\today} \linebreak \normalsize{} \vfill \begin{figure}[h] \begin{minipage}{14cm} \centerline{\includegraphics[width=8 cm]{logo}} \end{minipage} \end{figure} \end{center} \vfill \centerline{ \begin{tabular}[t]{|c|c|c|} \hline -\textbf{Version} & \textbf{Author} & \textbf{Email} \\ \hline\hline -0.0.1 & Holger Freyther & zecke@handhelds.org \\ \hline +\textbf{Version} & \textbf{Author} & \textbf{Email} \\ +\hline\hline +0.0.1 & Holger Freyther & zecke@handhelds.org \\ +\hline +0.0.2 & Stefan Eilers & eilers.stefan@epost.de \\ +\hline \end{tabular} } \end{titlepage} \tableofcontents{} \pagebreak \input{introduction.tex} \input{seperation.tex} \input{backend.tex} \input{frontend.tex} \input{backendimplementation.tex} \input{new_note.tex} \input{gui_xref.tex} \pagebreak \listoffigures \end{document} diff --git a/development/pim/pimpaper/seperation.tex b/development/pim/pimpaper/seperation.tex index 544d5c1..e865fb0 100644 --- a/development/pim/pimpaper/seperation.tex +++ b/development/pim/pimpaper/seperation.tex @@ -1,66 +1,65 @@ \section{Components of Opie PIM} \subsection{The Record} -With our API everything is based on a OPimRecord, this record -got a Identifier which is unique to the Backend it belongs, it is -also possible to assign a new Unique Identifier (uid) on a newly +The basic component of our API is the OPimRecord. Every record is identified +by an identifier, which is unique to the backend it belongs to +\comment{Why it is just unique to the backend? (eilers)}. +If expected, is also possible to assign a new Unique Identifier (UID) on a newly created OPimRecord.\\ -The OPimRecord allows to assign Categories this record is in, to get -a Rich Text summary of the content of the Record and finally to match +The OPimRecord allows to be assigned to categories, to provide a Rich Text +summary of its content and finally to match the content of the Record with a regular expression. \subsection{The Frontend} -Opie PIM got Frontends to access Todos, Events and Addressees. Using -the default Constructor of either OTodoAccess, ODatebookAccess or -OContactAccess uses the default data. These Access methods offer -the common load, save, clear, reload methods and have all in common -to query for an example record, sort a list of records for specific -characteristics, and to match the content against a regular expression - and give access to the Records inside the database/storage.\\ -The Frontend provide a value based Interface and operates on Records -that inherit from OPimRecord and add extra task specific methods to it. +Opie PIM implements frontends to access Todos, Datebook-Events and Addresses. +The frontend provides a value based interface and operates on records inherited +from OPimRecord and add extra task specific methods to it. + +Access methods offer the common load, save, clear, reload methods, +give access to the records inside the database/storage and implement a general +interface to query, for example, a record, request a sorted lists of records for specific +characteristics and to match the content against a regular expression.\\ \subsection{ORecordList and Iterator} -The result of a query or the content of the database is a ORecordList. -To iterate over a ORecordList you can use the Iterator. The Iterators -behaves like the Iterators found in Qt and on dereferencing you get -the reference to the record. Internally the record is fetched just -in time. This delayed loading allows to exploit full power of the specific -Backend. +The result of a query or the content of the database is is abstracted by an ORecordList. +To iterate over an ORecordList useing an Iterator. +Using STL like iterators, it is possible to iterate through an ORecordList. +Accessing a record is easy possible by dereferencing the iterator. +Internally, the record is fetched just in time, called delayed loading. +This delayed loading allows to exploit \comment{exploit??} full power of the specific +backend. \subsection{The Backend} -The Backend is a template based interface that operates on OPimRecord -inherited data types. To implement the delayed loading the Backends -Implementation return only a list of UIDs and these get converted -to a OPimRecordList<T> by the Frontend. +The backend is a template based interface that operates on data types, inherited from OPimRecord. +Delayed loading is implemented by the idea of storing just a list of UIDs instead complete records +in an OPimRecordList<T> by the frontend and to fetch the records just on demand. -\subsection{The cache and read ahead} -To speed up the repeated lookup of records, specially when iterating -over the OPimRecordList we've a cache in the Frontend which is filled -by the Backend and specially in the iterator case the Backend -can do a read ahead to fill the cache. +\subsection{Caching} +To speed up the repeated lookup of records, especially while iterating +over the OPimRecordList, a caching mechanism, located in the frontend, is filled +by the backend automatically. \subsection{Backend vs. Frontend} -The Frontend is meant to be used by the normal API user to access -and query the Records and to save it with different Backend to -a different file if needed. -The Backend is used to implement concrete storage such as XML, VCF -and SQL and exploit possible features of the chosen storage. For example -a SQL Backend can use the power of query, lookup, sorting of the database +The frontend is meant to be used by the user API to access +and query the Records. \comment{ Ist hier irrelevant und verwirrt: and to save it with different backend to +a different file if needed}. +The backend is used to implement the real storage, such as XML, VCF +and SQL and exploit \comment{exploit?} special features of the chosen storage. For example +a SQL backend can use the power of query, lookup, sorting of the database and do true delayed loading of records whereas the XML resource on -a simple file-system normally can't (XMLLiveConnect on ReiserFS). On remote -Backends such as LDAP one might want to use delayed initialisation and -fetching of records as well. Due the clean separation of Frontend and Backend -this is possible but the ease of development and deployment -of both Backends and Frontend remain. +a simple file-system normally can't (XMLLiveConnect on ReiserFS\comment{???}). +On remote backends, such as LDAP, one might want to use delayed initialisation and +fetching of records as well. Due to the clean separation of frontend and backend, +it is possible to use the power of the used databases, but still keep the ease of development +and deployment. \subsection{Occurrences} -A Frontend/Backend can be queried to include OPimRecords for a -period of time. Traditionally this only applies to Events but -with the Opie1.2 revision of PIM this can also be applied to -Todo, Address and Notes. -It behaves similar to OPimRecordList and supports the delayed -loading of Records. +A frontend/backend can be queried to provide OPimRecords which occur in a +period of time. Traditionally this only applies to Calendar-Events, but +due to the the revision of Opie (release 1.2), this can also be applied to +Todo, Address and Notes, as well. +OPimOccurence behaves similar to OPimRecordList and supports the delayed +loading of Records as described above. %TODO implement it.... :} |