Package org.apache.qpid.protonj2.buffer

Interface ProtonBufferAllocator

  • All Known Implementing Classes:
    ProtonByteBufferAllocator, ProtonNettyByteBufferAllocator
    public interface ProtonBufferAllocator
    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

      All Methods Instance Methods Abstract Methods 
      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 maximum capacity should be that of the underlying buffer implementations limit.
      ProtonBuffer allocate​(int initialCapacity, int maximumCapacity)
      Create a new ProtonBuffer instance with the given initial capacity and the maximum capacity should that of the value specified by the caller.
      ProtonBuffer outputBuffer​(int initialCapacity)
      Create a new output ProtonBuffer instance with the given initial capacity and the maximum capacity should be that of the underlying buffer implementations limit.
      ProtonBuffer outputBuffer​(int initialCapacity, int maximumCapacity)
      Create a new output ProtonBuffer instance with the given initial capacity and the maximum capacity should that of the value specified by the caller.
      ProtonBuffer wrap​(byte[] array)
      Create a new ProtonBuffer that wraps the given byte array.
      ProtonBuffer wrap​(byte[] array, int offset, int length)
      Create a new ProtonBuffer that wraps the given byte array using the provided offset and length values to confine the view of that array.
      ProtonBuffer wrap​(ByteBuffer buffer)
      Create a new ProtonBuffer that wraps the given ByteBuffer.

    • Method Detail

      • outputBuffer

        ProtonBuffer outputBuffer​(int initialCapacity)
        Create a new output ProtonBuffer instance with the given initial capacity and the maximum 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.

      • outputBuffer

        ProtonBuffer outputBuffer​(int initialCapacity,
                          int maximumCapacity)
        Create a new output ProtonBuffer instance with the given initial capacity and the maximum capacity should that of the value specified by the caller.

        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.
        maximumCapacity - The largest amount of bytes the new ProtonBuffer is allowed to grow to.
        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. It is not recommended that these buffers be backed by a pooled resource as there is no defined release point within the buffer API and if used by an AMQP engine they could be lost as buffers are copied or aggregated together.
        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 maximum capacity should be that of the underlying buffer implementations limit. It is not recommended that these buffers be backed by a pooled resource as there is no defined release point within the buffer API and if used by an AMQP engine they could be lost as buffers are copied or aggregated together.
        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​(int initialCapacity,
                      int maximumCapacity)
        Create a new ProtonBuffer instance with the given initial capacity and the maximum capacity should that of the value specified by the caller. It is not recommended that these buffers be backed by a pooled resource as there is no defined release point within the buffer API and if used by an AMQP engine they could be lost as buffers are copied or aggregated together.
        Parameters:
        initialCapacity - The initial capacity to use when creating the new ProtonBuffer.
        maximumCapacity - The largest amount of bytes the new ProtonBuffer is allowed to grow to.
        Returns:
        a new ProtonBuffer instance with the given initial capacity.

      • wrap

        ProtonBuffer wrap​(byte[] array)
        Create a new ProtonBuffer that wraps the given byte array.

        The capacity and maximum capacity for the resulting ProtonBuffer should equal to the length of the wrapped array and the returned array offset is zero.

        Parameters:
        array - the byte array to wrap.
        Returns:
        a new ProtonBuffer that wraps the given array.

      • wrap

        ProtonBuffer wrap​(byte[] array,
                  int offset,
                  int length)
        Create a new ProtonBuffer that wraps the given byte array using the provided offset and length values to confine the view of that array. The maximum capacity of the buffer should be that of the length of the wrapped array.

        The capacity and maximum capacity for the resulting ProtonBuffer should equal to the length parameter provided and the returned buffer offset will be zero.

        Parameters:
        array - the byte array to wrap.
        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 wraps the given array.

      • wrap

        ProtonBuffer wrap​(ByteBuffer buffer)
        Create a new ProtonBuffer that wraps the given ByteBuffer. The maximum capacity of the returned buffer should be same as the remaining bytes within the wrapped ByteBuffer.

        The capacity and maximum capacity of the returned ProtonBuffer will be the same as that of the underlying ByteBuffer. The ProtonBuffer will return true from the ProtonBuffer.hasArray() method only when the wrapped ByteBuffer reports that it is backed by an array.

        Parameters:
        buffer - the ByteBuffer to wrap.
        Returns:
        a new ProtonBuffer that wraps the given ByteBuffer.