DJUTILS SERIALIZATION

What is in the DJUTILS-SERIALIZATION project?

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.

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 Kwakkel 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.04.12</version>
  </dependency>
    ... other dependencies go here ...
</dependencies>

Of course, the version number (1.04.12 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 two packages (djutils and djunits), which have a few further dependencies:

  • djutils for the base helper classes
  • djunits for the scalar, vector and matrix fields
  • tinylog for providing an easy-to-use and fast logger (via djutils)
  • 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: