247 lines
9.9 KiB
TeX
247 lines
9.9 KiB
TeX
% vim: set ts=2 sw=2 et tw=80:
|
|
|
|
\documentclass[12pt,a4paper]{scrartcl}
|
|
\usepackage[utf8]{inputenc}
|
|
\usepackage[margin=2.5cm]{geometry}
|
|
\usepackage{hyperref}
|
|
\usepackage{listings}
|
|
\usepackage{xcolor}
|
|
\usepackage{lmodern}
|
|
\usepackage{listings}
|
|
\setlength{\parindent}{0cm}
|
|
|
|
\lstset{
|
|
basicstyle=\small\ttfamily,
|
|
%frame=shadowbox,
|
|
rulesepcolor=\color{black},
|
|
columns=fullflexible,
|
|
commentstyle=\color{gray},
|
|
keywordstyle=\color{blue},
|
|
mathescape=true,
|
|
aboveskip=1em,
|
|
captionpos=b,
|
|
abovecaptionskip=1em,
|
|
belowcaptionskip=1em
|
|
}
|
|
|
|
|
|
\title{Assginment 1 -- Software Design and Modelling}
|
|
|
|
\author{Volodymyr Karpenko \and Claudio Maggioni}
|
|
|
|
\begin{document}
|
|
\maketitle
|
|
|
|
\section{Project selection process}
|
|
|
|
We need to find a project that is a single unit in terms of compilation
|
|
modules\footnote{A problem for Pattern4J as compiled \texttt{.class} files are
|
|
distributed across several directories and would have to be merged manually for
|
|
analyzing them}
|
|
self contained and with as little external dependencies as possible to ease the
|
|
analysis project. Additionally, it would be nice if we choose a project that we
|
|
already know as library clients.
|
|
|
|
\subsection {Projects Considered}
|
|
|
|
We considered the following GitHub repositories:
|
|
|
|
\begin{description}
|
|
\item[vavr-io/vavr] a Java library for functional programming, discarded as
|
|
the project is less than 20K LOC and doesn't meet the selection criteria;
|
|
\item[bitcoin4j/bitcoin4j] a Java implementation of the bitcoin protocol,
|
|
discarded as the project is distributed in several subprojects;
|
|
\item[FasterXML/jackson-core] a Java JSON serialization and
|
|
deserialization library. We chose this library because it meets the
|
|
selection criteria, it doesn't rely on external components for its
|
|
execution, and its project structure uses a single Maven module for its
|
|
sources and thus easy to analyze.
|
|
\end{description}
|
|
|
|
|
|
\subsection {The Jackson Core Library}
|
|
As already mentioned, \texttt{Jackson} is a library that offers serialization
|
|
and deseralization capabilities in JSON format. The library is highly extensible
|
|
and customizable through a robust but flexible API and module suite that allows
|
|
to change the serialization and deserialization rules, or in the case of the
|
|
\texttt{jackson-dataformat-xml} module, to allow to target XML instead of JSON.
|
|
|
|
The chosen repository contains only the \textit{core} module of Jackson. The
|
|
\textit{core} module implements the necessary library abstractions and
|
|
interfaces to allow other modules to be plugged-in. Additionally, the
|
|
\textit{core} module implements the tokenizer and low-level abstractions to work
|
|
with the JSON format.
|
|
|
|
We chose to analyze version 2.13.4 of the module (corresponding to the code
|
|
under the git tag \texttt{jackson-core-2.13.4}) because it is the latest stable
|
|
version available at the time of writing.
|
|
|
|
\section{Analysis Implementation}
|
|
|
|
We use
|
|
\href{https://users.encs.concordia.ca/~nikolaos/pattern\_detection.html}{\textit{Pattern4}}
|
|
as a pattern detection tool. This tool needs compiled \texttt{.class} files in
|
|
order to perform analysis. Therefore, as \texttt{jackson-core} is a standard
|
|
Maven project, we compile the sources using the command \texttt{mvn clean
|
|
compile}. The \texttt{pom.xml} of the library specifies Java 1.6 as a
|
|
compilation target, which is not supported by JDK 17 or above. We used JDK 11
|
|
instead, as it is the previous LTS version.
|
|
|
|
An XML dump of the \textit{Pattern4j} analysis results are included in the
|
|
submission as the file \texttt{analysis.xml}.
|
|
|
|
\section{Structural Patterns}
|
|
|
|
\subsection{Singleton Pattern}
|
|
Lots of false positives for the Singleton pattern. Example,
|
|
com.fasterxml.jackson.core.sym.Name1 has a package private constructor and a
|
|
public static final instance of it, but reading the documentation the class
|
|
represents (short) JSON string literals and therefore is clearly
|
|
initialized by client code.
|
|
|
|
(com.fasterxml.jackson.core omitted for brevity)
|
|
|
|
\begin{description}
|
|
\item[sym.Name1, JsonLocation, DefaultIndenter,
|
|
util.DefaultPrettyPrinter\$FixedSpaceIndenter] not a singleton (detected
|
|
cause of "convenient" default instance given as static final field), the
|
|
constructor is not used but the class is extensible
|
|
\item[JsonPointer, filter.TokenFilter] like above, but constructors are protected
|
|
\item[JsonpCharacterEscapes, util.DefaultPrettyPrinter\$NopIndenter,
|
|
Version] a singleton but with a public constructor that is never called
|
|
in the module code, may be called in tests
|
|
\item[io.JsonStringEncoder] like above, but the class is final
|
|
\item[util.InternCache, io.CharTypes\$AltEscapes]
|
|
actual singleton, thread-unsafe initialization
|
|
\item[io.ContentReference] like above, but constructor is protected
|
|
\end{description}
|
|
|
|
\subsection{Abstract Factory Pattern}
|
|
\textit{Pattern4} detects only two instances of the abstract factory pattern:
|
|
|
|
\begin{description}
|
|
\item[TokenStreamFactory] which indeed is a factory for \textbf{JsonParser} and
|
|
\textbf{JsonGenerator} objects, although two overloaded factory methods
|
|
exist on this class (one for each class) catering for different combination of
|
|
arguments. A concrete implementation of this factory is included in the form
|
|
of the \textbf{JsonFactory} class, although other modules may add additional
|
|
implementations to cater for different encodings (like the
|
|
\texttt{jackson-dataformat-xml} module for XML);
|
|
\item[TSFBuilder] which is also a factory for concrete implementations of
|
|
\textbf{TokenStreamFactory} to allow slight changes in the serialization and
|
|
deserialization rules (e.g. changing the quote character used in JSON keys
|
|
from \texttt{"} to \texttt{'}). Like \textbf{TokenStreamFactory}, this class
|
|
is only implemented by one class, namely \textbf{JsonFactoryBuilder}, whitin
|
|
the scope of this module. And as mentioned previously, this abstract factory
|
|
is also likely to be extended by concrete implementations in other
|
|
\textit{Jackson} modules.
|
|
\end{description}
|
|
|
|
\subsection{Builder Pattern}
|
|
|
|
The builder pattern does not seem to be analyzed by
|
|
\textit{Pattern4}, as the analysis output does not mention the pattern, even
|
|
just to report that no instances of it have been found (as it is the case with
|
|
other patterns, e.g. the observer pattern). A manual search in the source code
|
|
produced the following results:
|
|
|
|
\begin{description}
|
|
\item[TSFBuilder] is also a builder other than an abstract factory. As mentioned
|
|
previously, this class allows to alter slightly the serialization and
|
|
deserialization rules used to build outputtting \textbf{JsonFactory}
|
|
objects. Each rule is represented by an object or enum instance implementing
|
|
the \textbf{util.JacksonFeature} interface. \texttt{TSFBuilder} then
|
|
provides several overloaded methods to enable and disable features
|
|
represented by the interface. Enabled features are stored in several
|
|
bitmask \texttt{protected int} fields, which are then directly accessed by
|
|
the constructor of the \textbf{TokenStreamFactory} concrete implementation
|
|
to build;
|
|
\item[JsonFactoryBuilder] an concrete factory implementation of
|
|
\textbf{TSFBuilder} that builds \textbf{JsonFactory} instances;
|
|
\item[util.ByteArrayBuilder] provides facilities to build \texttt{byte[]} objects
|
|
of varying length, akin to \textbf{StringBuilder} building \textbf{String}
|
|
objects. This is not a strict implementation of the builder pattern per se
|
|
(as Java arrays do not have a ``real'' constructor),
|
|
but it is nevertheless included since the features it exposes (namely
|
|
dynamic sizing while building) are decoupled by the underlying (fixed-size)
|
|
array representation.
|
|
\end{description}
|
|
|
|
\section{Creational Patterns}
|
|
\subsection{Adapter Pattern}
|
|
TBD
|
|
|
|
\subsection{Bridge Pattern}
|
|
TBD
|
|
|
|
\subsection{Composite Pattern}
|
|
TBD
|
|
|
|
\subsection{Facade Pattern}
|
|
TBD
|
|
|
|
\subsection{Proxy Pattern}
|
|
TBD
|
|
|
|
\section{Behavioral Patterns}
|
|
\subsection{Command Pattern}
|
|
TBD
|
|
|
|
\subsection{Observer Pattern}
|
|
TBD
|
|
|
|
\subsection{Strategy Pattern}
|
|
TBD
|
|
|
|
\subsection{Template Method Pattern}
|
|
Due to the extendibility of Jackson, it is of no surprise that the template
|
|
method pattern is used extensively to create a class hierarchy that provides
|
|
rich interfaces while maintaining behavioural flexibility. \textit{Pattern4}
|
|
correctly detects several instances of the pattern, namely
|
|
\textbf{JsonStreamContext}, \textbf{JsonGenerator}, \textbf{type.ResolvedType},
|
|
\textbf{JsonParser}, \textbf{base.ParserBase}, \textbf{base.GeneratorBase},
|
|
\textbf{base.ParserMinimalBase}. All these classes implement several concrete
|
|
\texttt{public} methods throwgh the use of \texttt{protected abstract} methods.
|
|
Although the concrete (i.e. the template) methods are usually not vary complex
|
|
(as the pattern example shown in class), they still follow the principles of the
|
|
template method pattern. We show as an example some template methods found in
|
|
\textbf{base.ParserBase}:
|
|
|
|
\begin{lstlisting}[caption=Template method \texttt{void close()} and step
|
|
methods \texttt{void \_closeInput()} and \texttt{void \_releaseBuffers()} in
|
|
\textbf{base.ParserBase}., language=java]
|
|
@Override public void close() throws IOException {
|
|
if (!_closed) {
|
|
// 19-Jan-2018, tatu: as per [core#440] need to ensure no more data
|
|
// assumed available
|
|
_inputPtr = Math.max(_inputPtr, _inputEnd);
|
|
_closed = true;
|
|
try {
|
|
_closeInput();
|
|
} finally {
|
|
// as per [JACKSON-324], do in finally block
|
|
// Also, internal buffer(s) can now be released as well
|
|
_releaseBuffers();
|
|
}
|
|
}
|
|
}
|
|
|
|
protected abstract void _closeInput() throws IOException;
|
|
|
|
protected void _releaseBuffers() throws IOException {
|
|
/* implementation omitted */
|
|
}
|
|
\end{lstlisting}
|
|
|
|
Here the pattern is slightly modified by providing a default implementation of
|
|
\texttt{void \_releaseBuffers()}. In this case, child classes occasionally
|
|
override the method with a body first calling \texttt{super()} and then adding
|
|
additional buffer release code after.
|
|
|
|
|
|
\subsection{Visitor Pattern}
|
|
TBD
|
|
|
|
\end{document}
|
|
|