Package db.buffers

Class LocalManagedBufferFile

java.lang.Object

db.buffers.LocalBufferFile

db.buffers.LocalManagedBufferFile

All Implemented Interfaces:

BufferFile, ManagedBufferFile

public class LocalManagedBufferFile
extends LocalBufferFile
implements ManagedBufferFile

LocalManagedBufferFile implements a BufferFile as block-oriented random-access file which utilizes a BufferFileManager to identify and facilitate versioning of buffer files. This type of buffer file supports both save-as and save operations. The file format used is identical to a LocalBufferFile, although additional support is provided for associated files which facilitate versioning (e.g., ChangeMapFile, VersionFile, and changed data files).

Field Summary

Fields inherited from class db.buffers.LocalBufferFile

BUFFER_FILE_EXTENSION, PRESAVE_FILE_EXT, PRESAVE_FILE_PREFIX, TEMP_FILE_EXT

Constructor Summary

Constructors

Constructor	Description
LocalManagedBufferFile(int bufferSize, BufferFileManager bfManager, long checkinId)	Open the initial version of a block file for writing.
LocalManagedBufferFile(BufferFileManager bfManager, boolean versionUpdateEnabled, int minChangeDataVer, long checkinId)	Open the current version of an existing block file as read-only.
LocalManagedBufferFile(BufferFileManager bfManager, int version, int minChangeDataVer)	Open an older version of an existing buffer file as read-only and NOT UPDATEABLE (bfMgr remains null).

Method Summary

Modifier and Type	Method	Description
boolean	canSave()	Returns true if a save file is provided for creating a new version of this buffer file.
void	close()	Close the buffer file.
void	createNewVersion(ManagedBufferFile destFile, java.lang.String fileComment, TaskMonitor monitor)	Create a new buffer file version (used for check-in)
boolean	delete()	Delete this buffer file if writable.
DataBuffer	get(DataBuffer buf, int index)	Get the specified buffer.
long	getCheckinID()	Returns the checkin ID corresponding to this buffer file.
byte[]	getForwardModMapData(int oldVersion)	Returns a bit map corresponding to all buffers modified since oldVersion.
InputBlockStream	getInputBlockStream()	Obtain a direct stream to read all blocks of this buffer file
InputBlockStream	getInputBlockStream(byte[] changeMapData)	Obtain a direct stream to read modified blocks of this buffer file based upon the specified changeMap
BufferFile	getNextChangeDataFile(boolean getFirst)	Get the next change data file which corresponds to this buffer file.
OutputBlockStream	getOutputBlockStream(int blockCount)	Obtain a direct stream to write blocks to this buffer file
BufferFile	getSaveChangeDataFile()	Returns a temporary change data buffer file which should be used to store a application-level ChangeSet associated with this new buffer file version.
ManagedBufferFile	getSaveFile()	Returns a Save file if available.
LocalManagedBufferFile	getSaveFile(TaskMonitor monitor)	Returns a Save file if available.
void	put(DataBuffer buf, int index)	Store a data buffer at the specified block index.
void	saveCompleted(boolean commit)	After getting the save file, this method must be invoked to terminate the save.
boolean	setReadOnly()	If file is open read-write, the modified contents are flushed and the file re-opened as read-only.
void	setVersionComment(java.lang.String comment)	Set the comment which will be associated with this buffer file if saved.
void	updateFrom(ManagedBufferFile versionedBufferFile, int oldVersion, TaskMonitor monitor)	Create a new version of this file by updating it from a versionedBufferFile.

Methods inherited from class db.buffers.LocalBufferFile

cleanupOldPreSaveFiles, clearParameters, clone, copyFile, dispose, finalize, getBufferFileBlock, getBufferSize, getDataBuffer, getFile, getFreeIndexes, getIndexCount, getParameter, getParameterNames, isReadOnly, peek, poke, setFreeIndexes, setParameter, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface db.buffers.BufferFile

clearParameters, dispose, getBufferSize, getFreeIndexes, getIndexCount, getParameter, getParameterNames, isReadOnly, setFreeIndexes, setParameter

Constructor Detail

LocalManagedBufferFile

public LocalManagedBufferFile(int bufferSize,
                              BufferFileManager bfManager,
                              long checkinId)
                       throws java.io.IOException

Open the initial version of a block file for writing.

Parameters:

bufferSize - user buffer size

bfManager - buffer file version manager

checkinId - the checkinId for creating a versioned buffer file.

Throws:

java.io.IOException - if an IO error occurs or the incorrect magicNumber was read from the file.

LocalManagedBufferFile

public LocalManagedBufferFile(BufferFileManager bfManager,
                              boolean versionUpdateEnabled,
                              int minChangeDataVer,
                              long checkinId)
                       throws java.io.IOException

Open the current version of an existing block file as read-only.

Parameters:

bfManager - buffer file version manager

