org.jnetstream.capture
Interface FastIterator

All Superinterfaces:

com.slytechs.utils.collection.IOIterator<com.slytechs.utils.memory.PartialBuffer>, com.slytechs.utils.collection.IORemovable, java.lang.Iterable<com.slytechs.utils.memory.PartialBuffer>

public interface FastIterator
extends com.slytechs.utils.collection.IOIterator<com.slytechs.utils.memory.PartialBuffer>, java.lang.Iterable<com.slytechs.utils.memory.PartialBuffer>

Special iterator that allows very low level iteration over large buffers of aquired packet data. The buffers are encapsulated is a special PartialBuffer. The partial buffer allows portions of a file or segment of a file to be loaded based upon certain variables. The FastIterator hides the complexity of actual implementation of a capture file representation, the editor that allows mutable operations on the file, the buffering, caching and many other details. The user works with the FastIterator and PartialBuffer objects which deliver large portions of the underlying file per iteration and allows the user access underlying file data.

To understand how to use the FastIterator, the user must first understand a little bit about the back end representation of the underlying file or capture. The file is management and maintained through a FileEditor. The FileEditor provides means of making low level modifications to the file. The FileEditor maintains a list of segments that make up the file. Initialially the entire file is a single semgment, no matter what it size is. As the user makes edits to the file, the file is segmented with certain segments pointing at the contents still residing on a phycial disk, while other segments point buffers in memory. Therefore accessing the contents of the file requires iteration through the list of segments, which can be of arbitrary size, even too great to fit into physical memory, and then iterating through one or more, a series of ParticalBuffer objects. The partial buffer represents data from the underlying editor in memory. The PartialBuffer may be refering to a cached buffer, an in memory buffer created after a user edit operation on the underlying file, or newly created buffer that fetched certain amount of data from file into memory.

The FastIterator is special in the sense that you will utilize 2 loops, outter and inner to iterate over all of the contents of the file or more precicely over FileEditor contents some of which may be fetched from the underlying file and some other from edit buffers already in memory. The first outter loop traverses all of the segments of the file and fetches PartialBuffer objects in its Iterator#Next method. The outter loop takes care of the details of fetching new buffers and moving from segment to segment seemlessly and behind the scenes. The second loop is a low level scan of the actual data buffer. The buffer is not adavanced from record to record as is the case with RawIterator and others, but operation is left up to the user. So the user has to scan the partial buffer herself/himself and advance from record to record. In addition the user has determine if the inner loop scan has reached the end or edge of the PartialBuffer and break out of the inner loop and allow the outter loop to fetch the next PartialBuffer and/or segment.

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	getBufferPosition() Gets the partial position of the current or last PartialBuffer that was returned or the current iterator is pointing at.
long	getGlobalPosition() Gets the global position within the underlying capture.
HeaderReader	getHeaderReader() A utility class that reads the the various record headers of this current file format.
long	getRegionalPosition() Gets the regional position of the current or last segment that was used to fetch the PartialBuffer.
void	incGlobalPosition(int delta) Advanced the global position of the iterator by delta bytes.
void	seekFirst() Positions the iterator at the start of the first record which usually a block record (a file header).
void	seekSecond() Positions the iterator at the start of the second record which skips over the first block record (file header).

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

hasNext, next, remove

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

seekFirst

void seekFirst()

Positions the iterator at the start of the first record which usually a block record (a file header). The second record is where the packet data starts.

seekSecond

void seekSecond()

Positions the iterator at the start of the second record which skips over the first block record (file header). The second record is the first packet data record in most file formats.

incGlobalPosition

void incGlobalPosition(int delta)

Advanced the global position of the iterator by delta bytes.

Parameters:

delta - number of bytes to advance the global position of this iterator

getHeaderReader

HeaderReader getHeaderReader()

A utility class that reads the the various record headers of this current file format.

Returns:

a read that can read certain fields of each record header

getGlobalPosition

long getGlobalPosition()

Gets the global position within the underlying capture. The method explicitly is named "global" to differentiate the fact that at low level, jNetStream utilizes 3 levels of addressing (global, regional and buffer local). Global address or position are relative to the start of the file at position 0 and end of the file which is equal to the length of the file. The regional addresses are relative to each segment when the file has been segmented. Buffer local addresses are relative to the start and end of the PartialBuffer which represents a portion of a segment.

Returns:

current position in bytes of the iterator in the global address space

getRegionalPosition

long getRegionalPosition()

Gets the regional position of the current or last segment that was used to fetch the PartialBuffer.

Returns:

current position in bytes of the iterator in the regional address space of the current segment

getBufferPosition

long getBufferPosition()

Gets the partial position of the current or last PartialBuffer that was returned or the current iterator is pointing at.

Returns:

current position in byte of the iterator in the local address space of the current PartialBuffer