source: Doc/Backend/DBInterface.tex @ 299

Last change on this file since 299 was 299, checked in by jkraaijeveld, 13 years ago

Updated Get() table to be up to date with the current version
File size: 12.9 KB
Line 
1\documentclass{article}
2\title{Database Connection for the CPS Facilitator Tool}
3\author{Jos Kraaijeveld}
4\date{\today}
5\usepackage{moreverb}
6\usepackage{fullpage}
7\usepackage{framed}
8\usepackage{float}
9\usepackage{multirow}
10\usepackage[final]{pdfpages}
11\usepackage{hyperref}
12\begin{document}
13
14\maketitle
15
16\pagebreak
17
18\tableofcontents
19
20\pagebreak
21\section{Changelog}
22        \textit{13-01-2012}: Fixed the issue with Open-Closed, updated documentation accordingly.
23
24\section{Introduction}
25        This document describes the database design and implementation for the CPS Facilitator Tool. The goal is to make
26        sure everyone can communicate with the RDF-based database without having to write queries. The DBInterface is
27        written in PHP and requires slight PHP knowledge before use. It is heavily based on initial work by Bas van Nuland. \\
28               
29        If you use this framework, you can skip to the `How to use'-part of this document (\ref{howtouse}). If you are
30        planning to improve this framework, I recommend reading the RDF Primer\footnote{http://www.w3.org/TR/rdf-primer/} and
31        SPARQL Query Language for RDF\footnote{http://www.w3.org/TR/rdf-sparql-query/}. A full specification of the current
32        implementation can be found in section \ref{spec}. The areas I suggest improving upon first are described in section
33        \ref{futurework}.
34
35\section{How to use}\label{howtouse}
36        \subsection{Initialization}
37                Before the database can be used, you should remember to import master.php on every page:
38                \begin{verbatimtab}
39                        require 'classes/master.php';
40                \end{verbatimtab}
41
42        \subsection{Basic queries}
43                \subsubsection{Retrieving data}
44                        Getting data is done by calling the get method of the class for which you want to retrieve data. The
45                        specification for this method is the same for every class and is as follows.\\ \\
46                        \begin{tabular}{| l || r |} \hline
47                                \multicolumn{2}{|c|}{Function get()} \\ \hline
48                                Second argument: \$arguments & Array \\ \hline
49                                Return type: & Array/Variable \\ \hline
50                        \end{tabular}  \\ \\
51
52                        The return type is an Array of objects with the type corresponding to the class you caled it on. For
53                        instance, if you call User::get() you will only get User objects. Below are a few examples showing the usage
54                        of get(). A description of what arguments are possible per type is given in section \ref{arguments}.
55
56                        \begin{figure}[H]
57                                \caption{Retrieving all questions and echo their title.}
58                                \begin{framed}
59                                        \begin{verbatimtab}
60$questions = User::get(array());
61foreach ($questions as $question)
62{
63        echo $question->title;
64}
65                                        \end{verbatimtab}
66                                \end{framed}   
67                        \end{figure}   
68
69                        \begin{figure}[H]
70                                \caption{Retrieving all surveys containing questions with UIDs q1 and q2, created by the user
71                                        Jos, printing all questions in those surveys}
72                                \begin{framed}
73                                        \begin{verbatimtab}
74//To get all surveys created by the user Jos, we need his UID.
75//We first query the database for the User object belonging to Jos.
76$userResults = User::get(array("name" => "Jos"));
77//Assuming there is a result, the UID is:
78$josUID = $userResults[0]->uid;
79//Now to get the requested surveys:
80$surveys = Survey::get(array("questions" => array("q1", "q2"),
81                                    "creator" => $josUID));
82//And to print all the questions in these surveys:
83foreach($surveys as $survey)
84{
85        echo "All the questions in " . $survey->name;
86        foreach($survey->questions as $question)
87        {
88                print_r($question);
89        }
90}
91                                        \end{verbatimtab}
92                                \end{framed}
93                        \end{figure}   
94
95                \subsubsection{Storing data}
96                        Storing data is easy, as long as you stick to using the given PHP Classes. Retrieve these objects by using
97                        the get() function, and call the save() function of the objects.: \\ \\
98                        \begin{tabular}{| l || r |} \hline
99                                \multicolumn{2}{|c|}{Function save()} \\ \hline
100                                Returns: \$boolean  & succeeded \\ \hline
101                        \end{tabular}  \\ \\
102                        If the save function returns false, there is an invalid references in that object which needs to be resolved
103                        before saving. This ensures the database is always valid.
104                        Another important thing to note is that currently it will overwrite a previous object with the same UID in
105                        the database. The following examples show how to create new objects and save them, as well as edit old
106                        objects and save them.
107
108                        \begin{figure}[H]
109                                \caption{Creating a new Answer object and storing this in the database.}
110                                \begin{framed}
111                                        \begin{verbatimtab}
112//For this example, I choose a random question to answer                                       
113$questions = Question::get(array());
114$question = $questions[2];
115//Note two things:
116//1 - If you pass 'null' as first argument when creating any object
117//        A new UID will be generated, indicating a new object.
118//2 - Depending on the question, there can be multiple answers
119//        This means the values-argument (third argument) is an array.
120$answer = new Answer(null, $question, array("12345", "four"));
121//Save the answer in the database
122if($answer->save())
123        echo "Success";
124                                        \end{verbatimtab}
125                                \end{framed}   
126                        \end{figure}   
127
128                        \begin{figure}[H]
129                                \caption{Getting a Survey object from the database and removing the first question. Also alter this
130                                        question.}
131                                \begin{framed}
132                                        \begin{verbatimtab}
133//Get the survey
134$surveyResults = Survey::get(array("uid" => "b91d39e8667372e220bb861b3f94b5bd"));                               
135$survey = surveyResults[0];
136//Remove the question
137$question = $survey->questions[0];
138unset($survey->questions[0]);
139//Change the question
140$question->title = "New Title";
141//Save the survey and question
142$question->save(); $survey->save();
143                                        \end{verbatimtab}
144                                \end{framed}
145                        \end{figure}
146
147
148        \subsection{Arguments}\label{arguments}
149                The arguments you can supply when calling the get() function differ greatly per type. Unfortunately, there is no
150                way around this, so here is a complete overview of arguments per type. \\
151                \begin{tabular}{| l | c | c | l |} \hline
152                        \textbf{Type}                                           & \textbf{Argument name}                & \textbf{Argument type}                & \textbf{Extra notes}  \\ \hline \hline
153                        \multirow{3}{*}{Answer}                                 & uid                                           & String                                        &                                               \\
154                                                                                        & question                                      & String                                        & UID of the question   \\
155                                                                                        & values                                        & Array of Strings                              &                                               \\ \hline \hline
156                        \multirow{5}{*}{AnswerSet}                              & uid                                           & String                                        &                                               \\
157                                                                                        & survey                                        & String                                        & UID of the Survey             \\
158                                                                                        & respondent                            & String                                        & UID of the Respondent \\
159                                                                                        & datetime                                      & String                                        & Unix Timestamp. \\
160                                                                                        & answers                                       & Array of Strings                              & UIDs of the Answers   \\ \hline \hline
161                        \multirow{4}{*}{Application}                            & uid                                           & String                                        & \\
162                                                                                        & title                                         & String                                        & \\
163                                                                                        & description                                   & String                                        & \\
164                                                                                        & style                                 & String                                        & \\ \hline \hline
165                        \multirow{6}{*}{Question}                               & uid                                           & String                                        & \\
166                                                                                        & code                                  & String                                        & \\
167                                                                                        & title                                         & String                                        & \\
168                                                                                        & type                                  & String                                        & \\
169                                                                                        & description                                   & String                                        & \\
170                                                                                        & category                                      & String                                        & \\
171                                                                                        & definedanswers                                & Array of Strings                              & String values of possible answers \\ \hline \hline
172                        \multirow{4}{*}{Respondent/User}                        & uid                                           & String                                        & \\
173                                                                                        & email                                 & String                                        & \\
174                                                                                        & passwordHash                          & String                                        & Use hashes to store passwords \\
175                                                                                        & passwordSalt                          & String                                        & \\ \hline \hline
176                        \multirow{7}{*}{Session}                                        & uid                                           & String                                        & \\
177                                                                                        & title                                         & String                                        & \\
178                                                                                        & creator                                       & String                                        & UID of the User \\
179                                                                                        & creationdate                          & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
180                                                                                        & applications                          & Array of Strings                              & UIDs of the Applications \\
181                                                                                        & surveys                                       & Array of Strings                              & UIDs of the Surveys \\
182                        \multirow{9}{*}{SessionInstance}                        & uid                                           & String                                        &  \\
183                                                                                        & title                                         & String                                        & \\
184                                                                                        & location                                      & String                                        & \\
185                                                                                        & facilitator                                   & String                                        & UID of the user that facilitated the session \\
186                                                                                        & startime                                      & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
187                                                                                        & endtime                                       & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
188                                                                                        & notes                                 & Array of Strings                              & \\
189                                                                                        & session                                       & String                                        & UID of the Session this Instance refers to. \\
190                                                                                        & applicationinstances                  & Array of Strings                              & UIDs of the ApplicationInstances \\
191                                                                                        & surveyinstances                               & Array of Strings                              & UIDs of the SurveyInstances \\ \hline \hline
192                        \multirow{4}{*}{Survey}                                 & uid                                           & String                                        & \\
193                                                                                        & title                                         & String                                        & \\
194                                                                                        & description                                   & String                                        & \\
195                                                                                        & creator                                       & String                                        & UID of the user that created this survey \\
196                                                                                        & questions                                     & Array of Strings                              & UIDs of the Questions \\ \hline \hline
197                        \multirow{8}{*}{ApplicationInstance}                    & uid                                           & String                                        & \\
198                                                                                        & of\_application                               & String                                        & UID of the corresponding application \\
199                                                                                        & startime                                      & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
200                                                                                        & endtime                                       & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
201                                                                                        & open                                  & Integer                                       & 1 for true, 0 for false. \\
202                                                                                        & playerresults                         & Array of Strings                              & Not yet implemented. \\
203                                                                                        & groupresults                          & Array of Strings                              & Not yet implemented. \\
204                                                                                        & periodicresults                               & Array of Strings                              & Not yet implemented. \\ \hline \hline
205                        \multirow{7}{*}{SurveyInstance}                 & uid                                           & String                                        & \\ \pagebreak
206                                                                                        & of\_survey                                    & String                                        & UID of the Survey \\
207                                                                                        & startime                                      & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
208                                                                                        & endtime                                       & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
209                                                                                        & open                                  & Integer                                       & 1 for true, 0 for false. \\                                                           
210                                                                                        & preset\_answers                               & Array of Strings                              & Array with Answer UIDs to define default answers.  \\
211                                                                                        & answersets                            & Array of Strings                              & Array with AnswerSet UIDs \\ \hline
212
213                \end{tabular} \\
214
215                Whenever an Array has to be supplied, it will match for results that satisfy \textit{all} the constraints given
216                in the array.
217                       
218\section{Specification}\label{spec}
219        \subsection{Models}
220                The framework heavily relies on the Object Oriented Programming paradigm, and only allows you to create, edit
221                and store data through instances of precreated classes. All these classes inherit from a global
222                ResearchToolObject class. A UML class diagram of the model classes can be found in Appendix \ref{models}. 
223                The most important thing to note is that references to other objects are not evaluated immediately. Rather,
224                these classes with references have to override the evaluate() function, which in turn tries to query the
225                database and resolve those UIDs to model objects. This gives us two advantages: initial queries do not scale
226                exponentially because of the 'lazy' evaluation, and the boolean return value notifies us when there exists an
227                incorrect reference. By evaluating before saving an object, we ensure that there cannot exist invalid values in
228                the database.
229
230        \subsection{Static functions, non-static functions}
231                It is important to note that the get() function of each object is static, whilst the save() function is not.
232                This is to provide a better saving mechanism in the future: tracking when an object gets changed and saving it
233                automatically. The get() function is static because there is no reason for it to be linked to a specific Object,
234                only to the type it describes as a whole.
235
236        \subsection{Adding to the system}
237                Adding support for new datatypes is easy and can be done by extending the ResearchToolObject class and ensuring
238                the get() and save() methods are implemented correctly. Simply look at the existing classes and stick to the
239                same idea unless you want to radically change the infrastructure.
240
241        \subsection{PHPDoc}     
242                PHPDoc for the database classes can be found at
243                \href{http://svn.tbm.tudelft.nl/TBM-CPS/RESEARCHTOOL/Doc/Backend/PHPDoc/index.html}{SVN}.
244
245\section{Future Work}\label{futurework}
246        \subsection{Deal with invalid or missing values}
247                This goes in two parts. Firstly, the database now assumes that given an entry, all the fields for its type are there and
248                filled in. This is unwanted since it can cause issues with backwards compatability of certain .rdf files. Secondly, it
249                assumes that fields containing a UID to a different entry actually point to a valid entry. For instance, a Survey evaluation will
250                try to get a User object as its creator value from the database as well, assuming it exists. It will return false if this user object
251                does not exist.
252
253\appendix
254\pagebreak
255\section{Class diagram of the models}\label{models}
256        \begin{figure}
257                \includepdf[scale=1.22]{DBModels.pdf}
258        \end{figure}   
259
260\end{document}
Note: See TracBrowser for help on using the repository browser.