Top Description Fields Constructors Methods
org.jabref.logic.exporter

public Class AtomicFileOutputStream

extends FilterOutputStream
Class Inheritance
Imports
java.io.FileOutputStream, .FilterOutputStream, .IOException, .OutputStream, java.nio.channels.FileLock, .OverlappingFileLockException, java.nio.file.Files, .Path, .StandardCopyOption, java.nio.file.attribute.PosixFilePermission, java.util.EnumSet, .Set, org.jabref.logic.util.BackupFileType, org.jabref.logic.util.io.FileUtil, org.slf4j.Logger, .LoggerFactory
A file output stream that is similar to the standard FileOutputStream, except that all writes are first redirected to a temporary file. When the stream is closed, the temporary file (atomically) replaces the target file.

In detail, the strategy is to:

  1. Write to a temporary file (with .tmp suffix) in the same directory as the destination file.
  2. Create a backup (with .bak suffix) of the original file (if it exists) in the same directory.
  3. Move the temporary file to the correct place, overwriting any file that already exists at that location.
  4. Delete the backup file (if configured to do so).
If all goes well, no temporary or backup files will remain on disk after closing the stream.

Errors are handled as follows:

  1. If anything goes wrong while writing to the temporary file, the temporary file will be deleted (leaving the original file untouched).
  2. If anything goes wrong while copying the temporary file to the target file, the backup of the original file is kept.

Implementation inspired by code from Marty Lamb and Apache.

Field Summary

Modifier and TypeField and Description
private final Path
backupFile

A backup of the target file (if it exists), created when the stream is closed

private boolean
errorDuringWrite

private final boolean
keepBackup

private static final Logger
LOGGER

private static final String
SAVE_EXTENSION

private final Path
targetFile

The file we want to create/replace.

private static final String
TEMPORARY_EXTENSION

private final Path
temporaryFile

The file to which writes are redirected to.

private FileLock
temporaryFileLock

Inherited from java.io.FilterOutputStream:
out

Constructor Summary

AccessConstructor and Description
public
AtomicFileOutputStream(Path
the path of the file to write to or replace
path, boolean
whether to keep the backup file (.sav) after a successful write process
keepBackup)

Creates a new output stream to write to or replace the file at the specified path.

public
AtomicFileOutputStream(Path
the path of the file to write to or replace
path)

Creates a new output stream to write to or replace the file at the specified path.

pack-priv
AtomicFileOutputStream(Path path, Path pathOfTemporaryFile, OutputStream temporaryFileOutputStream, boolean keepBackup)

Required for proper testing

Method Summary

Modifier and TypeMethod and Description
public void
abort()

Closes the write process to the temporary file but does not commit to the target file.

private void
cleanup()

public void
close()

Overrides java.io.FilterOutputStream.close.

Implements java.io.Closeable.close.

perform the final operations to move the temporary file to its final destination

public void
flush()

Overrides java.io.FilterOutputStream.flush.

Implements java.io.Flushable.flush.

Flushes this output stream and forces any buffered output bytes to be written out to the stream.

public Path
getBackup()

Returns the path of the backup copy of the original file (may not exist)

private static Path
getPathOfSaveBackupFile(Path targetFile)

private static Path
getPathOfTemporaryFile(Path targetFile)

public void
write(byte[]
the data.
b, int
the start offset in the data.
off, int
the number of bytes to write.
len)

Overrides java.io.FilterOutputStream.write.

Overridden because of cleanup actions in case of an error

public void
write(int
the byte.
b)

Overrides java.io.FilterOutputStream.write.

Writes the specified byte to this output stream.

Inherited from java.io.FilterOutputStream:
write

Field Detail

backupFileback to summary
private final Path backupFile

A backup of the target file (if it exists), created when the stream is closed

errorDuringWriteback to summary
private boolean errorDuringWrite
keepBackupback to summary
private final boolean keepBackup
LOGGERback to summary
private static final Logger LOGGER
SAVE_EXTENSIONback to summary
private static final String SAVE_EXTENSION
targetFileback to summary
private final Path targetFile

The file we want to create/replace.

TEMPORARY_EXTENSIONback to summary
private static final String TEMPORARY_EXTENSION
temporaryFileback to summary
private final Path temporaryFile

The file to which writes are redirected to.

temporaryFileLockback to summary
private FileLock temporaryFileLock

Constructor Detail

AtomicFileOutputStreamback to summary
public AtomicFileOutputStream(Path path, boolean keepBackup) throws IOException

Creates a new output stream to write to or replace the file at the specified path.

Parameters
path:Path

the path of the file to write to or replace

keepBackup:boolean

whether to keep the backup file (.sav) after a successful write process

AtomicFileOutputStreamback to summary
public AtomicFileOutputStream(Path path) throws IOException

Creates a new output stream to write to or replace the file at the specified path. The backup file (.sav) is deleted when write was successful.

Parameters
path:Path

the path of the file to write to or replace

AtomicFileOutputStreamback to summary
pack-priv AtomicFileOutputStream(Path path, Path pathOfTemporaryFile, OutputStream temporaryFileOutputStream, boolean keepBackup) throws IOException

Required for proper testing

Method Detail

abortback to summary
public void abort()

Closes the write process to the temporary file but does not commit to the target file.

cleanupback to summary
private void cleanup()
closeback to summary
public void close() throws IOException

Overrides java.io.FilterOutputStream.close.

Implements java.io.Closeable.close.

perform the final operations to move the temporary file to its final destination

Annotations
@Override
Exceptions
IOException:

Doc from java.io.FilterOutputStream.close.

if an I/O error occurs.

flushback to summary
public void flush() throws IOException

Overrides java.io.FilterOutputStream.flush.

Implements java.io.Flushable.flush.

Doc from java.io.FilterOutputStream.flush.

Flushes this output stream and forces any buffered output bytes to be written out to the stream.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.
getBackupback to summary
public Path getBackup()

Returns the path of the backup copy of the original file (may not exist)

getPathOfSaveBackupFileback to summary
private static Path getPathOfSaveBackupFile(Path targetFile)
getPathOfTemporaryFileback to summary
private static Path getPathOfTemporaryFile(Path targetFile)
writeback to summary
public void write(byte[] b, int off, int len) throws IOException

Overrides java.io.FilterOutputStream.write.

Overridden because of cleanup actions in case of an error

Parameters
b:byte[]

Doc from java.io.FilterOutputStream.write.

the data.

off:int

Doc from java.io.FilterOutputStream.write.

the start offset in the data.

len:int

Doc from java.io.FilterOutputStream.write.

the number of bytes to write.

Annotations
@Override
Exceptions
IOException:

Doc from java.io.FilterOutputStream.write.

if an I/O error occurs.

writeback to summary
public void write(int b) throws IOException

Overrides java.io.FilterOutputStream.write.

Doc from java.io.FilterOutputStream.write.

Writes the specified byte to this output stream.

The write method of FilterOutputStream calls the write method of its underlying output stream, that is, it performs out.write(b).

Implements the abstract write method of OutputStream.

Parameters
b:int

the byte.

Annotations
@Override
Exceptions
IOException:
if an I/O error occurs.