jNetWorks SDK
Hardware-accelerated Java packet capture

Kernel-bypass packet capture for Java. DPDK and Napatech SmartNIC support. Full L2–L7 dissection. Inline, capture, and transmit modes. The foundation that powers Lynx, Sentinel, Quarry, and the Vantage Platform.

Hello, Capture

Create a runtime, open a channel, fork a task worker. The same pattern works across DPDK, Napatech, and libpcap: swap the runtime class, keep everything else.

Switch from PcapRuntime to DpdkRuntime or NtapiRuntime with a single line change.

channel.get() blocks until a packet is available and returns a zero-copy view into native memory. channel.release() returns it to the pool: no GC, no allocation. For workers that cannot block, tryGet provides timed and non-blocking variants.

shutdownAfter(Duration) cleanly winds down all workers, drains in-flight packets, and closes the runtime. The session tree tracks exactly what's blocking at every step.

HelloCapture.java
public void run() {
    // use DpdkRuntime with DPDK capable NICs/Ports
    // use NtapiRuntime with Napatech SmartNIC configured adapters/Ports
    try (NetRuntime net = new PcapRuntime("pcap-capture")) {

        PacketChannel channel = net.packetChannel("hello-channel");

        // Start capture only, on first active (with traffic) ETH port
        Capture capture = net.capture("hello-capture", "en0")
                // Capture all packets
                .filter(PacketFilter.all())
                // Traffic distributed to this channel, need to fork a Task
                .assignTo(channel)
                // Start capture, no tx capabilities
                .apply();

        System.out.println("Selected port for capture: " + capture.getPort());

        try (TaskExecutor executor = net.executor("packet-task")) {
            executor.fork(channel, this::processPackets)
                    .shutdownAfter(Duration.ofSeconds(10))
                    .awaitCompletion();

        } catch (Throwable e) {
            e.printStackTrace();
        }

        System.out.printf("Capture complete: %d packets%n", capture.metrics().packetsAssigned());

    } catch (NetException | FilterException e) {
        e.printStackTrace();
    }
}

void processPackets(PacketChannel channel) throws SessionShutdownException, InterruptedException {
    System.out.println("Starting packet capture...");

    long count = 0;

    // Will turn to false when task or net session is shutdown.
    while (channel.isActive()) {
        // Acquire blocks with interrupt
        Packet packet = channel.get();

        // Optionally can persist packets either from Arena or pool
        // Packet.persist(), Packet.copy(), Packet.persistTo(pool), Packet.copyTo(pool)

        count++;
        System.out.printf("Packet #%d: len=%,-6d, ts=%s%n",
                count,
                packet.captureLength(),
                packet.timestampInfo());

        // Must release
        channel.release(packet);

    }

    System.out.println("Capture stopped.");
}

From HelloCapture.java on GitHub, without the license header, imports and main method. jnetworks-examples has ten examples in all, covering file read and write, replay, packet filters and the packet DSL.

Capture. Inline. Transmit.
All at Once.

A single NetRuntime session can run capture-only, inline IDS, and traffic generation simultaneously, each with their own channel pool, worker threads, and protocol stack. The code below is abridged from the Showcase example.

