All Packages  This Package  Class Hierarchy  Class Search  Index

Class calypso.util.CacheOutputStream

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

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.

public class  CacheOutputStream
     extends java.io.OutputStream
{
          // Fields 6
     protected Object bs_handle;
     protected OutputStream bs_stream;
     protected byte[] mem_cache;
     protected int mem_cache_fp;
     protected double mem_cache_increment;
     protected int mem_cache_max_size;

          // Constructors 3
     public CacheOutputStream();
     public CacheOutputStream(int);
     public CacheOutputStream(int, int);

          // Methods 13
     public void close() throws IOException;
     protected InputStream createBackingStoreInputStream() throws FileNotFoundException;
     protected void discardBackingStore();
     public synchronized void discardBuffer();
     protected void finalize();
     public void flush() throws IOException;
     protected void growMemCache(int) throws IOException;
     protected void increaseCapacity(int) throws IOException;
     public InputStream makeInputStream() throws IOException, FileNotFoundException;
     protected void switchToBackingStore() throws IOException;
     public void write(byte[]) throws IOException;
     public void write(byte[], int, int) throws IOException;
     public void write(int) throws IOException;
}

• 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 Object bs_handle

• bs_stream

   protected OutputStream bs_stream

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

• write

   public void write(byte[] bytes)  throws IOException

Overrides:

write in class OutputStream

• write

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

Overrides:

write in class OutputStream

• write

   public void write(int b)  throws IOException

Overrides:

write in class OutputStream

• close

   public void close()  throws 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 OutputStream

• flush

   public void flush()  throws IOException

Overrides:

flush in class OutputStream

• increaseCapacity

   protected void increaseCapacity(int count)  throws 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 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 synchronized 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 InputStream makeInputStream()  throws IOException, 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 Object

• switchToBackingStore

   protected void switchToBackingStore()  throws 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 InputStream createBackingStoreInputStream()  throws 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.

All Packages  This Package  Class Hierarchy  Class Search  Index