Package org.apache.qpid.protonj2.buffer

Interface ProtonBufferAllocator

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
Netty4ProtonBufferAllocator, Netty5ProtonBufferAllocator, ProtonByteArrayBufferAllocator
public interface ProtonBufferAllocator extends AutoCloseable
Interface for a ProtonBuffer allocator object that can be used by Proton objects to create memory buffers using the preferred type of the application or library that embeds the Proton engine.

  • Method Summary

    Modifier and Type
    Method
    Description
    ProtonBuffer
    allocate()
    Create a new ProtonBuffer instance with default initial capacity.
    ProtonBuffer
    allocate(int initialCapacity)
    Create a new ProtonBuffer instance with the given initial capacity and the implicit growth limit should be that of the underlying buffer implementations maximum capacity limit.
    ProtonBuffer
    allocateHeapBuffer()
    Create a new ProtonBuffer instance with default initial capacity.
    ProtonBuffer
    allocateHeapBuffer(int initialCapacity)
    Create a new ProtonBuffer instance with the given initial capacity and the implicit growth limit should be that of the underlying buffer implementations maximum capacity limit.
    default void
    close()
     
    ProtonCompositeBuffer
    composite()
    Creates a new composite buffer instance that uses this allocator to create new backing space when the buffer writes exceed capacity or the ensure writable space API is used.
    ProtonCompositeBuffer
    composite(ProtonBuffer buffer)
    Creates a new composite buffer instance that uses this allocator to create new backing space when the buffer writes exceed capacity or the ensure writable space API is used.
    ProtonCompositeBuffer
    composite(ProtonBuffer[] buffers)
    Creates a new composite buffer instance that uses this allocator to create new backing space when the buffer writes exceed capacity or the ensure writable space API is used.
    default ProtonBuffer
    copy(byte[] array)
    Create a new ProtonBuffer that copies the given byte array.
    ProtonBuffer
    copy(byte[] array, int offset, int length)
    Create a new ProtonBuffer that copies the given byte array using the provided offset and length values to confine the view of that array.
    static ProtonBufferAllocator
    defaultAllocator()
    Gets an allocator from the proton internal buffer allocator which can be a default version or may have been configured to ensure all allocations use a specific allocator instance.
    ProtonBuffer
    outputBuffer(int initialCapacity)
    Create a new output ProtonBuffer instance with the given initial capacity and the implicit growth capacity should be that of the underlying buffer implementations limit.

  • Method Details

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable

    • defaultAllocator

      static ProtonBufferAllocator defaultAllocator()
      Gets an allocator from the proton internal buffer allocator which can be a default version or may have been configured to ensure all allocations use a specific allocator instance.
      Returns:
      a ProtonBufferAllocator for use in the application.

    • outputBuffer

      ProtonBuffer outputBuffer(int initialCapacity)
      Create a new output ProtonBuffer instance with the given initial capacity and the implicit growth capacity should be that of the underlying buffer implementations limit. The buffer implementation should support growing the buffer on an as needed basis to allow writes without the user needing to code extra capacity and buffer reallocation checks.

      The returned buffer will be used for frame output from the Proton engine and can be a pooled buffer which the IO handler will then need to release once the buffer has been written.

      Parameters:
      initialCapacity - The initial capacity to use when creating the new ProtonBuffer.
      Returns:
      a new ProtonBuffer instance with the given initial capacity.

    • allocate

      ProtonBuffer allocate()
      Create a new ProtonBuffer instance with default initial capacity. The buffer implementation should support growing the buffer on an as needed basis to allow writes without the user needing to code extra capacity and buffer reallocation checks.

      Proton buffers are closable resources and their life-span requires that they be closed upon reaching their determined end of life.

      Returns:
      a new ProtonBuffer instance with default initial capacity.

    • allocate

      ProtonBuffer allocate(int initialCapacity)
      Create a new ProtonBuffer instance with the given initial capacity and the implicit growth limit should be that of the underlying buffer implementations maximum capacity limit.

      Proton buffers are closable resources and their life-span requires that they be closed upon reaching their determined end of life.

      Parameters:
      initialCapacity - The initial capacity to use when creating the new ProtonBuffer.
      Returns:
      a new ProtonBuffer instance with the given initial capacity.

    • allocateHeapBuffer

      ProtonBuffer allocateHeapBuffer()
      Create a new ProtonBuffer instance with default initial capacity. The buffer implementation should support growing the buffer on an as needed basis to allow writes without the user needing to code extra capacity and buffer reallocation checks. The buffer allocated must be a heap buffer for cases where the buffered resource may not be easily closed and must revert to GC reclaim semantics.

      Proton buffers are closable resources and their life-span requires that they be closed upon reaching their determined end of life.

      Returns:
      a new ProtonBuffer instance with default initial capacity.

    • allocateHeapBuffer

      ProtonBuffer allocateHeapBuffer(int initialCapacity)
      Create a new ProtonBuffer instance with the given initial capacity and the implicit growth limit should be that of the underlying buffer implementations maximum capacity limit. The buffer allocated must be a heap buffer for cases where the buffered resource may not be easily closed and must revert to GC reclaim semantics.

      Proton buffers are closable resources and their life-span requires that they be closed upon reaching their determined end of life.

      Parameters:
      initialCapacity - The initial capacity to use when creating the new ProtonBuffer.
      Returns:
      a new ProtonBuffer instance with the given initial capacity.

    • composite

      ProtonCompositeBuffer composite()
      Creates a new composite buffer instance that uses this allocator to create new backing space when the buffer writes exceed capacity or the ensure writable space API is used. The created buffer will be empty and can be expanded with the normal buffer API or extended with the addition of buffers.
      Returns:
      a new empty composite buffer instance.

    • composite

      ProtonCompositeBuffer composite(ProtonBuffer buffer)
      Creates a new composite buffer instance that uses this allocator to create new backing space when the buffer writes exceed capacity or the ensure writable space API is used. The created buffer will be composed of the given sequence of buffers.
      Parameters:
      buffer - the buffers to compose
      Returns:
      a new composite buffer instance.

    • composite

      ProtonCompositeBuffer composite(ProtonBuffer[] buffers)
      Creates a new composite buffer instance that uses this allocator to create new backing space when the buffer writes exceed capacity or the ensure writable space API is used. The created buffer will be composed of the given sequence of buffers.
      Parameters:
      buffers - the array of buffers to compose
      Returns:
      a new composite buffer instance.

    • copy

      default ProtonBuffer copy(byte[] array)
      Create a new ProtonBuffer that copies the given byte array.

      The capacity for the resulting ProtonBuffer should equal to the length of the copied array and the returned array read offset is zero The returned buffer can be expanded using the normal write or expand methods and its write offset will be set to the buffer capacity.

      Changes to the input buffer after calling this method will not affect the contents of the returned buffer copy.

      Parameters:
      array - the byte array to copy.
      Returns:
      a new ProtonBuffer that is a copy of the given array.

    • copy

      ProtonBuffer copy(byte[] array, int offset, int length)
      Create a new ProtonBuffer that copies the given byte array using the provided offset and length values to confine the view of that array.

      The initial capacity of the buffer should be that of the length of the wrapped array. The returned buffer can be expanded using the normal write or expand methods. The write offset of the returned buffer will be set to the capacity.

      Changes to the input buffer after calling this method will not affect the contents of the returned buffer copy.

      Parameters:
      array - the byte array to copy.
      offset - the offset into the array where the view begins.
      length - the number of bytes in the array to expose
      Returns:
      a new ProtonBuffer that is a copy of the given array.