Package org.eclipse.jetty.util

Class BufferUtil

java.lang.Object
org.eclipse.jetty.util.BufferUtil
public class BufferUtil extends Object
Buffer utility methods.

The standard JVM ByteBuffer can exist in two modes: In fill mode the valid data is between 0 and pos; In flush mode the valid data is between the pos and the limit. The various ByteBuffer methods assume a mode and some of them will switch or enforce a mode: Allocate and clear set fill mode; flip and compact switch modes; read and write assume fill and flush modes. This duality can result in confusing code such as: 

     buffer.clear();
     channel.write(buffer);

Which looks as if it should write no data, but in fact writes the buffer worth of garbage.

The BufferUtil class provides a set of utilities that operate on the convention that ByteBuffers will always be left, passed in an API or returned from a method in the flush mode - ie with valid data between the pos and limit. This convention is adopted so as to avoid confusion as to what state a buffer is in and to avoid excessive copying of data that can result with the usage of compress.

Thus this class provides alternate implementations of allocate(int), allocateDirect(int) and clear(ByteBuffer) that leave the buffer in flush mode. Thus the following tests will pass: 

     ByteBuffer buffer = BufferUtil.allocate(1024);
     assert(buffer.remaining()==0);
     BufferUtil.clear(buffer);
     assert(buffer.remaining()==0);

If the BufferUtil methods fill(ByteBuffer, byte[], int, int), append(ByteBuffer, byte[], int, int) or put(ByteBuffer, ByteBuffer) are used, then the caller does not need to explicitly switch the buffer to fill mode. If the caller wishes to use other ByteBuffer bases libraries to fill a buffer, then they can use explicit calls of #flipToFill(ByteBuffer) and #flipToFlush(ByteBuffer, int) to change modes. Note because this convention attempts to avoid the copies of compact, the position is not set to zero on each fill cycle and so its value must be remembered: 

      int pos = BufferUtil.flipToFill(buffer);
      try
      {
          buffer.put(data);
      }
      finally
      {
          flipToFlush(buffer, pos);
      }

