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 |
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. |
protected void | finalize() |
byte[] | getBytes()
Returns byte[] that holds all buffered data in its first getLength() bytes.
|
InputStream | getInputStream()
Returns InputSream for reading buffered data. |
int | getLength()
Returns number of bytes buffered so far. |
OutputStream | getOutputStream()
Returns OutputStream filling this buffer. |
String | getString(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(InputStream is)
Reads all available data from input stream. |
void | seek(int offset)
Repositions InputStream at given offset within buffered data. |
void | setTempDirectory(File dir)
Override directory to create temporary file in.
|
void | truncate(int offset)
Truncates buffered data to specified size. |
void | writeTo(OutputStream os)
Writes efficiently whole content to output stream. |
void | writeTo(OutputStream os, int start_offset, int length)
Writes efficiently part of the content to output stream. |
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.
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.
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.
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.
public void close()
Clears all data and closes/deletes backing temporary file if used.
Throws: IOException when something goes wrong.
protected void finalize()
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
public InputStream getInputStream()
Returns InputSream for reading buffered data.
Returns: InputSream for reading buffered data.
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() .
public OutputStream getOutputStream()
Returns OutputStream filling this buffer.
Returns: OutputStream for writing in the buffer.
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.
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
public void readFrom(InputStream is)
Reads all available data from input stream.
Parameters: is
Throws: IOException
public void seek(int offset)
Repositions InputStream at given offset within buffered data.
Throws: IOException when something goes wrong.
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
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.
public void writeTo(OutputStream os)
Writes efficiently whole content to output stream.
Parameters: os OutputStream to write to
Throws: IOException
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.