versionUpdateEnabled - if true Save support is enabled (pre-save starts automatically).

minChangeDataVer - indicates the oldest change data buffer file to be included. A -1 indicates only the last change data buffer file is applicable.

checkinId - the checkinId for versioned buffer files which are opened for update.

Throws:

java.io.IOException - if an IO error occurs or the incorrect magicNumber was read from the file.

LocalManagedBufferFile

public LocalManagedBufferFile(BufferFileManager bfManager,
                              int version,
                              int minChangeDataVer)
                       throws java.io.IOException

Open an older version of an existing buffer file as read-only and NOT UPDATEABLE (bfMgr remains null). Version files must exist for all versions starting with the requested version. These version files will be used in conjunction with the current buffer file to emulate an older version buffer file.

Parameters:

bfManager - buffer file version manager

version - version of file to be opened

minChangeDataVer - indicates the oldest change data buffer file to be included. A -1 indicates only the last change data buffer file is applicable.

Throws:

java.io.IOException - if an IO error occurs or a problem with the version reconstruction.

Method Detail

getNextChangeDataFile

public BufferFile getNextChangeDataFile(boolean getFirst)
                                 throws java.io.IOException

Description copied from interface: ManagedBufferFile

Get the next change data file which corresponds to this buffer file. This method acts like an iterator which each successive invocation returning the next available file. Null is returned when no more files are available. The invoker is responsible for closing each file returned. It is highly recommended that each file be closed prior to requesting the next file.

Specified by:

getNextChangeDataFile in interface ManagedBufferFile

Parameters:

getFirst - causes the iterator to reset and return the first available file.

Throws:

java.io.IOException - if an I/O error occurs

getCheckinID

public long getCheckinID()

Description copied from interface: ManagedBufferFile

Returns the checkin ID corresponding to this buffer file. The returned value is only valid if this buffer file has an associated buffer file manager and is either being created (see isReadOnly) or is intended for update (see canSave).

Specified by:

getCheckinID in interface ManagedBufferFile

setVersionComment

public void setVersionComment(java.lang.String comment)
                       throws java.io.IOException

Description copied from interface: ManagedBufferFile

Set the comment which will be associated with this buffer file if saved. The comment must be set prior to invoking close or setReadOnly.

Specified by:

setVersionComment in interface ManagedBufferFile

Parameters:

comment - comment text

Throws:

java.io.IOException - if an I/O error occurs

get

public DataBuffer get(DataBuffer buf,
                      int index)
               throws java.io.IOException

Description copied from interface: BufferFile

Get the specified buffer. DataBuffer data and flags are read from the file at index and stored within the supplied DataBuffer object. If the read buffer is empty, the DataBuffer's data field will remain unchanged (which could be null).

Specified by:

get in interface BufferFile

Overrides:

get in class LocalBufferFile

Parameters:

buf - a buffer whose data array will be filled-in or replaced.

index - index of buffer to be read. First user buffer is at index 0.

Throws:

java.io.EOFException - if the requested buffer index is greater than the number of available buffers of the end-of-file was encountered while reading the buffer.

java.io.IOException - if an I/O error occurs

put

public void put(DataBuffer buf,
                int index)
         throws java.io.IOException

Description copied from interface: BufferFile

Store a data buffer at the specified block index.

Specified by:

put in interface BufferFile

Overrides:

put in class LocalBufferFile

Parameters:

buf - data buffer

index - block index

Throws:

java.io.IOException - thrown if an IO error occurs

setReadOnly

public boolean setReadOnly()
                    throws java.io.IOException

Description copied from interface: BufferFile

If file is open read-write, the modified contents are flushed and the file re-opened as read-only. This is also used to commit a new version if the file had been modified for update.

Specified by:

setReadOnly in interface BufferFile

Overrides:

setReadOnly in class LocalBufferFile

Returns:

true if successfully transitioned from read-write to read-only

Throws:

java.io.IOException - if an I/O error occurs

close

public void close()
           throws java.io.IOException

Description copied from interface: BufferFile

Close the buffer file. If the file was open for write access, all buffers are flushed and the file header updated. Once closed, this object is immediately disposed and may no longer be used.

Specified by:

close in interface BufferFile

Overrides:

close in class LocalBufferFile

Throws:

java.io.IOException - if an I/O error occurs

delete

public boolean delete()

Description copied from interface: BufferFile

Delete this buffer file if writable. Once deleted, this object is immediately disposed and may no longer be used.

Specified by:

delete in interface BufferFile

Overrides:

delete in class LocalBufferFile

Returns:

true if deleted, false if the file is read-only

getForwardModMapData

public byte[] getForwardModMapData(int oldVersion)
                            throws java.io.IOException

Description copied from interface: ManagedBufferFile

