Package org.eclipse.jetty.util

Class BufferUtil

java.lang.Object

org.eclipse.jetty.util.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

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)	Clear 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	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	isFull(java.nio.ByteBuffer buf)	Check for a non null and full buffer.
static boolean	isMappedBuffer(java.nio.ByteBuffer buffer)
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	readFrom(java.io.File file, java.nio.ByteBuffer buffer)
static void	readFrom(java.io.InputStream is, int needed, java.nio.ByteBuffer buffer)
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.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

clear

public static void clear(java.nio.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(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)

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.

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

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

isMappedBuffer

public static boolean isMappedBuffer(java.nio.ByteBuffer buffer)

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)