structural pattern draft done

report.tex

@@ -70,30 +70,99 @@ 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}.
 
+\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}
 
 
-\subsection{Comments}
+Structural patterns provide flexible ways of combining and connecting components.
-\begin{itemize}
+- abstract factory
-  \item Lots of false positives for the Singleton pattern. Example,
+- singleton
-    com.fasterxml.jackson.core.sym.Name1 has a package private constructor and a
+- builder
-    public static final instance of it, but reading the documentation the class
+
-    represents (short) JSON string literals and therefore is clearly
+Creational patterns deal with object creation mechanisms in situations where directly using constructors is inconvenient.
-    initialized by client code.
+- adapter
-    \begin{description}
+- bridge
-      \item[sym.Name1, JsonLocation, DefaultIndenter,
+- composite 
-        util.DefaultPrettyPrinter\$FixedSpaceIndenter] not a singleton (detected
+- facade
-        cause of "convenient" default instance given as static final field), the
+- proxy
-        constructor is not used but the class is extensible
+
-      \item[JsonPointer, filter.TokenFilter] like above, but constructors are protected
+Behavioral patterns provides way of coordinating object behavior without increasing coupling too much.
-      \item[JsonpCharacterEscapes, util.DefaultPrettyPrinter\$NopIndenter,
+- command
-        Version] a singleton but with a public constructor that is never called
+- observer
-        in the module code, may be called in tests
+- strategy
-      \item[io.JsonStringEncoder] like above, but the class is final
+- template method
-      \item[util.InternCache, io.CharTypes\$AltEscapes]
+- visitor
-          actual singleton, thread-unsafe initialization
-      \item[io.ContentReference] like above, but constructor is protected
-    \end{description}
-  \item TBD
-\end{itemize}
 \end{document}