common.io
Class AtomicOutputStream

java.lang.Object
  extended byjava.io.OutputStream
      extended bycommon.io.AtomicOutputStream

public final class AtomicOutputStream
extends java.io.OutputStream

An "atomic" output stream. It is "atomic" in the sense that the target file won't be overwritten until "close()" is called, at which point a rename is done. A point of note that for this stream to actually be atomic, "rename" needs to be atomic, such as in POSIX systems. Windows, for example, doesn't have this property, so this stream tries to do the next best thing (delete the original, then rename).

This stream works a little bit differently than other streams, in the sense that it has a second close method called rollback(). This method just discards the temporary file used to write the data and leaves the target file untouched. The only way to overwrite the target file is to call close(). If the instance is left for garbage collection, rollback() will be called during finalization, instead of close().

Since:
CC 0.9.4
Author:
Marcelo Vanzin

Constructor Summary
AtomicOutputStream(java.io.File path)
          Creates a new atomic stream.
AtomicOutputStream(java.lang.String path)
          Creates a new atomic stream.
 
Method Summary
 void close()
          Closes the temporary stream and renames the temp file to the target file.
protected  void finalize()
          For the forgetful.
 void flush()
           
 void rollback()
          Removes the temporary file without overwriting the target.
 void write(byte[] b)
           
 void write(byte[] b, int off, int len)
           
 void write(int b)
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AtomicOutputStream

public AtomicOutputStream(java.lang.String path)
                   throws java.io.IOException
Creates a new atomic stream.

See Also:
AtomicOutputStream(File)

AtomicOutputStream

public AtomicOutputStream(java.io.File path)
                   throws java.io.IOException
Creates a new atomic stream. The user must have permission to write to the directory of path, otherwise this will throw an IOException.

Parameters:
path - The path of the target file.
Throws:
java.io.IOException - If the temp file cannot be created.
Method Detail

close

public void close()
           throws java.io.IOException
Closes the temporary stream and renames the temp file to the target file. It is safe to call this method several times, or after a rollback() (it won't do anything in those cases).

Throws:
java.io.IOException - If there's a problem closing the temp stream, or renaming the temp file to the target file.

flush

public void flush()
           throws java.io.IOException
Throws:
java.io.IOException

write

public void write(byte[] b)
           throws java.io.IOException
Throws:
java.io.IOException

write

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

write

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

rollback

public void rollback()
Removes the temporary file without overwriting the target. It is safe to call this method several times, or after a close() (it won't do anything in those cases).


finalize

protected void finalize()
For the forgetful. Remember kids: streams want to be free(d).