Showcase.java: Multi-Channel Setup (excerpt)
// use DpdkRuntime with DPDK capable NICs/Ports
// use NtapiRuntime with Napatech SmartNIC configured adapters/Ports
try (NetRuntime net = new PcapRuntime()) {

    // Packet channels will receive packets (captured, dissected, analyzed or empty
    // for transmit)
    PacketChannel[] capChannels = net.packetChannels("capture-channel", 4);
    PacketChannel[] idsChannels = net.packetChannels("inline-ids-channel", 8);
    PacketChannel[] genChannels = net.packetChannels("traffic-gen-channel", 4);
    PacketChannel exportChannel = net.packetChannel("export-channel");

    // The channels that will receive reassembled TCP segments
    ProtocolChannel<TcpSegment>[] tcpChannels = net.protocolChannels("tcp-channel", 15, TcpSegment.class);

    // Tokens are lightweight, stateless analysis objects (16+ bytes). Many token
    // types available.
    TokenChannel<TcpToken> tcpTokens = net.tokenChannel("analysis-tokens", TcpToken.class);

    // Start capture only, on ethernet port
    Capture capture = net.capture("udp-capture-channel", "en0")
            // Pcap BPF filter
            .filter(PacketFilter.tcp())
            // Traffic distributed to these channels, need to fork multiple tasks
            .assignTo(capChannels)
            // Start capture, no tx capabilities
            .apply();

    // Start inline capture-forward-transmit, en1 -> en0
    Inline inline = net.inline("inline-ids-channel", "en1")
            // Pcap BPF filter Pcap.setFilter()
            .filter(PacketFilter.all())
            // Traffic distributed to these channels, need to fork multiple tasks
            .assignTo(idsChannels)
            // Default TX flags on each packet
            .txEnable(true)
            // Default TX port
            .txPorts("en0")
            // Do not preserve IFG
            .txImmediately()
            // Start capture + tx-queue router
            .apply();

    // Enable TX on all ETH ports that are UP and generate custom traffic
    Transmit transmit = net.transmit("traffic-gen-channel")
            // Will provide empty buffers for pkt gen
            .assignTo(genChannels)
            // Default TX flags on each packet
            .txEnable(true)
            // Default TX port, can override in task worker on per-packet basis
            .txPort("en0")
            // Do not preserve IFG
            .txImmediately()
            // Start buffers flowing and tx-queue packet router
            .apply();

    // Demonstrate the protocol stack usage
    // Enables IPF/TCP reassembly
    ProtocolStack stack = new ProtocolStack()
            .enableIpReassembly()
            .enableTcpReassembly();

    // Assign TCP traffic for IP/TCP processing
    Capture tcpReassembled = net.capture("tcp-reassembled-capture", "en0")
            // limit to TCP traffic only
            .filter(PacketFilter.tcp())
            // assign to protocol channel, will receive protocol objects not packets
            .assignTo(tcpChannels)
            // Protocol analysis tokens sent to this token channel
            .assignTo(tcpTokens)
            // Use this protocol stack for protocol level processing
            .protocol(stack)
            .apply();

    // ... port reporting omitted

    // Manage and fork our task workers try-with-resources for proper shutdown/error
    // handling
    try (TaskExecutor executor = net.executor("packet-tasks")) {

        // How to handle errors if not handled inside the task worker, or can use
        // defaults
        executor.onTaskException(this::handleErrors)
                .maxRestarts(3)
                .restartDelay(Duration.ofSeconds(1));

        // ... port lookup omitted

        // Use different fork methods to attach task workers to channels
        // 4 workers
        executor.fork(capChannels, this::capturedPackets)
                // 8 workers
                .fork(idsChannels, this::intrusionDetection)
                // Can pass multiple args too, 4 workers
                .fork(genChannels, en0, en1, this::generateTraffic)
                // 15 workers
                .fork(tcpChannels, this::processTcpStreams)
                // 1 worker
                .fork(tcpTokens, this::analyzeTcpTokens)
                .fork(exportChannel, ch -> {/* Merged cap channels for file dump */})
                // Shutdown the group in 5 minutes
                .shutdownAfter(Duration.ofMinutes(5))
                // Wait for this task group to shutdown, 32 workers
                .awaitCompletion();

        // Can have sub-groups executor.group("new group").fork()...
        // Workers can be affinity locked to DPDK LCORE threads

    }
    // ... error handling and capture summary omitted
}

Abridged from Showcase.java. The full example, including every task worker, is on GitHub.

Three Channel Modes

PacketChannel for capture or transmit. ProtocolChannel<T> for reassembled protocol objects like TcpSegment. TokenChannel<T> for analysis event tokens. Each has its own get/release lifecycle.

Inline Drop & Forward

Inline mode receives packets before transmission. Set packet.tx().setTxEnabled(false) to drop. Override the TX port per-packet. Inject timestamps, CRCs, or custom headers using mbuf-style memory segments.

Traffic Generation

Transmit channels supply empty buffers from a memory pool. Write raw bytes, set the capture length, release and the packet transmits. Prefill mode cycles pre-built packets for retransmission with zero work per packet.

Task Error Recovery

onTaskException() with TaskRecovery.RESTART_DELAYED or SHUTDOWN_GROUP. Configure max restarts and delay. Workers recover without restarting the entire session or losing other channels.

Analysis Without Slowing Capture

Token workers receive lightweight 16-byte analysis events out-of-band, completely independent of the packet path. The same token feeds Lynx's live UI, pcapng sidecar storage, and ML pipelines simultaneously. Subscribe to only what you need; unsubscribed packs cost exactly zero.

