org.mortbay.util
Class TempByteHolder

java.lang.Object
  |
  +--org.mortbay.util.TempByteHolder

public class TempByteHolder

extends java.lang.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(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.

TempByteHolder(int in_memory_capacity)
Creates a new instance of TempByteHolder allocating memory buffer of given capacity.

Method Summary

void	clear() Erases all unread buffered data and prepares for next use cycle.
void	close() Clears all data and closes/deletes backing temporary file if used.
void	finalize()
byte[]	getBytes() Returns byte[] that holds all buffered data in its first getLength() bytes.
java.io.InputStream	getInputStream() Returns InputSream for reading buffered data.
int	getLength() Returns number of bytes buffered so far.
java.io.OutputStream	getOutputStream() Returns OutputStream filling this buffer.
java.lang.String	getString(java.lang.String character_encoding) Returns buffered data as String using given character encoding.
boolean	isLarge() Tells whether buffered data is small enough to fit in memory buffer so that it can be returned as byte[].
void	readFrom(java.io.InputStream is) Reads all available data from input stream.
void	seek(int offset) Repositions InputStream at given offset within buffered data.
void	setTempDirectory(java.io.File dir) Override directory to create temporary file in.
void	truncate(int offset) Truncates buffered data to specified size.
void	writeTo(java.io.OutputStream os) Writes efficiently whole content to output stream.
void	writeTo(java.io.OutputStream os, int start_offset, int length) Writes efficiently part of the content to output stream.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

finalize

public void finalize()

Overrides:

finalize in class java.lang.Object

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()
           throws java.io.IOException

Clears all data and closes/deletes backing temporary file if used.

Throws:

java.io.IOException - when something goes wrong.

seek

public void seek(int offset)
          throws java.io.IOException

Repositions InputStream at given offset within buffered data.

Throws:

java.io.IOException - when something goes wrong.

truncate

public void truncate(int offset)
              throws java.io.IOException

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.

java.io.IOException

setTempDirectory

public void setTempDirectory(java.io.File dir)
                      throws java.io.IOException

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:

java.io.IOException

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() .

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(String)

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:

java.lang.IllegalStateException - when data is too big to be read this way.

See Also:

isLarge(), getLength(), getString(String), getInputStream()

getString

public java.lang.String getString(java.lang.String character_encoding)
                           throws java.io.UnsupportedEncodingException

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:

java.lang.IllegalStateException - when data is too large to be read this way.

java.io.UnsupportedEncodingException - when this encoding is not supported.

getOutputStream

public java.io.OutputStream getOutputStream()

Returns OutputStream filling this buffer.

Returns:

OutputStream for writing in the buffer.

getInputStream

public java.io.InputStream getInputStream()

Returns InputSream for reading buffered data.

Returns:

InputSream for reading buffered data.

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException

Writes efficiently whole content to output stream.

Parameters:

os - OutputStream to write to

Throws:

java.io.IOException

writeTo

public void writeTo(java.io.OutputStream os,
                    int start_offset,
                    int length)
             throws java.io.IOException

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:

java.io.IOException

readFrom

public void readFrom(java.io.InputStream is)
              throws java.io.IOException

Reads all available data from input stream.

Parameters:

is -

Throws:

java.io.IOException