% Body of the documentation for atdj.
% This file is used to generate the README file for atdj,
% and also is included as a section within the PSAPI manual.

The ATDJ tool generates a Java interface from an ATD interface.  In particular,
given a set of ATD types, this tool generates a set of Java classes
representing those types.  These classes may then be instantiated from
JSON representations of those same ATD types.

The primary benefits of using the generated interface, over manually
manipulating JSON strings from within Java, are safety and ease of use.
Specifically, the generated interface offers the following features:

\begin{itemize}
\item JSON strings are automatically checked for correctness with
  respect to the ATD specificion.

\item Details such as optional fields and their associated default values are
  automatically handled.

\item Several utility methods are included ``for free''.
  These support equality testing, the visitor pattern and conversion
  back to JSON.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Installation}

\begin{enumerate}
\item Install the dependencies: ATD and Atdgen.  These may be
obtained from \url{http://martin.jambon.free.fr/atd-biniou-intro.html}.
Alternatively, they are available as the packages \verb+godi-atd+
and \verb+godi-atdgen+ using the GODI package manager
(\url{http://godi.camlcity.org/godi/index.html}).

\item Having set the appropriate \verb+OCAMLPATH+ (if necessary),
build the ATDJ tool:

\begin{verbatim}
omake atdj
\end{verbatim}
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Quick-start}

In this section we briefly describe how to to generate a Java interface from an
example ATD file \texttt{test.atd}.  We then show how to
build and run an
example application \texttt{AtdjTest} that uses the
generated interface.

\begin{enumerate}
\item Generate and compile the interface:

\begin{verbatim}
./atdj -graph -package com.mylife.test test.atd
export CLASSPATH='.:json.jar'
javac com/mylife/test/*.java
\end{verbatim}

\item Compile and run the example, saving the output for later inspection:

\begin{verbatim}
javac AtdjTest.java
java AtdjTest >test.out
\end{verbatim}

\item Optionally, generate Javadoc documentation:

\begin{verbatim}
  javadoc -d doc -public com.mylife.test
\end{verbatim}

The resulting documentation is located in the directory
\texttt{doc}.

\item Optionally, generate a class graph of the generated interface:

\begin{verbatim}
dot -Tpdf test.dot >test.pdf
\end{verbatim}
\end{enumerate}

The output file \texttt{test.pdf} contains a class graph of the
generated Java interface.  The required \texttt{dot} program is part of the
Graphviz graph visualisation package, and may be download from
\url{http://www.graphviz.org/}.

Alternatively, if the source distribution is present, all of the
above steps can be run as \texttt{omake example}.

In the following sections we discuss the individual steps in more detail,
using the example from above.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Generating the interface}

In this section we describe the process of generating a Java interface from an
ATD specification.

A Java interface is generated from an ATD file as

\begin{verbatim}
./atdj -package <package> <atd_file>
\end{verbatim}

This outputs a set of Java source files.  The \texttt{-package} option
causes the
resulting classes to be members of the specified package, and also to
be located
in the corresponding output directory.  If no package is specified, then the
default package of \texttt{out} is used.

For example, the command

\begin{verbatim}
./atdj -graph -package com.mylife.test test.atd
\end{verbatim}

\begin{sloppypar}
causes the generated files to be members of the package
\texttt{com.mylife.test} and to be located in the directory
\texttt{com/mylife/test}.
\end{sloppypar}

The generated source files reference various members of the included org.json
package.  Therefore, in order to compile the generated files, the
\texttt{org.json}
package must be located within the Java classpath.  Supposing that the
\texttt{org.json}
package is located within the archive \texttt{json.jar} within the
current directory,
it is sufficient to set the classpath as follows:

\begin{verbatim}
export CLASSPATH='json.jar'
\end{verbatim}

Returning to our example, the generated source files may then be compiled as:

\begin{verbatim}
javac com/mylife/test/*.java
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Generating Javadoc documentation}

The generated Java code contains embedded Javadoc comments.
These may be extracted to produce Javadoc documentation.
In the case of our example, it is sufficient to run the following command:

\begin{verbatim}
  javadoc -d doc/example -public com.mylife.test
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Generating a class graph}

We now discuss the \texttt{-graph} option of ATDJ.  When enabled, this
causes ATDJ to
output a graph of the class hierarchy of the generated code.  The output is
intended to document the generated code, helping users to avoid consulting the
source code.

Continuing with our example, the use of this option results in the
generation of
an additional output file named \texttt{test.dot}.
Assuming that the \texttt{dot}
program is installed, a PDF class graph named
\texttt{test.pdf} can then
created by running the command

\begin{verbatim}
dot -Tpdf test.dot >test.pdf
\end{verbatim}

In the generated class graph,
rectangular and oval nodes correspond to classes
and interfaces, respectively.  Field names are specified in the second line of
retangular (class) nodes.  Solid arcs denote subtyping
(\texttt{implements}/\texttt{extends}),
whilst dashed arcs link fields to their types.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Translation reference}

In this section we informally define how Java types are generated from ATD
types.

\subsection{Bools, ints, floats, string, lists}

\begin{tabular}{ll}
\toprule
ATD type, \tt t & Java type, \tt <t> \\
\midrule
\tt bool     & \tt boolean \\
\tt int      & \tt int \\
\tt float    & \tt double \\
\tt string   & \tt String \\
\tt t list   & \tt <t>[] \\
\bottomrule
\end{tabular}

\subsection{Options}

Suppose that we have ATD type \texttt{t option}.  Then this is
translated into the following Java reference type:

\begin{verbatim}
public class CNAME implements Atdj {
  // Constructor
  public CNAME(String s) throws JSONException { ... }

// Get the optional value, if present
public CNAME get() throws JSONException     { ... }

// Comparison and equality
public int     compareTo(CNAME that)        { ... }
public boolean equals(CNAME that)           { ... }

public <t> value;           // The value
public boolean is_set;      // Whether the value is set
}
\end{verbatim}

\subsection{Records}

Suppose that we have the ATD record type

\begin{verbatim}
{ f_1: t_1
;  ...
; f_n: t_n
}
\end{verbatim}

Then this is translated into the following Java reference type:

\begin{verbatim}
public class CNAME implements Atdj {
  // Constructor
  public CNAME(String s) throws JSONException { ... }

// Comparison and equality
public int     compareTo(CNAME that)        { ... }
public boolean equals(CNAME that)           { ... }

// The individual fields
public <t_1> f_1;
...
public <t_n> f_n;
}
\end{verbatim}

An optional field \texttt{\~{}f\_i: t\_i} causes the class field
\texttt{f\_i} to be given a default
value of type \texttt{<t\_i>} if the field is absent from the JSON
string used to instantiate the class.  The default values are as follows:

\begin{tabular}{ll}
\toprule
ATD type & Default Java value \\
\midrule
\tt bool     & \tt false \\
\tt int      & \tt 0 \\
\tt float    & \tt 0.0 \\
\tt string   & \tt "" \\
\tt t list   & Empty array \\
\tt t option & Optional value with \tt is\_set = false \\
\bottomrule
\end{tabular}

Default values cannot be defined for record and sum types.

An optional field \texttt{?f\_i: t\_i option} has the same default
behaviour as above,
with the additional behaviour that if the field is present in the JSON string
then the value must be of type <t> (not <t> option); the value is then
automatically lifted into a <t> option, with is\_set = true.

\subsection{Sums}

Suppose that we have the ATD sum type

\begin{verbatim}
[ C_1 of t_1
| ...
| C_n of t_n
]
\end{verbatim}

Then this is translated into the following Java reference types:

\begin{verbatim}
public interface IFCNAME extends Atdj {
  public int     compareTo(IFCNAME that);
  public boolean equals(IFCNAME that);
  ...
}
\end{verbatim}

\begin{verbatim}
public class CNAME_i implements IFCNAME, Atdj {
  // Comparison and equality
  public int     compareTo(CNAME that)        { ... }
  public boolean equals(CNAME that)           { ... }

public <t_i> value;
}
\end{verbatim}

The value field is absent if the constructor C\_i has no argument.

\subsection{The Atdj and Visitor interfaces}

All generated reference types additionally implement the interface

\begin{verbatim}
interface Atdj {
  String toString();
  String toString(int indent);
  int hashCode();
  Visitor accept(Visitor v);
}
\end{verbatim}

where the Visitor interface is defined as

\begin{verbatim}
public interface Visitor {
  public void visit(CNAME_1 value);
  ...
  public void visit(CNAME_n value);
}
\end{verbatim}

for generated reference types \texttt{CNAME}\_i.  Visit methods for primitive
and optional primitive types are omitted.
