org.jnetstream.capture.file
Interface FileIndexer<G,S,R>

All Superinterfaces:

java.io.Closeable, java.io.Flushable, IndexedFileModifier<S,R>, java.lang.Iterable<G>

All Known Subinterfaces:

PacketIndexer<I>, RawIndexer, RecordIndexer<T>

public interface FileIndexer<G,S,R>
extends IndexedFileModifier<S,R>, java.io.Closeable, java.io.Flushable, java.lang.Iterable<G>

Provides indexing services to file based captures. Any file, or more generally finate and immediately determinate capture session can be indexed, in some cases very efficiently and in other not so efficiently. Indexed capture sessions allow the user to access packets as if they were simple lists, hiding all the complexity of actually achieving this kind of a view on a packet dataset behind the capture session.

The indexer is a class that turns an ordinary file capture into a similar entity that a Collections list is. All the standard List methods are implemented by the counter part interface IOList that mimics the behaviour and functionality of the regular list with the addtional restriction that each method can throw an IOException at anytime since the actuall capture session data set is backed by IO operations. Due to the fact that capture files can be of increadible size, the implementation algorithm only caches and keeps in memory only portions of the overall packet dataset. Previously cached information may be discarded at any time and when accessed again at a later time may have to be reaquired using various IO operations, at which time there is a risk that an IOException may occur once more.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Method Summary

G	get(long index) Main getter method for accessing elements from this indexer.
java.lang.Object	keepInMemory(long start, long length) With this method, you can ensure that any portion of the index table are always kept in memory.
long	mapIndexToPosition(long index) Maps an index to a global position within the capture session.
void	setAutoflush(boolean state) Enables or disables the autoflush (enabled by default).
long	size() Number of elements currently present.

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

setAutoflush

void setAutoflush(boolean state)
                  throws java.io.IOException

Enables or disables the autoflush (enabled by default). Autoflush allows modifications to a capture file to be flushed to physical storage. With autoflush disabled, all changes made are kept in memory and the user is responsible for invoking flush() method manually. A close() operation always does a flush before closing the connection to the underlying physical storage.

Parameters:

state - true sets autoflush to enabled and false disables it

Throws:

java.io.IOException - any IO errors as a result of the state change

get

G get(long index)
      throws java.io.IOException

Main getter method for accessing elements from this indexer. The element type returned is specific to the indexer implementing this interface.

Parameters:

index - index position of the element to get

Returns:

the element at the specified index position

Throws:

java.io.IOException - any IO errors

java.lang.IndexOutOfBoundsException - if index is greater then the amount of records and indexes

size

long size()
          throws java.io.IOException

Number of elements currently present. This is not a static value as it will change depending on various properties. If the capture file is not in FileMode.ReadOnly and it is being actively modified, the size returned will reflect the latest state of the capture sesssion. Also if a file has been applied or changed this number will change accordingly as well.

Returns:

number of elements currently in the indexer

Throws:

java.io.IOException - any IO errors

mapIndexToPosition

long mapIndexToPosition(long index)
                        throws java.io.IOException

Maps an index to a global position within the capture session.

Parameters:

index - index of the record to map to

Returns:

global position of the record at the specified index

Throws:

java.io.IOException - any IO errors

keepInMemory

java.lang.Object keepInMemory(long start,
                              long length)
                              throws java.io.IOException

With this method, you can ensure that any portion of the index table are always kept in memory. The opaque Object returned is a handle that ensures that the indexes are kept in memory and not reclaimed by java's garbage collector when memory runs low. As long as the user holds a hard reference to the returned object, the indexes will be kept in memory. To release the index references to be possibly garbage collected, the user has to release any hard references to the object.

Parameters:

start - starting index number of of the block of indexes to be retained in memory

length - number of consecutive indexes to retain in memory, starting with the "start" index

Returns:

an opaque handle which allows prevents requested indexes from being reclaimed by java's garbage collector

Throws:

java.io.IOException - any IO errors if indexes had to be reaquired by rescanning the file