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