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