Babel 2 Distributed Protocol Framework API Documentation
Babel 2 Distributed Protocol Framework
Welcome to the unified API documentation for Babel 2, a high-performance, event-driven framework for developing and evaluating distributed protocols in Java 17+.
Architecture Overview
Babel 2 decouples distributed protocol logic from network transports and execution models, providing compile-time type safety, zero-reflection serialization, and cryptographic security.
| Subsystem / Module | Description & Key Packages |
|---|---|
| Babel 2 Core |
Runtime orchestration, protocol lifecycle, event dispatching, execution threading models,
and protocol extensions.
|
| Babel 2 IP Network Layer |
High-performance Netty-based network channels, binary serialization, and secure transport mechanisms.
|
Quick Start Example
Building a Babel 2 application involves three main steps: defining messages, implementing a protocol with declarative event annotations, and bootstrapping the runtime with an execution model and transport channels.
1. Define a Network Message
Annotate a record with @BabelIPMessage and assign a unique numeric identifier.
The annotation processor generates zero-reflection binary serializers automatically at compile time.
import pt.unl.fct.di.novasys.babel2.channels.BabelIPMessage;
import pt.unl.fct.di.novasys.babel2.channels.BabelMessage;
@BabelIPMessage(id = 100)
public record PingMessage(String content) implements BabelMessage {}
2. Implement a Protocol
Implement BabelProtocol and annotate handlers with @UponMessageIn.
Messages are sent to peers via the assigned ComposedBabelChannel.
import pt.unl.fct.di.novasys.babel2.annotations.UponMessageIn;
import pt.unl.fct.di.novasys.babel2.channels.ComposedBabelChannel;
import pt.unl.fct.di.novasys.babel2.core.Babel;
import pt.unl.fct.di.novasys.babel2.core.BabelNode;
import pt.unl.fct.di.novasys.babel2.core.BabelProtocol;
public class PingPongProtocol implements BabelProtocol {
private ComposedBabelChannel channel;
@Override
public void init(Babel runtime, ComposedBabelChannel channel) {
this.channel = channel;
}
@UponMessageIn
public void onPing(PingMessage msg, BabelNode sender) {
System.out.printf("Received '%s' from %s%n", msg.content(), sender);
// Reply back to sender across the composed channel
channel.send(sender, new PingMessage("pong"));
}
}
3. Bootstrap and Initialize the Runtime
Configure node cryptographic identity, Netty event loops, execution holder factories,
channel builders, and register protocols before starting the runtime with init():
import java.net.InetSocketAddress;
import java.security.KeyPair;
import io.netty.channel.EventLoopGroup;
import pt.unl.fct.di.novasys.babel2.channels.DefaultNodeStore;
import pt.unl.fct.di.novasys.babel2.channels.PublicKeyBabelNode;
import pt.unl.fct.di.novasys.babel2.channels.tcp_tls.AbstractTCPBabelChannel.TCPBabelChannelAuthMode;
import pt.unl.fct.di.novasys.babel2.channels.tcp_tls.TCPBabelChannel;
import pt.unl.fct.di.novasys.babel2.channels.utils.BabelIpUtils;
import pt.unl.fct.di.novasys.babel2.core.Babel;
import pt.unl.fct.di.novasys.babel2.core.NettyExecutorProtocolHolderFactory;
import pt.unl.fct.di.novasys.babel2.utils.CryptoUtils;
public class Application {
public static void main(String[] args) {
// 1. Generate identity cryptographic key pair & node representation
KeyPair keyPair = CryptoUtils.generateKeyPair();
PublicKeyBabelNode myself = new PublicKeyBabelNode(keyPair.getPublic());
// 2. Configure event loop and protocol execution policy
EventLoopGroup eventLoop = BabelIpUtils.createLoopGroup(4);
var nettyHolder = new NettyExecutorProtocolHolderFactory(4096, eventLoop);
// 3. Configure network transport channel builder
var tcpChannel = TCPBabelChannel.builder()
.setBindingAddress(new InetSocketAddress(10000))
.setEventLoopGroup(eventLoop)
.setAuthMode(TCPBabelChannelAuthMode.FULL_AUTH)
.verifyIdentity();
// 4. Instantiate protocol
var pingPong = new PingPongProtocol();
// 5. Bootstrap runtime, register protocol with holder and channel, and initialize
Babel runtime = Babel.builder()
.setMyself(myself)
.setKeyPair(keyPair)
.setNodeStore(new DefaultNodeStore(10, 1))
.registerProtocol(pingPong, nettyHolder, tcpChannel)
.build()
.init();
}
}Packages
Package
Description
Annotations used to mark methods as handlers for various events and messages
in the Babel 2 framework.
Channel abstractions, lifecycle builders, wire messages, and node components for Babel 2.
Channel extensions and interfaces for local network broadcast and multicast communication.
Exception types thrown by Babel 2 channel and serialization subsystems.
In-memory simulated communication channels for intra-JVM protocol testing and message passing.
Control and framing messages for backward-compatible legacy channels.
Legacy server-side channel implementation compatible with legacy clients.
Handshake messages specific to the legacy simple server channel protocol.
Network handshake and discovery messages exchanged across IP channels.
QUIC transport channel implementation for Babel 2, providing multiplexed,
stream-oriented communication secured by mutual TLS.
Core serializer abstractions, registries, and primitive wire serializers for Babel 2 IP messaging.
Serializers for core Babel runtime types including nodes, components, and messages.
Serializers for standard Java collection and map types over Netty ByteBuf buffers.
Serializers for primitive array types (boolean[], byte[], short[], int[], long[], float[], double[], CharSequence).
Serializers for Java primitive wrapper types (Boolean, Byte, Short, Integer, Long, Float, Double, Character).
TCP transport channel implementation for Babel 2, providing reliable, ordered,
connection-oriented message delivery over persistent TCP sockets with configurable
authentication modes and identity verification.
UDP datagram channel implementation for connectionless unicast and multicast messaging.
Platform transport utilities and helper methods for Netty network channels.
Core runtime, protocol lifecycle, executor models, and protocol extensions for Babel 2.
Provides interfaces and extensions for implementing and consuming
broadcast services in the Babel 2 framework.
Contains events used by broadcast protocols to communicate
between consumers and providers in the Babel 2 framework.
Provides interfaces and extensions for implementing and consuming
membership (overlay network) services in the Babel 2 framework.
Contains events used by membership protocols to communicate
overlay neighbour changes between providers and consumers.
Address and node component resolution protocol abstractions and extensions for Babel 2.
Events exchanged during node identity probe and address resolution.
Cryptographically signed message support and extensions for Babel 2 protocols.
Annotations for handling inbound and outbound signed messages in Babel 2 protocols.
Protocol events delivering signed message reception and send outcomes.
Event hierarchy defining network states, message delivery outcomes, protocol notifications, and runtime lifecycle events in Babel 2.
Functional interfaces defining internal handler signatures for routing Babel events to protocol callback methods.
Local network peer discovery protocols for dynamic node address and channel resolution.
Network probe and answer messages exchanged during local network node discovery.
Binary wire serializers for local network discovery protocol messages and structures.
Ephemeral self-signed certificate generation and peer identity authentication
for TLS/QUIC and TLS/TCP in Babel 2.
General utility classes for configuration loading and cryptographic operations in Babel 2.