Major change
[u/philim/db2osl_thesis.git] / program_arch.tex
CommitLineData
c31df1ed
PM
1\section{Architecture}
2\label{arch}
3\subsection{Libraries used}
4\subsection{Coarse structuring}
28b54c67 5\label{coarse}
c31df1ed
PM
6TODO: overall description, modularity, extendability, ex: easy to add new in-/output formats
7TODO: mapping profiles (maybe better in next subsection)
b96bb723 8TODO: Java, OPTIQUE
26717a83 9
62fe6284 10\subsubsection{Package structuring}
26717a83
PM
11The $45$ classes of \myprog{} were assigned to $11$ packages, each containing
12classes responsible for the same area of operation or taking over similar roles.
13Care was taken that package division happened senseful, producing meaningful packages
14with obvious task fields on the one hand, while on the other hand implementing an
15incisive separation with a notable degree of decoupling.
16Packages were chosen not to be nested but to be set out vapidly.
17Since this doesn't have any functional implications \cite{java}, but is rather an
b96bb723 18implementation detail, this is further explained in Section~\fullref{code_packages}.
26717a83
PM
19
20The packages are introduced and described in table \ref{arch_tbl_packages}.
21The lists of classes each package contains are given in table \ref{arch_tbl_classes}
b96bb723 22in the next Section~\fullref{fine}.
62fe6284 23For a detailed package description, refer to Appendix TODO.
26717a83
PM
24
25\begin{table}[H]
26 \begin{tabular}{p{3cm}|p{13cm}} %\KOMAoption{fontsize}{\smallerfontsize{}}
27 Package & Description\\
28 \hline
29 \code{bootstrapping} & Classes performing bootstrapping\\
30 \code{cli} & Classes related to the command line interface of \myprog{}\\
31 \code{database} & Classes related to the representation of relational databases and attached tasks\\
32 \code{helpers} & Helper classes used program-wide\\
33 \code{log} & Classes related to logging and diagnostic output\\
34 \code{main} & The \code{Main} class\\
b96bb723 35 \code{osl} & Classes representing OBDA specifications (as described in \cite{eng}) using the \oslboth{}\\
002fa020 36 \code{output} & Classes used to output OBDA specifications as described in \cite{eng}\\
26717a83
PM
37 \code{settings} & Classes related to program and job settings (including command line parsing)\\
38 \code{specification} & Classes representing (parts of) OBDA specifications (as described in \cite{eng}) directly, without involving \osl{}\\
39 \code{test} & Classes offering testing facilities\\
40 \end{tabular} %\KOMAoption{fontsize}{\myfontsize{}}
41 \caption{Descriptions of the packages in \myprog{}}
42 \label{arch_tbl_packages}
43\end{table}
44
45Besides intuition, as stated, care was involved when partitioning the program into
46these packages, which included the analysis of the package
47interaction under a given structure, and the carrying out of changes to
48make this structure achieve the desired pronounced decoupling with
49limited and intelligible dependencies.
50
51The \code{main} package was introduced to make the \code{Main} class,
52which carries information needed by other packages
53-- most prominently, the program name --,
54\code{import}able from inside these packages.
55For this, it is required for \code{Main} not to reside in the \code{default}
56package \cite{java}.
57
62fe6284
PM
58Decoupling some of the functionality of a package into a new package -- which,
59in a nesting package structure, most probably would have become a sub-package -- and
60thus sacrificing the benefit of having fewer packages also played a role in some cases.
61Namely, \code{osl} is a package on its own instead of being part of the
62\code{specification} package, the \code{bootstrapping} classes also form a package
63on their own instead of belonging to the \code{specification} package,
64the classes of the \code{log} and the \code{cli} packages were not merged into
65one package, although logging currently exclusively happens on the command line,
66and the functionality of the \code{test} package, though containing only a few
67lines of code, was separated into its own package.
68
69Even though the package structure would have become quite simpler with these changes
70applied -- $4$ out of $11$ packages could have been saved this way --
71the first aim mentioned -- meaningfulness and intuitiveness -- was taken seriously
72and the presented partitioning was considered a more natural and
73comprehensible structuring, emphasizing different roles and thus being a more proper
74foundation for future extensions of the program.
75For example, because the \code{bootstrapping} package is central to the program and
002fa020 76takes over an active, processing role and in that is completely different
62fe6284
PM
77from the classes of the \code{specification} package which on their part have a
78\emph{representing} role, it was considered senseful not to merge these two packages.
79This undergirds the separation of concerns within the program and stresses that
80the functionality of the \code{bootstrapping} package should not interweave with
81that in the \code{specification} package, making it easier for both to stay
82independent and further develop into understandable and suitable units.
83
84
26717a83
PM
85\subsubsection{Package interaction}
86As mentioned, the structuring of the packages was driven by the aim to gain a notable
87amount of decoupling.
88How this reflected in the dependency structure, thus the classes from other packages
89that the classes of a package depend on, is described in the following.
90As was also mentioned, the information presented here also acted back on the
91package partitioning, which changed in consequence.
92
93Dependencies of or on package \code{helpers} are not considered in the following,
94since this package precisely was meant to offer services used by many other packages.
95In fact, all facilities provided by \code{helpers} could just as well be part of
96the \name{Java} API, but unfortunately are not.
b96bb723
PM
97The current dependency structure, factoring in this restriction, is shown in
98Figure~\ref{arch_fig_packages} and reveals a conceivably tidy system of
99dependencies.
26717a83
PM
100
101\begin{figure}[H]\begin{center}
102 \includegraphics[scale=0.86]{Images/package_graph.pdf}
103 \caption[Package dependencies in \myprog{}]{Package dependencies in \myprog{}.
104 ``$\rightarrow$'' means ``depends on''.}
105 \label{arch_fig_packages}
106\end{center}\end{figure}
107
62fe6284
PM
108Except for the package \code{settings} (which is further explained below),
109every package has at most two outgoing edges, that is packages it depends on.
110Previous versions of \myprog{} had a quite more complicated package dependency structure,
b96bb723 111depicted in Figure~\ref{arch_fig_packages_earlier}.
62fe6284
PM
112In this previous package structure, the maximum number of dependencies of
113packages other than \code{settings} on other packages is three, which also seems
114reasonably less.
115However, in the new structuring, \code{specification} has no packages it depends on
116and thus suits its purpose of providing a mundane and straight-forward
002fa020 117representation of an OBDA specification much better.
62fe6284
PM
118%Furthermore, \code{output} doesn't depend on \code{database} anymore.
119
120\begin{figure}[H]\begin{center}
121 \includegraphics[scale=0.86]{Images/package_graph_earlier.pdf}
122 \caption[Package dependencies in earlier versions of \myprog{}]{Package dependencies
123 in earlier versions of \myprog{}. ``$\rightarrow$'' again means ``depends on''.}
124 \label{arch_fig_packages_earlier}
125\end{center}\end{figure}
126
127Though there still are quite a number of dependencies (to be precise: $19$),
128many of them ($8$, thus, nearly half) trace back to one central package
129in the middle, \code{settings}.
130This may seem odd at first glance, considering that most of the edges connecting to
131the \code{settings} node are outgoing edges and only one is incoming,
26717a83
PM
132whereas in a design where the settings are configured from within a single package
133and accessed from many other packages this would be the other way round.
b96bb723 134The reason for this constellation is that, as described in Section~\fullref{interface},
26717a83
PM
135all settings in \myprog{} are configured per bootstrapping job
136(there are no global settings) and so \code{settings}
62fe6284
PM
137contains a class \code{Job} (and currently no other classes),
138which represents the configuration of a bootstrapping job but also
26717a83
PM
139provides a \code{perform()} method combining the facilities offered by the other
140packages.
141
62fe6284 142By this means, the \code{perform()} method of the \code{Job} class acts as the central
b96bb723 143driver performing the bootstrapping process, reducing the \code{main()} method to
26717a83
PM
144only $7$ lines of code and turning \code{settings} into something like an externalized
145part of the \code{main} package.
146If, in a future version of the program, this approach is changed and global settings or
147configuration files are introduced, \code{settings} will still be the central package,
148leaving the package structure and dependencies unchanged,
149since it either way contains information used by many other packages.
150This was the reason why it was not renamed to, for example, \code{driver}, which was
62fe6284
PM
151considered, since at first glance it seems quite a bit unnatural
152to have the driver class reside in a package called ``settings''.
26717a83
PM
153
154%Package \code{helpers} depends on package \code{database}, which provides the \code{static}
155%method \code{getSQLTypeName}.
c31df1ed
PM
156
157\subsection{Fine structuring}
26717a83 158\label{fine}
b96bb723 159While the packages in \myprog{} are introduced and described in Section~\fullref{coarse},
26717a83 160the classes that comprise them are addressed in this section.
62fe6284
PM
161For a detailed class index, refer to Appendix TODO.
162TODO: total classes etc.
163
164\subsubsection{Package contents}
165\label{package_details}
28b54c67 166
26717a83
PM
167Table \ref{arch_tbl_classes} lists the classes each package contains.
168The packages \code{cli}, \code{main}, \code{osl} and \code{settings} contain only
169one class each, while the by far most extensive package is \code{database},
62fe6284 170containing $15$ classes.
26717a83
PM
171
172\begin{table}[H]
28b54c67 173 \begin{multicols}{2}\begin{itemize} %\KOMAoption{fontsize}{\smallerfontsize{}}
26717a83 174 \item \code{bootstrapping}
28b54c67
PM
175 \begin{itemize}
176 \item \code{Bootstrapping}
177 \item \code{DirectMappingURIBuilder}
178 \item \code{URIBuilder}
179 \end{itemize}
26717a83 180 \item \code{cli}
28b54c67
PM
181 \begin{itemize}
182 \item \code{CLIDatabaseInteraction}
183 \end{itemize}
26717a83 184 \item \code{database}
28b54c67
PM
185 \begin{itemize}
186 \item \code{Column}
187 \item \code{ColumnSet}
188 \item \code{DatabaseException}
189 \item \code{DBSchema}
190 \item \code{ForeignKey}
28b54c67
PM
191 \item \code{Key}
192 \item \code{PrimaryKey}
193 \item \code{ReadableColumn}
194 \item \code{ReadableColumnSet}
195 \item \code{ReadableForeignKey}
196 \item \code{ReadableKey}
197 \item \code{ReadablePrimaryKey}
198 \item \code{RetrieveDBSchema}
28b54c67
PM
199 \item \code{Table}
200 \item \code{TableSchema}
201 \end{itemize}
26717a83 202 \item \code{helpers}
28b54c67 203 \begin{itemize}
62fe6284 204 \item \code{Helpers}
28b54c67
PM
205 \item \code{MapValueIterable}
206 \item \code{MapValueIterator}
207 \item \code{ReadOnlyIterable}
208 \item \code{ReadOnlyIterator}
62fe6284 209 \item \code{SQLType}
28b54c67
PM
210 \item \code{UserAbortException}
211 \end{itemize}
212 \newpage
26717a83 213 \item \code{log}
28b54c67
PM
214 \begin{itemize}
215 \item \code{ConsoleDiagnosticOutputHandler}
216 \item \code{GlobalLogger}
217 \end{itemize}
26717a83 218 \item \code{main}
28b54c67
PM
219 \begin{itemize}
220 \item \code{Main}
221 \end{itemize}
26717a83 222 \item \code{osl}
28b54c67
PM
223 \begin{itemize}
224 \item \code{OSLSpecification}
225 \end{itemize}
26717a83 226 \item \code{output}
28b54c67
PM
227 \begin{itemize}
228 \item \code{ObjectSpecPrinter}
229 \item \code{OSLSpecPrinter}
230 \item \code{SpecPrinter}
231 \end{itemize}
26717a83 232 \item \code{settings}
28b54c67
PM
233 \begin{itemize}
234 \item \code{Job}
235 \end{itemize}
26717a83 236 \item \code{specification}
28b54c67
PM
237 \begin{itemize}
238 \item \code{AttributeMap}
239 \item \code{EntityMap}
240 \item \code{IdentifierMap}
241 \item \code{InvalidSpecificationException}
242 \item \code{OBDAMap}
243 \item \code{OBDASpecification}
244 \item \code{RelationMap}
245 \item \code{SubtypeMap}
246 \item \code{TranslationTable}
247 \end{itemize}
26717a83 248 \item \code{test}
28b54c67
PM
249 \begin{itemize}
250 \item \code{CreateTestDBSchema}
251 \item \code{GetSomeDBSchema}
252 \end{itemize}
26717a83
PM
253 \end{itemize}\end{multicols} %\KOMAoption{fontsize}{\myfontsize{}}
254 \caption{Class attachment to packages in \myprog{}}
255 \label{arch_tbl_classes}
28b54c67
PM
256\end{table}
257
26717a83
PM
258\subsubsection{Class organization}
259\label{hierarchies}
260Organizing classes in a structured, obvious manner such that classes have well-defined
261roles, behave in an intuitive way, ideally representing artifacts from the world
262modeled in the program directly \cite{str3}, is a prerequisite to make the code
263clear and comprehensible on the architectural level.
264
b96bb723 265Section \fullref{code_classes} as part of Section~\fullref{code}
62fe6284 266describes the identification and naming scheme for the classes in \myprog{}.
26717a83
PM
267However, it is also important, to arrange these classes in useful, comprehensible
268class hierarchies to avoid code duplication, make appropriate use of the type system,
269ease the design of precise and flexible interfaces and enhance the
270adaptability and extensibility of the program.
28b54c67 271
b96bb723
PM
272\newcounter{myFigureNumber}
273\setcounter{myFigureNumber}{\value{figure}}
274\newcommand{\stepfigcounter}{\stepcounter{myFigureNumber}\setcounter{figure}
275 {\value{myFigureNumber}}}
276
277\newcounter{mySubfigureNumber}
278\newcommand{\stepsubfigcounter}{\stepcounter{mySubfigureNumber}\setcounter{subfigure}
279 {\value{mySubfigureNumber}}}
280
281\newcommand{\nextsubfig}{~\\\vspace{12px}}
282
283\begin{figure}[H]\centering\begin{subfigure}[b]{\textwidth}
28b54c67 284 \includegraphics[scale=0.86]{Images/inherit_graph_8.pdf}
b96bb723
PM
285 \caption{\code{ColumnSet} class hierarchy in \myprog{}}
286 \label{hier_colset}
287\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.5\textwidth}
288 \includegraphics[scale=0.86]{Images/inherit_graph_8_simplified.pdf}
289 \stepsubfigcounter{}
290 \caption{\code{ColumnSet} class hierarchy in \myprog{} -- simplified}
291 \label{hier_colset_simple}
292\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.3\textwidth}
28b54c67 293 \includegraphics[scale=0.86]{Images/inherit_graph_7.pdf}
b96bb723
PM
294 \stepsubfigcounter{}
295 \caption{\code{Column} class hierarchy\\in \myprog{}}
296 \label{hier_column}
297\end{subfigure}
298 \stepfigcounter{}
299 \caption[Database class hierarchies in \myprog{}]{
300 Database class hierarchies in \myprog{}.
301 Interface names are italicized,
302 external classes or interfaces are hemmed with a gray frame.}
303 \label{hiers_db}
304\end{figure}
305
306\setcounter{mySubfigureNumber}{0}
307\begin{figure}[H]\centering\begin{subfigure}[b]{0.3\textwidth}
28b54c67 308 \includegraphics[scale=0.86]{Images/inherit_graph_1.pdf}
b96bb723
PM
309 \label{hier_uribuilder}
310 \caption{\code{URIBuilder} class hierarchy in \myprog{}}
311\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.5\textwidth}
312 \includegraphics[scale=0.86]{Images/inherit_graph_19.pdf}
313 \stepsubfigcounter{}
314 \caption{\code{OBDAMap} class hierarchy in \myprog{}}
315 \label{hier_obdamap}
316\end{subfigure}
317 \stepfigcounter{}
318 \caption[OBDA specification class hierarchies in \myprog{}]{
319 OBDA specification class hierarchies in \myprog{}.
320 Interface names are italicized,
321 external classes or interfaces are hemmed with a gray frame.}
322 \label{hiers_obdaspec}
323\end{figure}
324
325\setcounter{mySubfigureNumber}{0}
326\begin{figure}[H]\centering\begin{subfigure}[c]{0.6\textwidth}
28b54c67 327 \includegraphics[scale=0.86]{Images/inherit_graph_17.pdf}
b96bb723
PM
328 \caption{\code{SpecPrinter} class hierarchy in \myprog{}}
329 \label{hier_specprinter}
330\end{subfigure}\begin{subfigure}[c]{0.3\textwidth}
28b54c67 331 \includegraphics[scale=0.86]{Images/inherit_graph_13.pdf}
b96bb723
PM
332 \stepsubfigcounter{}
333 \caption{\code{StreamHandler} class hierarchy in \myprog{}}
334 \label{hier_streamhandler}
335\end{subfigure}
336 \stepfigcounter{}
337 \caption[Logging and output class hierarchies in \myprog{}]{
338 Logging and output class hierarchies in \myprog{}.
339 Interface names are italicized,
340 external classes or interfaces are hemmed with a gray frame.}
341 \label{hiers_output}
342\end{figure}
343
344\begin{figure}[H]\centering
345 \includegraphics[scale=0.86]{Images/inherit_graph_18.pdf}
346 \caption[\code{Job} class hierarchy in \myprog{}]{
347 \code{Job} class hierarchy in \myprog{}.
348 Interface names are italicized,
349 external classes or interfaces are hemmed with a gray frame.}
350 \label{hier_job}
351\end{figure}
352\stepfigcounter{}
353
354\setcounter{mySubfigureNumber}{0}
355\begin{figure}[H]\centering\begin{subfigure}[b]{\textwidth}
356 \includegraphics[scale=0.86]{Images/inherit_graph_5.pdf}
357 \caption{\code{Iterable} class hierarchy in \myprog{}}
358 \label{hier_iterable}
359\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.3\textwidth}
360 \includegraphics[scale=0.86]{Images/inherit_graph_21_extended.pdf}
361 \stepsubfigcounter{}
362 \caption{\code{ReadOnlyIterator} class\\hierarchy in \myprog{}}
363 \label{hier_roiterator}
364\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.8\textwidth}
28b54c67 365 \includegraphics[scale=0.86]{Images/inherit_graph_3.pdf}
b96bb723
PM
366 \stepsubfigcounter{}
367 \caption{\code{Iterator} class hierarchy in \myprog{}}
368 \label{hier_iterator}
369\end{subfigure}\nextsubfig{}\begin{subfigure}[c]{0.4\textwidth}
28b54c67 370 \includegraphics[scale=0.86]{Images/inherit_graph_12.pdf}
b96bb723
PM
371 \stepsubfigcounter{}
372 \caption{\code{Exception} class hierarchy\\in \myprog{}}
373 \label{hier_exception}
374\end{subfigure}\begin{subfigure}[c]{0.5\textwidth}
28b54c67 375 \includegraphics[scale=0.86]{Images/inherit_graph_4.pdf}
b96bb723
PM
376 \stepsubfigcounter{}
377 \caption{\code{RuntimeException} class hierarchy in \myprog{}}
378 \label{hier_rtexception}
379\end{subfigure}
380 \stepfigcounter{}
381 \caption[Miscellaneous class hierarchies in \myprog{}]{
382 Miscellaneous class hierarchies in \myprog{}.
383 Interface names are italicized,
384 external classes or interfaces are hemmed with a gray frame.}
385 \label{hiers_misc}
386\end{figure}
c31df1ed 387
c31df1ed
PM
388\begin{table}[H]\begin{center}
389 \begin{tabular}{l}
390 \itm{} \code{main.Main}\\
c31df1ed 391 \itm{} \code{database.RetrieveDBSchema}\\
c31df1ed 392 \itm{} \code{database.Table}\\
62fe6284
PM
393 \itm{} \code{helpers.Helpers}\\
394 \itm{} \code{helpers.SQLType}\\
c31df1ed
PM
395 \itm{} \code{specification.OBDASpecification}\\
396 \itm{} \code{osl.OSLSpecification}\\
397 \itm{} \code{bootstrapping.Bootstrapping}\\
398 \itm{} \code{cli.CLIDatabaseInteraction}\\
399 \itm{} \code{log.GlobalLogger}\\
400 \itm{} \code{test.CreateTestDBSchema}\\
401 \itm{} \code{test.GetSomeDBSchema}\\
402 \end{tabular}\\
403 \caption{Standalone classes in \myprog{}}
b96bb723 404 \label{lone_classes}
c31df1ed
PM
405\end{center}\end{table}
406
26717a83
PM
407Note that every class hierarchy has at least one \code{interface} at its top.
408Classes not belonging to a class hierarchy were chosen not to be given an interface
002fa020
PM
409``factitiously'', which would have made them part of a (small) class hierarchy \cite{java}.
410Deliberately, the scheme often recommended \cite{gof}
26717a83
PM
411to give every class an interface it \code{implements} was not followed
412but the approach described by Stroustrup \cite{str4} to provide a rich set of
413so called ``concrete types'' not designed for use within class hierarchies, which
002fa020 414``build the foundation of every well-designed program'' \cite{str4}.
b96bb723
PM
415The details of this consideration are explained in Paragraph~``\nameref{code_interfaces}''
416in Section~\fullref{code_classes}.
62fe6284
PM
417In fact, many useful types were already offered by the \name{Java} API
418and of course were not re-implemented.
26717a83 419
002fa020 420Class \code{Column} with its interface \code{ReadableColumn} is an exception
26717a83
PM
421in that it was given an interface although it is basically a concrete type.
422The reason for this is the chosen way to implement const correctness,
b96bb723
PM
423described in Paragraph~``\nameref{const}''
424(which is part of Section~\fullref{code_classes}) TODO.
26717a83
PM
425This technique forced class \code{Column} to
426\code{implement} an interface, thus needlessly making it part of a class hierarchy,
427but also complicated the structure of some class hierarchies.
428Consider the class hierarchy around \code{ColumnSet},
b96bb723 429shown in Figure~\ref{hier_colset_simple}.
26717a83
PM
430Definitely, it seems overly complicated at the first glance.
431But this complexity solely is introduced by the artificial
432\code{Readable...} interfaces;
433would \name{Java} provide a mechanism like \name{C++}'s \code{const},
b96bb723 434this hierarchy would be as simple as in TODO.
26717a83 435
62fe6284
PM
436However, since const correctness is an important mechanism effectively preventing
437errors while on the other hand introducing clarity by itself, it was considered
438too important to be sacrificed, even for a cleaner and more intuitive class hierarchy.
439The fact that the \code{Readable...} scheme is very straight-forward and a programmer
440reading the documentation knows about its purpose and the real, much smaller,
441complexity also makes some amends for the simplicity sacrificed.
442The const correctness mechanism itself thereby hinders uninformed or ignorant
443programmers from mistakenly using the wrong class in an interface in many cases.
26717a83
PM
444
445For more information about the program structure on the class level,
b96bb723 446see Section~\fullref{code}, while for a detailed class index refer to Appendix TODO.