IHMC Pub Sub

Allocation free Java libraries for DDSI-RTPS messaging using eProsima’s Fast-DDS.

Fast-DDS release: 2.14.4

Features

• Allocation free Publisher and Subscriber API in Java
• Java data type generator for Object Management Group (OMG) IDL files (*.idl)
• Serialize messages to JSON, BSON, YAML, Java Properties, and XML
• Gradle plugin to generate Java types from IDL files

The eProsima Fast-DDS documentation can be useful as a reference guide on more advanced features and the inner working of the RTPS layer https://fast-dds.docs.eprosima.com/en/v2.14.4/.

Java type generator

The IHMC Pub Sub generator creates Java classes from OMG DDS IDL formatted files. The resulting classes can be used to serialize and deserialize to the Common Data Representation (CDR) format.

Features

• Pure Java serialization/deserialization. Allows message generation without having to compile native libraries.
• Allocation free during serialization/deserialization. All elements of the message are preallocated.
• StringBuilder instead of string allow allocation free string deserialzation.
• Support for wchar and wstring to map directly to Java’s UTF-16.
• Automatically generated equals() and toString() methods for testing and debugging.
• Support for #include directives and other C preprocessor directives. The include search path is the current directory and the parent directory of the .idl file.
• Optional serialization and deserialization to JSON/BSON/YAML and XML (ihmc-pub-sub-serializers-extra).
• @Abstract(type=”[fully qualified class name]”) annotation to generate an abstract Pub Sub type. This allows reusing exisiting Java data objects in combination with IDL specified data without marshalling. Use [Name]PubSubType.setImplementation() to implement.

Limitations

• Sequences of arrays and arrays of sequences are not supported.
• Long Doubles are not supported due to limitations in the Java language.
• Union, alias, value, sparse, set and map are not implemented.
• Interfaces are not implemented.

Compatibility notes

• CDR Byte stream is validated against FastCDR generated byte stream.
• FastRTPS’s fastrtpsgen does not seem to support wstring and Sequence<Enum>

Extra serializers:

The IHMC Pub Sub extra datatypes library provides support for serializing and deserialization of IDL datatypes to JSON, BSON, YAML, and XML.

This library uses Jackson internally. Unlike IHMC Pub Sub, the functionality in this library will allocate objects when used.

See test/us/ihmc/idl/serializers/extra for examples as test cases.

Usage

Supported platforms:

• Linux (Ubuntu 20.04+ or similar x86_64, arm64)
• Windows (Windows 10+ x86_64)
• macOS (macOS 12+ Intel, Apple Silicon)

Requires Java 17.

Generating Java code from .idl messages

Use the IDLGenerator to compile your .idl messages into [MessageType].java and [MessagePubSubType].java.

FileTools.deleteQuietly(Paths.get("generated-java")); // remove old files

// Generate Java types for all (*.idl) files in `src/test/idl` and put them in `src/test/generated-java`
for (Path idl : Files.list(Paths.get("idl")).toArray(Path[]::new))
{
   IDLGenerator.execute(idl.toFile(), // *.idl file
                        "us.ihmc.idl.generated", // package prefix
                        Paths.get("generated-java").toFile(), // output directory
                        Arrays.asList(Paths.get("idl").toFile())); // include path
}

The IHMC Pub Sub generator can either be used as a gradle plugin (recommended) or standalone library.

This creates a task to compile IDL files. The following properties can be set

• idlFiles: FileCollection of idl files to compile [Required]
• inludeDirs: FileCollection of include directories
• targetDirectory: File target directory

task generateIDL(type: us.ihmc.idl.generator.IDLGeneratorTask) {
	idlFiles = fileTree(dir: 'idl')
	includeDirs = files(".")
	targetDirectory = file("generated")
	packagePrefix = "us.ihmc.idl.generated"
}

Java application

Run us.ihmc.idl.generator.IDLGenerator. There are three options for generating IDL files

• No command line arguments: Dialogs will popup to select the IDL file and provide a target directory and package name.
• Command line arguments: us.ihmc.idl.generator.IDLGenerator [idl filename] [package] [target directory]
• Call directly from Java: us.ihmc.idl.generator.IDLGenerator.execute(String idlFilename, String packageName, File targetDirectory)

Examples

Examples for a creating simple publisher and subscriber can also be found in ihmc-pub-sub-generator/src/test/java/us/ihmc/pubsub/examples.

Participant

A single participant is needed to join a domain. Multiple publisher/subscribers can be added to a participant.

``` Domain domain = DomainFactory.getDomain(PubSubImplementation.FAST_RTPS);

File truncated at 100 lines see the full file