IHMC Pub Sub

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

Fast-DDS release: 2.14.3

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.3/.

Java type generator

The IHMC Pub Sub generator creates Java classes from OMG DDS IDL formatted files. The resulting classes can be used in conjunction with IHMC Pub Sub 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 (using IHMC Pub Sub serializers extra ) serialization and deserialization to JSON/BSON/YAML and XML.
• @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);
ParticipantAttributes attributes = domain.createParticipantAttributes([numeric domain ID], [participant name]);
Participant participant = domain.createParticipant(attributes);

Publisher

TopicDataType dataType = // IHMC Pub Sub generator generated PubSubType
PublisherAttributes publisherAttributes = domain.createPublisherAttributes(participant, dataType, [Topic name], ReliabilityKind.RELIABLE);           
Publisher publisher = domain.createPublisher(participant, publisherAttributes);

[Type] message = // IHMC Pub Sub generator generated message
publisher.write(message);

Subscriber

private class SubscriberListenerImpl implements SubscriberListener
{
   private final [Type] message = // IHMC Pub Sub generator generated message
   private final SampleInfo info = new SampleInfo();

   @Override
   public void onNewDataMessage(Subscriber subscriber)
   {
      if (subscriber.takeNextData(message, info))	// Note: No memory is allocated as the message is re-used. 
      {
         // Use data here
      }
   }

   @Override
   public void onSubscriptionMatched(Subscriber subscriber, MatchingInfo info)
   {
   }
}

TopicDataType dataType = // IHMC Pub Sub generator generated PubSubType
SubscriberAttributes subscriberAttributes = domain.createSubscriberAttributes(participant, dataType, [Topic name], ReliabilityKind.BEST_EFFORT);
domain.createSubscriber(participant, subscriberAttributes, new SubscriberListenerImpl());      

Building

Java code generation and compilation

This step is necessary to generate required classes from JAXB schema. The code will not compile until this is run once.

This will also clone the git submodules.

ihmc-pub-sub-group $ gradle compositeTask -PtaskName=compileJava

Native compilation

Required Tools for Compiling: Linux:

• GNU C Compiler (g++)
• swig
• CMake

Windows:

• Visual Studio 2019
• swig
• CMake

macOS:

• XCode 1.13.1+
• swig
• CMake

Run the cross-platform build script in the project root directory:

bash cppbuild.bash

Cross-compiling for ARM64 on Linux:

Install the required compilers:

sudo apt install qemu-user gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu g++-aarch64-linux-gnu

Run the build script with an added environment variable:

LINUX_CROSS_COMPILE_ARM=1 bash cppbuild.bash

Cross-compiling for ARM64 on macOS:

Run the build script with an added environment variable:

MAC_CROSS_COMPILE_ARM=1 bash cppbuild.bash

License

The IHMC Pub Sub library is licensed under the Apache 2.0. See LICENSE.txt