org.jnetstream.capture.file
Interface RawIndexer

All Superinterfaces:

java.io.Closeable, FileIndexer<java.nio.ByteBuffer,java.nio.ByteBuffer,java.lang.Long>, java.io.Flushable, IndexedFileModifier<java.nio.ByteBuffer,java.lang.Long>, java.lang.Iterable<java.nio.ByteBuffer>

public interface RawIndexer
extends FileIndexer<java.nio.ByteBuffer,java.nio.ByteBuffer,java.lang.Long>

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.

Method Summary

void	add(long index, java.nio.ByteBuffer buffer, boolean copy) Adds a new record at the current indexed position.
void	add(long index, java.nio.ByteBuffer b1, java.nio.ByteBuffer b2) Adds a new record using two buffers.
void	replace(long index, java.nio.ByteBuffer buffer, boolean copy) Replaces the record at indexed position with the new record found in the buffer.
void	replaceInPlace(long index) Replaces the indexed 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 index, long size) Changes the length of the indexed record.

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

get, keepInMemory, mapIndexToPosition, setAutoflush, size

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

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

Methods inherited from interface java.io.Closeable

close

Methods inherited from interface java.io.Flushable

flush

Methods inherited from interface java.lang.Iterable

iterator

Method Detail

resize

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

Changes the length of the indexed 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(long index,
         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 #add(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(long index,
         java.nio.ByteBuffer buffer,
         boolean copy)
         throws java.io.IOException

Adds a new record at the current indexed 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(long index,
             java.nio.ByteBuffer buffer,
             boolean copy)
             throws java.io.IOException

Replaces the record at indexed 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(long index)
                    throws java.io.IOException

Replaces the indexed 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