org.jnetstream.capture.file
Interface RawIterator

All Superinterfaces:

java.io.Closeable, FileIterator<java.nio.ByteBuffer,java.nio.ByteBuffer,java.lang.Long>, FileModifier<java.nio.ByteBuffer,java.lang.Long>, java.io.Flushable, com.slytechs.utils.collection.IOAddable<java.nio.ByteBuffer>, com.slytechs.utils.collection.IOIterator<java.nio.ByteBuffer>, com.slytechs.utils.collection.IOPositional, com.slytechs.utils.collection.IORemovable, com.slytechs.utils.collection.IOSeekable<java.nio.ByteBuffer>, com.slytechs.utils.collection.IOSeekableFirstLast, com.slytechs.utils.collection.IOSkippable, com.slytechs.utils.collection.IOSkippableIterator<java.nio.ByteBuffer>, java.lang.Iterable<java.nio.ByteBuffer>

public interface RawIterator
extends FileIterator<java.nio.ByteBuffer,java.nio.ByteBuffer,java.lang.Long>, java.lang.Iterable<java.nio.ByteBuffer>

An iterator that allows iteration over elements contained in a capture file. Simple IOIterator.next() and IOIterator.hasNext() methods are used to iterate over a long sequence of element which reside physically on a some storage device. Elements which are typically records, are efficiently accessed and returned as shared ByteBuffers who's position and limit properties are set to enclose the contents of the record within some shared buffer.

The data returned by next, is a shared buffer, not a view of the buffer but shared instance as returned by the next call. It is important to note that any consecutive call to next overrides the position and limit properties of the shared buffer that is returned in both instances. Therefore it is upto the user to either save that information or create a view of the buffer using ByteBuffer.slice() method. RawIterator purposely does not return such views and leaves that upto the user to do. This way views are created only when truely required where persistance is needed. This optimization affords increadible performance when using a RawIterator. The author has measured 6,000,000 packet per second iteration speeds over very large capture files. Pefromance goes considerably down even when a single buffer view or any other object instance is created within critical sections of the iterator's code. The implementation goes to great lengths not to initiate even a single object when working with the IOSkippableIterator methods next and skip. These methods are optimized for maximum speed possible. Lastly note that skip is even more efficient then next at skipping over records. Skip's implementation is able to omit certain amount of logic in order to skip accross records even faster then next can.

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

void	add(java.nio.ByteBuffer buffer, boolean copy) Adds a new record at the current cursor position.
void	add(java.nio.ByteBuffer b1, java.nio.ByteBuffer b2) Adds a new record using two buffers.
Filter	getFilter()
void	replace(java.nio.ByteBuffer buffer, boolean copy) Replaces the record at current cursor position with the new record found in the buffer.
void	replaceInPlace() Replaces the current record with its own contents and causes the original region to become invalid and replaced by new in-memory cache buffer which contains the same content.
void	resize(long size) Changes the length of the current record.
com.slytechs.utils.collection.SeekResult	seek(Filter<RecordFilterTarget> filter) Seek the first record from the current position that will match the supplied filter.
com.slytechs.utils.collection.SeekResult	seekSecond()
com.slytechs.utils.collection.SeekResult	seekToIndex(long recordIndex) Seeks to a record by its zero-based index as counted from the first record.
RecordError[]	skipOverErrors() Skips over a packet record and ignores errors if any.

Methods inherited from interface org.jnetstream.capture.file.FileIterator

seek, setAutoflush

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

seekEnd, seekFirst, seekLast

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 org.jnetstream.capture.file.FileModifier

abortChanges, add, addAll, addAll, remove, removeAll, removeAll, removeAll, removeAll, replace, retainAll, retainAll, swap

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

seek, seek

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

getPosition, setPosition, setPosition

Methods inherited from interface java.io.Flushable

flush

Methods inherited from interface java.io.Closeable

close

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

seekToIndex

com.slytechs.utils.collection.SeekResult seekToIndex(long recordIndex)
                                                     throws java.io.IOException

