org.grouplens.lenskit.util.io

## Class 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

All Methods
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