netscape.ldap.util
Class ByteBuf

java.lang.Object
  |
  +--netscape.ldap.util.ByteBuf

public final class ByteBuf

extends java.lang.Object

implements java.io.Serializable

This class is similar to the java.lang.StringBuffer class. Instead of storing a string, an object of this class stores an array of bytes. (This is referred to as a "byte buffer".)

This class also differs from StringBuffer in the following ways:

• None of the methods are synchronized. You cannot share a byte buffer among multiple threads.
• Converting to a String requires a copy of the character data.
• In order to speed up memory allocation, Alloc and Recycle methods are provided. You can "recycle" any ByteBuf objects you no longer need by using the Recycle method. Calling the Alloc method will reuse objects that have been "recycled." To To clear out the cache of these "recycled" objects, use the EmptyRecycler method.
• Additional "helper" methods are provided (for example, functions for comparing data).

See Also:

Serialized Form

Constructor Summary

ByteBuf()
Constructs an empty byte buffer with the default length of 16.

ByteBuf(byte[] bytes, int offset, int length)
Constructs a byte buffer with the specified length.

ByteBuf(int length)
Constructs an empty byte buffer with the specified initial length.

ByteBuf(java.lang.String str)
Constructs a byte buffer with the specified initial value.

Method Summary

ByteBuf	append(boolean b) Appends a boolean to the end of this byte buffer.
ByteBuf	append(byte b) Appends a byte to the end of this byte buffer.
ByteBuf	append(byte[] str) Appends an array of bytes to the end of this byte buffer.
ByteBuf	append(byte[] str, int offset, int len) Appends a part of an array of bytes to the end of this byte buffer.
ByteBuf	append(ByteBuf buf) Appends a byte buffer to the end of this byte buffer.
ByteBuf	append(double d) Appends a double to the end of this byte buffer.
ByteBuf	append(float f) Appends a float to the end of this byte buffer.
ByteBuf	append(int i) Appends an integer to the end of this byte buffer.
ByteBuf	append(long l) Appends a long value to the end of this byte buffer.
ByteBuf	append(java.lang.Object obj) Appends an object to the end of this byte buffer.
ByteBuf	append(java.lang.String str) Appends a string to the end of this byte buffer.
byte	byteAt(int index) Returns the byte at the specified index.
int	capacity() Returns the current capacity of the byte buffer.
void	ensureCapacity(int minimumCapacity) Ensures that the capacity of the buffer is at least equal to the specified minimum capacity.
void	getBytes(int srcBegin, int srcEnd, byte[] dst, int dstBegin) Copies the bytes (from the section of the byte buffer from the index srcBegin to the index srcEnd - 1 ) into the specified byte array.
int	length() Returns the length (character count) of the byte buffer.
int	read(java.io.InputStream file, int max_bytes) Invokes the InputStream.read method and appends the the bytes read to this byte buffer.
int	read(java.io.RandomAccessFile file, int max_bytes) Invokes the RandomAccessFile.read method, appending the bytes read to this byte buffer.
void	setByteAt(int index, byte b) Sets the value of the byte at the specified index.
void	setLength(int newLength) Sets the length of the byte buffer.
byte[]	toBytes() Returns the data in the byte buffer as a byte array.
java.lang.String	toString() Returns the data in the byte buffer to a string.
void	write(java.io.OutputStream out) Writes the contents of the byte buffer to the specified output stream.
void	write(java.io.RandomAccessFile out) Writes the contents of the byte buffer to the specified RandomAccessFile object.

Methods inherited from class java.lang.Object

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

Constructor Detail

ByteBuf

public ByteBuf()

Constructs an empty byte buffer with the default length of 16.

ByteBuf

public ByteBuf(int length)

Constructs an empty byte buffer with the specified initial length.

Parameters:

length - initial number of bytes that this buffer should hold

ByteBuf

public ByteBuf(java.lang.String str)

Constructs a byte buffer with the specified initial value. The new byte buffer is 16 bytes longer than the initial value.

Parameters:

str - initial value that this buffer should hold

ByteBuf

public ByteBuf(byte[] bytes,
               int offset,
               int length)

Constructs a byte buffer with the specified length. An initial value is stored in this buffer, starting at the specified offset.

Parameters:

bytes - array of bytes to initially store in the buffer

offset - index where you want the initial value to start in the array

length - length of the buffer to allocate

Method Detail

length

public int length()

Returns the length (character count) of the byte buffer.

capacity

public int capacity()

Returns the current capacity of the byte buffer. The capacity is the amount of storage available for newly inserted bytes. If the capacity is exceeded, more space will be allocated.

ensureCapacity

public void ensureCapacity(int minimumCapacity)

Ensures that the capacity of the buffer is at least equal to the specified minimum capacity.

Parameters:

minimumCapacity - the minimum number of bytes that you want the byte buffer to hold

setLength

public void setLength(int newLength)

Sets the length of the byte buffer. If you set a length that is shorter than the current length, bytes at the end of the buffer are lost. If you increase the length of the buffer, the values of the new bytes in the buffer are set to 0.

Parameters:

newLength - the new length of the buffer

Throws:

StringIndexOutOfBoundsException - You have specified an invalid length.

byteAt

public byte byteAt(int index)

Returns the byte at the specified index. The value of an index can range from 0 to length - 1.

Parameters:

index - index of the byte to find

Throws:

StringIndexOutOfBoundsException - You have specified an invalid index.

getBytes

