source: Doc/Backend/DBInterface.tex @ 147

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

Started documenting the database interface
File size: 8.3 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\begin{document}
11
12\maketitle
13
14\pagebreak
15
16\tableofcontents
17
18\pagebreak
19
20\section{Introduction}
21        This document describes the database design and implementation for the CPS Facilitator Tool. The goal is to make
22        sure everyone can communicate with the RDF-based database without having to write queries. The DBInterface is
23        written in PHP and requires slight PHP knowledge before use. It is heavily based on initial work by Bas van Nuland. \\
24               
25        If you use this framework, you can skip to the `How to use'-part of this document (\ref{howtouse}). If you are
26        planning to improve this framework, I recommend reading the RDF Primer\footnote{http://www.w3.org/TR/rdf-primer/} and
27        SPARQL Query Language for RDF\footnote{http://www.w3.org/TR/rdf-sparql-query/}. A full specification of the current
28        implementation can be found in section \ref{spec}. The areas I suggest improving upon first are described in section
29        \ref{futurework}.
30
31\section{How to use}\label{howtouse}
32        \subsection{Initialization}
33                Before the database can be used, you should initialize a \textit{DatabaseInterface} object. This is the only
34                database class you will use. This is done calling the DatabaseInterface constructor.
35                \begin{verbatimtab}
36                        $db = new DatabaseInterface();
37                \end{verbatimtab}
38
39        \subsection{Basic queries}
40                \subsubsection{Retrieving data}
41                        Getting data is done by calling the get method of the DatabaseInterface class. The specification for this
42                        method is as follows. \\ \\
43                        \begin{tabular}{| l || r |} \hline
44                                \multicolumn{2}{|c|}{Function get()} \\ \hline
45                                First argument: \$type  & String \\ \hline
46                                Second argument: \$arguments & Array \\ \hline
47                                Return type: & Array/Variable \\ \hline
48                        \end{tabular}  \\ \\
49
50                        The return type is an Array of objects with the type specified as the first argument. For instance, if
51                        the first argument is ``user", the function will return an array of User objects. The second argument can be
52                        left out if you want to retrieve all entries of a specific type. Below are a few examples showing the usage
53                        of get(). A description of what arguments are possible per type is given in section \ref{arguments}.
54
55                        \begin{figure}[H]
56                                \caption{Retrieving all questions and echo their title.}
57                                \begin{framed}
58                                        \begin{verbatimtab}
59$questions = $db->get("question");
60foreach ($questions as $question)
61{
62        echo $question->title;
63}
64                                        \end{verbatimtab}
65                                \end{framed}   
66                        \end{figure}   
67
68                        \begin{figure}[H]
69                                \caption{Retrieving all surveys containing questions with IDs q1 and q2, created by the user
70                                        Jos, printing all questions in those surveys}
71                                \begin{framed}
72                                        \begin{verbatimtab}
73//To get all surveys created by the user Jos, we need his UID.
74//We first query the database for the User object belonging to Jos.
75$userResults = $db->get("user", array("name" => "Jos"));
76//Assuming there is a result, the UID is:
77$josUID = $userResults[0]->uid;
78//Now to get the requested surveys:
79$surveys = $db->get("survey", array("questions" => array("q1", "q2"),
80                                    "creator" => $josUID));
81//And to print all the questions in these surveys:
82foreach($surveys as $survey)
83{
84        echo "All the questions in " . $survey->name;
85        foreach($survey->questions as $question)
86        {
87                print_r($question);
88        }
89}
90                                        \end{verbatimtab}
91                                \end{framed}
92                        \end{figure}   
93
94                \subsubsection{Storing data}
95                        Storing data is easy, as long as you stick to using the given PHP Classes. Retrieve these classes by using
96                        the get() function, and pass them as a parameter to the set() function of the DatabaseInterface. This set()
97                        function will determine what type the object is and store it at the correct location. The method overview is
98                        as follows: \\ \\
99                        \begin{tabular}{| l || r |} \hline
100                                \multicolumn{2}{|c|}{Function set()} \\ \hline
101                                First argument: \$rToolObject  & Variable \\ \hline
102                        \end{tabular}  \\ \\
103                       
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 = $db->get("question");
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
122$db->set($answer);
123                                        \end{verbatimtab}
124                                \end{framed}   
125                        \end{figure}   
126
127                        \begin{figure}[H]
128                                \caption{Getting a Survey object from the database and removing the first question. Also alter this
129                                        question.}
130                                \begin{framed}
131                                        \begin{verbatimtab}
132//Get the survey
133$surveyResults = $db->get("survey", array("uid" => "b91d39e8667372e220bb861b3f94b5bd"));                               
134$survey = surveyResults[0];
135//Remove the question
136$question = $survey->questions[0];
137unset($survey->questions[0]);
138//Change the question
139$question->title = "New Title";
140//Save the survey and question
141$db->batchSet(array($survey, $question));
142                                        \end{verbatimtab}
143                                \end{framed}
144                        \end{figure}
145
146
147        \subsection{Arguments}\label{arguments}
148                The arguments you can supply when calling the get() function differ greatly per type. Unfortunately, there is no
149                way around this, so here is a complete overview of arguments per type. \\
150                \begin{tabular}{| l | c | c | l |} \hline
151                        \textbf{Type}                                   & \textbf{Argument name}        & \textbf{Argument type}        & \textbf{Extra notes}  \\ \hline \hline
152                        \multirow{3}{*}{Answer}                 & uid                                           & String                                        &                                               \\
153                                                                                        & question                                      & String                                        & UID of the question   \\
154                                                                                        & values                                        & Array of Strings                      &                                               \\ \hline \hline
155                        \multirow{4}{*}{AnswerSet}              & uid                                           & String                                        &                                               \\
156                                                                                        & survey                                        & String                                        & UID of the Survey             \\
157                                                                                        & respondent                            & String                                        & UID of the Respondent \\
158                                                                                        & answers                                       & Array of Strings                      & UIDs of the Answers   \\ \hline \hline
159                        \multirow{4}{*}{Application}    & uid                                           & String                                        & \\
160                                                                                        & title                                         & String                                        & \\
161                                                                                        & description                           & String                                        & \\
162                                                                                        & style                                         & String                                        & \\ \hline \hline
163                        \multirow{5}{*}{Question}               & uid                                           & String                                        & \\
164                                                                                        & title                                         & String                                        & \\
165                                                                                        & type                                          & String                                        & \\
166                                                                                        & description                           & String                                        & \\
167                                                                                        & category                                      & String                                        & \\
168                                                                                        & answers                                       & Array of Strings                      & String values of possible answers \\ \hline \hline
169                        \multirow{3}{*}{Respondent/User}& uid                                           & String                                        & \\
170                                                                                        & name                                          & String                                        & \\
171                                                                                        & password                                      & String                                        & Use hashes to store passwords \\ \hline \hline
172                        \multirow{6}{*}{Session}                & uid                                           & String                                        & \\
173                                                                                        & title                                         & String                                        & \\
174                                                                                        & datetime                                      & String                                        & Unix Timestamp. No way to search on intervals (yet). \\
175                                                                                        & applications                          & Array of Strings                      & UIDs of the Applications \\
176                                                                                        & surveys                                       & Array of Strings                      & UIDs of the Surveys \\
177                                                                                        & answersets                            & Array of Strings                      & UIDs of the AnswerSets \\ \hline \hline
178                        \multirow{4}{*}{Survey}                 & uid                                           & String                                        & \\
179                                                                                        & title                                         & String                                        & \\
180                                                                                        & description                           & String                                        & \\
181                                                                                        & creator                                       & String                                        & UID of the user that created this survey \\
182                                                                                        & questions                                     & Array of Strings                      & UIDs of the Questions \\ \hline \hline
183                \end{tabular} \\
184
185                Whenever an Array has to be supplied, it will match for results that satisfy \textit{all} the constraints given
186                in the array.
187                       
188
189
190
191
192\section{Specification}\label{spec}
193        //TODO: Generate HTML documentation
194
195\section{Future Work}\label{futurework}
196        //TODO
197
198
199\end{document}
Note: See TracBrowser for help on using the repository browser.