Package db.buffers

# Class LocalBufferFile

java.lang.Object
db.buffers.LocalBufferFile

All Implemented Interfaces:
  `BufferFile`

Direct Known Subclasses:
  `LocalManagedBufferFile`

public class LocalBufferFile extends Object implements BufferFile
`LocalBufferFile` implements a BufferFile as block-oriented random-access file. This type of buffer file supports save-as but does not support the save operation.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `LocalBufferFile.InputBlockStreamFactory`
  A simple interface that allows for dependency injection

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `BUFFER_FILE_EXTENSION`
  `static final String`
  `PRESAVE_FILE_EXT`
  `static final String`
  `PRESAVE_FILE_PREFIX`
  `static final String`
  `TEMP_FILE_EXT`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LocalBufferFile(File file, boolean readOnly)`
  Open an existing block file.
  `LocalBufferFile(File file, int bufferSize)`
  Create a new buffer file for writing.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `cleanupOldPreSaveFiles(File dir, long beforeNow)`
  Attempt to remove all pre-save files.
  `void`
  `clearParameters()`
  Deletes all parameters
  `void`
  `clone(File destinationFile, TaskMonitor monitor)`
  Clone this buffer file to the specified file.
  `void`
  `close()`
  Close the buffer file.
  `static void`
  `copyFile(BufferFile srcFile, BufferFile destFile, ChangeMap changeMap, TaskMonitor monitor)`
  Copy the complete content of a specified srcFile into a destFile excluding file ID.
  `boolean`
  `delete()`
  Delete this buffer file if writable.
  `void`
  `dispose()`
  Dispose of this buffer file object.
  `DataBuffer`
  `get(DataBuffer buf, int index)`
  Get the specified buffer.
  `static BufferFileBlock`
  `getBufferFileBlock(DataBuffer buf, int bufferSize)`
  Generate a BufferFileBlock instance which corresponds to the specified DataBuffer based upon LocalBufferFile block usage.
  `int`
  `getBufferSize()`
  Return the actual size of a user data buffer.
  `static DataBuffer`
  `getDataBuffer(BufferFileBlock block)`
  Generate a DataBuffer instance which corresponds to the specified block based upon LocalBufferFile block usage.
  `File`
  `getFile()`
  Returns the physical file associated with this BufferFile.
  `int[]`
  `getFreeIndexes()`
  Returns the list of free indexes sorted by value.
  `int`
  `getIndexCount()`
  Returns the number of allocated buffer indexes.
  `InputBlockStream`
  `getInputBlockStream()`
  Obtain a direct stream to read all blocks of this buffer file
  `OutputBlockStream`
  `getOutputBlockStream(int blockCount)`
  Obtain a direct stream to write blocks to this buffer file
  `int`
  `getParameter(String name)`
  Get a the stored value for a named parameter.
  `String[]`
  `getParameterNames()`
  Returns a list of all parameter names.
  `boolean`
  `isReadOnly()`
  Returns true if this file may not be modified via the buffer put method.
  `static DataBuffer`
  `peek(File file, int bufferIndex)`
  Read a buffer from an existing buffer file.
  `static void`
  `poke(File file, int bufferIndex, DataBuffer buf)`
  Modify an existing buffer file.
  `void`
  `put(DataBuffer buf, int index)`
  Store a data buffer at the specified block index.
  `void`
  `setFreeIndexes(int[] indexes)`
  Sets the list of free buffer indexes.
  `void`
  `setParameter(String name, int value)`
  Set the integer value for a named parameter.
  `boolean`
  `setReadOnly()`
  If file is open read-write, the modified contents are flushed and the file re-opened as read-only.
  `String`
  `toString()`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### BUFFER_FILE_EXTENSION

    public static final String BUFFER_FILE_EXTENSION
    See Also:
      - Constant Field Values

  - ### PRESAVE_FILE_EXT

    public static final String PRESAVE_FILE_EXT
    See Also:
      - Constant Field Values

  - ### PRESAVE_FILE_PREFIX

    public static final String PRESAVE_FILE_PREFIX
    See Also:
      - Constant Field Values

  - ### TEMP_FILE_EXT

    public static final String TEMP_FILE_EXT
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### LocalBufferFile

    public LocalBufferFile(File file, int bufferSize) throws IOException
    Create a new buffer file for writing. If the file does not exist and create is true, a new buffer file will be created. The file will be saved when closed.
    Parameters:
      `file` - buffer file
      `bufferSize` - user buffer size
    Throws:
      `DuplicateFileException` - if file already exists
      `IOException` - if an I/O error occurs during file creation

  - ### LocalBufferFile

    public LocalBufferFile(File file, boolean readOnly) throws IOException
    Open an existing block file.
    Parameters:
      `file` - block file
      `readOnly` - if true the file will be opened read-only
    Throws:
      `IOException` - if an error occurs or the incorrect magicNumber was read from the file.

- ## Method Details

  - ### poke

    public static void poke(File file, int bufferIndex, DataBuffer buf) throws IOException
    Modify an existing buffer file.

    WARNING! Use with extreme caution since this modifies the original file and could destroy data if used improperly.

    Parameters:
      `file` - block file
      `bufferIndex` - the index at which to place the buffer
      `buf` - the buffer add to the file
    Throws:
      `IOException` - if an I/O error occurs

  - ### peek

    public static DataBuffer peek(File file, int bufferIndex) throws IOException
    Read a buffer from an existing buffer file.
    Parameters:
      `file` - block file
      `bufferIndex` - the index from which to read the buffer
    Returns:
      the buffer
    Throws:
      `IOException` - if an I/O error occurs

  - ### getFile

    public File getFile()
    Returns the physical file associated with this BufferFile.
    Returns:
      the file

  - ### isReadOnly

    public boolean isReadOnly()
    Description copied from interface: `BufferFile`
    Returns true if this file may not be modified via the buffer put method. A read-only file may be considered "updateable" if the canSave method returns true. The term "updateable" means that a Save file can be obtained via the getSaveFile method.
    Specified by:
      `isReadOnly` in interface `BufferFile`

  - ### getParameter

    public int getParameter(String name) throws NoSuchElementException
    Description copied from interface: `BufferFile`
    Get a the stored value for a named parameter.
    Specified by:
      `getParameter` in interface `BufferFile`
    Parameters:
      `name` - parameter name
    Returns:
      integer value
    Throws:
      `NoSuchElementException` - thrown if parameter not found

  - ### setParameter

    public void setParameter(String name, int value)
    Description copied from interface: `BufferFile`
    Set the integer value for a named parameter.
    Specified by:
      `setParameter` in interface `BufferFile`
    Parameters:
      `name` - parameter name
      `value` - parameter value

  - ### clearParameters

    public void clearParameters()
    Description copied from interface: `BufferFile`
    Deletes all parameters
    Specified by:
      `clearParameters` in interface `BufferFile`

  - ### getParameterNames

    public String[] getParameterNames()
    Description copied from interface: `BufferFile`
    Returns a list of all parameter names.
    Specified by:
      `getParameterNames` in interface `BufferFile`

  - ### getFreeIndexes

    public int[] getFreeIndexes()
    Description copied from interface: `BufferFile`
    Returns the list of free indexes sorted by value. The management of the free-index-list is implementation specific.
    Specified by:
      `getFreeIndexes` in interface `BufferFile`

  - ### setFreeIndexes

    public void setFreeIndexes(int[] indexes)
    Description copied from interface: `BufferFile`
    Sets the list of free buffer indexes. The management of the free-index-list is implementation specific.
    Specified by:
      `setFreeIndexes` in interface `BufferFile`

  - ### getDataBuffer

    public static DataBuffer getDataBuffer(BufferFileBlock block)
    Generate a DataBuffer instance which corresponds to the specified block based upon LocalBufferFile block usage.
    Parameters:
      `block` - the buffer file block to be converted
    Returns:
      DataBuffer instance or null if head block. If empty block DataBuffer will have null data

  - ### getBufferFileBlock

    public static BufferFileBlock getBufferFileBlock(DataBuffer buf, int bufferSize)
    Generate a BufferFileBlock instance which corresponds to the specified DataBuffer based upon LocalBufferFile block usage. This should generally not be used for writing empty blocks since they will not be properly linked which is normally handled during header flush which is performed by BufferFile close on files being written.
    Parameters:
      `buf` - the data buffer to be converted
      `bufferSize` - data buffer size used for integrity check and generating empty buffer
    Returns:
      BufferFileBlock instance.

  - ### get

    public DataBuffer get(DataBuffer buf, int index) throws IOException
    Description copied from interface: `BufferFile`
    Get the specified buffer. DataBuffer data and flags are read from the file at index and stored within the supplied DataBuffer object. If the read buffer is empty, the DataBuffer's data field will remain unchanged (which could be null).
    Specified by:
      `get` in interface `BufferFile`
    Parameters:
      `buf` - a buffer whose data array will be filled-in or replaced.
      `index` - index of buffer to be read. First user buffer is at index 0.
    Throws:
      `EOFException` - if the requested buffer index is greater than the number of available buffers of the end-of-file was encountered while reading the buffer.
      `IOException` - if an I/O error occurs

  - ### put

    public void put(DataBuffer buf, int index) throws IOException
    Description copied from interface: `BufferFile`
    Store a data buffer at the specified block index.
    Specified by:
      `put` in interface `BufferFile`
    Parameters:
      `buf` - data buffer
      `index` - block index
    Throws:
      `IOException` - thrown if an IO error occurs

  - ### getBufferSize

    public int getBufferSize()
    Description copied from interface: `BufferFile`
    Return the actual size of a user data buffer. This value should be used when constructing DataBuffer objects.
    Specified by:
      `getBufferSize` in interface `BufferFile`
    Returns:
      DataBuffer data size as a number of bytes

  - ### getIndexCount

    public int getIndexCount()
    Description copied from interface: `BufferFile`
    Returns the number of allocated buffer indexes. When a new buffer is allocated, and the file size grows, the buffer will remain allocated although it may be added to the list of free-indexes. A file will never shrink in size due to this permanent allocation.
    Specified by:
      `getIndexCount` in interface `BufferFile`

  - ### dispose

    public void dispose()
    Description copied from interface: `BufferFile`
    Dispose of this buffer file object. If file is not readOnly and has not been closed, an attempt will be made to delete the associated file(s). Once disposed, it may no longer be used.
    Specified by:
      `dispose` in interface `BufferFile`

  - ### setReadOnly

    public boolean setReadOnly() throws IOException
    Description copied from interface: `BufferFile`
    If file is open read-write, the modified contents are flushed and the file re-opened as read-only. This is also used to commit a new version if the file had been modified for update.
    Specified by:
      `setReadOnly` in interface `BufferFile`
    Returns:
      true if successfully transitioned from read-write to read-only
    Throws:
      `IOException` - if an I/O error occurs

  - ### close

    public void close() throws IOException
    Description copied from interface: `BufferFile`
    Close the buffer file. If the file was open for write access, all buffers are flushed and the file header updated. Once closed, this object is immediately disposed and may no longer be used.
    Specified by:
      `close` in interface `BufferFile`
    Throws:
      `IOException` - if an I/O error occurs

  - ### delete

    public boolean delete()
    Description copied from interface: `BufferFile`
    Delete this buffer file if writable. Once deleted, this object is immediately disposed and may no longer be used.
    Specified by:
      `delete` in interface `BufferFile`
    Returns:
      true if deleted, false if the file is read-only

  - ### clone

    public void clone(File destinationFile, TaskMonitor monitor) throws IOException, CancelledException
    Clone this buffer file to the specified file. The file must not already exist. If the operation is cancelled or an error occurs the file is not created.
    Parameters:
      `destinationFile` - destination file
      `monitor` - progress monitor
    Throws:
      `IOException` - if IO error occurs.
      `CancelledException` - if the monitor cancels the operation.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getInputBlockStream

    public InputBlockStream getInputBlockStream() throws IOException
    Obtain a direct stream to read all blocks of this buffer file
    Returns:
      input block stream
    Throws:
      `IOException` - if there is an exception creating the stream

  - ### getOutputBlockStream

    public OutputBlockStream getOutputBlockStream(int blockCount) throws IOException
    Obtain a direct stream to write blocks to this buffer file
    Parameters:
      `blockCount` - number of blocks to be transferred
    Returns:
      output block stream
    Throws:
      `IOException` - if an I/O error occurs

  - ### copyFile

    public static void copyFile(BufferFile srcFile, BufferFile destFile, ChangeMap changeMap, TaskMonitor monitor) throws IOException, CancelledException
    Copy the complete content of a specified srcFile into a destFile excluding file ID. Both files remain open.
    Parameters:
      `srcFile` - open buffer file
      `destFile` - empty buffer file which is open for writing.
      `changeMap` - optional change map which indicates those buffers which must be copied. Any buffer index outside the range of the change map will also be copied.
      `monitor` - progress monitor
    Throws:
      `IOException` - if IO error occurs.
      `CancelledException` - if the monitor cancels the operation.

  - ### cleanupOldPreSaveFiles

    public static void cleanupOldPreSaveFiles(File dir, long beforeNow)
    Attempt to remove all pre-save files. Those still open by an existing process should not be removed by the operating system.
    Parameters:
      `dir` - data directory containing pre-save files
      `beforeNow` - if not 0, file mod time must be less than the specified time