Major change

[u/philim/db2osl_thesis.git] / program_arch.tex

\section{Architecture of \myprog{}}
\label{arch}
\subsection{Libraries used in \myprog{}}
\subsection{Coarse structuring of \myprog{}}
\label{coarse}
TODO: overall description, modularity, extendability, ex: easy to add new in-/output formats
TODO: mapping profiles (maybe better in next subsection)
TODO: Java, OPTIQUE

\subsubsection{Package structuring of \myprog{}}
The $45$ classes of \myprog{} were assigned to $11$ packages, each containing
classes responsible for the same area of operation or taking over similar roles.
Care was taken that package division happened senseful, producing meaningful packages
with obvious task fields on the one hand, while on the other hand implementing an
incisive separation with a notable degree of decoupling.
Packages were chosen not to be nested but to be set out vapidly.
Since this doesn't have any functional implications \cite{java}, but is rather an
implementation detail, this is further explained in Section~\fullref{code_packages}.

The packages are introduced and described in Table~\ref{arch_tbl_packages}.
The lists of classes each package contains are given in Table~\ref{app_tbl_classes}
in Appendix~\fullref{app_pkgs}.

\begin{table}[H]
        \begin{tabular}{p{3cm}|p{13cm}} %\KOMAoption{fontsize}{\smallerfontsize{}}
                Package & Description\\
                \hline
                \code{bootstrapping} & Classes performing bootstrapping\\
                \code{cli} & Classes related to the command line interface of \myprog{}\\
                \code{database} & Classes related to the representation of relational databases and attached tasks\\
                \code{helpers} & Helper classes used program-wide\\
                \code{log} & Classes related to logging and diagnostic output\\
                \code{main} & The \code{Main} class\\
                \code{osl} & Classes representing OBDA specifications (as described in \cite{eng}) using the \oslboth{}\\
                \code{output} & Classes used to output OBDA specifications as described in \cite{eng}\\
                \code{settings} & Classes related to program and job settings (including command line parsing)\\
                \code{specification} & Classes representing (parts of) OBDA specifications (as described in \cite{eng}) directly, without involving \osl{}\\
                \code{test} & Classes offering testing facilities\\
        \end{tabular} %\KOMAoption{fontsize}{\myfontsize{}}
        \caption{Descriptions of the packages in \myprog{}}
        \label{arch_tbl_packages}
\end{table}

Besides intuition, as stated, care was involved when partitioning the program into
these packages, which included the analysis of the package
interaction under a given structure, and the carrying out of changes to
make this structure achieve the desired pronounced decoupling with
limited and intelligible dependencies.

The \code{main} package was introduced to make the \code{Main} class,
which carries information needed by other packages
-- most prominently, the program name --,
\code{import}able from inside these packages.
For this, it is required for \code{Main} not to reside in the \code{default}
package \cite{java}.

Decoupling some of the functionality of a package into a new package -- which,
in a nesting package structure, most probably would have become a sub-package -- and
thus sacrificing the benefit of having fewer packages also played a role in some cases.
Namely, \code{osl} is a package on its own instead of being part of the
\code{specification} package, the \code{bootstrapping} classes also form a package
on their own instead of belonging to the \code{specification} package,
the classes of the \code{log} and the \code{cli} packages were not merged into
one package, although logging currently exclusively happens on the command line,
and the functionality of the \code{test} package, though containing only a few
lines of code, was separated into its own package.

Even though the package structure would have become quite simpler with these changes
applied -- $4$ out of $11$ packages could have been saved this way --
the first aim mentioned -- meaningfulness and intuitiveness -- was taken seriously
and the presented partitioning was considered a more natural and
comprehensible structuring, emphasizing different roles and thus being a more proper
foundation for future extensions of the program.
For example, because the \code{bootstrapping} package is central to the program and
takes over an active, processing role and in that is completely different
from the classes of the \code{specification} package which on their part have a
\emph{representing} role, it was considered senseful not to merge these two packages.
This undergirds the separation of concerns within the program and stresses that
the functionality of the \code{bootstrapping} package should not interweave with
that in the \code{specification} package, making it easier for both to stay
independent and further develop into understandable and suitable units.


