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 emtpy and will compact the buffer if there is no space.

Field Summary

Fields

Modifier and Type	Field and Description
static ByteBuffer	EMPTY_BUFFER

Constructor Summary

Constructors

Constructor and Description
BufferUtil()

Method Summary

Methods

Modifier and Type	Method and Description
static ByteBuffer	allocate(int capacity) Allocate ByteBuffer in flush mode.
static ByteBuffer	allocateDirect(int capacity) Allocate ByteBuffer in flush mode.
static void	append(ByteBuffer to, byte b) Appends a byte to a buffer
static void	append(ByteBuffer to, byte[] b, int off, int len) Append bytes to a buffer.
static int	append(ByteBuffer to, ByteBuffer b) Appends a byte to a buffer
static void	clear(ByteBuffer buffer) Clear the buffer to be empty in flush mode.
static void	clearToFill(ByteBuffer buffer) Clear the buffer to be empty in fill mode.
static boolean	compact(ByteBuffer buffer) Compact the buffer
static ByteBuffer	ensureCapacity(ByteBuffer buffer, int capacity)
static int	fill(ByteBuffer to, byte[] b, int off, int len) Like append, but does not throw BufferOverflowException
static int	flipPutFlip(ByteBuffer from, ByteBuffer to) Deprecated. use append(ByteBuffer, ByteBuffer)
static int	flipToFill(ByteBuffer buffer) Flip the buffer to fill mode.
static void	flipToFlush(ByteBuffer buffer, int position) Flip the buffer to Flush mode.
static boolean	hasContent(ByteBuffer buf) Check for a non null and non empty buffer.
static boolean	isEmpty(ByteBuffer buf) Check for an empty or null buffer.
static boolean	isFull(ByteBuffer buf) Check for a non null and full buffer.
static boolean	isPrefix(ByteBuffer prefix, ByteBuffer buffer)
static int	length(ByteBuffer buffer) Get remaining from null checked buffer
static int	put(ByteBuffer from, ByteBuffer to) Put data from one buffer into another, avoiding over/under flows
static void	putCRLF(ByteBuffer buffer)
static void	putDecInt(ByteBuffer buffer, int n)
static void	putDecLong(ByteBuffer buffer, long n)
static void	putHexInt(ByteBuffer buffer, int n)
static void	readFrom(File file, ByteBuffer buffer)
static void	readFrom(InputStream is, int needed, ByteBuffer buffer)
static int	space(ByteBuffer buffer) Get the space from the limit to the capacity
static int	takeInt(ByteBuffer buffer) Convert buffer to an integer.
static byte[]	toArray(ByteBuffer buffer) Convert a ByteBuffer to a byte array.
static ByteBuffer	toBuffer(byte[] array) Create a new ByteBuffer using provided byte array.
static ByteBuffer	toBuffer(byte[] array, int offset, int length) Create a new ByteBuffer using the provided byte array.
static ByteBuffer	toBuffer(int value)
static ByteBuffer	toBuffer(long value)
static ByteBuffer	toBuffer(Resource resource, boolean direct)
static ByteBuffer	toBuffer(String s)
static ByteBuffer	toBuffer(String s, Charset charset)
static String	toDebugString(ByteBuffer buffer) Convert buffer to a Debug String.
static String	toDetailString(ByteBuffer buffer) Convert Buffer to a detail debug string of pointers and content
static String	toDetailString(ByteBuffer[] buffer)
static ByteBuffer	toDirectBuffer(String s)
static ByteBuffer	toDirectBuffer(String s, Charset charset)
static int	toInt(ByteBuffer buffer) Convert buffer to an integer.
static long	toLong(ByteBuffer buffer) Convert buffer to an long.
static ByteBuffer	toMappedBuffer(File file)
static String	toString(ByteBuffer buffer) Convert the buffer to an ISO-8859-1 String
static String	toString(ByteBuffer buffer, Charset charset) Convert the buffer to an ISO-8859-1 String
static String	toString(ByteBuffer buffer, int position, int length, Charset charset) Convert a partial buffer to an ISO-8859-1 String
static String	toSummaryString(ByteBuffer buffer)
static String	toUTF8String(ByteBuffer buffer) Convert the buffer to an UTF-8 String
static void	writeTo(ByteBuffer buffer, 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 ByteBuffer EMPTY_BUFFER

Constructor Detail

BufferUtil

public BufferUtil()

Method Detail

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

clear

public static void clear(ByteBuffer buffer)

Clear 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)

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.

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.

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

flipPutFlip

public static int flipPutFlip(ByteBuffer from,
              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(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

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

append

public static int append(ByteBuffer to,
         ByteBuffer b)

Appends a byte to a buffer

Parameters:

to - Buffer is flush mode

b - bytes to append

fill

public static int fill(ByteBuffer to,
       byte[] b,
       int off,
       int len)

Like append, but does not throw BufferOverflowException

Parameters:

to - Buffer is flush mode

b - bytes to fill

off - offset into byte

len - length to fill

readFrom

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

Throws:

IOException

readFrom

public static void readFrom(InputStream is,
            int needed,
            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.

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.

toString

public static String toString(ByteBuffer buffer,
              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 String toString(ByteBuffer buffer,
              int position,
              int length,
              Charset charset)

Convert a partial 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.

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

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)

toDirectBuffer

public static ByteBuffer toDirectBuffer(String s)

toBuffer

public static ByteBuffer toBuffer(String s,
                  Charset charset)

toDirectBuffer

public static ByteBuffer toDirectBuffer(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

toMappedBuffer

public static ByteBuffer toMappedBuffer(File file)
                                 throws IOException

Throws:

IOException

toBuffer

public static ByteBuffer toBuffer(Resource resource,
                  boolean direct)
                           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 -

Returns:

A string showing the pointers and content of the buffer

toDebugString

public static String toDebugString(ByteBuffer buffer)

Convert buffer to a Debug String.

Parameters:

buffer -

Returns:

A string showing the escaped content of the buffer around the position and limit (marked with <<< and >>>)

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)