Public API

The jNetWorks Public API is designed for simplicity, fluency, and performance. It provides a builder-style, type-safe interface for configuring capture sessions, creating streams, applying filters, and managing parallel processing — all while hiding the complexity of high-speed backends.

The core entry point is the Net interface.

Core Classes and Interfaces

Class/Interface	Purpose
Net	Main factory and session manager. Create streams, configure capture.
PacketStream	Untyped stream of raw Packet objects. Ideal for custom processing.
ProtocolStream<T>	Typed stream delivering fully dissected protocol objects (e.g., IpDatagram, TcpSegment).
PacketStreamSettings	Optional fine-tuning (buffer sizes, memory pools, etc.).
PortFilter	Fluent interface for selecting capture interfaces.
HashType	Flow distribution strategies (3-tuple, 5-tuple, etc.).

Creating a Net Session

try (Net net = new PcapBackend()) {        // Development/testing
// try (Net net = new DpdkBackend()) {     // Production high-speed
// try (Net net = new NtapiBackend()) {    // Napatech SmartNIC

    // Your capture code here
}

The same code works across all backends — switch with a single line.

Creating Streams

Single Stream

PacketStream stream = net.createPacketStream("main");

Multiple Parallel Streams (Recommended for Performance)

// Create N named streams — ideal for CPU-core affinity
PacketStream[] streams = net.createPacketStreams("worker-%d", Runtime.getRuntime().availableProcessors());

Typed Protocol Streams

ProtocolStream<IpDatagram> ipStream =
        net.createProtocolStream("ip", IpDatagram.class);

ProtocolStream<TcpSegment> tcpStream =
        net.createProtocolStream("tcp", TcpSegment.class);

Configuring and Starting Capture

The capture builder is fully fluent:

net.capture(PortFilter.ethernet().up())  // Auto-select active Ethernet ports
   .filter("tcp port 443")               // Standard BPF syntax
   .pipe(streams)                        // Send packets to your stream(s)
   .hash(HashType.HASH_5_TUPLE)          // Load-balance flows across streams
   .slice(128)                           // Capture only first 128 bytes (headers only)
   .apply();                             // Activate configuration

Key Builder Methods

Method	Description
.capture(...)	Specify interfaces via PortFilter or string varargs
.filter(String bpf)	Apply libpcap-style BPF filter
.hash(HashType)	Distribute flows: HASH_3_TUPLE, HASH_5_TUPLE, etc.
.slice(int bytes)	Truncate capture to first N bytes (reduces memory bandwidth)
.pipe(PacketStream...)	Route packets to one or more packet based streams
.pipe(ProtocolStream...)	Route directly to typed protocol streams
.onPortSelection(Consumer)	Callback when ports are selected, for debugging or logging
.apply()	Activate and return a Registration (for later cancellation)

Processing Packets

Always release packets when done:

Packet packet = stream.take();
try {
    // Process packet
} finally {
    stream.release(packet);
}

For typed streams:

TcpSegment segment = tcpStream.take();
try {
    System.out.printf("TCP %d → %d seq=%d%n",
            segment.srcPort(), segment.dstPort(), segment.seq());
} finally {
    tcpStream.release(segment);
}

Structured Concurrency with TaskScope

Safely manage timeouts and parallel workers:

try (TaskScope scope = new TaskScope(net)) {
    scope.shutdownAfter(Duration.ofMinutes(10));

    scope.fork(streams, stream -> {
        while (stream.isActive()) {
            Packet p = stream.take();
            // process...
            stream.release(p);
        }
    });

    scope.awaitCompletion();  // Wait for all workers
}

Next Steps

• Getting Started – Full runnable examples

• Tutorials – Multi-core, typed streams, and more

• Hardware Integration – Switching to DPDK/Napatech

The public API is intentionally concise — most users need only a handful of methods to achieve line-rate performance.