opendis7-source-generator

This project generates a type-safe Java implementation of the DIS Protocol version 7, IEEE Standard 1278.1-2012 from SISO and IEEE specifications. This project is written for Java developers working on autogenerated source-code production.

This project is not for end users or developers integrating DIS in other application tools. This project produces a fairly complete implementation of the IEEE DIS Protocol and associated enumerations that are integrated in the opendis7-java and related projects. In preparation: opendis7-python.

Recent project products include full Java support for all 72 DISv7 Protocol Data Units (PDUs) and over 22,000 SISO-REF-010 enumerations.

Additional testing and experimentation is performed in the NPS MOVES Networked Graphics MV3500 course.

Work in progress includes similar autogeneration of a complete opendis7-python version.

Background

This work is an updated continuation of the open-dis/xmlpg project created by the late Don McGregor of the Naval Postgraduate School (NPS).

Project goals are twofold:

To provide reference implementations of the DIS protocol network messages in several programming languages.
To do so by means of single XML descriptions of the protocol which are then referenced by individual language generators.

While there exists code in the project to generate source in JavaScript, Python and other languages, that code is legacy, and so far only the Java implementation is complete.

This work is driven by two specifications.

IEEE Std 1278.1-2012, IEEE Standard for Distributed Interactive Simulation—Application Protocols
SISO-REF-010 Enumerations, Simulation Interoperability Standards Organization (SISO).

The first reference describes the DIS protocol in detail -- specifying application algorithms as well as the precise format of network data. The second reference enumerates specific values for fields within the network data which correspond to actual entities in the real world.

The SISO specification is issued in several file formats. One of these is XML and the latest version of that file is used directly by this project. The IEEE specification is textual and initial work was required to describe its defined data structures in a set of XML files. Both the SISO file and the IEEE-based XML files used as input to this project are found in the xml subdirectory.

