org.jnetstream.capture
Enum FileMode

java.lang.Object
  java.lang.Enum<FileMode>
      org.jnetstream.capture.FileMode

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<FileMode>

public enum FileMode
extends java.lang.Enum<FileMode>

Defines a file mode for either open or new files created. The file mode is only usable with file captures and no other type. There are a number of file modes available with some default behaviours defined under each mode constant. Typical usage is as follows:

 FileCapture capture;
 capture = Captures.openFile(new File("temp.pcap"), FileMode.ReadOnly);
 capture.close();
 

or

 FileCapture capture;
 capture = Captures.newFile(new File(FormatType.Pcap, "temp.pcap", FileMode.ReadWrite);
 capture.close();
 

For convenience both of these modes are available with no FileMode version of each of the above 2 methods Captures.openFile(java.io.File) and org.jnetstream.capture.Captures#newFile(FormatType, java.io.File) and other variations. You can of course specify any of the constants defined below in order to open the file in another mode.

Another important feature of the FileMode selection is the associated memory model with the file mode. The critical aspect is the usage of memory mapped files. All modern operating systems provide a very efficient means of accessing contents of a file by mapping its contents directly to memory. This is typically done in hardware by a memory controller, which provides the contents of a file as if they were normal RAM memory. This is a very low level function that is typically much more efficient then tranditional read data into a user provided buffer. Some of the constants below provide different options of when to use the map function of the kernel.

Warning about mapped files

There is a known caviat with using any of the modes that map file contents directly to memory using an OS call "map". Sun Microsystems has an outstanding bug (Sun Bug ID# 4724038) which prevents files from being truncated, renamed or deleted after a map function has been used on a file. The bug more specifically, does not allow a previously mapped file to be unmapped which keeps the file handle open in the OS and file contents locked, even after a close call in java. It may take some time for the file contents to become unmapped and until then, the above mentioned file operations will fail. Therefore the default readonly mode, assumes that since the file is being opened in readonly mode by the user, that no immediate file modifications will take place upon the file. Eventually though, the file will be cleared of any mappings and the file operations will succeed. The amount of time needed for this to happen is undefined, even when all references to any mapped file buffers are released by the user, i.e. references through packets or records, directly to buffers as returned by {org.jnetstream.packet.Packet#getBuffer()} call. Therefore the user is advised to choose a different readonly mode that explicitely does not use file mapping function if some kind of file manipulation will be required relatively soon after the FileCapture is to be closed. No file manipulation is possible when file capture is open wheather mapped or not.

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Enum Constant Summary

Append
File is opened for general read and write operations, which have portions of the file memory mapped and with the limitation that only structural change peration that is permitted is append or add at the end of the file.

AppendNoMap
File is opened for general read and no write operations and only structural change peration that is permitted is append or add at the end of the file.

ReadOnly
File and file editor is opened in read only mode.

ReadOnlyNoMap
File and file editor is opened in read only mode without using memory map OS function.

ReadWrite
The file is opened in read-write mode and no memory map functions are utilized.

ReadWriteWithMap
File is opened for read and write operations while utilizing the very efficient file memory mapping feature, but no operations which result in structural changes such as add, remove, swap, retain, etc.

Method Summary

boolean	isAppend() Checks if append structural operation is permitted.
boolean	isContent() Checks if the file content is allowed to be modified, non structuraly.
boolean	isMap() Checks if capture file is memory mapped for efficiency purposes.
boolean	isStructure() Determines if record structure can be modified.
static FileMode	valueOf(java.lang.String name) Returns the enum constant of this type with the specified name.
static FileMode[]	values() Returns an array containing the constants of this enum type, in the order they're declared.

Methods inherited from class java.lang.Enum

clone, compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Enum Constant Detail

ReadOnly

public static final FileMode ReadOnly

File and file editor is opened in read only mode. All mutable operations are disabled and the buffer operated on and returned to the user is read only as well.

In readonly mode, file contents are fetched using 3 different algorithms:

• Into a byte[] backed ByteBuffer - for small file sizes, around a few kilo bytes, a simple byte array backed ByteBuffer is created. The data is read into the buffer. The buffer is cached and returned as readonly and no further modifications are possible.
• Into a direct ByteBuffer - for larger files, upto 10 mega bytes, a direct byte buffer is created which is slower to instantiate but provides native level access speed to its contents. The OS is instructed to read the file contents into the direct buffer which is all done outside of java space at native speeds.
• File content is mapped to memory - for even larger files, larger then 10 mega bytes, the file is mapped to memory using a kernel call "map". The mapping itself is much slower then allocating the memory in the above 2 steps, but once the file is mapped access to it is increadibly fast. So this is the reason why mapping the file only makes sense for very large files. It may not be possible to map the entire file to memory all at once, and the file is mapped in large chunks. Each mapped buffer is cached and returned readonly to the user.

Each of these algorithms is applied accrodingly to each request for a portion of a file. That is if only 100 bytes were left to be read in at the end of a multi-giga byte file, the byte[] algorithm would be chosen to read in those bytes, instead of memory mapping them.

Warning about mapped files

There is a known caviat with this mode. Sun Microsystems has an outstanding bug (Sun Bug ID# 4724038) which prevents files from being truncated, renamed or deleted after a map function has been used on a file. The bug more specifically, does not allow a previously mapped file to be unmapped which keeps the file handle open in the OS and file contents locked, even after a close call in java. It may take some time for the file contents to become unmapped and until then, the above mentioned file operations will fail. Therefore the default readonly mode, assumes that since the file is being opened in readonly mode by the user, that no immediate file modifications will take place upon the file. Eventually though, the file will be cleared of any mappings and the file operations will succeed. The amount of time needed for this to happen is undefined, even when all references to any mapped file buffers are released by the user, i.e. references through packets or records, directly to buffers as returned by {org.jnetstream.packet.Packet#getBuffer()} call. Therefore the user is advised to choose another mode that explicitely does not use file mapping function if some kind of file manipulation will be required relatively soon after the FileCapture is to be closed. No file manipulation is possible when file capture is open wheather mapped or not.

ReadOnlyNoMap

public static final FileMode ReadOnlyNoMap

File and file editor is opened in read only mode without using memory map OS function. All mutable operations are disabled and the buffer operated on and returned to the user is read only as well. In this mode the file mapping to memory OS function is not used and this mode does not suffer any of the file locking or manipulation issues described in the main description.

In readonly mode, file contents are fetched using 2 different algorithms:

• Into a byte[] backed ByteBuffer - for small file sizes, around a few kilo bytes, a simple byte array backed ByteBuffer is created. The data is read into the buffer. The buffer is cached and returned as readonly and no further modifications are possible.
• Into a direct ByteBuffer - for larger files, upto any size, a direct byte buffer is created which is slower to instantiate but provides native level access speed to its contents. The OS is instructed to read the file contents into the direct buffer which is all done outside of java space at native speeds.

Each of these algorithms is applied accrodingly to each request for a portion of a file. That is if only 100 bytes were left to be read in at the end of a multi-giga byte file, the byte[] algorithm would be chosen to read in those bytes, instead of allocating a direct buffer for them.

ReadWrite

public static final FileMode ReadWrite

The file is opened in read-write mode and no memory map functions are utilized. All mutable operations are allowed in this mode. All changes have to be flushed by a call to flush(), close() or flushed automatically by the autoflush mechanism. No memory map functions are used to map file contents to memory for direct manipulation in this default mode. Therefore this mode does not suffer any of the file manipulation issues as described in the description.

In read-write mode, file contents are fetched using 2 different algorithms:

• Into a byte[] backed ByteBuffer - for small file sizes, around a few kilo bytes, a simple byte array backed ByteBuffer is created. The data is read into the buffer.
• Into a direct ByteBuffer - for larger files, upto any size, a direct byte buffer is created which is slower to instantiate but provides native level access speed to its contents. The OS is instructed to read the file contents into the direct buffer which is all done outside of java space at native speeds.

On the initial read, the buffer is returned by the API as readonly. An immediate call to getBuffer on any of the returned packets or records the buffer returned there, are readonly. The first call to any of the mutable methods in the API with autoedit enabled will convert the buffer to read-write and mark the buffer as dirty so that it may eventually be sunchronized with the physical file using a flush or a close call. You may also use the org.jnetstream.packet.Packet#edit() or jnetstrea.capture.file.Record#edit() calls to manually put the buffer in read-write mode.

Note that in this mode, any changes that have been made to any of the records or file structure (i.e. removed records or packets, insert packets, etc..) can be undone if they have not been flushed yet. Since with autoflush enabled it may not be possible to determine or prevent edits from being flushed unexpectidely, you may need to set the autoflush mode with org.jnetstream.capture.FileCapture#setAutoflush method to false. This will require the user to manually call flush every so often, since all the changes are kept in memory and eventually the system may run out of memory.

ReadWriteWithMap

public static final FileMode ReadWriteWithMap

File is opened for read and write operations while utilizing the very efficient file memory mapping feature, but no operations which result in structural changes such as add, remove, swap, retain, etc. Any change that does not result in structural change is allowed. The limitation comes from the fact that once a structural change has been made to the record within the capture file it may be neccessary to perform a function on the physical file which is not allowed when used with file memory mapping. Please read section in the main description about the map limitation.

Append

public static final FileMode Append

File is opened for general read and write operations, which have portions of the file memory mapped and with the limitation that only structural change peration that is permitted is append or add at the end of the file. Operations such as remove, retain, swap or replace are not allowed. The buffers returned are read write and allow to be modified. Any modifications to buffer is synchronized with the file immediately and no flush is required. A flush is required when data has been appended to the file. Initialy those changes are kept in memory but will be synched with the physical file by a flush or close operation.

Since portions of the file are memory mapped, it may not be possible to do certain operations on the main file, even after the FileCapture has been closed. Please read the section in the main description about the map limitation.

AppendNoMap

public static final FileMode AppendNoMap

File is opened for general read and no write operations and only structural change peration that is permitted is append or add at the end of the file. Operations such as remove, retain, swap or replace are not allowed. The buffers returned are readonly and are not allowed to be modified. A flush is required when data has been appended to the file. Initialy those changes are kept in memory but will be synched with the physical file by a flush, close operation or autoflush if enabled.

Method Detail

values

public static final FileMode[] values()

Returns an array containing the constants of this enum type, in the order they're declared. This method may be used to iterate over the constants as follows:

for(FileMode c : FileMode.values())
        System.out.println(c);

Returns:

an array containing the constants of this enum type, in the order they're declared

valueOf

public static FileMode valueOf(java.lang.String name)

Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

java.lang.IllegalArgumentException - if this enum type has no constant with the specified name

isAppend

public final boolean isAppend()

Checks if append structural operation is permitted. Append operation is an add operation that is done at the end of the file. No other operation, qualifies as an append operation.

Returns:

true means that append operation is permitted, otherwise false

isContent

public final boolean isContent()

Checks if the file content is allowed to be modified, non structuraly. The content may be modified as long as the record's structure remains the same length.

Returns:

true means the content can be modified otherwise false

isMap

public final boolean isMap()

Checks if capture file is memory mapped for efficiency purposes. This flag in conjuction with the flag isContent() determines if the memory map will be READ_ONLY or READ_WRITE. If content is not modifiable the memory map will be READ_ONLY resulting in READ_ONLY ByteBuffers.

Returns:

true means that file contents will be memory mapped otherwise memory map function will never be used

isStructure

public final boolean isStructure()

Determines if record structure can be modified. Record structure is modified by methods such as add, remove, retain, swap or replace.

Returns:

if true, any of the structure modification operations are permitted, otherwise false