ariba.util.core
Class FileReplacer

java.lang.Object
  ariba.util.core.FileReplacer

All Implemented Interfaces:

OutputStreamHolder

public class FileReplacer
extends java.lang.Object
implements OutputStreamHolder

Utility class that supports replacing a given base file with a new file (typically, a new version of that file.)

There is support for obtaining an OutputStream to write a changed version of the file, applying the changes, then reverting the changes (you can apply and revert changes as many times as desired) before finally committing either the applied or reverted changes (dropping the files used for temporary storage.)

The temporary files are stored in the same directory as the base file. File.rename() is used to apply and revert which is an attempt to make the file replacement happen as quickly as possible.

Important note: This class is in no way multi-thread safe.

Nested Class Summary

static class

FileReplacer.BadStateException

Constructor Summary

FileReplacer(java.io.File baseFile)

FileReplacer(java.io.File directory, java.lang.String baseFileName)

Method Summary

void	applyChanges() Closes the stream opened in getOutputStream() and renames the temporary file to realms.xml (after making a backup copy of it).
void	checkGoodState()
void	commit() Drops the temporary and backup files associated with this FileReplacer thereby making the changes finally durable.
java.lang.String	getBadStateMessage()
java.io.File	getBaseFile() Returns the file on which this replacer is based.
java.io.FileInputStream	getBaseFileInputStream() Returns a FileInputStream on the base file.
java.io.OutputStream	getOutputStream() Returns the output stream associated with the temporary file.
java.io.FileInputStream	getTempFileInputStream() Returns a FileInputStream on the temp file.
java.io.FilenameFilter	getTempFilenameFilter() Returns a FilenameFilter object that can be used for filtering the temporary files that are created by FileReplacer pattern.
static java.io.FilenameFilter	getTempFilenameFilter(java.io.File file) Returns a FilenameFilter object that can be used for filtering the temporary files that are created by FileReplacer pattern.
boolean	hasAppliedChanges() Returns true if pending changes have been applied to the base file.
boolean	hasNoChanges() Returns true if no changes have been made to the base file (either pending or applied) and false otherwise.
boolean	hasPendingChanges() Returns true if there are any pending changes to be made to the base file.
boolean	isInGoodState() Returns whether or not this is in a valid state.
java.io.OutputStream	makeOutputStream() Closes the existing output stream on the temporary file (if any) creates a new output stream and returns it.
void	repairFromBadState()
void	revertChanges() Closes the stream opened in getOutputStream() and deletes the temporary file.

Methods inherited from class java.lang.Object

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

Constructor Detail

FileReplacer

public FileReplacer(java.io.File directory,
                    java.lang.String baseFileName)

Parameters:

directory - the directory in which to create the temporary file

baseFileName - the name of the file

FileReplacer

public FileReplacer(java.io.File baseFile)

Method Detail

hasNoChanges

public boolean hasNoChanges()

Returns true if no changes have been made to the base file (either pending or applied) and false otherwise.

hasPendingChanges

public boolean hasPendingChanges()

Returns true if there are any pending changes to be made to the base file.

hasAppliedChanges

public boolean hasAppliedChanges()

Returns true if pending changes have been applied to the base file.

getBaseFile

public java.io.File getBaseFile()

Returns the file on which this replacer is based.

getBaseFileInputStream

public java.io.FileInputStream getBaseFileInputStream()
                                               throws java.io.IOException

Returns a FileInputStream on the base file.

Note that a reference is retained to the returned file stream. It will be forcibly closed when applyChanges() is called.

Throws:

java.io.IOException

getTempFileInputStream

public java.io.FileInputStream getTempFileInputStream()
                                               throws java.io.IOException

Returns a FileInputStream on the temp file. The temp file must exist--it is only created when this hasPendingChanges().

Note that a reference is retained to the returned file stream. It will be forcibly closed when applyChanges() is called.

Throws:

java.io.IOException

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException

Returns the output stream associated with the temporary file. If there is no output stream already opened on the temporary file opens an output stream on it and returns the stream.

Important note: This FileReplacer must either have no changes or must have pending changes when this method is called. It is an error to try to obtain an output stream if this has applied changes. (If the client wishes to do this, he must first revert the applied changes and then request the stream.

It is the client's responsibility to close the stream.

Specified by:

getOutputStream in interface OutputStreamHolder

Throws:

java.io.IOException - if an exception occurs while creating or opening the stream

makeOutputStream

public java.io.OutputStream makeOutputStream()
                                      throws java.io.IOException

Closes the existing output stream on the temporary file (if any) creates a new output stream and returns it.

Throws:

java.io.IOException

applyChanges

public void applyChanges()
                  throws java.io.IOException,
                         FileReplacer.BadStateException

Closes the stream opened in getOutputStream() and renames the temporary file to realms.xml (after making a backup copy of it).

Throws:

java.io.IOException

FileReplacer.BadStateException

revertChanges

public void revertChanges()
                   throws java.io.IOException,
                          FileReplacer.BadStateException

Closes the stream opened in getOutputStream() and deletes the temporary file.

Throws:

java.io.IOException

FileReplacer.BadStateException

commit

public void commit()

Drops the temporary and backup files associated with this FileReplacer thereby making the changes finally durable. (There is no way to further apply or revert the changes.)

After this method is called this goes to the hasNoChanges() state.

getBadStateMessage

public java.lang.String getBadStateMessage()

isInGoodState

public boolean isInGoodState()

Returns whether or not this is in a valid state.

There is one invalid state for objects of this class, which is the state in which there exists a backup file (of the base file) and a temporary file (containing the changes to base file.)

In the normal course this should not happen: either the changes are applied and the base file is backed up (to allow a revert) or the changes are not applied, the base file is unchanged and there's no backup file.

However, during applyChanges() or revertChanges() the base file is deleted and the temporary or backup file is renamed to the base file, respectively. In either case it's possible for the delete to succeed and the rename to fail leaving us in this invalid state.

checkGoodState

public void checkGoodState()
                    throws FileReplacer.BadStateException

Throws:

FileReplacer.BadStateException

repairFromBadState

public void repairFromBadState()
                        throws java.io.IOException

Throws:

java.io.IOException

getTempFilenameFilter

public java.io.FilenameFilter getTempFilenameFilter()

Returns a FilenameFilter object that can be used for filtering the temporary files that are created by FileReplacer pattern.

Returns:

the filename filter

getTempFilenameFilter

public static java.io.FilenameFilter getTempFilenameFilter(java.io.File file)

Returns a FilenameFilter object that can be used for filtering the temporary files that are created by FileReplacer pattern.

Parameters:

file - the file that the filter pattern is based on.

Returns:

the filename filter