## calypso.util
Class CacheOutputStream

    java.lang.Object
      |
      +--java.io.OutputStream
            |
            +--calypso.util.CacheOutputStream

public class CacheOutputStream
extends java.io.OutputStream

This class provides buffering for arbitrarily large streams of data. It is an `OutputStream`, so you just write the data you want to cache to it. Then, when you've written all of your data (and called `close()`) you can get the data back by calling `makeInputStream()`, which returns an `InputStream`.

If you decide you don't want the data at all, you should call `discardBuffer()` as early as possible, to avoid having a temporary file stay around longer than necessary. It's not necessary to call `discardBuffer()` if you have called `makeInputStream()`; it is called automatically when that stream is closed. However, it is ok to call `discardBuffer()` than once.

So, one conservative way of using this would be:

`CacheOutputStream output = new CacheOutputStream();`
`try {`
`` ... write bytes to `output' ...
`output.close();`
`InputStream input = output.makeInputStream();`
`try {`
`` ... read bytes from `input' ...
`} finally {`
`input.close();`
`}`
`} finally {`
`output.discardBuffer();`
`}`

Implementation:

  The bytes written to the stream are buffered in memory, until a size threshold is reached, or a memory-allocation error occurs. At that point, a temporary file is created, and buffering continues there. Therefore, files are not used for small objects; this ensures that buffering of small objects is fast, but buffering of arbitrarily large objects is possible.

Field Summary
`protected java.lang.Object` | `bs_handle`
`protected java.io.OutputStream` | `bs_stream`
`protected byte[]` | `mem_cache`
`protected int` | `mem_cache_fp`
`protected double` | `mem_cache_increment`
`protected int` | `mem_cache_max_size`

Constructor Summary
`CacheOutputStream()` Creates a CacheOutputStream with default buffer sizes.
`CacheOutputStream(int max_resident_size)` Creates a CacheOutputStream with the given maximum memory usage.
`CacheOutputStream(int probable_size, int max_resident_size)` Creates a CacheOutputStream with the given initial memory buffer size, and given maximum memory usage.

Method Summary
`void` | `close()` Indicate (only) that no more data will be written in to the buffer.
`protected java.io.InputStream` | `createBackingStoreInputStream()` Assuming backing-store is in use, creates an InputStream that reads from the underlying TempFile, and will call this.discardBuffer() when that InputStream reaches EOF.
`protected void` | `discardBackingStore()` Assuming backing-store is in use, delete the underlying temp file.
`void` | `discardBuffer()` Call this when you're done with this object.
`protected void` | `finalize()` Calls discardBuffer(), in case this object was dropped without being properly shut down.
`void` | `flush()`
`protected void` | `growMemCache(int count)` Assuming the memory cache is in use, expand the mem_cache to be able to hold an additional `count' bytes if necessary.
`protected void` | `increaseCapacity(int count)` Ensure that there is room to write an additonal `count' bytes.
`java.io.InputStream` | `makeInputStream()` Returns an InputStream that returns the data previously written into this object.
`protected void` | `switchToBackingStore()` Assuming the memory cache is in use, switch to using the disk cache.
`void` | `write(byte[] bytes)`
`void` | `write(byte[] bytes, int start, int length)`
`void` | `write(int b)`

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### mem_cache

    protected byte[] mem_cache

### mem_cache_fp

    protected int mem_cache_fp

### mem_cache_max_size

    protected int mem_cache_max_size

### mem_cache_increment

    protected double mem_cache_increment

### bs_handle

    protected java.lang.Object bs_handle

### bs_stream

    protected java.io.OutputStream bs_stream

Constructor Detail

### CacheOutputStream

    public CacheOutputStream()

  Creates a CacheOutputStream with default buffer sizes.

### CacheOutputStream

    public CacheOutputStream(int max_resident_size)

  Creates a CacheOutputStream with the given maximum memory usage. If an attempt is made to buffer more than the specified number of bytes, then the memory buffer will be traded for a disk buffer.

### CacheOutputStream

    public CacheOutputStream(int probable_size,
                             int max_resident_size)

  Creates a CacheOutputStream with the given initial memory buffer size, and given maximum memory usage. If an attempt is made to buffer more than the specified number of bytes, then the memory buffer will be traded for a disk buffer.

Method Detail

### write

    public void write(byte[] bytes)
               throws java.io.IOException

  Overrides:
    write in class java.io.OutputStream

### write

    public void write(byte[] bytes,
                      int start,
                      int length)
               throws java.io.IOException

  Overrides:
    write in class java.io.OutputStream

### write

    public void write(int b)
               throws java.io.IOException

  Overrides:
    write in class java.io.OutputStream

### close

    public void close()
               throws java.io.IOException

  Indicate (only) that no more data will be written in to the buffer. After calling `close()`, one must eventually call either `makeInputStream()` or `discardBuffer()`.
  Overrides:
    close in class java.io.OutputStream

### flush

    public void flush()
               throws java.io.IOException

  Overrides:
    flush in class java.io.OutputStream

### increaseCapacity

    protected void increaseCapacity(int count)
                             throws java.io.IOException

  Ensure that there is room to write an additonal `count' bytes. If this would exceed the memory cache size, set up the disk cache.

### growMemCache

    protected void growMemCache(int count)
                         throws java.io.IOException

  Assuming the memory cache is in use, expand the mem_cache to be able to hold an additional `count' bytes if necessary.

### discardBuffer

    public void discardBuffer()

  Call this when you're done with this object. It's important that you call this if you're not planning on calling makeInputStream(); if you don't, a temp file could stay around longer than necessary.

  You must not use this CacheOutputStream object after having called discardBuffer().

  If you call makeInputStream(), you must not call discardBuffer() before you are finished with the returned stream.

### makeInputStream

    public java.io.InputStream makeInputStream()
                                        throws java.io.IOException,
                                               java.io.FileNotFoundException

  Returns an InputStream that returns the data previously written into this object. This may only be called once, and only after `close()` has been called. It is also important that the returned InputStream be closed when the caller is done with it; failure to do so could cause a temp file to stay around longer than necessary.

### finalize

    protected void finalize()

  Calls discardBuffer(), in case this object was dropped without being properly shut down.
  Overrides:
    finalize in class java.lang.Object

### switchToBackingStore

    protected void switchToBackingStore()
                                 throws java.io.IOException

  Assuming the memory cache is in use, switch to using the disk cache.

### discardBackingStore

    protected void discardBackingStore()

  Assuming backing-store is in use, delete the underlying temp file.

### createBackingStoreInputStream

    protected java.io.InputStream createBackingStoreInputStream()
                                                         throws java.io.FileNotFoundException

  Assuming backing-store is in use, creates an InputStream that reads from the underlying TempFile, and will call this.discardBuffer() when that InputStream reaches EOF.