Major change
[u/philim/db2osl_thesis.git] / program_arch.tex
1 \section{Architecture}
2 \label{arch}
3 \subsection{Libraries used}
4 \subsection{Coarse structuring}
5 \label{coarse}
6 TODO: overall description, modularity, extendability, ex: easy to add new in-/output formats
7 TODO: mapping profiles (maybe better in next subsection)
8 TODO: Java, OPTIQUE
9
10 \subsubsection{Package structuring}
11 The $45$ classes of \myprog{} were assigned to $11$ packages, each containing
12 classes responsible for the same area of operation or taking over similar roles.
13 Care was taken that package division happened senseful, producing meaningful packages
14 with obvious task fields on the one hand, while on the other hand implementing an
15 incisive separation with a notable degree of decoupling.
16 Packages were chosen not to be nested but to be set out vapidly.
17 Since this doesn't have any functional implications \cite{java}, but is rather an
18 implementation detail, this is further explained in Section~\fullref{code_packages}.
19
20 The packages are introduced and described in table \ref{arch_tbl_packages}.
21 The lists of classes each package contains are given in table \ref{arch_tbl_classes}
22 in the next Section~\fullref{fine}.
23 For a detailed package description, refer to Appendix TODO.
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\\
35                 \code{osl} & Classes representing OBDA specifications (as described in \cite{eng}) using the \oslboth{}\\
36                 \code{output} & Classes used to output OBDA specifications as described in \cite{eng}\\
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
45 Besides intuition, as stated, care was involved when partitioning the program into
46 these packages, which included the analysis of the package
47 interaction under a given structure, and the carrying out of changes to
48 make this structure achieve the desired pronounced decoupling with
49 limited and intelligible dependencies.
50
51 The \code{main} package was introduced to make the \code{Main} class,
52 which carries information needed by other packages
53 -- most prominently, the program name --,
54 \code{import}able from inside these packages.
55 For this, it is required for \code{Main} not to reside in the \code{default}
56 package \cite{java}.
57
58 Decoupling some of the functionality of a package into a new package -- which,
59 in a nesting package structure, most probably would have become a sub-package -- and
60 thus sacrificing the benefit of having fewer packages also played a role in some cases.
61 Namely, \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
63 on their own instead of belonging to the \code{specification} package,
64 the classes of the \code{log} and the \code{cli} packages were not merged into
65 one package, although logging currently exclusively happens on the command line,
66 and the functionality of the \code{test} package, though containing only a few
67 lines of code, was separated into its own package.
68
69 Even though the package structure would have become quite simpler with these changes
70 applied -- $4$ out of $11$ packages could have been saved this way --
71 the first aim mentioned -- meaningfulness and intuitiveness -- was taken seriously
72 and the presented partitioning was considered a more natural and
73 comprehensible structuring, emphasizing different roles and thus being a more proper
74 foundation for future extensions of the program.
75 For example, because the \code{bootstrapping} package is central to the program and
76 takes over an active, processing role and in that is completely different
77 from 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.
79 This undergirds the separation of concerns within the program and stresses that
80 the functionality of the \code{bootstrapping} package should not interweave with
81 that in the \code{specification} package, making it easier for both to stay
82 independent and further develop into understandable and suitable units.
83
84
85 \subsubsection{Package interaction}
86 As mentioned, the structuring of the packages was driven by the aim to gain a notable
87 amount of decoupling.
88 How this reflected in the dependency structure, thus the classes from other packages
89 that the classes of a package depend on, is described in the following.
90 As was also mentioned, the information presented here also acted back on the
91 package partitioning, which changed in consequence.
92
93 Dependencies of or on package \code{helpers} are not considered in the following,
94 since this package precisely was meant to offer services used by many other packages.
95 In fact, all facilities provided by \code{helpers} could just as well be part of
96 the \name{Java} API, but unfortunately are not.
97 The current dependency structure, factoring in this restriction, is shown in
98 Figure~\ref{arch_fig_packages} and reveals a conceivably tidy system of
99 dependencies.
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
108 Except for the package \code{settings} (which is further explained below),
109 every package has at most two outgoing edges, that is packages it depends on.
110 Previous versions of \myprog{} had a quite more complicated package dependency structure,
111 depicted in Figure~\ref{arch_fig_packages_earlier}.
112 In this previous package structure, the maximum number of dependencies of
113 packages other than \code{settings} on other packages is three, which also seems
114 reasonably less.
115 However, in the new structuring, \code{specification} has no packages it depends on
116 and thus suits its purpose of providing a mundane and straight-forward
117 representation of an OBDA specification much better.
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
127 Though there still are quite a number of dependencies (to be precise: $19$),
128 many of them ($8$, thus, nearly half) trace back to one central package
129 in the middle, \code{settings}.
130 This may seem odd at first glance, considering that most of the edges connecting to
131 the \code{settings} node are outgoing edges and only one is incoming,
132 whereas in a design where the settings are configured from within a single package
133 and accessed from many other packages this would be the other way round.
134 The reason for this constellation is that, as described in Section~\fullref{interface},
135 all settings in \myprog{} are configured per bootstrapping job
136 (there are no global settings) and so \code{settings}
137 contains a class \code{Job} (and currently no other classes),
138 which represents the configuration of a bootstrapping job but also
139 provides a \code{perform()} method combining the facilities offered by the other
140 packages.
141
142 By this means, the \code{perform()} method of the \code{Job} class acts as the central
143 driver performing the bootstrapping process, reducing the \code{main()} method to
144 only $7$ lines of code and turning \code{settings} into something like an externalized
145 part of the \code{main} package.
146 If, in a future version of the program, this approach is changed and global settings or
147 configuration files are introduced, \code{settings} will still be the central package,
148 leaving the package structure and dependencies unchanged,
149 since it either way contains information used by many other packages.
150 This was the reason why it was not renamed to, for example, \code{driver}, which was
151 considered, since at first glance it seems quite a bit unnatural
152 to have the driver class reside in a package called ``settings''.
153
154 %Package \code{helpers} depends on package \code{database}, which provides the \code{static}
155 %method \code{getSQLTypeName}.
156
157 \subsection{Fine structuring}
158 \label{fine}
159 While the packages in \myprog{} are introduced and described in Section~\fullref{coarse},
160 the classes that comprise them are addressed in this section.
161 For a detailed class index, refer to Appendix TODO.
162 TODO: total classes etc.
163
164 \subsubsection{Package contents}
165 \label{package_details}
166
167 Table \ref{arch_tbl_classes} lists the classes each package contains.
168 The packages \code{cli}, \code{main}, \code{osl} and \code{settings} contain only
169 one class each, while the by far most extensive package is \code{database},
170 containing $15$ classes.
171
172 \begin{table}[H]
173         \begin{multicols}{2}\begin{itemize} %\KOMAoption{fontsize}{\smallerfontsize{}}
174                         \item \code{bootstrapping}
175                         \begin{itemize}
176                                 \item \code{Bootstrapping}
177                                 \item \code{DirectMappingURIBuilder}
178                                 \item \code{URIBuilder}
179                         \end{itemize}
180                         \item \code{cli}
181                         \begin{itemize}
182                                 \item \code{CLIDatabaseInteraction}
183                         \end{itemize}
184                         \item \code{database}
185                         \begin{itemize}
186                                 \item \code{Column}
187                                 \item \code{ColumnSet}
188                                 \item \code{DatabaseException}
189                                 \item \code{DBSchema}
190                                 \item \code{ForeignKey}
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}
199                                 \item \code{Table}
200                                 \item \code{TableSchema}
201                         \end{itemize}
202                         \item \code{helpers}
203                         \begin{itemize}
204                                 \item \code{Helpers}
205                                 \item \code{MapValueIterable}
206                                 \item \code{MapValueIterator}
207                                 \item \code{ReadOnlyIterable}
208                                 \item \code{ReadOnlyIterator}
209                                 \item \code{SQLType}
210                                 \item \code{UserAbortException}
211                         \end{itemize}
212                         \newpage
213                         \item \code{log}
214                         \begin{itemize}
215                                 \item \code{ConsoleDiagnosticOutputHandler}
216                                 \item \code{GlobalLogger}
217                         \end{itemize}
218                         \item \code{main}
219                         \begin{itemize}
220                                 \item \code{Main}
221                         \end{itemize}
222                         \item \code{osl}
223                         \begin{itemize}
224                                 \item \code{OSLSpecification}
225                         \end{itemize}
226                         \item \code{output}
227                         \begin{itemize}
228                                 \item \code{ObjectSpecPrinter}
229                                 \item \code{OSLSpecPrinter}
230                                 \item \code{SpecPrinter}
231                         \end{itemize}
232                         \item \code{settings}
233                         \begin{itemize}
234                                 \item \code{Job}
235                         \end{itemize}
236                         \item \code{specification}
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}
248                         \item \code{test}
249                         \begin{itemize}
250                                 \item \code{CreateTestDBSchema}
251                                 \item \code{GetSomeDBSchema}
252                         \end{itemize}
253                 \end{itemize}\end{multicols} %\KOMAoption{fontsize}{\myfontsize{}}
254                 \caption{Class attachment to packages in \myprog{}}
255                 \label{arch_tbl_classes}
256 \end{table}
257
258 \subsubsection{Class organization}
259 \label{hierarchies}
260 Organizing classes in a structured, obvious manner such that classes have well-defined
261 roles, behave in an intuitive way, ideally representing artifacts from the world
262 modeled in the program directly \cite{str3}, is a prerequisite to make the code
263 clear and comprehensible on the architectural level.
264
265 Section \fullref{code_classes} as part of Section~\fullref{code}
266 describes the identification and naming scheme for the classes in \myprog{}.
267 However, it is also important, to arrange these classes in useful, comprehensible
268 class hierarchies to avoid code duplication, make appropriate use of the type system,
269 ease the design of precise and flexible interfaces and enhance the
270 adaptability and extensibility of the program.
271
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}
284                 \includegraphics[scale=0.86]{Images/inherit_graph_8.pdf}
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}
293                 \includegraphics[scale=0.86]{Images/inherit_graph_7.pdf}
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}
308                 \includegraphics[scale=0.86]{Images/inherit_graph_1.pdf}
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}
327                 \includegraphics[scale=0.86]{Images/inherit_graph_17.pdf}
328                 \caption{\code{SpecPrinter} class hierarchy in \myprog{}}
329                 \label{hier_specprinter}
330 \end{subfigure}\begin{subfigure}[c]{0.3\textwidth}
331                 \includegraphics[scale=0.86]{Images/inherit_graph_13.pdf}
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}
365                 \includegraphics[scale=0.86]{Images/inherit_graph_3.pdf}
366                 \stepsubfigcounter{}
367                 \caption{\code{Iterator} class hierarchy in \myprog{}}
368                 \label{hier_iterator}
369 \end{subfigure}\nextsubfig{}\begin{subfigure}[c]{0.4\textwidth}
370                 \includegraphics[scale=0.86]{Images/inherit_graph_12.pdf}
371                 \stepsubfigcounter{}
372                 \caption{\code{Exception} class hierarchy\\in \myprog{}}
373                 \label{hier_exception}
374 \end{subfigure}\begin{subfigure}[c]{0.5\textwidth}
375                 \includegraphics[scale=0.86]{Images/inherit_graph_4.pdf}
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}
387
388 \begin{table}[H]\begin{center}
389                 \begin{tabular}{l}
390                         \itm{} \code{main.Main}\\
391                         \itm{} \code{database.RetrieveDBSchema}\\
392                         \itm{} \code{database.Table}\\
393                         \itm{} \code{helpers.Helpers}\\
394                         \itm{} \code{helpers.SQLType}\\
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{}}
404         \label{lone_classes}
405 \end{center}\end{table}
406
407 Note that every class hierarchy has at least one \code{interface} at its top.
408 Classes not belonging to a class hierarchy were chosen not to be given an interface
409 ``factitiously'', which would have made them part of a (small) class hierarchy \cite{java}.
410 Deliberately, the scheme often recommended \cite{gof}
411 to give every class an interface it \code{implements} was not followed
412 but the approach described by Stroustrup \cite{str4} to provide a rich set of
413 so called ``concrete types'' not designed for use within class hierarchies, which
414 ``build the foundation of every well-designed program'' \cite{str4}.
415 The details of this consideration are explained in Paragraph~``\nameref{code_interfaces}''
416 in Section~\fullref{code_classes}.
417 In fact, many useful types were already offered by the \name{Java} API
418 and of course were not re-implemented.
419
420 Class \code{Column} with its interface \code{ReadableColumn} is an exception
421 in that it was given an interface although it is basically a concrete type.
422 The reason for this is the chosen way to implement const correctness,
423 described in Paragraph~``\nameref{const}''
424 (which is part of Section~\fullref{code_classes}) TODO.
425 This technique forced class \code{Column} to
426 \code{implement} an interface, thus needlessly making it part of a class hierarchy,
427 but also complicated the structure of some class hierarchies.
428 Consider the class hierarchy around \code{ColumnSet},
429 shown in Figure~\ref{hier_colset_simple}.
430 Definitely, it seems overly complicated at the first glance.
431 But this complexity solely is introduced by the artificial
432 \code{Readable...} interfaces;
433 would \name{Java} provide a mechanism like \name{C++}'s \code{const},
434 this hierarchy would be as simple as in TODO.
435
436 However, since const correctness is an important mechanism effectively preventing
437 errors while on the other hand introducing clarity by itself, it was considered
438 too important to be sacrificed, even for a cleaner and more intuitive class hierarchy.
439 The fact that the \code{Readable...} scheme is very straight-forward and a programmer
440 reading the documentation knows about its purpose and the real, much smaller,
441 complexity also makes some amends for the simplicity sacrificed.
442 The const correctness mechanism itself thereby hinders uninformed or ignorant
443 programmers from mistakenly using the wrong class in an interface in many cases.
444
445 For more information about the program structure on the class level,
446 see Section~\fullref{code}, while for a detailed class index refer to Appendix TODO.