\label{coarse}
TODO: overall description, modularity, extendability, ex: easy to add new in-/output formats
TODO: mapping profiles (maybe better in next subsection)
-TODO: package description
-TODO: package interaction description
+
+\subsubsection{Package structuring}
+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{arch_tbl_classes}
+in the next section \fullref{fine}.
+For a detailed package description, refer to Appendix TODO.
+
+\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 OBDA Specification Language (\osl{})\\
+ \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 TODO 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 two
+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}
-\subsubsection{Class organization}
-TODO: Every class hierarchy has at least one interface
+\label{fine}
+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 detailed class index, refer to Appendix TODO.
+TODO: total classes etc.
+
+\subsubsection{Package contents}
+\label{package_details}
+
+Table \ref{arch_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.
-\begin{table}
+\begin{table}[H]
\begin{multicols}{2}\begin{itemize} %\KOMAoption{fontsize}{\smallerfontsize{}}
- \item \code{bootstrapping}
+ \item \code{bootstrapping}
\begin{itemize}
\item \code{Bootstrapping}
\item \code{DirectMappingURIBuilder}
\item \code{URIBuilder}
\end{itemize}
- \item \code{cli}
+ \item \code{cli}
\begin{itemize}
\item \code{CLIDatabaseInteraction}
\end{itemize}
- \item \code{database}
+ \item \code{database}
\begin{itemize}
\item \code{Column}
\item \code{ColumnSet}
\item \code{DatabaseException}
\item \code{DBSchema}
\item \code{ForeignKey}
- \item \code{Helpers}
\item \code{Key}
\item \code{PrimaryKey}
\item \code{ReadableColumn}
\item \code{ReadableKey}
\item \code{ReadablePrimaryKey}
\item \code{RetrieveDBSchema}
- \item \code{SQLType}
\item \code{Table}
\item \code{TableSchema}
\end{itemize}
- \item \code{helpers}
+ \item \code{helpers}
\begin{itemize}
+ \item \code{Helpers}
\item \code{MapValueIterable}
\item \code{MapValueIterator}
\item \code{ReadOnlyIterable}
\item \code{ReadOnlyIterator}
+ \item \code{SQLType}
\item \code{UserAbortException}
\end{itemize}
\newpage
- \item \code{log}
+ \item \code{log}
\begin{itemize}
\item \code{ConsoleDiagnosticOutputHandler}
\item \code{GlobalLogger}
\end{itemize}
- \item \code{main}
+ \item \code{main}
\begin{itemize}
\item \code{Main}
\end{itemize}
- \item \code{osl}
+ \item \code{osl}
\begin{itemize}
\item \code{OSLSpecification}
\end{itemize}
- \item \code{output}
+ \item \code{output}
\begin{itemize}
\item \code{ObjectSpecPrinter}
\item \code{OSLSpecPrinter}
\item \code{SpecPrinter}
\end{itemize}
- \item \code{settings}
+ \item \code{settings}
\begin{itemize}
\item \code{Job}
\end{itemize}
- \item \code{specification}
+ \item \code{specification}
\begin{itemize}
\item \code{AttributeMap}
\item \code{EntityMap}
\item \code{SubtypeMap}
\item \code{TranslationTable}
\end{itemize}
- \item \code{test}
+ \item \code{test}
\begin{itemize}
\item \code{CreateTestDBSchema}
\item \code{GetSomeDBSchema}
\end{itemize}
- \end{itemize}\end{multicols} %\KOMAoption{fontsize}{\myfontsize{}}
- \caption{Class affiliation to packages in \myprog{}}
- \label{arch_tbl_classes}
+ \end{itemize}\end{multicols} %\KOMAoption{fontsize}{\myfontsize{}}
+ \caption{Class attachment to packages in \myprog{}}
+ \label{arch_tbl_classes}
\end{table}
+\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.
+Figure \ref{arch_fig_hierachies} shows the class hierarchies in \myprog{},
+while standalone classes are listed in table \ref{arch_tbl_lone_classes}.
+\stepcounter{figure}
+\newcounter{figureNumberOfClassHierarchyFigure}
+\setcounter{figureNumberOfClassHierarchyFigure}{\value{figure}}
\begin{figure}[H]\begin{center}
\ContinuedFloat*
\includegraphics[scale=0.86]{Images/inherit_graph_8.pdf}
+ \label{first_hierarchy}
\end{center}\end{figure}
\vspace{6px}
\begin{figure}[H]\begin{center}
\begin{figure}[H]\begin{center}
\ContinuedFloat*
\includegraphics[scale=0.86]{Images/inherit_graph_4.pdf}
- \setcounter{figure}{1}
+ \setcounter{figure}{\value{figureNumberOfClassHierarchyFigure}}
\caption[Class hierarchies in \myprog{}]{Class hierarchies in \myprog{}.
Interface names are italicized,
external classes or interfaces are hemmed with a gray frame.}
- \label{arch_fig_inheritance}
+ \label{arch_fig_hierachies}
\end{center}\end{figure}
-
\begin{table}[H]\begin{center}
\begin{tabular}{l}
\itm{} \code{main.Main}\\
- \itm{} \code{database.Helpers}\\
\itm{} \code{database.RetrieveDBSchema}\\
- \itm{} \code{database.SQLType}\\
\itm{} \code{database.Table}\\
+ \itm{} \code{helpers.Helpers}\\
+ \itm{} \code{helpers.SQLType}\\
\itm{} \code{specification.OBDASpecification}\\
\itm{} \code{osl.OSLSpecification}\\
\itm{} \code{bootstrapping.Bootstrapping}\\
\label{arch_tbl_lone_classes}
\end{center}\end{table}
-%For more information about the program structure on the class level, see section \fullref{code}.
+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 TODO.
+Deliberately, the scheme often recommended in the Java world TODO
+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}'' TODO.
+The details of this consideration are explained in section \fullref{code_interfaces}.
+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 TODO
+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 section \nameref{const} (which is part of section \fullref{code_classes}).
+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 the \hyperref[first_hierarchy]{first graph} of figure \ref{arch_fig_hierachies}.
+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 the following graph:
+
+\begin{figure}[H]\begin{center}
+ \includegraphics[scale=0.86]{Images/inherit_graph_8_simplified.pdf}
+ \caption{\code{ColumnSet} class hierarchy in \myprog{} -- simplified}
+ \label{arch_fig_colset_hierarchy_simplified}
+\end{center}\end{figure}
+
+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.
git://git.uio.no / u / philim / db2osl_thesis.git / blobdiff