The flipToFill method will effectively clear the buffer if it is empty and will compact the buffer if there is no space.

  • Field Details

    • EMPTY_BYTES

      public static final byte[] EMPTY_BYTES

    • EMPTY_BUFFER

      public static final ByteBuffer EMPTY_BUFFER

  • Constructor Details

    • BufferUtil

      public BufferUtil()

  • Method Details

    • allocate

      public static ByteBuffer allocate(int capacity)
      Allocate ByteBuffer in flush mode. The position and limit will both be zero, indicating that the buffer is empty and must be flipped before any data is put to it.
      Parameters:
      capacity - capacity of the allocated ByteBuffer
      Returns:
      Buffer

    • allocateDirect

      public static ByteBuffer allocateDirect(int capacity)
      Allocate ByteBuffer in flush mode. The position and limit will both be zero, indicating that the buffer is empty and in flush mode.
      Parameters:
      capacity - capacity of the allocated ByteBuffer
      Returns:
      Buffer

    • allocate

      public static ByteBuffer allocate(int capacity, boolean direct)
      Allocates a ByteBuffer in flush mode. The position and limit will both be zero, indicating that the buffer is empty and must be flipped before any data is put to it.
      Parameters:
      capacity - capacity of the allocated ByteBuffer
      direct - whether the ByteBuffer is direct
      Returns:
      the newly allocated ByteBuffer

    • copy

      public static ByteBuffer copy(ByteBuffer buffer)
      Deep copy of a buffer
      Parameters:
      buffer - The buffer to copy
      Returns:
      A copy of the buffer

    • reset

      public static void reset(ByteBuffer buffer)
      Resets the buffer's endianness to ByteOrder.BIG_ENDIAN and clears the buffer to be empty in flush mode. The position and limit are set to 0.
      Parameters:
      buffer - the buffer to reset.

    • clear

      public static void clear(ByteBuffer buffer)
      Clears the buffer to be empty in flush mode. The position and limit are set to 0.
      Parameters:
      buffer - the buffer to clear.

    • clearToFill

      public static void clearToFill(ByteBuffer buffer)
      Clear the buffer to be empty in fill mode. The position is set to 0 and the limit is set to the capacity.
      Parameters:
      buffer - The buffer to clear.

    • flipToFill

      public static int flipToFill(ByteBuffer buffer)
      Flip the buffer to fill mode. The position is set to the first unused position in the buffer (the old limit) and the limit is set to the capacity. If the buffer is empty, then this call is effectively clearToFill(ByteBuffer). If there is no unused space to fill, a ByteBuffer.compact() is done to attempt to create space.

      This method is used as a replacement to ByteBuffer.compact().

      Parameters:
      buffer - The buffer to flip
      Returns:
      The position of the valid data before the flipped position. This value should be passed to a subsequent call to flipToFlush(ByteBuffer, int)

    • flipToFlush

      public static void flipToFlush(ByteBuffer buffer, int position)
      Flip the buffer to Flush mode. The limit is set to the first unused byte(the old position) and the position is set to the passed position.

      This method is used as a replacement of Buffer.flip().

      Parameters:
      buffer - the buffer to be flipped
      position - The position of valid data to flip to. This should be the return value of the previous call to flipToFill(ByteBuffer)

    • putIntLittleEndian

      public static void putIntLittleEndian(ByteBuffer buffer, int value)
      Put an integer little endian
      Parameters:
      buffer - The buffer to put to
      value - The value to put.

    • toArray

      public static byte[] toArray(ByteBuffer buffer)
      Convert a ByteBuffer to a byte array.
      Parameters:
      buffer - The buffer to convert in flush mode. The buffer is not altered.
      Returns:
      An array of bytes duplicated from the buffer.

    • isTheEmptyBuffer

      public static boolean isTheEmptyBuffer(ByteBuffer buf)
      Parameters:
      buf - the buffer to check
      Returns:
      true if buf is equal to EMPTY_BUFFER

    • isEmpty

      public static boolean isEmpty(ByteBuffer buf)
      Check for an empty or null buffer.
      Parameters:
      buf - the buffer to check
      Returns:
      true if the buffer is null or empty.

    • isEmpty

      public static boolean isEmpty(ByteBuffer[] buf)
      Check for an empty or null buffers.
      Parameters:
      buf - the buffer to check
      Returns:
      true if the buffer is null or empty.

    • remaining

      public static long remaining(ByteBuffer... buf)
      Get the remaining bytes in 0 or more buffers.
      Parameters:
      buf - the buffers to check
      Returns:
      number of bytes remaining in all buffers.

    • hasContent

      public static boolean hasContent(ByteBuffer buf)
      Check for a non null and non empty buffer.
      Parameters:
      buf - the buffer to check
      Returns:
      true if the buffer is not null and not empty.

    • isFull

      public static boolean isFull(ByteBuffer buf)
      Check for a non null and full buffer.
      Parameters:
      buf - the buffer to check
      Returns:
      true if the buffer is not null and the limit equals the capacity.

    • length

      public static int length(ByteBuffer buffer)
      Get remaining from null checked buffer
      Parameters:
      buffer - The buffer to get the remaining from, in flush mode.
      Returns:
      0 if the buffer is null, else the bytes remaining in the buffer.

    • space

      public static int space(ByteBuffer buffer)
      Get the space from the limit to the capacity
      Parameters:
      buffer - the buffer to get the space from
      Returns:
      space

    • compact

      public static boolean compact(ByteBuffer buffer)
      Compact the buffer
      Parameters:
      buffer - the buffer to compact
      Returns:
      true if the compact made a full buffer have space

    • put

      public static int put(ByteBuffer from, ByteBuffer to)
      Put data from one buffer into another, avoiding over/under flows
      Parameters:
      from - Buffer to take bytes from in flush mode
      to - Buffer to put bytes to in fill mode.
      Returns:
      number of bytes moved

    • append

      public static void append(ByteBuffer to, byte[] b, int off, int len) throws BufferOverflowException
      Append bytes to a buffer.
      Parameters:
      to - Buffer is flush mode
      b - bytes to append
      off - offset into byte
      len - length to append
      Throws:
      BufferOverflowException - if unable to append buffer due to space limits

    • append

      public static void append(ByteBuffer to, byte[] b) throws BufferOverflowException
      Append bytes to a buffer.
      Parameters:
      to - Buffer is flush mode
      b - bytes to append
      Throws:
      BufferOverflowException - if unable to append buffer due to space limits

    • append

      public static void append(ByteBuffer to, String s) throws BufferOverflowException
      Append a string to a buffer.
      Parameters:
      to - Buffer is flush mode
      s - String to append as UTF8
      Throws:
      BufferOverflowException - if unable to append buffer due to space limits

    • append

      public static void append(ByteBuffer to, byte b)
      Appends a byte to a buffer
      Parameters:
      to - Buffer is flush mode
      b - byte to append
      Throws:
      BufferOverflowException - if unable to append buffer due to space limits

    • append

      public static int append(ByteBuffer to, ByteBuffer b)
      Appends a buffer to a buffer
      Parameters:
      to - Buffer is flush mode
      b - buffer to append
      Returns:
      The position of the valid data before the flipped position.

    • fill

      public static int fill(ByteBuffer to, byte[] b, int off, int len)
      Like append, but does not throw BufferOverflowException
      Parameters:
      to - Buffer The buffer to fill to. The buffer will be flipped to fill mode and then flipped back to flush mode.
      b - bytes The bytes to fill
      off - offset into bytes
      len - length to fill
      Returns:
      the number of bytes taken from the buffer.

    • readFrom

      public static void readFrom(File file, ByteBuffer buffer) throws IOException
      Throws:
      IOException

    • readFrom

      public static void readFrom(Path path, ByteBuffer buffer) throws IOException
      Throws:
      IOException

    • readFrom

      public static int readFrom(ReadableByteChannel readableByteChannel, ByteBuffer byteBuffer) throws IOException
      Read content from a ReadableByteChannel into a buffer. This may spin if ReadableByteChannel.read(ByteBuffer) returns 0 in which case this will call Thread.onSpinWait().
      Parameters:
      readableByteChannel - the channel to read from.
      byteBuffer - the buffer to read into.
      Returns:
      the number of bytes read into the buffer.
      Throws:
      IOException - if an I/O error occurs.

    • readFrom

      public static void readFrom(InputStream is, int needed, ByteBuffer buffer) throws IOException
      Throws:
      IOException

    • readFrom

      public static int readFrom(InputStream is, ByteBuffer buffer) throws IOException
      Throws:
      IOException

    • writeTo

      public static void writeTo(ByteBuffer buffer, OutputStream out) throws IOException
      Throws:
      IOException

    • toString

      public static String toString(ByteBuffer buffer)
      Convert the buffer to an ISO-8859-1 String
      Parameters:
      buffer - The buffer to convert in flush mode. The buffer is unchanged
      Returns:
      The buffer as a string.

    • toString

      public static String toString(ByteBuffer buffer, Charset charset)
      Convert buffer to a String with specified Charset
      Parameters:
      buffer - The buffer to convert in flush mode. The buffer is unchanged
      charset - The Charset to use to convert the bytes
      Returns:
      The buffer as a string.

    • toString

      public static String toString(ByteBuffer buffer, int position, int length, Charset charset)
      Convert a partial buffer to a String.
      Parameters:
      buffer - the buffer to convert
      position - The position in the buffer to start the string from
      length - The length of the buffer
      charset - The Charset to use to convert the bytes
      Returns:
      The buffer as a string.

    • toUTF8String

      public static String toUTF8String(ByteBuffer buffer)
      Convert the buffer to an UTF-8 String
      Parameters:
      buffer - The buffer to convert in flush mode. The buffer is unchanged
      Returns:
      The buffer as a string.

    • toInt

      public static int toInt(ByteBuffer buffer)
      Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an IllegalArgumentException is thrown
      Parameters:
      buffer - A buffer containing an integer in flush mode. The position is not changed.
      Returns:
      an int

    • toInt

      public static int toInt(ByteBuffer buffer, int position, int length)
      Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an IllegalArgumentException is thrown
      Parameters:
      buffer - A buffer containing an integer in flush mode. The position is not changed.
      position - the position in the buffer to start reading from
      length - the length of the buffer to use for conversion
      Returns:
      an int of the buffer bytes

    • takeInt

      public static int takeInt(ByteBuffer buffer)
      Convert buffer to an integer. Parses up to the first non-numeric character. If no number is found an IllegalArgumentException is thrown
      Parameters:
      buffer - A buffer containing an integer in flush mode. The position is updated.
      Returns:
      an int

    • toLong

      public static long toLong(ByteBuffer buffer)
      Convert buffer to an long. Parses up to the first non-numeric character. If no number is found an IllegalArgumentException is thrown
      Parameters:
      buffer - A buffer containing an integer in flush mode. The position is not changed.
      Returns:
      an int

    • putHexInt

      public static void putHexInt(ByteBuffer buffer, int n)

    • putDecInt

      public static void putDecInt(ByteBuffer buffer, int n)

    • putDecLong

      public static void putDecLong(ByteBuffer buffer, long n)

    • toBuffer

      public static ByteBuffer toBuffer(int value)

    • toBuffer

      public static ByteBuffer toBuffer(long value)

    • toBuffer

      public static ByteBuffer toBuffer(String s)

    • toBuffer

      public static ByteBuffer toBuffer(String s, Charset charset)

    • toBuffer

      public static ByteBuffer toBuffer(byte[] array)
      Create a new ByteBuffer using provided byte array.
      Parameters:
      array - the byte array to back buffer with.
      Returns:
      ByteBuffer with provided byte array, in flush mode

    • toBuffer

      public static ByteBuffer toBuffer(byte[] array, int offset, int length)
      Create a new ByteBuffer using the provided byte array.
      Parameters:
      array - the byte array to use.
      offset - the offset within the byte array to use from
      length - the length in bytes of the array to use
      Returns:
      ByteBuffer with provided byte array, in flush mode

    • toBuffer

      public static ByteBuffer toBuffer(Resource resource, boolean direct) throws IOException
      Throws:
      IOException

    • toDirectBuffer

      public static ByteBuffer toDirectBuffer(String s)

    • toDirectBuffer

      public static ByteBuffer toDirectBuffer(String s, Charset charset)

    • toMappedBuffer

      public static ByteBuffer toMappedBuffer(Path path) throws IOException
      Throws:
      IOException

    • toMappedBuffer

      public static ByteBuffer toMappedBuffer(Path filePath, long pos, long len) throws IOException
      Throws:
      IOException

    • toMappedBuffer

      public static ByteBuffer toMappedBuffer(Resource resource) throws IOException
      Throws:
      IOException

    • toMappedBuffer

      public static ByteBuffer toMappedBuffer(Resource resource, long pos, long len) throws IOException
      Throws:
      IOException

    • toSummaryString

      public static String toSummaryString(ByteBuffer buffer)

    • toDetailString

      public static String toDetailString(ByteBuffer[] buffer)

    • toDetailString

      public static String toDetailString(ByteBuffer buffer)
      Convert Buffer to a detail debug string of pointers and content
      Parameters:
      buffer - the buffer to generate a detail string from
      Returns:
      A string showing the pointers and content of the buffer

    • toIDString

      public static String toIDString(ByteBuffer buffer)
      Convert Buffer to string ID independent of content
      Parameters:
      buffer - the buffet to generate a string ID from
      Returns:
      A string showing the buffer ID

    • toHexSummary

      public static String toHexSummary(ByteBuffer buffer)
      Convert buffer to a Hex Summary String.
      Parameters:
      buffer - the buffer to generate a hex byte summary from
      Returns:
      A string showing a summary of the content in hex

    • toHexString

      public static String toHexString(ByteBuffer buffer)
      Convert buffer to a Hex String.
      Parameters:
      buffer - the buffer to generate a hex byte summary from
      Returns:
      A hex string

    • putCRLF

      public static void putCRLF(ByteBuffer buffer)

    • isPrefix

      public static boolean isPrefix(ByteBuffer prefix, ByteBuffer buffer)

    • ensureCapacity

      public static ByteBuffer ensureCapacity(ByteBuffer buffer, int capacity)