Getting Started

This guide walks you through your first jNetWorks application: capturing packets, applying filters, and processing them in parallel across multiple CPU cores.

jNetWorks makes high-performance capture simple with a fluent, type-safe API — the same code works for development (libpcap) or production (DPDK/Napatech).

1. Add the Dependency

<dependency>
    <groupId>com.slytechs.sdk</groupId>
    <artifactId>jnetworks-sdk</artifactId>
    <version>3.0.0</version>
</dependency>

The core API and protocol dissection are fully Apache 2.0 licensed. DPDK and Napatech backends require a commercial license.

2. Activate License (Commercial Features Only)

If using DPDK or Napatech backends:

Net.activateLicense("your-commercial-key"); // Optional for libpcap

3. Basic Single-Stream Capture

Start with the simplest possible live capture:

import com.slytechs.sdk.jnetworks.Net;
import com.slytechs.sdk.jnetworks.PacketStream;
import com.slytechs.sdk.jnetworks.pcap.PcapBackend;
import com.slytechs.sdk.protocol.core.Packet;

try (Net net = new PcapBackend()) {

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

    net.capture("en0")           // Capture from interface en0
       .filter("tcp port 80")    // Optional BPF filter
       .pipe(stream)             // Send packets to our stream
       .apply();

    while (stream.isActive()) {
        Packet packet = stream.take();
        System.out.printf("Captured %d bytes (wirelen=%d)%n",
                packet.capLength(), packet.wireLength());

        stream.release(packet);  // Always release when done
    }

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

4. Multi-Core Parallel Processing (Recommended)

Scale effortlessly across CPU cores:

import java.time.Duration;
import com.slytechs.sdk.jnetworks.*;
import com.slytechs.sdk.jnetworks.config.HashType;
import com.slytechs.sdk.jnetworks.task.TaskScope;
import com.slytechs.sdk.protocol.core.Packet;

try (Net net = new PcapBackend()) {

    // Create 8 parallel streams (adjust to your CPU core count)
    PacketStream[] streams = net.createPacketStreams("worker-%d", 8);

    net.capture("en0", "en1")
       .filter("ip")                     // Capture only IP traffic
       .hash(HashType.HASH_5_TUPLE)      // Load-balance flows across streams
       .slice(96)                        // Capture only first 96 bytes (headers)
       .pipe(streams)
       .apply();

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

        // Fork one worker task per stream
        scope.fork(streams, stream -> {
            while (stream.isActive()) {
                Packet packet = stream.take();
                // Process packet (analysis, counting, forwarding, etc.)
                System.out.printf("%s: %s → %s%n",
                        stream.name(),
                        packet.ip4().src(),
                        packet.ip4().dst());

                stream.release(packet);
            }
        }).awaitCompletion();
    }

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

5. Typed Protocol Streams (Zero Manual Parsing)

Receive fully dissected objects directly:

import com.slytechs.sdk.jnetworks.ProtocolStream;
import com.slytechs.sdk.jnetworks.tcpip.IpDatagram;
import com.slytechs.sdk.jnetworks.tcpip.TcpSegment;

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

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

net.capture("en0")
   .filter("tcp")
   .pipe(tcpStream)
   .apply();

// In worker task:
TcpSegment segment = tcpStream.take();
System.out.printf("TCP %d → %d (seq=%d)%n",
        segment.srcPort(), segment.dstPort(), segment.seq());
tcpStream.release(segment);

Next Steps

• Tutorials – Full working examples (multi-core, typed streams)

• Public API – Deep dive into builders and configuration

• Hardware Integration – Switching to DPDK or Napatech

Welcome to wire-speed network programming in Java.