\subsubsection{Package interaction}
As mentioned, the structuring of the packages was driven by the aim to gain a notable
amount of decoupling.
How this reflected in the dependency structure, thus the classes from other packages
that the classes of a package depend on, is described in the following.
As was also mentioned, the information presented here also acted back on the
package partitioning, which changed in consequence.

Dependencies of or on package \code{helpers} are not considered in the following,
since this package precisely was meant to offer services used by many other packages.
In fact, all facilities provided by \code{helpers} could just as well be part of
the \name{Java} API, but unfortunately are not.
The current dependency structure, factoring in this restriction, is shown in
Figure~\ref{arch_fig_packages} and reveals a conceivably tidy system of
dependencies.

\begin{figure}[H]\begin{center}
                \includegraphics[scale=0.86]{Images/package_graph.pdf}
                \caption[Package dependencies in \myprog{}]{Package dependencies in \myprog{}.
                        ``$\rightarrow$'' means ``depends on''.}
                \label{arch_fig_packages}
\end{center}\end{figure}

Except for the package \code{settings} (which is further explained below),
every package has at most two outgoing edges, that is packages it depends on.
Previous versions of \myprog{} had a quite more complicated package dependency structure,
depicted in Figure~\ref{arch_fig_packages_earlier}.
In this previous package structure, the maximum number of dependencies of
packages other than \code{settings} on other packages is three, which also seems
reasonably less.
However, in the new structuring, \code{specification} has no packages it depends on
and thus suits its purpose of providing a mundane and straight-forward
representation of an OBDA specification much better.
%Furthermore, \code{output} doesn't depend on \code{database} anymore.

\begin{figure}[H]\begin{center}
                \includegraphics[scale=0.86]{Images/package_graph_earlier.pdf}
                \caption[Package dependencies in earlier versions of \myprog{}]{Package dependencies
                        in earlier versions of \myprog{}. ``$\rightarrow$'' again means ``depends on''.}
                \label{arch_fig_packages_earlier}
\end{center}\end{figure}

Though there still are quite a number of dependencies (to be precise: $19$),
many of them ($8$, thus, nearly half) trace back to one central package
in the middle, \code{settings}.
This may seem odd at first glance, considering that most of the edges connecting to
the \code{settings} node are outgoing edges and only one is incoming,
whereas in a design where the settings are configured from within a single package
and accessed from many other packages this would be the other way round.
The reason for this constellation is that, as described in Section~\fullref{interface},
all settings in \myprog{} are configured per bootstrapping job
(there are no global settings) and so \code{settings}
contains a class \code{Job} (and currently no other classes),
which represents the configuration of a bootstrapping job but also
provides a \code{perform()} method combining the facilities offered by the other
packages.

By this means, the \code{perform()} method of the \code{Job} class acts as the central
driver performing the bootstrapping process, reducing the \code{main()} method to
only $7$ lines of code and turning \code{settings} into something like an externalized
part of the \code{main} package.
If, in a future version of the program, this approach is changed and global settings or
configuration files are introduced, \code{settings} will still be the central package,
leaving the package structure and dependencies unchanged,
since it either way contains information used by many other packages.
This was the reason why it was not renamed to, for example, \code{driver}, which was
considered, since at first glance it seems quite a bit unnatural
to have the driver class reside in a package called ``settings''.

%Package \code{helpers} depends on package \code{database}, which provides the \code{static}
%method \code{getSQLTypeName}.

\subsection{Fine structuring of \myprog{}}
\label{fine}
TODO: OBDA spec rep

While the packages in \myprog{} are introduced and described in Section~\fullref{coarse},
the classes that comprise them are addressed in this section.
For a list of classes contained in each package, refer to Appendix \ref{app_pkgs}.

TODO: total classes etc.

\subsubsection{Package contents}
\label{package_details}

Table~\ref{app_tbl_classes} lists the classes each package contains.
The packages \code{cli}, \code{main}, \code{osl} and \code{settings} contain only
one class each, while the by far most extensive package is \code{database},
containing $15$ classes.

\subsubsection{Class organization}
\label{hierarchies}
Organizing classes in a structured, obvious manner such that classes have well-defined
roles, behave in an intuitive way, ideally representing artifacts from the world
modeled in the program directly \cite{str3}, is a prerequisite to make the code
clear and comprehensible on the architectural level.

