com.hunnysoft.jmime
Class ByteStringBuffer

java.lang.Object
  com.hunnysoft.jmime.ByteStringBuffer

public final class ByteStringBuffer
extends java.lang.Object

Class that represents a mutable sequence of single-byte characters or bytes.

This class works together with ByteString in the same way that StringBuffer works with String. The difference between StringBuffer and ByteStringBuffer is that StringBuffer contains character data only, using 16-bit Unicode code points, while ByteStringBuffer contains 8-bit character data or non-character byte data.

This class is necessary, because instances of ByteString are immutable. Therefore, to create a ByteString by concatenating several sequences of bytes, it is much more efficient to first create an instance of ByteStringBuffer, perform all the concatenation operations on it, and in the end convert it to an immutable instance of ByteString. When an instance of ByteStringBuffer is converted to an instance of ByteString by calling the ByteStringBuffer.toByteString() method, the internal byte array is passed directly to the new ByteString instance, making this operation very efficient.

Another difference between StringBuffer and ByteStringBuffer is that ByteStringBuffer does not have any synchronized methods. The lack of synchronized methods means that the methods will execute more quickly. However, it also means that you must not access a ByteStringBuffer from two different threads.

Important: This class is not intended for general use outside of Hunny JMIME. It is highly specialized, and is designed for maximum efficiency while sacrificing some safety features. The correct way -- that is, the safe way -- to use ByteStringBuffer is as follows:

1. Create an instance of ByteStringBuffer, preferrably indicating the initial size of the internal byte array.
2. Perform several append operations on the ByteStringBuffer
3. Call ByteStringBuffer.toByteString() to create a ByteString that contains the contents of the ByteStringBuffer
4. Set the reference to the ByteStringBuffer to null so that it can no longer be used. (It is now unsafe to use the ByteStringBuffer, because it shares an internal byte array with the ByteString.)

Constructor Summary

ByteStringBuffer()
Default constructor.

ByteStringBuffer(ByteString bstr)
Constructor with initial value taken from a byte string.

ByteStringBuffer(int length)
Constructor that takes initial length of internal byte array.

Method Summary

ByteStringBuffer	append(byte c) Appends a single byte to this buffer.
ByteStringBuffer	append(byte[] bytes) Appends a sequence of bytes to this buffer.
ByteStringBuffer	append(byte[] bytes, int offset, int length) Appends a sequence of bytes to this buffer.
ByteStringBuffer	append(ByteString bstr) Appends a byte string to this buffer.
ByteStringBuffer	append(char c) Appends a single character to this buffer.
ByteStringBuffer	append(double x) Appends a double value to this buffer.
ByteStringBuffer	append(float f) Appends a float value to this buffer.
ByteStringBuffer	append(int i) Appends an integer to this buffer.
ByteStringBuffer	append(long n) Appends a long integer to this buffer.
ByteStringBuffer	append(java.lang.Object obj) Appends an object to this buffer.
ByteStringBuffer	append(java.lang.String str) Appends a string to this buffer.
int	capacity() Returns the capacity of the internal byte array.
void	ensureCapacity(int n) Resizes internal byte array.
int	length() Returns the length of the buffer.
void	setLength(int newLength) Sets the length of the buffer.
ByteString	toByteString() Returns byte string with same contents as this buffer.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

ByteStringBuffer

public ByteStringBuffer()

Default constructor.

ByteStringBuffer

public ByteStringBuffer(int length)

Constructor that takes initial length of internal byte array.

If you know the size your buffer will eventually reach, you can eliminate the copying associated with resizing the internal byte array by specifying the initial size using this constructor.

Parameters:

length - desired initial length of internal byte array

ByteStringBuffer

public ByteStringBuffer(ByteString bstr)

Constructor with initial value taken from a byte string.

Parameters:

bstr - string to set as the initial value of the buffer

Method Detail

append

public ByteStringBuffer append(java.lang.Object obj)

Appends an object to this buffer.

Internally, this method converts the object to a String, then converts the String to bytes assuming the ISO-8859-1 character set.

Parameters:

obj - object to append

Returns:

this buffer

append

public ByteStringBuffer append(ByteString bstr)

Appends a byte string to this buffer.

Parameters:

bstr - byte string to append

Returns:

this buffer

append

public ByteStringBuffer append(java.lang.String str)

Appends a string to this buffer.

This string is converted to bytes assuming the ISO-8859-1 character set.

Parameters:

str - the string to append

Returns:

this buffer

append

public ByteStringBuffer append(byte[] bytes)

Appends a sequence of bytes to this buffer.

Parameters:

bytes - array of bytes to append

Returns:

this buffer

append

public ByteStringBuffer append(byte[] bytes,
                               int offset,
                               int length)

Appends a sequence of bytes to this buffer.

Parameters:

bytes - array containing the bytes to append

offset - offset of first byte in bytes to append

length - number of bytes to append

Returns:

this buffer

append

public ByteStringBuffer append(byte c)

Appends a single byte to this buffer.

Parameters:

c - the byte to append

Returns:

this buffer

append

public ByteStringBuffer append(char c)

Appends a single character to this buffer.

The character should be a character from the ISO-8859-1 characters set; that is, it should have a value between 0 and 256. The result of this method for a character that is not an ISO-8859-1 character is undefined.

Parameters:

c - the character to append

Returns:

this buffer

append

public ByteStringBuffer append(int i)

Appends an integer to this buffer.

Parameters:

i - the integer to append

Returns:

this buffer

append

public ByteStringBuffer append(long n)

Appends a long integer to this buffer.

Parameters:

n - long integer to append

Returns:

this buffer

append

public ByteStringBuffer append(float f)

Appends a float value to this buffer.

Parameters:

f - float value to append

Returns:

this buffer

append

public ByteStringBuffer append(double x)

Appends a double value to this buffer.

Parameters:

x - double value to append

Returns:

this buffer

capacity

public int capacity()

Returns the capacity of the internal byte array.

Returns:

capacity of the internal byte array

ensureCapacity

public void ensureCapacity(int n)

Resizes internal byte array.

If the internal byte array is smaller than the specified size, then this method will resize the internal byte array to a value that is at least the specified size.

Parameters:

n - requested size of interal byte array

length

public int length()

Returns the length of the buffer.

Returns:

current length of the buffer

setLength

public void setLength(int newLength)

Sets the length of the buffer.

Throws:

java.lang.IndexOutOfBoundsException - - if the argument is negative

toByteString

public ByteString toByteString()

Returns byte string with same contents as this buffer.

This method creates a new instance of ByteString that has the same contents as this buffer. The method passes the internal byte array directly to the new ByteString instance, making this operation very efficient.

After this method is called, the ByteStringBuffer should not be used again. (It is wise to enforce this by immediately setting the reference to null.)

Returns:

new byte string with same contents as this buffer

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object