Iterator API

The Iterator API provides a simplified, single-threaded alternative to jNetWorks' multi-stream capture. It implements the standard Java Iterator<T> interface, making it familiar and easy to use for developers who don't need high-performance parallel processing.

Overview

jNetWorks offers two capture patterns:

Pattern	API	Use Case
Multi-stream	PacketStream[] with while/take/release	Production, high-speed, parallel
Iterator	NetIterator<T> with hasNext/next/forEach	Development, simple apps, single-threaded

The Iterator pattern is ideal for:

• Getting started quickly

• Simple sequential processing

• Prototyping and debugging

• Collecting packets to lists or collections

Resource Management

CRITICAL: Each iterator creates a backing capture session. Always use try-with-resources.

// CORRECT - always use try-with-resources
try (NetIterator<Packet> packets = net.packetIterator("tcp", "en0")) {
    packets.forEach(this::process);
}  // Automatically closed

// WRONG - resource leak!
NetIterator<Packet> packets = net.packetIterator("tcp", "en0");
packets.forEach(this::process);
// Session still running!

Creating Iterators

Packet Iterator

// Simple
try (NetIterator<Packet> packets = net.packetIterator("tcp port 80", "en0")) {
    // ...
}

// Multiple ports
try (NetIterator<Packet> packets = net.packetIterator("tcp", "en0", "en1")) {
    // ...
}

// With settings
IteratorSettings settings = new IteratorSettings()
    .stack(stack)
    .snaplen(9000);

try (NetIterator<Packet> packets = net.packetIterator("tcp", settings, "en0")) {
    // ...
}

Protocol Iterator

try (NetIterator<HttpMessage> http = net.protocolIterator(
        HttpMessage.class, "tcp port 80", "en0")) {
    // ...
}

try (NetIterator<TcpSegment> tcp = net.protocolIterator(
        TcpSegment.class, "tcp", "en0")) {
    // ...
}

Token Iterator

try (NetIterator<Token> tokens = net.tokenIterator(
        TcpTokens.FLOW_BOUNDARY, "tcp", "en0")) {
    // ...
}

try (NetIterator<Token> alerts = net.tokenIterator(
        IdsTokens.ALERTS, "all", "en0")) {
    // ...
}

Basic Usage

While Loop

try (NetIterator<Packet> packets = net.packetIterator("tcp", "en0")) {
    
    Ip4 ip = new Ip4();
    Tcp tcp = new Tcp();
    
    while (packets.hasNext()) {
        Packet p = packets.next();
        
        if (p.hasHeader(ip) && p.hasHeader(tcp)) {
            System.out.printf("%s:%d -> %s:%d%n",
                ip.src(), tcp.srcPort(),
                ip.dst(), tcp.dstPort());
        }
    }
}

forEach

try (NetIterator<Packet> packets = net.packetIterator("udp port 53", "en0")) {
    packets.forEach(p -> {
        System.out.println("DNS packet: " + p.captureLength() + " bytes");
    });
}

As Iterable

Convert to Iterable for enhanced for-loop:

try (NetIterator<Packet> packets = net.packetIterator("tcp", "en0")) {
    Iterable<Packet> iterable = () -> packets;
    
    for (Packet p : iterable) {
        process(p);
    }
}

Protocol Objects

Process reassembled protocol objects instead of raw packets:

try (NetIterator<HttpMessage> http = net.protocolIterator(
        HttpMessage.class, "tcp port 80", "en0")) {
    
    while (http.hasNext()) {
        HttpMessage msg = http.next();
        
        if (msg.isRequest()) {
            System.out.println(msg.method() + " " + msg.uri());
            System.out.println("Host: " + msg.header("Host"));
        } else {
            System.out.println(msg.statusCode() + " " + msg.reasonPhrase());
        }
    }
}

Token Processing

Capture flow events and analysis tokens:

try (NetIterator<Token> tokens = net.tokenIterator(
        TcpTokens.FLOW_BOUNDARY | TcpTokens.RETRANSMIT, 
        "tcp", "en0")) {
    
    tokens.forEach(token -> {
        switch (token.type()) {
            case TcpTokens.SYN -> System.out.println("New connection");
            case TcpTokens.FIN -> System.out.println("Connection closed");
            case TcpTokens.RST -> System.out.println("Connection reset");
            case TcpTokens.RETRANSMIT -> System.out.println("Retransmission detected");
        }
    });
}

Session Control

Access the backing session for shutdown control:

