org.jnetstream.capture
Interface Capture<T extends CapturePacket>

All Superinterfaces:

java.io.Closeable, java.lang.Iterable<T>

All Known Subinterfaces:

FileCapture<T>, InputCapture<T>, LiveCapture, NapFile, NapInput, NapOutput, OutputCapture, PcapFile, PcapInput, PcapOutput, SnoopFile, SnoopInput, SnoopOutput

public interface Capture<T extends CapturePacket>
extends java.io.Closeable, java.lang.Iterable<T>

Main capture session interface. The Capture interface provides general services to any open and active sessions which aquire network packets from either a live network interface, a file, a memory based collection or from remote system over the network.

Capture is Iterable which means that it can be placed in a tight foreach loop. Care must be taken when the iterator functionality is used as aquiring packets usually means that some kind of back-end IO operation had to take place which can throw an IO exception at any time. The standard Iterator interface does not provide a way of throwing an IO exception therefore the Iterator will relay any IO exceptions as a runtime exception. Runtime exception is one that does not have to have a specified throws statement in its signature, but can throw an exception anyhow. The iterator specifically, will throw a IORuntimeException which will relay the original IO exception which caused an error. Care must be taken that even though this iterator can be passed to other non IO exception aware methods, that a runtime IO exception can occure at any time and cause the method and iterator to abort.

 
 FileCapture capture = Captures.openFile(new File("capture.pcap"));
 for (FilePacket packet : capture) {
        System.out.println(packet.toString());
 }
 
 

In addition to the convenient Iterator interface, a specialized IOIterator interface is also provided which mimics its java.util.Iterator counter part and provides exact same methods with exactly the same meanings, with the exception that IOIterator.hasNext() and IOIterator.next() methods also throw IO exception immediately. The IOIterator can not be used in the foreach loop as its not a the standard java.util.Iterator.

        
        FileCapture capture = Captures.openFile(new File("capture.pcap"));
        FileIterator i = capture.getFileIterator(); while (i.hasNext()) { // May
        throw IO exception FilePacket packet = i.next(); // May throw IO exception
        System.out.println(packet.toString()); }
        
 

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Method Summary

Filter<ProtocolFilterTarget>	getFilter() Gets the currently active filter set on this capture session.
com.slytechs.utils.collection.IOSkippableIterator<T>	getPacketIterator() Retrieves an iterator Iterator which can iterate over all the packets of this capture session.
CaptureType	getType() Returns the type of file capture this is.
boolean	isMutable() Tells if this capture session is mutable.
java.util.Iterator<T>	iterator() Creates a standard java iterator which will iterate over all packets within the current capture session.

Methods inherited from interface java.io.Closeable

close

Method Detail

getFilter

Filter<ProtocolFilterTarget> getFilter()

Gets the currently active filter set on this capture session. Filters allow efficient way of filtering, or rejecting certain packets while allowing the rest that match the filter criteria to be returned. Filters are usually very efficient at rejecting packets at the source of the packets such as right at the live network interface where typically the kernel accepts or rejects the incomming packets without any copying of packet data. For files filters again are used to efficiently map portions of the capture files so that packets in the file can be accepted or rejected as efficiently as possible, usually with just the single kernel level copies into its buffers.

Returns:

currently active filter

getPacketIterator

com.slytechs.utils.collection.IOSkippableIterator<T> getPacketIterator()
                                                                                             throws java.io.IOException

Retrieves an iterator Iterator which can iterate over all the packets of this capture session. The IO based iterator mimics the methods and behaviour of its counter part Iterator that it can throw IO exceptions in any of the methods.

Returns:

Iterator capable of throwing IO exceptions

Throws:

java.io.IOException - Any IO errors while retrieving a packet

getType

CaptureType getType()

Returns the type of file capture this is. The type can be exactly specified including the exact file format type.

Returns:

type of capture

isMutable

boolean isMutable()

Tells if this capture session is mutable. Typically file based and pure memory based capture sessions are mutable, meaning the capture sessions content can be modified. LiveCaptures and read-only file based capture sessions are types of captures that are non-mutable and this method will return false.

Returns:

true means this session is mutable, otherwise false

iterator

java.util.Iterator<T> iterator()

Creates a standard java iterator which will iterate over all packets within the current capture session. Since all operations behind this iterator actually use IO operations to aquire data, an IO exception may be thrown at anytime. The IO exception is relayed using a special com.slytechs.utils.io.IORuntimeException runtime exception. This may cause the iterator from being created or returned. Runtime exceptions do not have to be declared in the methods signature to be thrown, and to conform to java's standard interface Iterable this iterator getter does not declare one, but IORuntimeException might be thrown and must be caught when aquiring the iterator and later around the usage of the iterator returned.

The iterator's remove method is optional method and is only available on capture session's who's isMutable() method returns boolean. If you try to invoke the Iterator.remove() method on a non mutable capture session, and UnsupportedOperationException will be thrown to indicate that this is a non mutable capture session. I.e. LiveCaptures or read-only capture files are types of non mutable capture sessions.

Specified by:

iterator in interface java.lang.Iterable<T extends CapturePacket>

Returns:

packet iterator that will iterate over all packet within the capture session.