## 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`

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