org.lenskit.util.io

## Class StagedWrite

• java.lang.Object
• org.lenskit.util.io.StagedWrite
• All Implemented Interfaces:
java.io.Closeable, java.lang.AutoCloseable

public class StagedWrite
extends java.lang.Object
implements java.io.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:

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


The rename operation is atomic, so outside code will either see the old target file (or lack thereof), or the entire contents of the new target file; it will not see any intermediate states. It is possible that this code will fail on old versions of Windows, or on certain file systems; if you encounter problems with it, especially if it raises AtomicMoveNotSupportedException, please file a bug report.

• ### Method Summary

All Methods
Modifier and Type Method and Description
static StagedWrite begin(java.io.File target)
Begin a staged file writing operation.
static StagedWrite begin(java.nio.file.Path 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.
java.nio.file.Path getStagingFile()
Get the working file for this staging file.
java.nio.file.Path getTargetFile()
Get the target file for this staging file.
java.io.OutputStream 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(java.nio.file.Path target)

Begin a staged file writing operation.

Parameters:
target - The file to write.
Returns:
A staged file
• #### begin

public static StagedWrite begin(java.io.File target)

Begin a staged file writing operation.

Parameters:
target - The file to write.
Returns:
A staged file
• #### getTargetFile

public java.nio.file.Path getTargetFile()

Get the target file for this staging file.

Returns:
The target file that will be written.
• #### getStagingFile

public java.nio.file.Path 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 java.io.OutputStream openOutputStream()
throws java.io.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:
java.io.IOException - if there is an error opening the output stream.
• #### commit

public void commit()
throws java.io.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:
java.io.IOException - if there is an error moving the file.
• #### close

public void close()
throws java.io.IOException

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, or use the staged write in a try-with-resources block.

Specified by:
close in interface java.io.Closeable
Specified by:
close in interface java.lang.AutoCloseable
Throws:
java.io.IOException