Package org.simpleframework.util.buffer

## Class FileAllocator

- java.lang.Object
- - org.simpleframework.util.buffer.FileAllocator

- All Implemented Interfaces:
    `java.io.Closeable`, `java.lang.AutoCloseable`, `Allocator`

      public class FileAllocator
      extends java.lang.Object
      implements Allocator

  The `FileAllocator` object is used to create buffers that can be written to the file system. This creates buffers as files if they are larger than the specified limit. This ensures that buffers of arbitrary large size can be created. All buffer sizes under the limit are created using byte arrays allocated on the executing VM heap. This ensures that optimal performance is maintained for buffers of reasonable size.
  Author:
    Niall Gallagher

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FileAllocator()` | Constructor for the `FileAllocator` object.
    `FileAllocator​(int limit)` | Constructor for the `FileAllocator` object.
    `FileAllocator​(java.lang.String prefix)` | Constructor for the `FileAllocator` object.
    `FileAllocator​(java.lang.String prefix, int limit)` | Constructor for the `FileAllocator` object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Buffer` | `allocate()` | This will allocate a file buffer which will write data for the buffer to a file.
    `Buffer` | `allocate​(int size)` | This will allocate a file buffer which will write data for the buffer to a file.
    `void` | `close()` | This method is used to close the allocator so that resources that are occupied by the allocator can be freed.

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

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

- - ### Constructor Detail

    - #### FileAllocator

          public FileAllocator()
                        throws java.io.IOException

      Constructor for the `FileAllocator` object. This is used to create buffers in memory up to a threshold size. If a buffer is required over the threshold size then the data is written to a file, where it can be retrieved at a later point.
      Throws:
        `java.io.IOException`

    - #### FileAllocator

          public FileAllocator​(int limit)
                        throws java.io.IOException

      Constructor for the `FileAllocator` object. This is used to create buffers in memory up to a threshold size. If a buffer is required over the threshold size then the data is written to a file, where it can be retrieved at a later point.
      Parameters:
        `limit` - this is the maximum size for a heap buffer
      Throws:
        `java.io.IOException`

    - #### FileAllocator

          public FileAllocator​(java.lang.String prefix)
                        throws java.io.IOException

      Constructor for the `FileAllocator` object. This is used to create buffers in memory up to a threshold size. If a buffer is required over the threshold size then the data is written to a file, where it can be retrieved at a later point.
      Parameters:
        `prefix` - this is the file prefix for the file buffers
      Throws:
        `java.io.IOException`

    - #### FileAllocator

          public FileAllocator​(java.lang.String prefix,
                               int limit)
                        throws java.io.IOException

      Constructor for the `FileAllocator` object. This is used to create buffers in memory up to a threshold size. If a buffer is required over the threshold size then the data is written to a file, where it can be retrieved at a later point.
      Parameters:
        `prefix` - this is the file prefix for the file buffers
        `limit` - this is the maximum size for a heap buffer
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### allocate

          public Buffer allocate()
                          throws java.io.IOException

      This will allocate a file buffer which will write data for the buffer to a file. Buffers allocated by this method can be of arbitrary size as data is appended directly to a temporary file. This ensures there is no upper limit for appended data.
      Specified by:
        `allocate` in interface `Allocator`
      Returns:
        a buffer which will write to a temporary file
      Throws:
        `java.io.IOException`

    - #### allocate

          public Buffer allocate​(int size)
                          throws java.io.IOException

      This will allocate a file buffer which will write data for the buffer to a file. Buffers allocated by this method can be of arbitrary size as data is appended directly to a temporary file. This ensures there is no upper limit for appended data. If the size required is less than the limit then the buffer is an in memory array which provides optimal performance.
      Specified by:
        `allocate` in interface `Allocator`
      Parameters:
        `size` - this is the size of the buffer to be created
      Returns:
        a buffer which will write to a created temporary file
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      This method is used to close the allocator so that resources that are occupied by the allocator can be freed. This will allow the allocator to be created and closed repeatedly in a single process without holding on to resources such as mapped file buffers or threads.
      Specified by:
        `close` in interface `Allocator`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in interface `java.io.Closeable`
      Throws:
        `java.io.IOException`