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.