Package org.eclipse.jetty.util

Class BufferUtil

  • public class BufferUtil
extends java.lang.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 Summary

      Fields 
      Modifier and Type Field Description
      static java.nio.ByteBuffer EMPTY_BUFFER  

    • Constructor Summary

      Constructors 
      Constructor Description
      BufferUtil()  

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static java.nio.ByteBuffer allocate​(int capacity)
      Allocate ByteBuffer in flush mode.
      static java.nio.ByteBuffer allocateDirect​(int capacity)
      Allocate ByteBuffer in flush mode.
      static void append​(java.nio.ByteBuffer to, byte b)
      Appends a byte to a buffer
      static void append​(java.nio.ByteBuffer to, byte[] b, int off, int len)
      Append bytes to a buffer.
      static int append​(java.nio.ByteBuffer to, java.nio.ByteBuffer b)
      Appends a buffer to a buffer
      static void clear​(java.nio.ByteBuffer buffer)
      Clears the buffer to be empty in flush mode.
      static void clearToFill​(java.nio.ByteBuffer buffer)
      Clear the buffer to be empty in fill mode.
      static boolean compact​(java.nio.ByteBuffer buffer)
      Compact the buffer
      static java.nio.ByteBuffer copy​(java.nio.ByteBuffer buffer)
      Deep copy of a buffer
      static java.nio.ByteBuffer ensureCapacity​(java.nio.ByteBuffer buffer, int capacity)  
      static int fill​(java.nio.ByteBuffer to, byte[] b, int off, int len)
      Like append, but does not throw BufferOverflowException
      static int flipPutFlip​(java.nio.ByteBuffer from, java.nio.ByteBuffer to)
      Deprecated.
      use append(ByteBuffer, ByteBuffer)
      static int flipToFill​(java.nio.ByteBuffer buffer)
      Flip the buffer to fill mode.
      static void flipToFlush​(java.nio.ByteBuffer buffer, int position)
      Flip the buffer to Flush mode.
      static boolean hasContent​(java.nio.ByteBuffer buf)
      Check for a non null and non empty buffer.
      static boolean isEmpty​(java.nio.ByteBuffer buf)
      Check for an empty or null buffer.
      static boolean isEmpty​(java.nio.ByteBuffer[] buf)
      Check for an empty or null buffers.
      static boolean isFull​(java.nio.ByteBuffer buf)
      Check for a non null and full buffer.
      static boolean isMappedBuffer​(java.nio.ByteBuffer buffer)
      Deprecated.
      don't use - there is no way to reliably tell if a ByteBuffer is mapped.
      static boolean isPrefix​(java.nio.ByteBuffer prefix, java.nio.ByteBuffer buffer)  
      static boolean isTheEmptyBuffer​(java.nio.ByteBuffer buf)  
      static int length​(java.nio.ByteBuffer buffer)
      Get remaining from null checked buffer
      static int put​(java.nio.ByteBuffer from, java.nio.ByteBuffer to)
      Put data from one buffer into another, avoiding over/under flows
      static void putCRLF​(java.nio.ByteBuffer buffer)  
      static void putDecInt​(java.nio.ByteBuffer buffer, int n)  
      static void putDecLong​(java.nio.ByteBuffer buffer, long n)  
      static void putHexInt​(java.nio.ByteBuffer buffer, int n)  
      static void putIntLittleEndian​(java.nio.ByteBuffer buffer, int value)
      Put an integer little endian
      static void readFrom​(java.io.File file, java.nio.ByteBuffer buffer)  
      static void readFrom​(java.io.InputStream is, int needed, java.nio.ByteBuffer buffer)  
      static long remaining​(java.nio.ByteBuffer... buf)
      Get the remaining bytes in 0 or more buffers.
      static void reset​(java.nio.ByteBuffer buffer)
      Resets the buffer's endianness to ByteOrder.BIG_ENDIAN and clears the buffer to be empty in flush mode.
      static int space​(java.nio.ByteBuffer buffer)
      Get the space from the limit to the capacity
      static int takeInt​(java.nio.ByteBuffer buffer)
      Convert buffer to an integer.
      static byte[] toArray​(java.nio.ByteBuffer buffer)
      Convert a ByteBuffer to a byte array.
      static java.nio.ByteBuffer toBuffer​(byte[] array)
      Create a new ByteBuffer using provided byte array.
      static java.nio.ByteBuffer toBuffer​(byte[] array, int offset, int length)
      Create a new ByteBuffer using the provided byte array.
      static java.nio.ByteBuffer toBuffer​(int value)  
      static java.nio.ByteBuffer toBuffer​(long value)  
      static java.nio.ByteBuffer toBuffer​(java.lang.String s)  
      static java.nio.ByteBuffer toBuffer​(java.lang.String s, java.nio.charset.Charset charset)  
      static java.nio.ByteBuffer toBuffer​(Resource resource, boolean direct)  
      static java.lang.String toDetailString​(java.nio.ByteBuffer buffer)
      Convert Buffer to a detail debug string of pointers and content
      static java.lang.String toDetailString​(java.nio.ByteBuffer[] buffer)  
      static java.nio.ByteBuffer toDirectBuffer​(java.lang.String s)  
      static java.nio.ByteBuffer toDirectBuffer​(java.lang.String s, java.nio.charset.Charset charset)  
      static java.lang.String toHexString​(java.nio.ByteBuffer buffer)
      Convert buffer to a Hex String.
      static java.lang.String toHexSummary​(java.nio.ByteBuffer buffer)
      Convert buffer to a Hex Summary String.
      static java.lang.String toIDString​(java.nio.ByteBuffer buffer)
      Convert Buffer to string ID independent of content
      static int toInt​(java.nio.ByteBuffer buffer)
      Convert buffer to an integer.
      static int toInt​(java.nio.ByteBuffer buffer, int position, int length)
      Convert buffer to an integer.
      static long toLong​(java.nio.ByteBuffer buffer)
      Convert buffer to an long.
      static java.nio.ByteBuffer toMappedBuffer​(java.io.File file)  
      static java.nio.ByteBuffer toMappedBuffer​(java.nio.file.Path filePath, long pos, long len)  
      static java.lang.String toString​(java.nio.ByteBuffer buffer)
      Convert the buffer to an ISO-8859-1 String
      static java.lang.String toString​(java.nio.ByteBuffer buffer, int position, int length, java.nio.charset.Charset charset)
      Convert a partial buffer to a String.
      static java.lang.String toString​(java.nio.ByteBuffer buffer, java.nio.charset.Charset charset)
      Convert the buffer to an ISO-8859-1 String
      static java.lang.String toSummaryString​(java.nio.ByteBuffer buffer)  
      static java.lang.String toUTF8String​(java.nio.ByteBuffer buffer)
      Convert the buffer to an UTF-8 String
      static void writeTo​(java.nio.ByteBuffer buffer, java.io.OutputStream out)  

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • EMPTY_BUFFER

        public static final java.nio.ByteBuffer EMPTY_BUFFER

    • Constructor Detail

      • BufferUtil

        public BufferUtil()

    • Method Detail

      • allocate

        public static java.nio.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 java.nio.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

      • copy

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

      • reset

        public static void reset​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.ByteBuffer buf)
        Parameters:
        buf - the buffer to check
        Returns:
        true if buf is equal to EMPTY_BUFFER

      • isEmpty

        public static boolean isEmpty​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.ByteBuffer from,
                      java.nio.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

      • flipPutFlip

        public static int flipPutFlip​(java.nio.ByteBuffer from,
                              java.nio.ByteBuffer to)
        Deprecated.
        use append(ByteBuffer, ByteBuffer)
        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 flush mode. The buffer is flipToFill before the put and flipToFlush after.
        Returns:
        number of bytes moved

      • append

        public static void append​(java.nio.ByteBuffer to,
                          byte[] b,
                          int off,
                          int len)
                   throws java.nio.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:
        java.nio.BufferOverflowException - if unable to append buffer due to space limits

      • append

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

      • append

        public static int append​(java.nio.ByteBuffer to,
                         java.nio.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​(java.nio.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​(java.io.File file,
                            java.nio.ByteBuffer buffer)
                     throws java.io.IOException
        Throws:
        java.io.IOException

      • readFrom

        public static void readFrom​(java.io.InputStream is,
                            int needed,
                            java.nio.ByteBuffer buffer)
                     throws java.io.IOException
        Throws:
        java.io.IOException

      • writeTo

        public static void writeTo​(java.nio.ByteBuffer buffer,
                           java.io.OutputStream out)
                    throws java.io.IOException
        Throws:
        java.io.IOException

      • toString

        public static java.lang.String toString​(java.nio.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.

      • toUTF8String

        public static java.lang.String toUTF8String​(java.nio.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.

      • toString

        public static java.lang.String toString​(java.nio.ByteBuffer buffer,
                                        java.nio.charset.Charset charset)
        Convert the buffer to an ISO-8859-1 String
        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 java.lang.String toString​(java.nio.ByteBuffer buffer,
                                        int position,
                                        int length,
                                        java.nio.charset.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.

      • toInt

        public static int toInt​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.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​(java.nio.ByteBuffer buffer,
                             int n)

      • putDecInt

        public static void putDecInt​(java.nio.ByteBuffer buffer,
                             int n)

      • putDecLong

        public static void putDecLong​(java.nio.ByteBuffer buffer,
                              long n)

      • toBuffer

        public static java.nio.ByteBuffer toBuffer​(int value)

      • toBuffer

        public static java.nio.ByteBuffer toBuffer​(long value)

      • toBuffer

        public static java.nio.ByteBuffer toBuffer​(java.lang.String s)

      • toBuffer

        public static java.nio.ByteBuffer toBuffer​(java.lang.String s,
                                           java.nio.charset.Charset charset)

      • toBuffer

        public static java.nio.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 java.nio.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

      • toDirectBuffer

        public static java.nio.ByteBuffer toDirectBuffer​(java.lang.String s)

      • toDirectBuffer

        public static java.nio.ByteBuffer toDirectBuffer​(java.lang.String s,
                                                 java.nio.charset.Charset charset)

      • toMappedBuffer

        public static java.nio.ByteBuffer toMappedBuffer​(java.io.File file)
                                          throws java.io.IOException
        Throws:
        java.io.IOException

      • toMappedBuffer

        public static java.nio.ByteBuffer toMappedBuffer​(java.nio.file.Path filePath,
                                                 long pos,
                                                 long len)
                                          throws java.io.IOException
        Throws:
        java.io.IOException

      • isMappedBuffer

        @Deprecated
public static boolean isMappedBuffer​(java.nio.ByteBuffer buffer)
        Deprecated.
        don't use - there is no way to reliably tell if a ByteBuffer is mapped.
        Parameters:
        buffer - the buffer to test
        Returns:
        false

      • toBuffer

        public static java.nio.ByteBuffer toBuffer​(Resource resource,
                                           boolean direct)
                                    throws java.io.IOException
        Throws:
        java.io.IOException

      • toSummaryString

        public static java.lang.String toSummaryString​(java.nio.ByteBuffer buffer)

      • toDetailString

        public static java.lang.String toDetailString​(java.nio.ByteBuffer[] buffer)

      • toIDString

        public static java.lang.String toIDString​(java.nio.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

      • toDetailString

        public static java.lang.String toDetailString​(java.nio.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

      • toHexSummary

        public static java.lang.String toHexSummary​(java.nio.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 java.lang.String toHexString​(java.nio.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​(java.nio.ByteBuffer buffer)

      • isPrefix

        public static boolean isPrefix​(java.nio.ByteBuffer prefix,
                               java.nio.ByteBuffer buffer)

      • ensureCapacity

        public static java.nio.ByteBuffer ensureCapacity​(java.nio.ByteBuffer buffer,
                                                 int capacity)