String templates for the various output classes are used to define the basic structure of the generated code, and these files are found in the [stringTemplates/edu/nps/moves/dis7/source/generator](https://github.com/open-dis/opendis7-source-generator/tree/master/stringTemplates/edu/nps/moves/dis7/source/generator} directory.

Development Environment

The Ant build.xml is greatly improved and build tasks are now simply performed. The underlying build process for autogenerating complex software library in separate projects like this is quite involved.

The Java language is inherently cross-platform and any OS on any hardware for which a Java run-time is available should support running of this project. However, the configuration used by the initial developer is the following:

Apache Netbeans 20 Integrated Development Environment ("IDE")
Apache Ant Java build tool version 1.10.14
Git version control system (for downloading project; supported in Netbeans)
OpenJdk Java version OpenJdk 21.0.1

Please see Savage Developers Guide to find our current recommended development settings for using each of these tools.

The project is hosted at github.com/open-dis/opendis7-source-generator and the support files which are used to define the project structure are also included. Following the procedure below, a simple download, then a small number of additional steps are all that are required to build the source files for a DIS distribution.

The project does not automatically download run-time dependencies like a Maven-based project. Only one external dependency is used, and that is the Apache Commons-IO library. The jar for that is found in the libs/ directory of the project.

The generated source resides in the src-generated directory.
The generated entity jars reside in the dist directory.
The generated entity javadoc resides in the dist directory.

Project Directory Structure

The initial project directory structure looks like:

|-- images
|-- lib
|-- nbproject
|-- src-autogenerate
|   +-- edu
|       +-- nps
|           +-- moves
|               +-- dis7
|                   +-- source
|                       +-- generator
|                           +-- entityTypes
|                           +-- enumerations
|                           +-- pdus
|-- src-generated
|-- src-specialcase
|-- src-supporting
|-- stringTemplates
|   +-- edu
|       +-- nps
|           +-- moves
|               +-- dis7
|                   +-- source
|                       +-- generator
|                           +-- entitytypes
|                           +-- enumerations
|                           +-- pdus
+-- xml
    +-- xml/SISO
    +-- xml/dis_7_2012

After project execution, the directory tree will also contain:

|-- build
|-- dist
|   +-- javadoc
|-- test

build -- generated directory holding products of the Java compiler
dist -- generated jar files and javadoc, the products of the project
images -- illustrative image files
lib -- third-party Java libraries used by this project
nbproject -- files supporting the Netbeans project structure
src-autogenerate -- generator classes producing source files in Java, Python, etc.
src-generated -- Java source file output from the source generator
src-specialcase -- necessary DIS class files which required some modification after autogeneration
src-supporting -- additional class files satisfying generated source dependencies
stringTemplates -- supporting files, such as string templates
xml -- SISO and IEEE-based XML files which serve as the input to the generator
test -- unit tests for checking correctness are all migrated to populate opendis7-java tests

Products are then copied to the opendis7-java projects for further integration, testing and publication.

Project Internals

There are several logical output types described separately in the specifications.
This project processes them independently, i.e., the input XML is re-read for each type. Those types are:

Protocol Data Units (PDUs)
Enumerations
Object types
Radio Jammer types
Entity types

PDUs and Enumerations are the most commonly used. The number of distinct entity types is large, which translates to a large number of Java classes. The use of the generated entity types is optional in a DIS application, since a DIS programmer managing a small number of entities may choose to manually insert the appropriate values into his/her data structures. For that reason, plus the fact that the entity type classes simply implement an abstract class by supplying 1-4 integer values, the source is not intended to be included in a distribution. The completed class jar files are available in the dist/ directory.

When the project is "run", as described above, the class which serves as the entry point, or "main", is src/edu/nps/moves/dis7/source/generator/Main. As mentioned above, the 5 types of Java classes which are generated are done so independently. To that end, the main entry just listed simply calls similar Java "main" methods in 5 separate classes:

edu.nps.moves.dis7.source.generator.enumerations.GenerateEnumerations -- produces enumerations from the SISO specification
edu.nps.moves.dis7.source.generator.pdus.Main -- produces Pdus and assorted sub-object classes from the IEEE-derived XML inputs
edu.nps.moves.dis7.source.generator.entitytypes.GenerateJammers -- produces radio jammer classes from the SISO specification
edu.nps.moves.dis7.source.generator.entitytypes.GenerateObjectTypes -- produces miscellaneous object classes from the SISO specification
edu.nps.moves.dis7.source.generator.entitytypes.GenerateEntityTypes -- produces entity type classes from the SISO specification

Source Generation Method -- Pdus

This class contains remnants of legacy code which created pdus classes in different languages. The "JavaGenerator" subclass is the only one used in this project (to date).

edu.nps.moves.dis7.source.generator.pdus.Main first reads the IEEE XML files with a SAX parser and produces a map of class names-to-GeneratedClass objects. The GeneratedClass object contains fields which reflect the information contained in the XML for the particular pdu or object. This map is theoretically language-neutral is then used to produce pdus classes in various languages.

edu.nps.moves.dis7.source.generator.pdus.JavaGenerator then processes this map, generating source for each GeneratedClass object encountered. Template files are used so that the standard Java library String class may be used like the following:
String fileContents = String.format(template, value1, value2, value3 ...);

Source Generation Method -- Enumerations

These classes are simpler than Pdus and are created in a simpler way. The enumerated values in the SISO specification are implemented as either java Enumeration or java Bitset classes. (The latter uses an invented "BitField" class as a front end.)

A SAX ("Simple API for XML") Java implementation is used to process the XML input files. The generated uses SAX for operation when the "start" and "end" tags of the following elements are encountered:

enum
enumrow
bitfield
bitfieldrow
dict
dictrow

The enum, bitfield, and dict elements map to separate classes. The enumrow, bitfieldrow, and dictrow map to values within each of those classes.

When a SAX "end" element is encountered, the "current" element is written out as a complete Enumeration or BitField class, with enumerated values contained therein. Template files are used as above.

Source Generation Method -- Entity types, Object types, Jammers

These classes are also simpler than Pdus. Each of these three is hierarchically defined. For instance, a single Entity type is defined by entity, category, subcategory, specific and optional parameters, and not all of the sub parameters are required. Using a SAX parser, the SISO specification is read sequentially.

When a SAX "start" element is encountered, a new Java object is created -- one of EntityElem, CategoryElem, SubCategoryElem, SpecificElem, or ExtraElem. Since it is a hierarchical structure, when, e.g., a SubCategoryElem is encountered, the newly created object is inserted as a child of the previously created EntityElem.

When a SAX "end" element is encountered, the "current" element is written out as a complete EntityType class, with specific category, subcategory, etc., values. Template files are used as above.

Further work:

Refactor Java generator classes -- reasonably stable, minor refactoring occurs occasionally
Implement other language outputs -- Python work is in progress
Improve descriptions / javadoc in XML -- looking pretty good now!
Implement information "toString()" methods for classes like EulerAngles, EntityID, EntityKind

open-dis / opendis7-source-generator