TempByteHolder (Jetty HTTP Server 5.1.14 API)

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

Constructors
Constructor and Description
`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

Methods
Modifier and Type	Method and Description
`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.
`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
clone, 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
```
protected 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.
    
    Throws:
    
    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

Class TempByteHolder

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TempByteHolder

TempByteHolder

TempByteHolder

Method Detail

finalize

clear

close

seek

truncate

setTempDirectory

getLength

isLarge

getBytes

getString

getOutputStream

getInputStream

writeTo

writeTo

readFrom