Changeset 231 for Doc/Backend/DBInterface.tex

Timestamp:

01/13/12 11:49:05 (13 years ago)

Author:

jkraaijeveld

Message:

Updated documentation for updated Database design.

File:

• Doc/Backend/DBInterface.tex (modified) (12 diffs)

Doc/Backend/DBInterface.tex

@@ -19 +19 @@
 
 \pagebreak
+\section{Changelog}
+        \textit{13-01-2012}: Fixed the issue with Open-Closed, updated documentation accordingly.
 
 \section{Introduction}
@@ -33 +35 @@
 \section{How to use}\label{howtouse}
         \subsection{Initialization}
-                Before the database can be used, you should initialize a \textit{DatabaseInterface} object. This is the only
-                database class you will use. This is done calling the DatabaseInterface constructor. 
+                Before the database can be used, you should remember to import master.php on every page:
                 \begin{verbatimtab}
-                        $db = new DatabaseInterface();
+                        require 'classes/master.php';
                 \end{verbatimtab}
 
         \subsection{Basic queries}
                 \subsubsection{Retrieving data}
-                        Getting data is done by calling the get method of the DatabaseInterface class. The specification for this
-                        method is as follows. \\ \\
+                        Getting data is done by calling the get method of the class for which you want to retrieve data. The
+                        specification for this method is the same for every class and is as follows.\\ \\
                         \begin{tabular}{| l || r |} \hline
                                 \multicolumn{2}{|c|}{Function get()} \\ \hline
-                                First argument: \$type  & String \\ \hline
                                 Second argument: \$arguments & Array \\ \hline
                                 Return type: & Array/Variable \\ \hline
                         \end{tabular}  \\ \\
 
-                        The return type is an Array of objects with the type specified as the first argument. For instance, if
-                        the first argument is ``user", the function will return an array of User objects. The second argument can be
-                        left out if you want to retrieve all entries of a specific type. Below are a few examples showing the usage
+                        The return type is an Array of objects with the type corresponding to the class you caled it on. For
+                        instance, if you call User::get() you will only get User objects. Below are a few examples showing the usage
                         of get(). A description of what arguments are possible per type is given in section \ref{arguments}.
 
@@ -59 +58 @@
                                 \begin{framed}
                                         \begin{verbatimtab}