Seeks to a record by its zero-based index as counted from the first record. Efficiency of this method is currently not strictly defined and is implementation dependent.

Parameters:

recordIndex - zero-based index of the record to seek to

Returns:

result of the seek

Throws:

java.io.IOException - any IO errors

seek

com.slytechs.utils.collection.SeekResult seek(Filter<RecordFilterTarget> filter)
                                              throws java.io.IOException

Seek the first record from the current position that will match the supplied filter.

Parameters:

filter - a record filter to used in record matching

Returns:

the status of the seek

Throws:

java.io.IOException - any IO errors

seekSecond

com.slytechs.utils.collection.SeekResult seekSecond()
                                                    throws java.io.IOException

Throws:

java.io.IOException

resize

void resize(long size)
            throws java.io.IOException

Changes the length of the current record. All changes to the record size are done in-memory and may be cancelled using aborthChanges() call.

Parameters:

size - new size of the record

Throws:

java.io.IOException - any IO errors

add

void add(java.nio.ByteBuffer b1,
         java.nio.ByteBuffer b2)
         throws java.io.IOException

Adds a new record using two buffers. This method is more efficient then using #addAll(ByteBuffer[]) version as the two buffers are received as normal parameters. This version of the add method is used when record's header and content reside in two separate buffers. Addition is done by copy.

Parameters:

b1 - first buffer containing the record's header

b2 - second buffer containing the record's content

Throws:

java.io.IOException - any IO errors

add

void add(java.nio.ByteBuffer buffer,
         boolean copy)
         throws java.io.IOException

Adds a new record at the current cursor position. The record's header and content are to be found within the buffer bounded by ByteBuffer's properties position and limit. The additional boolean flag indicates if the buffer's content should be copied into private buffer or if the record's in-memory representation should be presented as the user supplied buffer. If copy is false, any changes made to the record will be reflected in the user buffer and visa versa, unless the supplied buffer is readonly. If the buffer is readonly, a copy of it will be made upon first change to the buffer automatically into a read-write buffer.

Parameters:

buffer - buffer containing the record

copy - true means that record's content found in the buffer will be copied into a private read-write buffer

Throws:

java.io.IOException - any IO errors

replace

void replace(java.nio.ByteBuffer buffer,
             boolean copy)
             throws java.io.IOException

Replaces the record at current cursor position with the new record found in the buffer. The record's header and content are to be found within the buffer bounded by ByteBuffer's properties position and limit. The additional boolean flag indicates if the buffer's content should be copied into private buffer or if the record's in-memory representation should be presented as the user supplied buffer. If copy is false, any changes made to the record will be reflected in the user buffer and visa versa, unless the supplied buffer is readonly. If the buffer is readonly, a copy of it will be made upon first change to the buffer automatically into a read-write buffer.

Parameters:

buffer - the buffer containing the new record

copy - true means that record's content found in the buffer will be copied into a private read-write buffer

Throws:

java.io.IOException - any IO errors

replaceInPlace

void replaceInPlace()
                    throws java.io.IOException

Replaces the current record with its own contents and causes the original region to become invalid and replaced by new in-memory cache buffer which contains the same content.

This method is primarily used by Packet and Record objects to setup the way their buffer modification are to take place. Either in-place or in the buffer they originally came from, or duplicated to in memory cache. The original content in physical storage stay unmodified while Packet and Record object make modifications to a duplicate copy of the buffer. Only a flush() forces the changes out to the physical storage. This is safer way to make changes as all the changes can be made in memory first, somewhat offline, and not be propaged to physical storage in case of crash or serious error. A flush() sends all the changes to physical storage in one step.

Throws:

java.io.IOException - any IO errors

skipOverErrors

RecordError[] skipOverErrors()
                             throws java.io.IOException

Skips over a packet record and ignores errors if any. If a record contains an error in the header, the skip operations performs a positional packet seek to search out the next valid record header starting at the current position (which has the corrupted record.) Otherwise it behaves exactly the same as IOSkippable.skip().

Returns:

TODO

Throws:

java.io.IOException

getFilter

Filter getFilter()

Returns: