org.mortbay.util

Class TempByteHolder

public class TempByteHolder extends Object

Temporary buffer for bytes to be used in situations where bytes need to be buffered but total size of data is not known in advance and may potentially be very large. Provides easy way to access small buffered data as byte[] or String. Enables efficient memory-only handling of small data while automatically switching to temporary file storage when data gets too big to fit in memory buffer. It is highly efficient for both byte-per-byte and block I/O. This class is not a FIFO - you can't mix reading and writing infinitely as all data keep being buffered, not just unread data. Mixing reads and writes may be inefficient in some situations but is fully supported.
Overall usage strategy: You first write data to the buffer using OutputStream returned by getOutputStream(), then examine data size using getLength() and isLarge() and either call getBytes() to get byte[], getString() to get data as String or getInputStream() to read data using stream. Instance of TempByteHolder can be safely and efficiently reused by calling clear(). When TempByteHolder is no longer needed you must call close() to ensure underlying temporary file is closed and deleted.

NOTE: For performance, this class is not synchronized. If you need thread safety, use synchronized wrapper.
This class can hold up to 2GB of data.

SECURITY NOTE: As data may be written to disk, don't use this for sensitive information.

Author: Jan Hlavat} <hlavac AT code.cz>

Constructor Summary
TempByteHolder(int in_memory_capacity)
Creates a new instance of TempByteHolder allocating memory buffer of given capacity.
TempByteHolder(byte[] byte_array)
Creates a new instance of TempByteHolder using passed byte[] as memory buffer.
TempByteHolder(byte[] byte_array, int offset, int prefilled_data_size)
Creates a new instance of TempByteHolder using passed byte[] which contains prefilled data as memory buffer.
Method Summary
voidclear()
Erases all unread buffered data and prepares for next use cycle.
voidclose()
Clears all data and closes/deletes backing temporary file if used.
protected voidfinalize()
byte[]getBytes()
Returns byte[] that holds all buffered data in its first getLength() bytes.
InputStreamgetInputStream()
Returns InputSream for reading buffered data.
intgetLength()
Returns number of bytes buffered so far.
OutputStreamgetOutputStream()
Returns OutputStream filling this buffer.
StringgetString(String character_encoding)
Returns buffered data as String using given character encoding.
booleanisLarge()
Tells whether buffered data is small enough to fit in memory buffer so that it can be returned as byte[].
voidreadFrom(InputStream is)
Reads all available data from input stream.
voidseek(int offset)
Repositions InputStream at given offset within buffered data.
voidsetTempDirectory(File dir)
Override directory to create temporary file in.
voidtruncate(int offset)
Truncates buffered data to specified size.
voidwriteTo(OutputStream os)
Writes efficiently whole content to output stream.
voidwriteTo(OutputStream os, int start_offset, int length)
Writes efficiently part of the content to output stream.

Constructor Detail

TempByteHolder

public TempByteHolder(int in_memory_capacity)
Creates a new instance of TempByteHolder allocating memory buffer of given capacity. You should use reasonably large buffer for potentionally large data to improve effect of caching for file operations (about 512 bytes).

Parameters: in_memory_capacity Size in bytes of memory buffer to allocate.

TempByteHolder

public TempByteHolder(byte[] byte_array)
Creates a new instance of TempByteHolder using passed byte[] as memory buffer.

Parameters: byte_array byte array to be used as memory buffer.

TempByteHolder

public TempByteHolder(byte[] byte_array, int offset, int prefilled_data_size)
Creates a new instance of TempByteHolder using passed byte[] which contains prefilled data as memory buffer.

Parameters: byte_array byte array to be used as memory buffer. offset offset of prefilled data in buffer. prefilled_data_size number of bytes that contain valid data.

Method Detail

clear

public void clear()
Erases all unread buffered data and prepares for next use cycle. If temporary file was used, it is not closed/deleted yet as it may be needed again.

close

public void close()
Clears all data and closes/deletes backing temporary file if used.

Throws: IOException when something goes wrong.

finalize

protected void finalize()

getBytes

public byte[] getBytes()
Returns byte[] that holds all buffered data in its first getLength() bytes. If this instance was created using (byte[]) constructor, this is the same array that has been passed to the constructor. If buffered data don't fit into memory buffer, IllegalStateException is thrown.

Returns: byte[] with data as its first getLength() bytes.

Throws: IllegalStateException when data is too big to be read this way.

See Also: isLarge getLength getString getInputStream

getInputStream

public InputStream getInputStream()
Returns InputSream for reading buffered data.

Returns: InputSream for reading buffered data.

getLength

public int getLength()
Returns number of bytes buffered so far.

Returns: total number of bytes buffered. If you need number of bytes to be read, use InputStream.available() .

getOutputStream

public OutputStream getOutputStream()
Returns OutputStream filling this buffer.

Returns: OutputStream for writing in the buffer.

getString

public String getString(String character_encoding)
Returns buffered data as String using given character encoding.

Parameters: character_encoding Name of character encoding to use for converting bytes to String.

Returns: Buffered data as String.

Throws: IllegalStateException when data is too large to be read this way. java.io.UnsupportedEncodingException when this encoding is not supported.

isLarge

public boolean isLarge()
Tells whether buffered data is small enough to fit in memory buffer so that it can be returned as byte[]. Data is considered large when it will not fit into backing memory buffer.

Returns: true when data is only accessible through InputStream interface; false when data can be also retrieved directly as byte[] or String.

See Also: getBytes getString

readFrom

public void readFrom(InputStream is)
Reads all available data from input stream.

Parameters: is

Throws: IOException

seek

public void seek(int offset)
Repositions InputStream at given offset within buffered data.

Throws: IOException when something goes wrong.

setTempDirectory

public void setTempDirectory(File dir)
Override directory to create temporary file in. Does not affect already open temp file.

Parameters: dir File object representing temporary directory. May be null which means that system default (java.io.tmpdir system property) should be used.

Throws: IOException

truncate

public void truncate(int offset)
Truncates buffered data to specified size. Can not be used to extend data. Repositions OutputStream at the end of truncated data. If current read offset or mark is past the new end of data, it is moved at the new end.

writeTo

public void writeTo(OutputStream os)
Writes efficiently whole content to output stream.

Parameters: os OutputStream to write to

Throws: IOException

writeTo

public void writeTo(OutputStream os, int start_offset, int length)
Writes efficiently part of the content to output stream.

Parameters: os OutputStream to write to start_offset Offset of data fragment to be written length Length of data fragment to be written

Throws: IOException

Copyright © 2004 Mortbay Consulting Pty. Ltd. All Rights Reserved.