-$questions = $db->get("question");
+$questions = User::get(array());
 foreach ($questions as $question)
 {
@@ -75 +74 @@
 //To get all surveys created by the user Jos, we need his UID. 
 //We first query the database for the User object belonging to Jos.
-$userResults = $db->get("user", array("name" => "Jos"));
+$userResults = User::get(array("name" => "Jos"));
 //Assuming there is a result, the UID is:
 $josUID = $userResults[0]->uid;
 //Now to get the requested surveys:
-$surveys = $db->get("survey", array("questions" => array("q1", "q2"),
+$surveys = Survey::get(array("questions" => array("q1", "q2"),
                                     "creator" => $josUID));
 //And to print all the questions in these surveys:
@@ -95 +94 @@
 
                 \subsubsection{Storing data}
-                        Storing data is easy, as long as you stick to using the given PHP Classes. Retrieve these classes by using
-                        the get() function, and pass them as a parameter to the set() function of the DatabaseInterface. This set()
-                        function will determine what type the object is and store it at the correct location. The method overview is
-                        as follows: \\ \\
+                        Storing data is easy, as long as you stick to using the given PHP Classes. Retrieve these objects by using
+                        the get() function, and call the save() function of the objects.: \\ \\
                         \begin{tabular}{| l || r |} \hline
-                                \multicolumn{2}{|c|}{Function set()} \\ \hline
-                                First argument: \$rToolObject  & Variable \\ \hline
+                                \multicolumn{2}{|c|}{Function save()} \\ \hline
+                                Returns: \$boolean  & succeeded \\ \hline
                         \end{tabular}  \\ \\
-                        
+                        If the save function returns false, there is an invalid references in that object which needs to be resolved
+                        before saving. This ensures the database is always valid.
                         Another important thing to note is that currently it will overwrite a previous object with the same UID in
                         the database. The following examples show how to create new objects and save them, as well as edit old
@@ -113 +111 @@
                                         \begin{verbatimtab}
 //For this example, I choose a random question to answer                                        
-$questions = $db->get("question");
+$questions = Question::get(array());
 $question = $questions[2];
 //Note two things:
@@ -122 +120 @@
 $answer = new Answer(null, $question, array("12345", "four"));
 //Save the answer in the database
-$db->set($answer);
+if($answer->save())
+        echo "Success";
                                         \end{verbatimtab}
                                 \end{framed}    
@@ -133 +132 @@
                                         \begin{verbatimtab}
 //Get the survey
-$surveyResults = $db->get("survey", array("uid" => "b91d39e8667372e220bb861b3f94b5bd"));                                
+$surveyResults = Survey::get(array("uid" => "b91d39e8667372e220bb861b3f94b5bd"));                               
 $survey = surveyResults[0];
 //Remove the question
@@ -141 +140 @@
 $question->title = "New Title";
 //Save the survey and question
-$db->batchSet(array($survey, $question));
+$question->save(); $survey->save();
                                         \end{verbatimtab}
                                 \end{framed}
@@ -209 +208 @@
                 incorrect reference. By evaluating before saving an object, we ensure that there cannot exist invalid values in
                 the database.
-        \subsection{Connectors}
-                Although the front end developer only uses one general DatabaseInterface, the different files for the different
-                datatypes are accessed by seperate connectors. A connector has to implement the IConnector interface, which
-                mainly enforces the get() and set() methods to ensure a connector can perform as expected. The rest of the
-                methods are implemented in the baseclass Connector, which should be extended. In every connector,
-                the get() and set() methods are different. A get() method builds the querystring based on the given arguments,
-                then retrieves the data and performs other necessary queries (like retrieving a set of fields of unspecified
-                length) to ensure the PHP DataModel is complete. A set() method has to store the data accordingly. 
+
+        \subsection{Static functions, non-static functions}
+                It is important to note that the get() function of each object is static, whilst the save() function is not.
+                This is to provide a better saving mechanism in the future: tracking when an object gets changed and saving it
+                automatically. The get() function is static because there is no reason for it to be linked to a specific Object,
+                only to the type it describes as a whole.
+
+        \subsection{Adding to the system}
+                Adding support for new datatypes is easy and can be done by extending the ResearchToolObject class and ensuring
+                the get() and save() methods are implemented correctly. Simply look at the existing classes and stick to the
+                same idea unless you want to radically change the infrastructure.
 
         \subsection{PHPDoc}     
@@ -223 +225 @@
 
 \section{Future Work}\label{futurework}
-        \subsection{Adhere to Open-Closed Principle}
-                At the moment, \textit{the DatabaseInterface.php} class violates the Open-Closed principle. Every new connector,
-                four lines need to be added in this class. This is unwanted if new RDF datatypes are added. The same holds for
-                the method createArguments in this class: extra cases have to be added if more types of arguments become possible.
-                Adhering to the Open-Closed principle will allow for easier extention and maintenance of the database-related classes.
-
         \subsection{Deal with invalid or missing values}
                 This goes in two parts. Firstly, the database now assumes that given an entry, all the fields for its type are there and
@@ -236 +232 @@
                 does not exist.
 
-        \subsection{Optimize queries}
-                Queries as they are at the moment can be a bottleneck in performance if the sets get really large. This is because of a
-                couple of things. For one, there are duplicate queries being executed: if a Session object is retrieved, it also retrieves
-                all the corresponding AnswerSets, which in turn retrieves the corresponding Questions. However, the Session also
-                retrieves the Surveys related to it, which afterwards also retrieve the same questions. There has been no benchmarking
-                of performance so I have no clue at what size of the .rdf files this will become an issue.
-
-                I have a gut feeling that the SPARQL queries can be optimized some as well. This is regarding entries with zero or more
-                elements of a specific type, like Survey. Now, there is a second query for getting all the IDs for all the questions, but
-                there must be a way to introduce this into the first query without getting the exponential growth of the RDF 'different
-                tree options'.
-
-
 \appendix
 \pagebreak