TCP Token Analysis Worker
void analyzeTcpTokens(TokenChannel<TcpToken> channel) throws SessionShutdownException, InterruptedException {

    while (channel.isActive()) {
        TcpToken token = channel.get();
        TcpStream stream = token.tcpStream();
        long frameno = token.frameNumber();

        State state = stateMap.get(stream.flowKey());

        switch (token.type()) {
        case STREAM_SYN -> state.handleConnectionStart(stream);
        case STREAM_FIN -> {
            state.handleConnectionEnd(stream);
            // Flag for cleanup
            state.markForEviction();
        }
        // Immediate removal
        case STREAM_TIMEOUT -> stateMap.remove(stream.flowKey());
        case SEGMENT_OUT_OF_ORDER -> state.detectAnomaly(stream, "OOO");
        case WINDOW_RESIZE -> state.monitorPerformance(stream);
        case STREAM_RST -> state.handleConnectionReset(stream);
        case RETRANSMIT -> state.detectLoss(stream);
        case FAST_RETRANSMIT -> state.detectCongestion(stream);
        case DUPLICATE_ACK -> state.analyzeCongestion(stream);

        // Per-channel disable - not interested in this token type - Automatic token
        // pruning
        default -> channel.disable(token.type());
        }

        channel.release(token);
    }
}

The analyzeTcpTokens worker from Showcase.java.

Per-Channel Token Pruning

channel.disable(token.type()) tells the runtime to stop emitting that token type to this specific channel. Zero serialization overhead for events you're not consuming.

Typed Token Channels

TokenChannel<TcpToken> gives you typed access to TCP-specific fields (stream.flowKey(), token.frameNumber(), state machine events) without casting or instanceof checks.

32-Bit Addressed Token Space

Severity and LOD level are encoded in the token ID: routers filter by criticality with a bitmask, no deserialization needed. PACK_ML = 0x3000 and PACK_USER = 0xF000 are reserved for ML inference and custom analyzers.

Persistent at Capture Time

Tokens write inline to pcapng sidecars as they're emitted. Open a historical file months later in Lynx: flow markers, alerts, and anomalies are already there. No re-analysis required.

What jNetWorks Does

Designed for 800 Gbps

Kernel bypass via DPDK. Napatech SmartNIC offload. NUMA-aware multi-queue distribution. Hash(5-tuple) keeps flows on the same ProcessorTree, no cross-thread synchronization.

L2–L7 Protocol Dissection

Ethernet, IP, TCP, UDP, TLS, HTTP/1–3, QUIC, DNS, GTP, and 90+ more. IP and TCP reassembly. Stream objects, segment objects, and application metadata all available as typed channels.

Zero-Allocation Hot Path

Pre-bound packet views, CAS pool get/release, VarHandle field access. No new in the packet path. No exceptions. No callbacks. No locks. No map lookups in routing.

Quarry Native

Direct read/write to Quarry with block-level efficiency. RDMA-striped writes across network nodes directly from adapters to SSD targets. Sidecar and index generation included.

Hardware Acceleration

Napatech SmartNIC offload for capture, timestamping, and filtering. FPGA-ready via Forge integration. Runtime-specific capabilities surfaced through the same NetRuntime API.

Managed Session Observability

Hierarchical session tree with live state inspection. See exactly which worker is blocked, on which operation, for how long. Frozen state preserved post-shutdown for post-mortem debugging.

Why VarHandle Field Access Matters

jNetWorks reads packet fields through static final VarHandles. Because each handle is a constant, the HotSpot JIT folds away its type and access checks and inlines the access, so the compiled code is a load from a base address plus a fixed offset: the same instruction a C compiler emits when it dereferences a pointer. Memory-segment bounds checks remain part of the contract, but in hot loops the JIT can usually hoist them out of the loop body. That is how Java code reads native packet memory at close to C cost.

The static final part is what makes this work. A VarHandle held in an ordinary field cannot be constant-folded and is far slower. jNetWorks requires JDK 25, a long-term-support release with Oracle Premier Support through September 2030. Newer releases are recommended, because each one continues to improve how the JIT optimizes Foreign Function & Memory access.

Hot Path Principles

Designing for 800 Gbps requires every decision in the packet path to be measurable in nanoseconds. These are non-negotiable rules that apply to every processor in the stack.

  Packet arrival (800 Gbps design path):

  1. packet = viewPool.allocate()           // CAS on free list - no allocation
  2. packet.dataMemory().bind(nativeData)   // Reference assignment only
  3. packet.descriptor().bind(nativeDesc)   // Reference assignment only
  4. processPacket(packet)                  // Zero allocation processing
  5. emit tokens out-of-band               // Independent of packet path
  6. viewPool.release(packet)              // CAS back to free list

  Rules - enforced across every processor:
  ──────────────────────────────────────────────────────────
  No new        Rebind, pool, reuse. GC never sees a packet.
  No exceptions Errors increment counters. Stacks never unwind.
  No locks      Single-threaded ProcessorTree. Hash(5-tuple) distribution.
  No callbacks  Direct method calls only. Lambda dispatch not used.
  Bitmask prune Disabled features vanish from the instruction stream.
  Pre-binding   VarHandle field access. All objects allocated before first packet.

Ready to Build on jNetWorks?

Talk to our engineering team about licensing and integration.