MappedFileBuffer (KDG Commons 1.0.17 API)

java.lang.Object
- net.sf.kdgcommons.buffer.MappedFileBuffer

All Implemented Interfaces:

Cloneable, BufferFacade
```
public class MappedFileBuffer
extends Object
implements BufferFacade, Cloneable
```
A wrapper for memory-mapped files that generally preserves the semantics of ByteBuffer, while supporing files larger than 2 GB. Unlike normal byte buffers, all access via absolute index, and indexes are long values.
This is achieved using a set of overlapping buffers, based on the "segment size" passed during construction. Segment size is the largest contiguous sub-buffer that may be accessed (via getBytes(long, int) and putBytes(long, byte[])), and may be no larger than 1 GB.
Warning: This class is not thread-safe. Caller must explicitly synchronize access, or call clone() to create a distinct buffer for each thread.

Constructor Summary

Constructors
Constructor and Description
`MappedFileBuffer(File file)` Opens and memory-maps the specified file for read-only access, using the maximum segment size.
`MappedFileBuffer(File file, boolean readWrite)` Opens and memory-maps the specified file for read-only or read-write access, using the maximum segment size.
`MappedFileBuffer(File file, int segmentSize, boolean readWrite)` Opens and memory-maps the specified file, for read-only or read-write access, with a specified segment size.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected ByteBuffer`	`buffer(long index)`
`long`	`capacity()` Returns the buffer's capacity -- the size of the mapped file.
`MappedFileBuffer`	`clone()` Creates a new buffer referencing the same file, but with a copy of the original underlying mappings.
`File`	`file()` Returns the file that is mapped by this buffer.
`void`	`force()` Iterates through the underlying buffers, calling `force()` on each; this will cause the buffers' contents to be written to disk.
`byte`	`get(long index)` Retrieves a single byte from the specified index.
`ByteOrder`	`getByteOrder()` Returns the byte-order of this buffer (actually, the order of the first child buffer; they should all be the same).
`byte[]`	`getBytes(long index, byte[] array, int off, int len)` Retrieves `len` bytes starting at the specified index, storing them in an existing `byte[]` at the specified offset.
`byte[]`	`getBytes(long index, int len)` Retrieves `len` bytes starting at the specified index, storing them in a newly created `byte[]`.
`char`	`getChar(long index)` Retrieves a two-byte character starting at the specified index (note that a Unicode code point may require calling this method twice).
`double`	`getDouble(long index)` Retrieves an eight-byte floating-point number starting at the specified index.
`float`	`getFloat(long index)` Retrieves a four-byte floating-point number starting at the specified index.
`int`	`getInt(long index)` Retrieves a four-byte integer starting at the specified index.
`long`	`getLong(long index)` Retrieves an eight-byte integer starting at the specified index.
`short`	`getShort(long index)` Retrieves a four-byte integer starting at the specified index.
`boolean`	`isWritable()` Indicates whether this buffer is read-write or read-only.
`long`	`limit()` Returns the buffer's limit -- the maximum index in the buffer + 1.
`void`	`put(long index, byte value)` Stores a single byte at the specified index.
`void`	`putBytes(long index, byte[] value)` Stores the contents of the passed byte array, starting at the given index.
`void`	`putBytes(long index, byte[] value, int off, int len)` Stores a section of the passed byte array, defined by `off` and `len`, starting at the given index.
`void`	`putChar(long index, char value)` Stores a two-byte character starting at the specified index.
`void`	`putDouble(long index, double value)` Stores an eight-byte floating-point number starting at the specified index.
`void`	`putFloat(long index, float value)` Stores a four-byte floating-point number starting at the specified index.
`void`	`putInt(long index, int value)` Stores a four-byte integer starting at the specified index.
`void`	`putLong(long index, long value)` Stores an eight-byte integer starting at the specified index.
`void`	`putShort(long index, short value)` Stores a four-byte integer starting at the specified index.
`void`	`setByteOrder(ByteOrder order)` Sets the order of this buffer (propagated to all child buffers).
`ByteBuffer`	`slice(long index)` Creates a new buffer, whose size will be >= segment size, starting at the specified offset.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MappedFileBuffer
```
public MappedFileBuffer(File file)
                 throws IOException
```
    Opens and memory-maps the specified file for read-only access, using the maximum segment size.
    
    Parameters:
    
    file - The file to open; must be accessible to user.
    
    Throws:
    
    IllegalArgumentException - if segmentSize is > 1GB.
    
    IOException
  - MappedFileBuffer
```
public MappedFileBuffer(File file,
                        boolean readWrite)
                 throws IOException
```
    Opens and memory-maps the specified file for read-only or read-write access, using the maximum segment size.
    
    Parameters:
    
    file - The file to open; must be accessible to user.
    
    readWrite - Pass true to open the file with read-write access, false to open with read-only access.
    
    Throws:
    
    IllegalArgumentException - if segmentSize is > 1GB.
    
    IOException
  - MappedFileBuffer
```
public MappedFileBuffer(File file,
                        int segmentSize,
                        boolean readWrite)
                 throws IOException
