Java/Json support with atdj

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:

  • JSON strings are automatically checked for correctness with respect to the ATD specificion.
  • Details such as optional fields and their associated default values are automatically handled.
  • Several utility methods are included “for free”. These support equality testing, the visitor pattern and conversion back to JSON.

Installation

Build and install the atdj command with opam:

opam install atdj

Quick-start

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

  1. Generate and compile the interface:

    atdj -graph -package com.mylife.test test.atd
    export CLASSPATH='.:json.jar'
    javac com/mylife/test/*.java
    
  2. Compile and run the example, saving the output for later inspection:

    javac AtdjTest.java
    java AtdjTest >test.out
    
  3. Optionally, generate Javadoc documentation:

    javadoc -d doc -public com.mylife.test
    

    The resulting documentation is located in the directory doc.

  4. Optionally, generate a class graph of the generated interface:

    dot -Tpdf test.dot >test.pdf
    

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

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

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

atdj -package <package> <atd_file>

This outputs a set of Java source files. The -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 out is used.

For example, the command

atdj -graph -package com.mylife.test test.atd

causes the generated files to be members of the package com.mylife.test and to be located in the directory com/mylife/test.

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

export CLASSPATH='json.jar'

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

javac com/mylife/test/*.java

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:

javadoc -d doc/example -public com.mylife.test

Generating a class graph

We now discuss the -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 test.dot. Assuming that the dot program is installed, a PDF class graph named test.pdf can then created by running the command

dot -Tpdf test.dot >test.pdf

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 (implements/extends), whilst dashed arcs link fields to their types.

Translation reference

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

Bools, ints, floats, string, lists

ATD type, t Java type, <t>
bool boolean
int int
float double
string String
t list <t>[]

Options

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

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
}

Records

Suppose that we have the ATD record type

{ f_1: t_1
;  ...
; f_n: t_n
}

Then this is translated into the following Java reference type:

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

An optional field ~f_i: t_i causes the class field f_i to be given a default value of type <t_i> if the field is absent from the JSON string used to instantiate the class. The default values are as follows:

ATD type Default Java value
bool false
int 0
float 0.0
string “”
t list Empty array
t option Optional value with is_set = false

Default values cannot be defined for record and sum types.

An optional field ?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.

Sums

Suppose that we have the ATD sum type

[ C_1 of t_1
| ...
| C_n of t_n
]

Then this is translated into the following Java reference types:

public interface IFCNAME extends Atdj {
  public int     compareTo(IFCNAME that);
  public boolean equals(IFCNAME that);
  ...
}
public class CNAME_i implements IFCNAME, Atdj {
  // Comparison and equality
  public int     compareTo(CNAME that)        { ... }
  public boolean equals(CNAME that)           { ... }

public <t_i> value;
}

The value field is absent if the constructor C_i has no argument.

The Atdj and Visitor interfaces

All generated reference types additionally implement the interface

interface Atdj {
  String toString();
  String toString(int indent);
  int hashCode();
  Visitor accept(Visitor v);
}

where the Visitor interface is defined as

public interface Visitor {
  public void visit(CNAME_1 value);
  ...
  public void visit(CNAME_n value);
}

for generated reference types CNAME_i. Visit methods for primitive and optional primitive types are omitted.