MappedFileBuffer

java.lang.Object
- pt.lsts.imc.lsf.MappedFileBuffer

All Implemented Interfaces:

java.lang.Cloneable
```
public class MappedFileBuffer
extends java.lang.Object
implements java.lang.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(java.io.File file)` Opens and memory-maps the specified file for read-only access, using the maximum segment size.
`MappedFileBuffer(java.io.File file, boolean readWrite)` Opens and memory-maps the specified file for read-only or read-write access, using the maximum segment size.
`MappedFileBuffer(java.io.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
`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
`java.io.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.
`java.nio.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(java.nio.ByteOrder order)` Sets the order of this buffer (propagated to all child buffers).
`java.nio.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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - MappedFileBuffer
```
public MappedFileBuffer(java.io.File file)
                 throws java.io.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:
    
    java.lang.IllegalArgumentException - if segmentSize is > 1GB.
    
    java.io.IOException
  - MappedFileBuffer
```
public MappedFileBuffer(java.io.File file,
                        boolean readWrite)
                 throws java.io.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:
    
    java.lang.IllegalArgumentException - if segmentSize is > 1GB.
    
    java.io.IOException
  - MappedFileBuffer
```
public MappedFileBuffer(java.io.File file,
                        int segmentSize,
                        boolean readWrite)
                 throws java.io.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:
    
    java.lang.IllegalArgumentException - if segmentSize is > 1GB.
    
    java.io.IOException
- Method Detail
  - capacity
```
public long capacity()
```
    Returns the buffer's capacity -- the size of the mapped file.
  - 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.
  - file
```
public java.io.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 java.nio.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(java.nio.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.
  - put
```
public void put(long index,
                byte value)
```
    Stores a single byte at the specified index.
  - getInt
```
public int getInt(long index)
```
    Retrieves a four-byte integer starting at the specified index.
  - putInt
```
public void putInt(long index,
                   int value)
```
    Stores a four-byte integer starting at the specified index.
  - getLong
```
public long getLong(long index)
```
    Retrieves an eight-byte integer starting at the specified index.
  - putLong
```
public void putLong(long index,
                    long value)
```
    Stores an eight-byte integer starting at the specified index.
  - getShort
```
public short getShort(long index)
```
    Retrieves a four-byte integer starting at the specified index.
  - putShort
```
public void putShort(long index,
                     short value)
```
    Stores a four-byte integer starting at the specified index.
  - getFloat
```
public float getFloat(long index)
```
    Retrieves a four-byte floating-point number starting at the specified index.
  - putFloat
```
public void putFloat(long index,
                     float value)
```
    Stores a four-byte floating-point number starting at the specified index.
  - getDouble
```
public double getDouble(long index)
```
    Retrieves an eight-byte floating-point number starting at the specified index.
  - putDouble
```
public void putDouble(long index,
                      double value)
```
    Stores an eight-byte floating-point number starting at the specified index.
  - 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).
  - putChar
```
public void putChar(long index,
                    char value)
```
    Stores a two-byte character starting at the specified index.
  - 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.
    
    Throws:
    
    java.lang.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:
    
    java.lang.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.
    
    Throws:
    
    java.lang.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:
    
    java.lang.IndexOutOfBoundsException - if the request would write past the end of file.
  - slice
```
public java.nio.ByteBuffer slice(long index)
```
    Creates a new buffer, whose size will be >= segment size, starting at the specified offset.
  - 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
    
    Overrides:
    
    clone in class java.lang.Object

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