address = {New York, NY, USA},
keywords = {Java, Javari, assignable, immutability, mutable, readonly, type system, verification},
}
-
-@book{str3,
- author = {Stroustrup, Bjarne},
- title = {The C++ Programming Language},
- year = {2000},
- isbn = {0201700735},
- edition = {3rd},
- publisher = {Addison-Wesley Longman Publishing Co., Inc.},
- address = {Boston, MA, USA},
-}
-
-@book{str4,
- author = {Stroustrup, Bjarne},
- title = {The C++ Programming Language},
- year = {2013},
- isbn = {0321563840, 9780321563842},
- edition = {4th},
- publisher = {Addison-Wesley Professional},
- address = {Boston, MA, USA},
-}
-
-@book{composed,
- author = {Beck, Kent},
- citeulike-article-id = {12725521},
- keywords = {anthology, book, object-thinking, pattern, smalltalk, testing},
- posted-at = {2013-10-17 09:40:32},
- priority = {2},
- publisher = {Prentice-Hall},
- title = {{Smalltalk} Best Practice Patterns},
- year = {1997}
-}
-
-@book{java,
- title={Java: The Complete Reference, Ninth Edition},
- author={Schildt, H.},
- isbn={9780071808552},
- lccn={2014006464},
- series={The Complete Reference},
- year={2014},
- publisher={McGraw-Hill Education},
- address={New York, NY, USA}
-}
-
-@article{obj,
- author = {Asgba, Prince Oghenekaro and Ogheneovo, Edward E.},
- title = {A Comparative Analysis of Structured and Object-Oriented Programming Methods},
- journal = {Journal of Environmental Management},
- keywords = {OOP, programming},
- number = 4,
- pages = {41--46},
- volume = 12,
- journal = {Journal of Environmental Management},
- keywords = {OOP, programming},
- number = 4,
- pages = {41--46},
- volume = 12,
- year = 2008
-}
-
-@article{final,
- author = {Tschantz, Matthew S. and Ernst, Michael D.},
- title = {Javari: Adding Reference Immutability to Java},
- journal = {SIGPLAN Not.},
- issue_date = {October 2005},
- volume = {40},
- number = {10},
- month = oct,
- year = {2005},
- issn = {0362-1340},
- pages = {211--230},
- numpages = {20},
- doi = {10.1145/1103845.1094828},
- acmid = {1094828},
- publisher = {ACM},
- address = {New York, NY, USA},
- keywords = {Java, Javari, assignable, immutability, mutable, readonly, type system, verification},
-}
-
\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 partitioning}
+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}.
+
+\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}.
+
+\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}
+
+Though there 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 of the node
+representing package \code{settings} 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).
+\code{Job} represents the configuration of a bootstrapping job but also
+provides a \code{perform()} method combining the facilities offered by the other
+packages.
+
+This way, 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 it seems quite a bit unnatural to have the driver class reside in
+a package called ``settings'' at first glance.
+
+Previous versions of \myprog{} had a quite more complicated package dependency structure,
+depicted in figure \ref{arch_fig_packages_earlier}.
+
+\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}
+
+%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}
+\subsubsection{Package contents}
+\label{package_details}
+While the packages in \myprog{} are introduced and described in section \fullref{coarse},
+the classes that comprise them are addressed in this section.
-\begin{table}
+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 $17$ classes.
+
+\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{Table}
\item \code{TableSchema}
\end{itemize}
- \item \code{helpers}
+ \item \code{helpers}
\begin{itemize}
\item \code{MapValueIterable}
\item \code{MapValueIterator}
\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} 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}.
\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}{2} %TODO: variable
\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}\\
\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,
+so they 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 first graph TODO 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, TODO: still good
+
+TODO: rest self-explanatory
+
+For more information about the program structure on the class level,
+see section \fullref{code}.
More generally, ``speaking code'' was used wherever possible,
as described in section \fullref{speaking},
which rendered many uses of comments unnecessary.
-In fact, the number of (plain, e.g. non-\name{Javadoc}) comments was consciously minimized,
-to enforce speaking code and avoid redundancy.
+In fact, the number of (plain, e.g. non-\name{Javadoc}) comments was
+consciously minimized, to enforce speaking code and avoid redundancy.
This technique is known TODO.
An exception of course from this is the highlighting of subdivisions.
Another alternative would have been to use separate methods for this code
pieces, as was done in other cases, and thereby sticking strictly to the so-called
``Composed Method Pattern'' \cite{composed}.
-However, this would have introduced additional artifacts with either long or non-speaking names,
+However, sticking to this pattern too rigidly would have introduced additional
+artifacts with either long or non-speaking names,
would have interrupted the reading flow and also would have increased complexity,
-because these methods would have been callable at least from everywhere in the source file.
+because these methods would have been callable at least from everywhere
+in the source file.
Wherever possible, the appropriate \name{Javadoc} comments were used in favor of
plain comments, for example to specify parameters, return types, exceptions
In fact, carefully avoiding the introduction of technical artifacts to mind,
preventing programmers from focusing on the actual program logic,
-is an important principle of writing clean code TODO.
+is an important principle of writing clean code \cite{str4}.
In modern programming languages, of course the main instruments for achieving
this are the type system and exceptions.
In particular, static type information should be used to reflect data
abstraction and the ``kind'' of data, an object reflects,
while dynamic type information should only be used implicitly,
-through dynamically dispatching method invocations\cite{str4}.
+through dynamically dispatching method invocations \cite{str4}.
Exceptions on the other hand should be used at any place related to errors
and error handling, separating error handling noticeably from other code and
enforcing the treatment of errors, preventing the programmer from using
There return type is the \name{Java} class \code{Boolean}, not the plain type
\code{boolean}, because the information they return is not always known.
In an early stage of the program, they returned \code{boolean} and were
-accompanied TODO by two methods
+accompanied by two methods
\code{public boolean knownIsNonNull()} and \code{public boolean knownIsUnique()},
telling the caller whether the respective information was known and thus the
value returned by \code{isNonNull()} or \code{isUnique()}, respectively,
even when the programmer forgets that he deals with objects.
However, when comparing two return values of one of the methods in general
-- as opposed to comparing one such return value against a constant --,
-errors could occur if the programmer writes \code{col1.isUnique() == col2.isUnique()}
+errors could occur if the programmer mistakenly writes \code{col1.isUnique() == col2.isUnique()}
instead of \code{col1.isUnique().booleanValue() == col2.isUnique().booleanValue()}.
-\\TODO: Java rules.
+In this case, since the two \code{Boolean} objects are compared for identity \cite{java},
+the former comparison can return \code{false}, even when the two boolean values are in fact
+the same.
+However, since this case was considered much less common than cases in which the other
+solution could make programmers making mistakes produce undetected errors, it was preferred.
-TODO: more, summary
+TODO: more (?), summary
\subsection{Classes}
-\label{classes}
+\label{code_classes}
Following the object-oriented programming paradigm, classes were heavily used
to abstract from implementation details and to yield intuitively usable objects with
a set of useful operations \cite{obj}.
but nevertheless expressive TODO.
\name{Java} packages were used to help attain this aim,
which is why the previously mentioned class names are unambiguous
-(for details about package use, see section \fullref{packages}, for the description
-of the packages in \myprog{} and their structuring, see section \fullref{coarse}).
+(for details about package use, see section \fullref{code_packages}, for the description
+of the packages themselves and their structuring, see section \fullref{coarse}).
Care was taken not to introduce unnecessary classes, thereby complicating
code structure and increasing the number of source files and program entities.
On the other hand of course, it usually is not the cleanest solution
to avoid such artificial classes entirely.
+Section \fullref{hierarchies} describes how the classes of \myprog{} are organized
+into class hierarchies.
+
\subsubsection{Const correctness}
+\label{const}
Specifying in the code which objects may be altered and which shall remain constant,
thus allowing for additional static checks preventing undesired modifications,
is commonly referred to as ``const correctness'' TODO.
Unfortunately, \name{Java} lacks a keyword like \name{C++}'s \code{const},
-making it harder to achieve const correctness.
+making it harder to achieve const correctness \cite{final}.
It only specifies the similar keyword \code{final}, which is much less expressive and
doesn't allow for a similarly effective error prevention \cite{final}.
In particular, because \code{final} is not part of an object's type information,
programmers that the resulting objects are to be used with care.
\subsubsection{Java interfaces}
+\label{code_interfaces}
In \name{Java} programming, it is quiet common and often recommended, that every
class has at least one \code{interface} it \code{implements},
specifying the operations the class provides. TODO
unnecessary at least, if not messy.
\subsection{Packages}
-\label{packages}
-As mentioned in section \fullref{classes}, class names were chosen to be
+\label{code_packages}
+As mentioned in section \fullref{code_classes}, class names were chosen to be
concise but nevertheless expressive.
This only was possible through the use of \name{Java} \code{package}s,
which also helped structure the program.
git://git.uio.no / u / philim / db2osl_thesis.git / commitdiff
