Package org.simpleframework.util.buffer

## Class FilterAllocator

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

- All Implemented Interfaces:
    `java.io.Closeable`, `java.lang.AutoCloseable`, `Allocator`
  Direct Known Subclasses:
    `BufferAllocator`

      public class FilterAllocator
      extends java.lang.Object
      implements Allocator

  The `FilterAllocator` object is used to provide a means to provide a general set of constraints around buffer allocation. It can ensure that a minimum capacity is used for default allocation and that an upper limit is used for allocation. In general this can be used in conjunction with another `Allocator` which may not have such constraints. It ensures that a set of requirements can be observed when allocating buffers.
  Author:
    Niall Gallagher

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected int` | `capacity` | This is the default initial minimum capacity of the buffer.
    `protected int` | `limit` | This is the maximum number of bytes that can be allocated.
    `protected Allocator` | `source` | This is the allocator the underlying buffer is allocated with.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FilterAllocator​(Allocator source)` | Constructor for the `FilterAllocator` object.
    `FilterAllocator​(Allocator source, int capacity)` | Constructor for the `FilterAllocator` object.
    `FilterAllocator​(Allocator source, int capacity, int limit)` | Constructor for the `FilterAllocator` object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Buffer` | `allocate()` | This method is used to allocate a default buffer.
    `Buffer` | `allocate​(int size)` | This method is used to allocate a default buffer.
    `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`

- - ### Field Detail

    - #### source

          protected Allocator source

      This is the allocator the underlying buffer is allocated with.

    - #### capacity

          protected int capacity

      This is the default initial minimum capacity of the buffer.

    - #### limit

          protected int limit

      This is the maximum number of bytes that can be allocated.

  - ### Constructor Detail

    - #### FilterAllocator

          public FilterAllocator​(Allocator source)

      Constructor for the `FilterAllocator` object. This is used to instantiate the allocator with a default buffer size of half a kilobyte. This ensures that it can be used for general purpose byte storage and for minor I/O tasks.
      Parameters:
        `source` - this is where the underlying buffer is allocated

    - #### FilterAllocator

          public FilterAllocator​(Allocator source,
                                 int capacity)

      Constructor for the `FilterAllocator` object. This is used to instantiate the allocator with a specified buffer size. This is typically used when a very specific buffer capacity is required, for example a request body with a known length.
      Parameters:
        `source` - this is where the underlying buffer is allocated
        `capacity` - the initial capacity of the allocated buffers

    - #### FilterAllocator

          public FilterAllocator​(Allocator source,
                                 int capacity,
                                 int limit)

      Constructor for the `FilterAllocator` object. This is used to instantiate the allocator with a specified buffer size. This is typically used when a very specific buffer capacity is required, for example a request body with a known length.
      Parameters:
        `source` - this is where the underlying buffer is allocated
        `capacity` - the initial capacity of the allocated buffers
        `limit` - this is the maximum buffer size created by this

  - ### Method Detail

    - #### allocate

          public Buffer allocate()
                          throws java.io.IOException

      This method is used to allocate a default buffer. This will allocate a buffer of predetermined size, allowing it to grow to an upper limit to accommodate extra data. If the buffer requested is larger than the limit an exception is thrown.
      Specified by:
        `allocate` in interface `Allocator`
      Returns:
        this returns an allocated buffer with a default size
      Throws:
        `java.io.IOException`

    - #### allocate

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

      This method is used to allocate a default buffer. This will allocate a buffer of predetermined size, allowing it to grow to an upper limit to accommodate extra data. If the buffer requested is larger than the limit an exception is thrown.
      Specified by:
        `allocate` in interface `Allocator`
      Parameters:
        `size` - the initial capacity of the allocated buffer
      Returns:
        this returns an allocated buffer with a default size
      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`