Section \fullref{code_classes} as part of Section~\fullref{code}
describes the identification and naming scheme for the classes in \myprog{}.
However, it is also important, to arrange these classes in useful, comprehensible
class hierarchies to avoid code duplication, make appropriate use of the type system,
ease the design of precise and flexible interfaces and enhance the
adaptability and extensibility of the program.

\newcounter{myFigureNumber}
\setcounter{myFigureNumber}{\value{figure}}
\newcommand{\stepfigcounter}{\stepcounter{myFigureNumber}\setcounter{figure}
        {\value{myFigureNumber}}}

\newcounter{mySubfigureNumber}
\newcommand{\stepsubfigcounter}{\stepcounter{mySubfigureNumber}\setcounter{subfigure}
        {\value{mySubfigureNumber}}}

\newcommand{\nextsubfig}{~\\\vspace{12px}}

\begin{figure}[H]\centering\begin{subfigure}[b]{\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_8.pdf}
                \caption{\code{ColumnSet} class hierarchy in \myprog{}}
                \label{hier_colset}
\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.5\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_8_simplified.pdf}
                \stepsubfigcounter{}
                \caption{\code{ColumnSet} class hierarchy in \myprog{} -- simplified}
                \label{hier_colset_simple}
\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.3\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_7.pdf}
                \stepsubfigcounter{}
                \caption{\code{Column} class hierarchy\\in \myprog{}}
                \label{hier_column}
\end{subfigure}
        \stepfigcounter{}
        \caption[Database class hierarchies in \myprog{}]{
                Database class hierarchies in \myprog{}.
                Interface names are italicized,
                external classes or interfaces are hemmed with a gray frame.}
        \label{hiers_db}
\end{figure}

\setcounter{mySubfigureNumber}{0}
\begin{figure}[H]\centering\begin{subfigure}[b]{0.3\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_1.pdf}
                \label{hier_uribuilder}
                \caption{\code{URIBuilder} class hierarchy in \myprog{}}
\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.5\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_19.pdf}
                \stepsubfigcounter{}
                \caption{\code{OBDAMap} class hierarchy in \myprog{}}
                \label{hier_obdamap}
\end{subfigure}
        \stepfigcounter{}
        \caption[OBDA specification class hierarchies in \myprog{}]{
                OBDA specification class hierarchies in \myprog{}.
                Interface names are italicized,
                external classes or interfaces are hemmed with a gray frame.}
        \label{hiers_obdaspec}
\end{figure}

\setcounter{mySubfigureNumber}{0}
\begin{figure}[H]\centering\begin{subfigure}[c]{0.6\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_17.pdf}
                \caption{\code{SpecPrinter} class hierarchy in \myprog{}}
                \label{hier_specprinter}
\end{subfigure}\begin{subfigure}[c]{0.3\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_13.pdf}
                \stepsubfigcounter{}
                \caption{\code{StreamHandler} class hierarchy in \myprog{}}
                \label{hier_streamhandler}
\end{subfigure}
        \stepfigcounter{}
        \caption[Logging and output class hierarchies in \myprog{}]{
                Logging and output class hierarchies in \myprog{}.
                Interface names are italicized,
                external classes or interfaces are hemmed with a gray frame.}
        \label{hiers_output}
\end{figure}

\begin{figure}[H]\centering
        \includegraphics[scale=0.86]{Images/inherit_graph_18.pdf}
        \caption[\code{Job} class hierarchy in \myprog{}]{
                \code{Job} class hierarchy in \myprog{}.
                Interface names are italicized,
                external classes or interfaces are hemmed with a gray frame.}
        \label{hier_job}
\end{figure}
\stepfigcounter{}

\setcounter{mySubfigureNumber}{0}
\begin{figure}[H]\centering\begin{subfigure}[b]{\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_5.pdf}
                \caption{\code{Iterable} class hierarchy in \myprog{}}
                \label{hier_iterable}
\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.3\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_21_extended.pdf}
                \stepsubfigcounter{}
                \caption{\code{ReadOnlyIterator} class\\hierarchy in \myprog{}}
                \label{hier_roiterator}