try (NetIterator<Packet> packets = net.packetIterator("all", "en0")) {
    
    // Schedule automatic shutdown
    packets.session().shutdownAfter(Duration.ofMinutes(5));
    
    while (packets.hasNext()) {
        process(packets.next());
    }
}

Graceful Shutdown from Loop

try (NetIterator<Packet> packets = net.packetIterator("tcp", "en0")) {
    
    int count = 0;
    while (packets.hasNext()) {
        Packet p = packets.next();
        process(p);
        
        if (++count >= 10000) {
            packets.session().shutdown();
        }
    }
    
    System.out.println("Processed " + count + " packets");
}

Timed Capture

try (NetIterator<Packet> packets = net.packetIterator("all", "en0")) {
    packets.session().shutdownAfter(Duration.ofSeconds(30));
    packets.forEach(System.out::println);
}

Collecting Packets

The Iterator API defaults to memory-copy mode, making it safe to collect packets:

try (NetIterator<Packet> packets = net.packetIterator("tcp port 80", "en0")) {
    packets.session().shutdownAfter(Duration.ofSeconds(10));
    
    List<Packet> list = new ArrayList<>();
    packets.forEach(list::add);  // Safe - each packet is independent
    
    System.out.println("Collected " + list.size() + " packets");
    
    // Process collected packets
    for (Packet p : list) {
        analyze(p);
    }
}

Configuration

IteratorSettings

IteratorSettings settings = new IteratorSettings()
    .stack(stack)                    // Protocol configuration
    .snaplen(65535)                  // Capture full packets
    .bufferSize(4 * 1024 * 1024)     // 4MB buffer
    .timeout(Duration.ofSeconds(1)); // Read timeout

try (NetIterator<Packet> packets = net.packetIterator("tcp", settings, "en0")) {
    packets.forEach(this::process);
}

With Protocol Stack

ProtocolStack stack = new ProtocolStack();

stack.setProtocol(new IpProtocol())
     .enableReassembly(true)
     .fragmentTimeout(30);

stack.setProtocol(new TcpProtocol())
     .enableReassembly(true);

IteratorSettings settings = new IteratorSettings()
    .stack(stack);

try (NetIterator<Packet> packets = net.packetIterator("ip", settings, "en0")) {
    // IP fragments reassembled automatically
    packets.forEach(this::process);
}

Complete Example

public class TrafficAnalyzer {
    
    public static void main(String[] args) {
        
        // Configure protocol stack
        ProtocolStack stack = new ProtocolStack();
        stack.setProtocol(new IpProtocol())
             .enableReassembly(true);
        stack.setProtocol(new TcpProtocol())
             .enableReassembly(true);
        
        // Configure settings
        IteratorSettings settings = new IteratorSettings()
            .stack(stack)
            .snaplen(65535);
        
        // Capture HTTP traffic
        try (NetIterator<HttpMessage> http = net.protocolIterator(
                HttpMessage.class, "tcp port 80", settings, "en0")) {
            
            // Run for 1 minute
            http.session().shutdownAfter(Duration.ofMinutes(1));
            
            Map<String, Integer> hostCounts = new HashMap<>();
            
            while (http.hasNext()) {
                HttpMessage msg = http.next();
                
                if (msg.isRequest()) {
                    String host = msg.header("Host");
                    hostCounts.merge(host, 1, Integer::sum);
                }
            }
            
            // Print results
            System.out.println("\nHTTP Requests by Host:");
            hostCounts.entrySet().stream()
                .sorted(Map.Entry.<String, Integer>comparingByValue().reversed())
                .limit(10)
                .forEach(e -> System.out.printf("  %s: %d%n", e.getKey(), e.getValue()));
                
        } catch (Exception e) {
            System.err.println("Capture error: " + e.getMessage());
        }
    }
}

NetIterator Interface

public interface NetIterator<T> extends Iterator<T>, AutoCloseable {
    
    // Iterator (inherited)
    @Override
    boolean hasNext();
    
    @Override
    T next();
    
    // forEach inherited from Iterator
    
    // Session access
    Session session();
    
    // AutoCloseable
    @Override
    void close();
}

Comparison with Multi-Stream API

Aspect	Multi-Stream	Iterator
Factory	net.createPacketStreams()	net.packetIterator()
Pattern	while/take/release	hasNext/next/forEach
Parallelism	Multiple streams per CPU	Single-threaded
Memory	Zero-copy option	Memory-copy (safe)
Resource release	Explicit release()	Automatic via GC
Session control	Per-stream ClientSession	session() method
Performance	Optimal	Slight overhead
Use case	Production	Development, simple apps

Choose Iterator for simplicity. Choose multi-stream for performance.