% -*- TeX-master: "finaler.tex" -*-

\label{sec:serializer}

The game serializer, contained in the \texttt{gizmoball.xml} package,
is responsible for loading and saving game board states in the
standard Gizmoball XML format.  This package itself uses Java's DOM
API for reading and writing the necessary XML data.

The loading and saving of game board states is divided into two
classes: \texttt{GizmoballReader} and \texttt{GizmoballWriter}.
\texttt{GizmoballReader} is a static factory responsible for loading
an existing game state.  It operates by using the standard GameBoard
constructor to construct an empty board, then populating it with
gizmos and connections as the XML data is traversed.
\texttt{GizmoballWriter} performs the reverse, taking in a file (which
may or may not exist) and an already populated GameBoard and writing
the appropriate XML data to the file.  Both of these processes can be
initiated by the user through the user interface.

To decrease coupling, the XML reader and writer leverage reflection to
find the gizmo classes and the property system to configure created
gizmos and discover gizmo configurations, respectively.  This way, the
reader and writer need to know almost nothing about the individual
gizmos, or even about which gizmos exist in the game.  All of this
information is simply inferred.  Without this system, the reader and
writer would have needed explicit knowledge of each supported type of
gizmo.

Reflection is well suited to this system because the names of the
gizmo classes are user-specified in the XML file, making it easy to
add new gizmos to the system by simply changing the XML schema to
allow them to be specified in the XML data.  However, because naming
conventions are enforced (as well as XML validation), this still
restricts the user to valid inputs.  The flippers are one exception to
this rule because they are represented by a single class in the game
system, but by two distinct tags in the XML format.  This is an
anacronism from the original specifications and may be fixed later
(while retaining backwards compatibility).  Currently this is handled
by a special case syntax transformer which translates the incoming
tags into an internal representation used for the flippers.