Returns a bit map corresponding to all buffers modified since oldVersion. This identifies all buffers contained within the oldVersion which have been modified during any revision up until this file version. Buffers added since oldVersion are not identified NOTE: The bit mask may identify empty/free buffers within this file version.

Specified by:

getForwardModMapData in interface ManagedBufferFile

Parameters:

oldVersion - indicates the older version of this file for which a change map will be returned. This method may only be invoked if this file is at version 2 or higher, has an associated BufferFileManager and the oldVersion related files still exist.

Returns:

ModMap buffer change map data

Throws:

java.io.IOException - if an I/O error occurs

getSaveChangeDataFile

public BufferFile getSaveChangeDataFile()
                                 throws java.io.IOException

Description copied from interface: ManagedBufferFile

Returns a temporary change data buffer file which should be used to store a application-level ChangeSet associated with this new buffer file version. The getSaveFile method must be successfully invoked prior to invoking this method.

Specified by:

getSaveChangeDataFile in interface ManagedBufferFile

Returns:

change data file or null if one is not available.

Throws:

java.io.IOException - if an I/O error occurs

createNewVersion

public void createNewVersion(ManagedBufferFile destFile,
                             java.lang.String fileComment,
                             TaskMonitor monitor)
                      throws CancelledException,
                             java.io.IOException

Create a new buffer file version (used for check-in)

Parameters:

destFile - must be an versioned file representing an earlier version of srcFile.

fileComment - a comment for the new version.

monitor - the current monitor.

Throws:

CancelledException - if the operation is canceled.

java.io.IOException - if the file is in an unexpected state.

getSaveFile

public ManagedBufferFile getSaveFile()
                              throws java.io.IOException

Description copied from interface: ManagedBufferFile

Returns a Save file if available. Returns null if a save can not be performed. This method may block for an extended period of time if the pre-save process has not already completed. This method does not accept a monitor since a remote TaskMonitor does not yet exist.

Specified by:

getSaveFile in interface ManagedBufferFile

Throws:

java.io.IOException - if an I/O error occurs

getSaveFile

public LocalManagedBufferFile getSaveFile(TaskMonitor monitor)
                                   throws java.io.IOException,
                                          CancelledException

Returns a Save file if available. Returns null if a save can not be performed. This method may block for an extended period of time if the pre-save process has not already completed. This method does not accept a monitor since a remote TaskMonitor does not yet exist.

Parameters:

monitor - optional monitor for canceling pre-save (may be null)

Throws:

java.io.IOException - if an I/O error occurs

CancelledException - if monitor specified and pre-save cancelled

saveCompleted

public void saveCompleted(boolean commit)
                   throws java.io.IOException

Description copied from interface: ManagedBufferFile

After getting the save file, this method must be invoked to terminate the save.

Specified by:

saveCompleted in interface ManagedBufferFile

Parameters:

commit - if true the save file will be reopened as read-only for update. If false, the save file will be deleted and the object will become invalid.

Throws:

java.io.IOException

canSave

public boolean canSave()

Description copied from interface: ManagedBufferFile

Returns true if a save file is provided for creating a new version of this buffer file.

Specified by:

canSave in interface ManagedBufferFile

See Also:

ManagedBufferFile.getSaveFile()

getOutputBlockStream

public OutputBlockStream getOutputBlockStream(int blockCount)
                                       throws java.io.IOException

Obtain a direct stream to write blocks to this buffer file

Overrides:

getOutputBlockStream in class LocalBufferFile

Parameters:

blockCount - number of blocks to be transferred

Returns:

output block stream

Throws:

java.io.IOException

getInputBlockStream

public InputBlockStream getInputBlockStream()
                                     throws java.io.IOException

Obtain a direct stream to read all blocks of this buffer file

Overrides:

getInputBlockStream in class LocalBufferFile

Returns:

input block stream

Throws:

java.io.IOException

getInputBlockStream

public InputBlockStream getInputBlockStream(byte[] changeMapData)
                                     throws java.io.IOException

Obtain a direct stream to read modified blocks of this buffer file based upon the specified changeMap

Returns:

input block stream

Throws:

java.io.IOException

updateFrom

public void updateFrom(ManagedBufferFile versionedBufferFile,
                       int oldVersion,
                       TaskMonitor monitor)
                throws java.io.IOException,
                       CancelledException

Create a new version of this file by updating it from a versionedBufferFile. This file must be open as read-only with versionUpdateEnabled and have been derived from an oldVersion of the versionedBufferFile (i.e., was based on a check-out of oldVersion). The save-file corresponding to this file is updated using those buffers which have been modified or added in the specified versionedBufferFile since olderVersion. When complete, this file should be closed as soon as possible.

Parameters:

versionedBufferFile - versioned buffer file

oldVersion - older version of versionedBufferFile from which this buffer file originated.

monitor - progress monitor

Throws:

java.io.IOException - if an I/O error occurs

CancelledException - if monitor cancels operation