com.atomikos.util

Class VersionedFile

java.lang.Object

com.atomikos.util.VersionedFile

public class VersionedFile
extends Object

A file with underlying version capabilities to ensure safe overwriting. Unlike regular files, this type of file is safe w.r.t. (over)writing a previous version: a backup version of the original content is kept until the client application explicitly states that a consistent new version has been written.

Constructor Summary

Constructors

Constructor and Description
VersionedFile(String baseDir, String baseName, String suffix) Creates a new instance based on the given name parameters.

Method Summary

Methods

Modifier and Type	Method and Description
void	close() Closes any open resources and resets the file for reading again.
void	discardBackupVersion() Discards the backup version (if any).
String	getBaseDir()
String	getBaseName()
String	getBaseUrl()
String	getCurrentVersionFileName()
long	getSize()
String	getSuffix()
FileInputStream	openLastValidVersionForReading() Opens the last valid version for reading.
FileChannel	openNewVersionForNioWriting() Opens a new version for writing to.
FileOutputStream	openNewVersionForWriting() Opens a new version for writing to.

Methods inherited from class java.lang.Object

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

Constructor Detail

VersionedFile

public VersionedFile(String baseDir,
             String baseName,
             String suffix)

Creates a new instance based on the given name parameters. The actual complete name(s) of the physical file(s) will be based on a version number inserted in between, to identify versions.

Parameters:

baseDir - The base folder.

baseName - The base name for of the file path/name.

suffix - The suffix to append to the complete file name.

Method Detail

getCurrentVersionFileName

public String getCurrentVersionFileName()

getBaseUrl

public String getBaseUrl()

getBaseDir

public String getBaseDir()

getBaseName

public String getBaseName()

getSuffix

public String getSuffix()

openLastValidVersionForReading

public FileInputStream openLastValidVersionForReading()
                                               throws IllegalStateException,
                                                      FileNotFoundException

Opens the last valid version for reading.

Returns:

A stream to read the last valid contents of the file: either the backup version (if present) or the current (and only) version if no backup is found.

Throws:

IllegalStateException - If a newer version was opened for writing.

FileNotFoundException - If no last version was found.

openNewVersionForWriting

public FileOutputStream openNewVersionForWriting()
                                          throws IOException

Opens a new version for writing to. Note that this new version is tentative and cannot be read by openLastValidVersionForReading() until discardBackupVersion() is called.

Returns:

A stream for writing to.

Throws:

IllegalStateException - If called more than once without a close in between.

IOException - If the file cannot be opened for writing.

openNewVersionForNioWriting

public FileChannel openNewVersionForNioWriting()
                                        throws FileNotFoundException

Opens a new version for writing to. Note that this new version is tentative and cannot be read by openLastValidVersionForReading() until discardBackupVersion() is called.

Returns:

A file for writing to.

Throws:

IOException

IllegalStateException - If called more than once without a close in between.

FileNotFoundException - If the file cannot be opened for writing.

IOException

discardBackupVersion

public void discardBackupVersion()
                          throws IllegalStateException,
                                 IOException

Discards the backup version (if any). After calling this method, the newer version produced after calling openNewVersionForWriting() becomes valid for reading next time when openLastValidVersionForReading() is called. Note: it is the caller's responsibility to make sure that all new data has been flushed to disk before calling this method!

Throws:

IllegalStateException - If openNewVersionForWriting() has not been called yet.

IOException - If the previous version exists but could no be deleted.

close

public void close()
           throws IOException

Closes any open resources and resets the file for reading again.

Throws:

IOException - If the output stream could not be closed.

getSize

public long getSize()