```
    Opens and memory-maps the specified file, for read-only or read-write access, with a specified segment size.
    
    Parameters:
    
    file - The file to open; must be accessible to user.
    
    segmentSize - The largest contiguous sub-buffer that can be created using slice(long). The maximum size is 2^30 - 1.
    
    readWrite - Pass true to open the file with read-write access, false to open with read-only access.
    
    Throws:
    
    IllegalArgumentException - if segmentSize is > 1GB.
    
    IOException
- Method Detail
  - capacity
```
public long capacity()
```
    Returns the buffer's capacity -- the size of the mapped file.
    
    Specified by:
    
    capacity in interface BufferFacade
  - limit
```
public long limit()
```
    Returns the buffer's limit -- the maximum index in the buffer + 1.
    This returns the same value as capacity(); it exists as part of the BufferFacade interface.
    
    Specified by:
    
    limit in interface BufferFacade
  - file
```
public File file()
```
    Returns the file that is mapped by this buffer.
  - isWritable
```
public boolean isWritable()
```
    Indicates whether this buffer is read-write or read-only.
  - getByteOrder
```
public ByteOrder getByteOrder()
```
    Returns the byte-order of this buffer (actually, the order of the first child buffer; they should all be the same).
  - setByteOrder
```
public void setByteOrder(ByteOrder order)
```
    Sets the order of this buffer (propagated to all child buffers).
  - get
```
public byte get(long index)
```
    Retrieves a single byte from the specified index.
    
    Specified by:
    
    get in interface BufferFacade
  - put
```
public void put(long index,
                byte value)
```
    Stores a single byte at the specified index.
    
    Specified by:
    
    put in interface BufferFacade
  - getInt
```
public int getInt(long index)
```
    Retrieves a four-byte integer starting at the specified index.
    
    Specified by:
    
    getInt in interface BufferFacade
  - putInt
```
public void putInt(long index,
                   int value)
```
    Stores a four-byte integer starting at the specified index.
    
    Specified by:
    
    putInt in interface BufferFacade
  - getLong
```
public long getLong(long index)
```
    Retrieves an eight-byte integer starting at the specified index.
    
    Specified by:
    
    getLong in interface BufferFacade
  - putLong
```
public void putLong(long index,
                    long value)
```
    Stores an eight-byte integer starting at the specified index.
    
    Specified by:
    
    putLong in interface BufferFacade
  - getShort
```
public short getShort(long index)
```
    Retrieves a four-byte integer starting at the specified index.
    
    Specified by:
    
    getShort in interface BufferFacade
  - putShort
```
public void putShort(long index,
                     short value)
```
    Stores a four-byte integer starting at the specified index.
    
    Specified by:
    
    putShort in interface BufferFacade
  - getFloat
```
public float getFloat(long index)
```
    Retrieves a four-byte floating-point number starting at the specified index.
    
    Specified by:
    
    getFloat in interface BufferFacade
  - putFloat
```
public void putFloat(long index,
                     float value)
```
    Stores a four-byte floating-point number starting at the specified index.
    
    Specified by:
    
    putFloat in interface BufferFacade
  - getDouble
```
public double getDouble(long index)
```
    Retrieves an eight-byte floating-point number starting at the specified index.
    
    Specified by:
    
    getDouble in interface BufferFacade
  - putDouble
```
public void putDouble(long index,
                      double value)
```
    Stores an eight-byte floating-point number starting at the specified index.
    
    Specified by:
    
    putDouble in interface BufferFacade
  - getChar
```
public char getChar(long index)
```
    Retrieves a two-byte character starting at the specified index (note that a Unicode code point may require calling this method twice).
    
    Specified by:
    
    getChar in interface BufferFacade
  - putChar
```
public void putChar(long index,
                    char value)
```
    Stores a two-byte character starting at the specified index.
    
    Specified by:
    
    putChar in interface BufferFacade
  - getBytes
```
public byte[] getBytes(long index,
                       int len)
```
    Retrieves len bytes starting at the specified index, storing them in a newly created byte[]. Will span segments if necessary to retrieve the requested number of bytes.
    
    Specified by:
    
    getBytes in interface BufferFacade
    
    Throws:
    
    IndexOutOfBoundsException - if the request would read past the end of file.
  - getBytes
```
public byte[] getBytes(long index,
                       byte[] array,
                       int off,
                       int len)
```
    Retrieves len bytes starting at the specified index, storing them in an existing byte[] at the specified offset. Returns the array as a convenience. Will span segments as needed.
    
    Throws:
    
    IndexOutOfBoundsException - if the request would read past the end of file.
  - putBytes
```
public void putBytes(long index,
                     byte[] value)
```
    Stores the contents of the passed byte array, starting at the given index. Will span segments as needed.
    
    Specified by:
    
    putBytes in interface BufferFacade
    
    Throws:
    
    IndexOutOfBoundsException - if the request would write past the end of file.
  - putBytes
```
public void putBytes(long index,
                     byte[] value,
                     int off,
                     int len)
```
    Stores a section of the passed byte array, defined by off and len, starting at the given index. Will span segments as needed.
    
    Throws:
    
    IndexOutOfBoundsException - if the request would write past the end of file.
  - slice
```
public ByteBuffer slice(long index)
```
    Creates a new buffer, whose size will be >= segment size, starting at the specified offset.
    
    Specified by:
    
    slice in interface BufferFacade
  - force
```
public void force()
```
    Iterates through the underlying buffers, calling force() on each; this will cause the buffers' contents to be written to disk. Note, however, that the OS may not physically write the buffers until a future time.
  - clone
```
public MappedFileBuffer clone()
```
    Creates a new buffer referencing the same file, but with a copy of the original underlying mappings. The new and old buffers may be accessed by different threads.
    
    Overrides:
    
    clone in class Object
  - buffer
```
protected ByteBuffer buffer(long index)
```

Class MappedFileBuffer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

MappedFileBuffer

MappedFileBuffer

MappedFileBuffer

Method Detail

capacity

limit

file

isWritable

getByteOrder

setByteOrder

get

put

getInt

putInt

getLong

putLong

getShort

putShort

getFloat

putFloat

getDouble

putDouble

getChar

putChar

getBytes

getBytes

putBytes

putBytes

slice

force

clone

buffer