public void getBytes(int srcBegin,
                     int srcEnd,
                     byte[] dst,
                     int dstBegin)

Copies the bytes (from the section of the byte buffer from the index srcBegin to the index srcEnd - 1 ) into the specified byte array. The copied bytes are inserted in the byte array at the index specified by dstBegin. Both srcBegin and srcEnd must be valid indexes in the buffer.

Parameters:

srcBegin - index identifying the start of the section of the byte buffer to copy

srcEnd - index identifying the end of the section of the byte buffer to copy. (Copy all bytes before the byte identified by this index.)

dst - the byte array to copy the data to

dstBegin - index of the byte array identifying the location to which the byte buffer is copied

Throws:

StringIndexOutOfBoundsException - You specified an invalid index into the buffer.

setByteAt

public void setByteAt(int index,
                      byte b)

Sets the value of the byte at the specified index.

Parameters:

index - the index of the byte to set

b - the new value to set

Throws:

StringIndexOutOfBoundsException - You have specified an invalid index.

append

public ByteBuf append(java.lang.Object obj)

Appends an object to the end of this byte buffer.

Parameters:

obj - the object to append to the buffer

Returns:

the same ByteBuf object (not a new object) with the string representation of the specified object appended.

append

public ByteBuf append(java.lang.String str)

Appends a string to the end of this byte buffer. This method appends one byte for each character in the string. The upper 8 bits of the character are stripped off.

If you want to retain all bits in the character (not just the lower 8 bits), use append(String.getBytes()) instead.

Parameters:

str - the string that you want appended to the buffer

Returns:

the same ByteBuf object (not a new object) with the specified string appended

append

public ByteBuf append(byte[] str)

Appends an array of bytes to the end of this byte buffer.

Parameters:

str - the array of bytes to append to this buffer

Returns:

the same ByteBuf object (not a new object) with the specified bytes appended.

append

public ByteBuf append(byte[] str,
                      int offset,
                      int len)

Appends a part of an array of bytes to the end of this byte buffer.

Parameters:

str - the array of bytes to append to this buffer

offset - the index in the array marking the start of the section to copy

len - the number of bytes to add

Returns:

the same ByteBuf object (not a new object) with the specified section of the byte array appended

append

public ByteBuf append(ByteBuf buf)

Appends a byte buffer to the end of this byte buffer.

Parameters:

buf - the byte buffer to append to this buffer

Returns:

the original ByteBuf object (not a new object) with bytes from the specified byte buffer appended.

append

public ByteBuf append(boolean b)

Appends a boolean to the end of this byte buffer.

Parameters:

b - the boolean value that you want appended to this buffer

Returns:

the original ByteBuf object (not a new object) with bytes from the string representation of the boolean value appended.

append

public ByteBuf append(byte b)

Appends a byte to the end of this byte buffer.

Parameters:

ch - the byte to append to this buffer

Returns:

the original ByteBuf object (not a new object) with the specified byte appended.

append

public ByteBuf append(int i)

Appends an integer to the end of this byte buffer.

Parameters:

i - the integer to append to this byte buffer

Returns:

the original ByteBuf object (not a new object) with the string representation of the specified integer appended.

append

public ByteBuf append(long l)

Appends a long value to the end of this byte buffer.

Parameters:

l - the long value to append to this buffer

Returns:

the original ByteBuf object (not a new object) with the string representation of the specified long value appended.

append

public ByteBuf append(float f)

Appends a float to the end of this byte buffer.

Parameters:

f - the float value to append to this buffer

Returns:

the original ByteBuf object (not a new object) with the string representation of the specified float value appended.

append

public ByteBuf append(double d)

Appends a double to the end of this byte buffer.

Parameters:

d - the double value to append to this buffer

Returns:

the original ByteBuf object (not a new object) with the string representation of the specified double value appended.

toString

public java.lang.String toString()

Returns the data in the byte buffer to a string.

Overrides:

toString in class java.lang.Object

Returns:

the string representation of the data in the byte buffer.

toBytes

public byte[] toBytes()

Returns the data in the byte buffer as a byte array.

Returns:

the byte array containing data in the byte buffer.

read

public int read(java.io.InputStream file,
                int max_bytes)
         throws java.io.IOException

Invokes the InputStream.read method and appends the the bytes read to this byte buffer.

Parameters:

file - the input stream from which to read the bytes

max_bytes - the maximum number of bytes to read into the byte buffer

Returns:

the number of bytes read, or -1 if there is no more data to read.

Throws:

java.io.IOException - An I/O error has occurred.

read

public int read(java.io.RandomAccessFile file,
                int max_bytes)
         throws java.io.IOException

Invokes the RandomAccessFile.read method, appending the bytes read to this byte buffer.

Parameters:

file - the RandomAccessFile object from which to read the bytes

max_bytes - the maximum number of bytes to read into the byte buffer

Returns:

the number of bytes read, or -1 if there is no more data to read.

Throws:

java.io.IOException - An I/O error has occurred.

write

public void write(java.io.OutputStream out)
           throws java.io.IOException

Writes the contents of the byte buffer to the specified output stream.

Parameters:

out - the output stream

Throws:

java.io.IOException - An I/O error has occurred.

write

public void write(java.io.RandomAccessFile out)
           throws java.io.IOException

Writes the contents of the byte buffer to the specified RandomAccessFile object.

Parameters:

out - the RandomAccessFile object dexception IOException An I/O error has occurred.