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
   .or(PortFilter.named("en0", "en1"))   // Or explicitly list
   .filter("tcp port 443")               // Standard BPF syntax
   .hash(HashType.HASH_5_TUPLE)          // Load-balance flows across streams
   .slice(128)                           // Capture only first 128 bytes (headers only)
   .pipe(streams)                        // Send packets to your stream(s)
   .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 streams
.pipe(ProtocolStream...)	Route directly to typed protocol streams
.onPortSelection(Consumer)	Callback when ports are selected
.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);
}

For medium-term usage, clone packets:

Packet cloned = packet.clone();  // Uses packet's clonePolicy (PacketPolicy)
try {
    // Use cloned for longer processing
} finally {
    // Release when done
}

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.