Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> mortbay >> [ util overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---

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.

---

Nested Class Summary
(package private)  class	TempByteHolder.InputStream           Internal implementation of InputStream used to read buffered data.
(package private)  class	TempByteHolder.OutputStream           Internal implementation of java.io.OutputStream used to fill the byte buffer.

 

Field Summary
(package private)  int	_file_high           offset of first byte after memory buffer
(package private)  boolean	_file_mode           buffer to use
(package private)  int	_file_pos           offset of fist byte to be read
(package private)  TempByteHolder.InputStream	_input_stream           Instance of InputStream is cached and reused.
(package private)  int	_mark_pos           current temp file seek offset; -1 = unknown
(package private)  byte[]	_memory_buffer
(package private)  TempByteHolder.OutputStream	_output_stream           Instance of OutputStream is cached and reused.
(package private)  int	_read_pos           offset of next byte to be writen; number of bytes written
(package private)  java.io.File	_temp_directory           Temporary directory to be used, or null for system default
(package private)  java.io.RandomAccessFile	_tempfile           Temporary file or null when none is used yet
(package private)  java.io.File	_tempfilef           File object representing temporary file.
(package private)  int	_window_high           offset of first byte in memory buffer
(package private)  int	_window_low           size of memory buffer
(package private)  int	_window_size           false: memory buffer mode (small data) true: temp file mode (large data)
(package private)  int	_write_pos           offset of fist byte not yet written to temp file

 

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.
private static boolean	contained(int range1_low, int range1_high, int range2_low, int range2_high)
private  void	createTempFile()           Create tempfile if it does not already exist
void	finalize()           Called on an object by the Virtual Machine at most once, at some point after the Object is determined unreachable but before it is destroyed.
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[].
private static int	max(int a, int b)           Simple maximum for 2 ints
private static int	min(int a, int b)           Simple minimum for 2 ints
private static int	min(int a, int b, int c)           Simple minimum for 3 ints
private  void	moveWindow(int start_offset)           Move file window, synchronizing data with file.
void	readFrom(java.io.InputStream is)           Reads all available data from input stream.
private  void	readFromTempFile(int at_offset, byte[] data, int offset, int len)           Read chunk of data from specified offset in tempfile
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.
private  void	writeToTempFile(int at_offset, byte[] data, int offset, int len)           Write chunk of data at specified offset in temp file.

 

Methods inherited from class java.lang.Object

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

 

Field Detail

_memory_buffer

byte[] _memory_buffer

---

_file_mode

boolean _file_mode

buffer to use

---

_window_size

int _window_size

false: memory buffer mode (small data) true: temp file mode (large data)

---

_window_low

int _window_low

size of memory buffer

---

_window_high

int _window_high

offset of first byte in memory buffer

---

_file_high

int _file_high

offset of first byte after memory buffer

---

_write_pos

int _write_pos

offset of fist byte not yet written to temp file

---

_read_pos

int _read_pos

offset of next byte to be writen; number of bytes written

---

_file_pos

int _file_pos

offset of fist byte to be read

---

_mark_pos

int _mark_pos

current temp file seek offset; -1 = unknown

---

_output_stream

TempByteHolder.OutputStream _output_stream

Instance of OutputStream is cached and reused.

---

_input_stream

TempByteHolder.InputStream _input_stream

Instance of InputStream is cached and reused.

---

_temp_directory

java.io.File _temp_directory

Temporary directory to be used, or null for system default

---

_tempfilef

java.io.File _tempfilef

File object representing temporary file.

---

_tempfile

java.io.RandomAccessFile _tempfile

Temporary file or null when none is used yet

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

---

TempByteHolder

public TempByteHolder(byte[] byte_array)

Creates a new instance of TempByteHolder using passed byte[] 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.

Method Detail

finalize

public void finalize()

Description copied from class: java.lang.Object

Called on an object by the Virtual Machine at most once, at some point after the Object is determined unreachable but before it is destroyed. You would think that this means it eventually is called on every Object, but this is not necessarily the case. If execution terminates abnormally, garbage collection does not always happen. Thus you cannot rely on this method to always work. For finer control over garbage collection, use references from the java.lang.ref package.

Virtual Machines are free to not call this method if they can determine that it does nothing important; for example, if your class extends Object and overrides finalize to do simply super.finalize().

finalize() will be called by a java.lang.Thread that has no locks on any Objects, and may be called concurrently. There are no guarantees on the order in which multiple objects are finalized. This means that finalize() is usually unsuited for performing actions that must be thread-safe, and that your implementation must be use defensive programming if it is to always work.

If an Exception is thrown from finalize() during garbage collection, it will be patently ignored and the Object will still be destroyed.

It is allowed, although not typical, for user code to call finalize() directly. User invocation does not affect whether automatic invocation will occur. It is also permitted, although not recommended, for a finalize() method to "revive" an object by making it reachable from normal code again.

Unlike constructors, finalize() does not get called for an object's superclass unless the implementation specifically calls super.finalize().

The default implementation does nothing.

---

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.

---

seek

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

Repositions InputStream at given offset within buffered data.

---

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.

---

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.

---

getLength

public int getLength()

Returns number of bytes buffered so far.

---

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.

---

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.

---

getString

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

Returns buffered data as String using given character encoding.

---

getOutputStream

public java.io.OutputStream getOutputStream()

Returns OutputStream filling this buffer.

---

getInputStream

public java.io.InputStream getInputStream()

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.

---

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.

---

readFrom

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

Reads all available data from input stream.

---

createTempFile

private void createTempFile()
                     throws java.io.IOException

Create tempfile if it does not already exist

---

writeToTempFile

private void writeToTempFile(int at_offset,
                             byte[] data,
                             int offset,
                             int len)
                      throws java.io.IOException

Write chunk of data at specified offset in temp file. Marks data as big. Updates high water mark on tempfile content.

---

readFromTempFile

private void readFromTempFile(int at_offset,
                              byte[] data,
                              int offset,
                              int len)
                       throws java.io.IOException

Read chunk of data from specified offset in tempfile

---

moveWindow

private void moveWindow(int start_offset)
                 throws java.io.IOException

Move file window, synchronizing data with file. Works somewhat like memory-mapping a file. This one was nightmare to write :-)

---

min

private static int min(int a,
                       int b)

Simple minimum for 2 ints

---

max

private static int max(int a,
                       int b)

Simple maximum for 2 ints

---

min

private static int min(int a,
                       int b,
                       int c)

Simple minimum for 3 ints

---

contained

private static boolean contained(int range1_low,
                                 int range1_high,
                                 int range2_low,
                                 int range2_high)

---

Overview  Package   Class  Use  Deprecated  Index
Home >> All >> org >> mortbay >> [ util overview ]	PREV CLASS  NEXT CLASS
SUMMARY:  JAVADOC |  SOURCE |  DOWNLOAD | NESTED | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

---