Introduction

What is DJUTILS-SERIALIZATION?

DJUTILS-SERIALIZATION contains a set of Java classes that can do strongly-typed serialization and deserialization of data. Example uses are network traffic where different programming languages are involved. We are not the first attempt to solve this problem. Many have gone before us, e.g.:

  • XML: extremely verbose format, requires complex encoders and parsers.
  • GZip-compressed XML: compact, requires complex encoders and parsers.
  • protobuf: not self-documenting, uses overly complex encoders and parsers (generated by a code generator).
  • ASN.1: most tools (code generators for encoders and decoders) only available in C or C++, or not open source

The (de)serialization methods are used by other TU Delft projects such as SIM0MQ, and the communication with aimsun in OpenTrafficSim (XXXX NOT YET; CURRENTLY USES PROTOBUF).

Some properties:

  • DJUTILS-SERIALIZATION stores one byte before each serialized field that indicates its type (compact and self-documenting encoded data).
  • DJUTILS-SERIALIZATION can use little-endian and big-endian encoding for multi-byte values (portability among different CPU types).
  • DJUTILS-SERIALIZATION handles Scalars, Vectors and Matrices from DJUNITS, including the scalar type and display type (e.g. Length in kilometers, Duration in minutes, an AreaVector in acres).
  • DJUTILS-SERIALIZATION is the basis for the (de)serialization of types in the SIM0MQ project.

Origin

DJUTILS-SERIALIZATION was developed at the Delft University of Technology as part of the SIM0MQ project and further refined within the Open Traffic Simulator project. The main authors/contributors of the DJUTILS project are Alexander Verbraeck and Peter Knoppers for the Java implementation, and Sibel Eker and Jan Kwakker for the Python implementation.

Maven use

Maven is one of the easiest ways to include DJUTILS-SERIALIZATION in a Java project. The Maven files for reside at https://djutils.org/maven. When a POM-file is created for the project, the following snippet needs to be included to include DJUTILS-SERIALIZATION:

<dependencies>
  <dependency>
    <groupId>org.djutils</groupId>
    <artifactId>djutils-serialization</artifactId>
    <version>1.02.00</version>
  </dependency>
    ... other dependencies go here ...
</dependencies>

Of course, the version number (1.02.00 in the above example) needs to be replaced with the version that one wants to include in the project.

Right now, the DJUTILS-SERIALIZATION files are kept on a server at TU Delft, and are not yet made available on Maven Central. Therefore, the repository location has to be specified separately in the Maven POM-file:

<repositories>
  <repository>
    <name>djutils Public Repository</name>
    <id>djutils</id>
    <url>https://djutils.org/maven</url>
  </repository>
    ... other repositories go here ...
</repositories>

Dependencies

DJUTILS-SERIALIZATION is directly dependent on five packages, which can have further dependencies:

  • tinylog for providing an easy-to-use and fast logger.
  • djutils for the base helper classes
  • djunits for the scalar, vector and matrix fields
  • joda-money for the money types (via djunits) XXXX NOT ANY MORE
  • ojalgo for matrix and vector calculations (via djunits)

If the DJUTILS-SERIALIZATION library is used as a part of a Maven project, all dependencies will be automatically resolved, and the programmer / user does not have to worry about finding the libraries.

Documentation and test reports: