org.jnetstream.capture
Interface LiveIterator

All Superinterfaces:

java.io.Closeable, com.slytechs.utils.collection.IOIterator<LivePacket>, com.slytechs.utils.collection.IORemovable, com.slytechs.utils.collection.IOSkippable, com.slytechs.utils.collection.IOSkippableIterator<LivePacket>

public interface LiveIterator
extends com.slytechs.utils.collection.IOSkippableIterator<LivePacket>, java.io.Closeable

IO based iterator over a live capture session. LiveIterator does not provide as many services as for example file PacketIterator. Also note that this iterator's remove() method is unsupported and will throw an UnuspportedOperationException if invoked.

You can aquire a LiveIterator from a LiveCapture session. Here is an example:

 LiveCapture capture = Captures.openLive(10); // Capture only 10 packets
 LiveIterator iterator = capture.getPacketIterator();
 
 while (iterator.hasNext()) {
        LivePacket packet = iterator.next();
        System.out.println(packet.toString());
 }
 
 capture.close(); // Don't forget to close
 

For convenience you can also use a tight foreach loop:

 for (LivePacket packet : Captures.openLive(10)) {
        System.out.println(packet.toString());
 }
 
 Captures.close(); // Close the last capture returned by our factory
 

Live iterator can also be interrupted from another thread, safely and gracefully by a call to LiveIterator.interruptNext:

 LiveCapture capture = Captures.openLive(10); // Capture only 10 packets
 LiveIterator iterator = capture.getPacketIterator();
 
 new Thread(new Runnable() {
        public void run() {
                Thread.sleep(10000); // sleep for 10 seconds
                iterator.interruptNext();
        }
 }).start();
 
 while (iterator.hasNext()) {
        LivePacket packet = iterator.next();
 
        if (packet == null) {
                // This means we were interrupted from another thread by a call to
                // iterator.interruptNext()
                // The interruption caused next() to exit early and return null. Any
                // packets that may have arrived are remembered and will be returned 
                // by subsequent calls to next, nothing has been lost. 
                // The main thing to remember is that when there is a possibility that
                // a call may be interrupted in a program, we must check for null being
                // returned.
        }
 }
 
 capture.close(); // Don't forget to close
 

It may also be a good idea to check LiveIterator.getQueueDrops() from time to time, especially if there was an interruption or any long delay between subsequent next() calls. The iterator maintains a queue of packets being received and is able to buffer a small amount of packets, but if they overwhelm the queue, the counter will indicate if any packets have been dropped due to the fact that the queue is full. Packets may continue to be dropped until the queue is drained. If the queue drop counter is increasing, even in a tight loop between calls to next, this means that the packets are arriving faster then the current thread can handle the processing of them.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

Nested classes/interfaces inherited from interface com.slytechs.utils.collection.IOIterator

com.slytechs.utils.collection.IOIterator.IteratorAdapter<E>

Method Summary

long	getQueueDrops() Retrieves the current value of the "queue drop" counter.
void	interruptNext() Politely interrupts the next() call.

Methods inherited from interface com.slytechs.utils.collection.IOSkippable

skip

Methods inherited from interface com.slytechs.utils.collection.IOIterator

hasNext, next, remove

Methods inherited from interface java.io.Closeable

close

Method Detail

getQueueDrops

long getQueueDrops()
                   throws java.io.IOException

Retrieves the current value of the "queue drop" counter. The counter maintains the number of packets that this particular iterator was not able to received due to its internall packet receive queue was full. The queue becomes full when the user of the iterator is not able to quickly enough draw queued packets to make room for new packets to be received by the iterator. Other iterator's queues are independent of this iterator queue and may hold a different state.

Returns:

number of packets dropped due to no more room on the queue

Throws:

java.io.IOException - any IO errors

interruptNext

void interruptNext()

Politely interrupts the next() call. This method is atomic and safe to call from any thread. next will gracefully exit while its waiting for a packet to arrive. The value returned from the interrupted next() will be null so if the user expects to use this interrupt method at any time, it should check all return values from next() for null reference.

Although the current next command may be interrupted, the LiveCapture session may continue capturing packets which will be queued up on this iterator. Any subsequent call to next after the interruption, will likely return the packet that it was waiting for originally.