org.grouplens.lenskit.util.io

Class StagedWrite

java.lang.Object

org.grouplens.lenskit.util.io.StagedWrite

All Implemented Interfaces:

Closeable, AutoCloseable

public class StagedWrite
extends Object
implements Closeable

Helper to do staged file writes. In a staged write, code first writes the output to a temporary file, then renames the temporary file on top of the target file. To use this file:

 StagedWrite stage = StagedWrite.begin(outputFile);
 try {
     OutputStream stream = stage.openOutputStream();
     // write to stream
     stream.close();
     stage.commit();
 } finally {
     stage.close();
 }

The logic used to implement this class is subject to race conditions, so it should not be used when multiple threads or processes may attempt to write the same file. In LensKit 3.0, the race condition will be removed on systems exposing POSIX file system semantics, but the APIs needed for us to provide that capability are not present on Java 6.

Since:

2.1

Method Summary

Modifier and Type	Method and Description
static StagedWrite	begin(File target) Begin a staged file writing operation.
void	close() Clean up the staged write, deleting the staging file if it still exists.
void	commit() Complete the staging write by replacing the target file with the staging file.
File	getStagingFile() Get the working file for this staging file.
File	getTargetFile() Get the target file for this staging file.
FileOutputStream	openOutputStream() Open an output stream for the staging file.

Methods inherited from class java.lang.Object

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

Method Detail

begin

public static StagedWrite begin(File target)

Begin a staged file writing operation.

Parameters:

target - The file to write.

Returns:

A staged file

getTargetFile

public File getTargetFile()

Get the target file for this staging file.

Returns:

The target file that will be written.

getStagingFile

public File getStagingFile()

Get the working file for this staging file. Code doing staged file writes should write to this file.

Returns:

The working file.

openOutputStream

public FileOutputStream openOutputStream()
                                  throws IOException

Open an output stream for the staging file. This method cannot be called multiple times.

Returns:

An output stream to write to the staging file. This output stream must be closed before calling commit().

Throws:

IOException - if there is an error opening the output stream.

commit

public void commit()
            throws IOException

Complete the staging write by replacing the target file with the staging file. Any streams or channels used to write the file must be closed and/or flushed prior to calling this method.

Throws:

IOException - if there is an error moving the file.

close

public void close()

Clean up the staged write, deleting the staging file if it still exists. It is safe to call this method multiple times, and safe to call it after calling commit(). Typical use of a staged write will call this method in a finally block.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable