ccs.utils
Class SwappingBuffer

java.lang.Object
  java.io.OutputStream
      ccs.utils.SwappingBuffer

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable

Direct Known Subclasses:

RepeatingSwappingBuffer

public class SwappingBuffer
extends java.io.OutputStream

A dual-mode buffer that efficiently stores an arbitrary amount of transient data. For small amounts, it uses memory. However, once the buffer size passes a threshold, it automatically copies this to a disk file and uses that from then on. The disk file is encrypted with a throw-away key; in this way if the app crashes before it has wiped any disk file, there is no security breach.

A SwappingBuffer is strictly a "single-shot" object. It has 4 lifecycle stages: writable, unwritable, read-committed and dead. It proceeds through each of these stages, in the above order:

• Writable: you can place data into the buffer.
• Calling close makes the buffer unwritable. No further writes are allowed.
• getInputStream or getByteArray may be called from either the writable or unwritable stage, but not read-committed or dead. They make the buffer read-committed. No further writes are allowed, and neither of the above methods may be called again.
• Alternatively, writeTo may be called from either the writable or unwritable stages, and takes the buffer straight to stage "dead".

These restrictive rules prevent the buffer from having to duplicate large chunks of memory, which is inefficient.

This class is MT-UNSAFE, and must not be accessible by multiple threads.

Any app which uses a SwappingBuffer MUST call FileKiller.waitForCompletion as part of its shutdown process.

Nested Class Summary

protected static class	SwappingBuffer.DestructiveBAIS
protected static class	SwappingBuffer.PeekableBAOS

Field Summary

protected SwappingBuffer.PeekableBAOS	baos
protected BCCHBlockCipher	cipher
protected CipherOutputStream	cos
static int	DEAD Lifecycle stage.
static int	DEFAULTSWAP The default buffer length after which the buffer is swapped to disk; 512K.
protected java.io.File	f
protected boolean	isFile
java.lang.String	mimeType The MIME type of the content of this buffer.
protected int	phase
static int	READCOMMITTED Lifecycle stage.
static int	UNWRITABLE Lifecycle stage.
protected byte[]	wad
static int	WRITABLE Lifecycle stage.

Constructor Summary

SwappingBuffer()
Creates a new SwappingBuffer with a default threshold (512K) and default auto-destruct.

SwappingBuffer(byte[] contents)
Creates a new "pre-filled" SwappingBuffer whose contents are the supplied buffer.

SwappingBuffer(java.io.InputStream srcIS, long total)
Creates a new "pre-filled" SwappingBuffer which wraps the supplied InputStream.

SwappingBuffer(int threshold)
Creates a new SwappingBuffer with the supplied threshold and default auto-destruct.

SwappingBuffer(int threshold, int autoDestruct)
Creates a new SwappingBuffer with the supplied threshold and auto-destruct level.

Method Summary

void	close() Closes the output stream and releases any system resources associated with it.
protected void	finalize()
void	flush() Attempts to flush the SwappingBuffer.
byte[]	getByteArray() Returns the contents of the buffer as a byte array.
java.io.File	getFile() Returns the swap file, if one is in use, otherwise null.
java.lang.String	getFilePath() Returns the path to the swap file, if one is in use, otherwise null.
java.io.InputStream	getInputStream() Returns a buffered input stream which reads from this buffer.
int	getLifecycleStage() Returns the current lifecycle stage of the SwappingBuffer: this is one of WRITABLE, UNWRITABLE, READCOMMITTED or DEAD.
boolean	isWritable() Whether the SwappingBuffer is still writable.
void	randomRead(byte[] wad, int woff, int len, long boff) Copies a part of the buffer into the supplied byte array.
long	size() returns the current length of data in the buffer.
void	write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to the output stream.
void	write(int b) Writes the specified byte to the output stream.
void	writeTo(java.io.OutputStream os) Writes the contents of the buffer to the supplied stream.

Methods inherited from class java.io.OutputStream

write

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULTSWAP

public static final int DEFAULTSWAP

The default buffer length after which the buffer is swapped to disk; 512K.

See Also:

Constant Field Values

WRITABLE

public static final int WRITABLE

Lifecycle stage. The buffer may be written to.

See Also:

Constant Field Values

UNWRITABLE

public static final int UNWRITABLE

Lifecycle stage. The buffer is closed for writing but has not been opened for reading.

See Also:

Constant Field Values

READCOMMITTED

public static final int READCOMMITTED

Lifecycle stage. The buffer is open for reading, and may not be opened for reading a second time.

See Also:

Constant Field Values

DEAD

public static final int DEAD

Lifecycle stage. The buffer has been read fully and is now scrap.

See Also:

Constant Field Values

mimeType

public java.lang.String mimeType

The MIME type of the content of this buffer. (This is a late addition to the spec and so is not always used where it should be). null by default.

baos

protected SwappingBuffer.PeekableBAOS baos

cos

protected CipherOutputStream cos

