com.atomikos.util

Class VersionedFile

java.lang.Object

com.atomikos.util.VersionedFile

public class VersionedFile
extends java.lang.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(java.lang.String baseDir, java.lang.String baseName, java.lang.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).
java.lang.String	getBaseDir()
java.lang.String	getBaseName()
java.lang.String	getBaseUrl()
java.lang.String	getCurrentVersionFileName()
long	getSize()
java.lang.String	getSuffix()
java.io.FileInputStream	openLastValidVersionForReading() Opens the last valid version for reading.
java.nio.channels.FileChannel	openNewVersionForNioWriting() Opens a new version for writing to.
java.io.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(java.lang.String baseDir,
             java.lang.String baseName,
             java.lang.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 java.lang.String getCurrentVersionFileName()

getBaseUrl

public java.lang.String getBaseUrl()

getBaseDir

public java.lang.String getBaseDir()

getBaseName

public java.lang.String getBaseName()

getSuffix

public java.lang.String getSuffix()

openLastValidVersionForReading

public java.io.FileInputStream openLastValidVersionForReading()
                                                       throws java.lang.IllegalStateException,
                                                              java.io.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:

java.lang.IllegalStateException - If a newer version was opened for writing.

java.io.FileNotFoundException - If no last version was found.

openNewVersionForWriting

public java.io.FileOutputStream openNewVersionForWriting()
                                                  throws java.io.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:

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

java.io.IOException - If the file cannot be opened for writing.

openNewVersionForNioWriting

public java.nio.channels.FileChannel openNewVersionForNioWriting()
                                                          throws java.io.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:

java.io.IOException

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

java.io.FileNotFoundException - If the file cannot be opened for writing.

java.io.IOException

discardBackupVersion

public void discardBackupVersion()
                          throws java.lang.IllegalStateException,
                                 java.io.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:

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

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

close

public void close()
           throws java.io.IOException

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

Throws:

java.io.IOException - If the output stream could not be closed.

getSize

public long getSize()