\end{subfigure}\nextsubfig{}\begin{subfigure}[b]{0.8\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_3.pdf}
                \stepsubfigcounter{}
                \caption{\code{Iterator} class hierarchy in \myprog{}}
                \label{hier_iterator}
\end{subfigure}\nextsubfig{}\begin{subfigure}[c]{0.4\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_12.pdf}
                \stepsubfigcounter{}
                \caption{\code{Exception} class hierarchy\\in \myprog{}}
                \label{hier_exception}
\end{subfigure}\begin{subfigure}[c]{0.5\textwidth}
                \includegraphics[scale=0.86]{Images/inherit_graph_4.pdf}
                \stepsubfigcounter{}
                \caption{\code{RuntimeException} class hierarchy in \myprog{}}
                \label{hier_rtexception}
\end{subfigure}
        \stepfigcounter{}
        \caption[Miscellaneous class hierarchies in \myprog{}]{
                Miscellaneous class hierarchies in \myprog{}.
                Interface names are italicized,
                external classes or interfaces are hemmed with a gray frame.}
        \label{hiers_misc}
\end{figure}

\begin{table}[H]\begin{center}
                \begin{tabular}{l}
                        \itm{} \code{main.Main}\\
                        \itm{} \code{database.RetrieveDBSchema}\\
                        \itm{} \code{database.Table}\\
                        \itm{} \code{helpers.Helpers}\\
                        \itm{} \code{helpers.SQLType}\\
                        \itm{} \code{specification.OBDASpecification}\\
                        \itm{} \code{osl.OSLSpecification}\\
                        \itm{} \code{bootstrapping.Bootstrapping}\\
                        \itm{} \code{cli.CLIDatabaseInteraction}\\
                        \itm{} \code{log.GlobalLogger}\\
                        \itm{} \code{test.CreateTestDBSchema}\\
                        \itm{} \code{test.GetSomeDBSchema}\\
                \end{tabular}\\
        \caption{Standalone classes in \myprog{}}
        \label{lone_classes}
\end{center}\end{table}

Note that every class hierarchy has at least one \code{interface} at its top.
Classes not belonging to a class hierarchy were chosen not to be given an interface
``factitiously'', which would have made them part of a (small) class hierarchy \cite{java}.
Deliberately, the scheme often recommended \cite{gof}
to give every class an interface it \code{implements} was not followed
but the approach described by Stroustrup \cite{str4} to provide a rich set of
so called ``concrete types'' not designed for use within class hierarchies, which
``build the foundation of every well-designed program'' \cite{str4}.
The details of this consideration are explained in Paragraph~``\nameref{code_interfaces}''
in Section~\fullref{code_classes}.
In fact, many useful types were already offered by the \name{Java} API
and of course were not re-implemented.

Class \code{Column} with its interface \code{ReadableColumn} is an exception
in that it was given an interface although it is basically a concrete type.
The reason for this is the chosen way to implement const correctness,
described in Paragraph~``\nameref{const}''
(which is part of Section~\fullref{code_classes}) TODO.
This technique forced class \code{Column} to
\code{implement} an interface, thus needlessly making it part of a class hierarchy,
but also complicated the structure of some class hierarchies.
Consider the class hierarchy around \code{ColumnSet},
shown in Figure~\ref{hier_colset_simple}.
Definitely, it seems overly complicated at the first glance.
But this complexity solely is introduced by the artificial
\code{Readable...} interfaces;
would \name{Java} provide a mechanism like \name{C++}'s \code{const},
this hierarchy would be as simple as in TODO.

However, since const correctness is an important mechanism effectively preventing
errors while on the other hand introducing clarity by itself, it was considered
too important to be sacrificed, even for a cleaner and more intuitive class hierarchy.
The fact that the \code{Readable...} scheme is very straight-forward and a programmer
reading the documentation knows about its purpose and the real, much smaller,
complexity also makes some amends for the simplicity sacrificed.
The const correctness mechanism itself thereby hinders uninformed or ignorant
programmers from mistakenly using the wrong class in an interface in many cases.

For more information about the program structure on the class level,
see Section~\fullref{code}, while for a detailed class index refer to Appendix TODO.