% 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}