f

protected java.io.File f

wad

protected byte[] wad

isFile

protected boolean isFile

phase

protected int phase

cipher

protected BCCHBlockCipher cipher

Constructor Detail

SwappingBuffer

public SwappingBuffer()

Creates a new SwappingBuffer with a default threshold (512K) and default auto-destruct.

SwappingBuffer

public SwappingBuffer(int threshold)

Creates a new SwappingBuffer with the supplied threshold and default auto-destruct.

SwappingBuffer

public SwappingBuffer(int threshold,
                      int autoDestruct)

Creates a new SwappingBuffer with the supplied threshold and auto-destruct level.

Parameters:

threshold - The threshold at which to swap to disk.

autoDestruct - The auto-destruct level for disk files; a constant from FileKiller.

SwappingBuffer

public SwappingBuffer(byte[] contents)

Creates a new "pre-filled" SwappingBuffer whose contents are the supplied buffer. This SwappingBuffer is effectively a ByteArrayInputStream in disguise.

SwappingBuffer

public SwappingBuffer(java.io.InputStream srcIS,
                      long total)

Creates a new "pre-filled" SwappingBuffer which wraps the supplied InputStream.

Parameters:

srcIS - The InputStream to wrap.

total - The amount of data available on the stream. It is the caller's responsibility to get this right: dummy values are not acceptable. Use a DammedInputStream if necessary.

Method Detail

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException

Returns a buffered input stream which reads from this buffer. Further writes are prohibited after this call. It is more efficient to use writeTo() if this will do the job. It is important that you close the supplied stream after you've finished with it, even if you "finished" by throwing; if you don't, then on-disk cruft may build up until the application quits. For a long-running server application this constitutes a disk "leak" which could be a significant issue. We recommend using a try... finally block to ensure this happens.

Returns:

the input stream.

Throws:

java.io.IOException - if there is a problem during the process.

getByteArray

public byte[] getByteArray()

Returns the contents of the buffer as a byte array. This call will not work (i.e. return null) if the buffer has been swapped to disk. Further writes are prohibited after this call, if it succeeds.

Returns:

The buffer, if still in memory.

randomRead

public void randomRead(byte[] wad,
                       int woff,
                       int len,
                       long boff)
                throws java.io.IOException

Copies a part of the buffer into the supplied byte array. Further writes are prohibited after this call. However, this call will not read-commit the buffer. If the buffer has been copied to disk, then this call will take time proportional to boff - the encryption means that all of the file before the start of the buffer must be read and then discarded. If the buffer wraps an InputStream, this call will throw.

Parameters:

wad - The array to copy into.

woff - The offset in wad whither to start copying.

len - The number of bytes to copy.

boff - The offset in the main buffer whence to start copying.

Throws:

java.io.IOException - If the buffer is swapped to disk, and the disk access fails.

writeTo

public void writeTo(java.io.OutputStream os)
             throws java.io.IOException

Writes the contents of the buffer to the supplied stream. Further writes to the buffer are prohibited after this call. If the buffer wraps an InputStream, the InputStream will be closed.

Parameters:

os - The stream to write to.

Throws:

java.io.IOException - if the call failed.

getLifecycleStage

public int getLifecycleStage()

Returns the current lifecycle stage of the SwappingBuffer: this is one of WRITABLE, UNWRITABLE, READCOMMITTED or DEAD.

isWritable

public boolean isWritable()

Whether the SwappingBuffer is still writable.

getFilePath

public java.lang.String getFilePath()

Returns the path to the swap file, if one is in use, otherwise null.

Returns:

The file path.

getFile

public java.io.File getFile()

Returns the swap file, if one is in use, otherwise null.

Returns:

The file.

write

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

Writes the specified byte to the output stream.

Specified by:

write in class java.io.OutputStream

Parameters:

b - The byte.

Throws:

java.io.IOException - if the write fails.

write

public void write(byte[] b,
                  int off,
                  int len)
           throws java.io.IOException

Writes len bytes from the specified byte array starting at offset off to the output stream.

Overrides:

write in class java.io.OutputStream

Parameters:

b - The array.

off - The offset

len - The length.

Throws:

java.io.IOException - if the write fails.

flush

public void flush()
           throws java.io.IOException

Attempts to flush the SwappingBuffer. However, this is a null operation when the buffer in is memory, and doesn't always work properly when the buffer is written to disk; this is due to the way the Blowfishy cipher works. To ensure the stream is completely flushed you must close it.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.OutputStream

Throws:

java.io.IOException - if the flush fails.

close

public void close()
           throws java.io.IOException

Closes the output stream and releases any system resources associated with it. Done automatically when the buffer is read.

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.OutputStream

Throws:

java.io.IOException - if the close fails.

size

public long size()

returns the current length of data in the buffer.

Returns:

The length

finalize

protected void finalize()
                 throws java.io.IOException

Overrides:

finalize in class java.lang.Object

Throws:

java.io.IOException