atg.vfs.journal

Class Journal

java.lang.Object

atg.vfs.journal.Journal

All Implemented Interfaces:

atg.vfs.journal.ResourceConstants, java.io.Serializable

public final class Journal
extends java.lang.Object
implements atg.vfs.journal.ResourceConstants, java.io.Serializable

A persistent storage mechanism for a set of changes to a virtual file system. A journal contains a List of add, update, and remove operations. The operations can be played back against a virtual file system.

Operations are put in the journal (i.e., journaled) by calling methods such as addFile(), updateFile(), and deleteFile(). The operations in the journal can later be read via entry iterator. The journal is implemented using an index file and a sparse directory tree. The index file contains the List of virtual file operations in the order they were added to the journal. The sparse directory tree contains the contents of the files that were added and updated. The format of the index file is:

• header
• entries

The header is 16 bytes in the following format:

• count (long) - number of entries in the journal
• checksum (long) - CRC-32 sum of the entry data

Each entry is stored in the following format:

• length (int) - length of the entry in bytes
• data - the serialized Entry object, which is length bytes long

See Also:

JournalingFileSystem, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Journal.Entry A journal entry represents a change to a specific virtual path.
class	Journal.EntryIterator Iterator for journal entries.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string
static java.lang.String	DATA_DIRECTORY_NAME name of the data directory
static java.lang.String	INDEX_FILE_NAME name of the index file

Fields inherited from interface atg.vfs.journal.ResourceConstants

EJO_CHECKSUM, EJO_CLOSE, EJO_CREATE, EJO_READ, EJO_READ_BYTE_COUNT, EJO_READING_ENTRY, EJO_WRITING_ENTRY

Constructor Summary

Constructors

Constructor and Description
Journal(java.io.File pDirectory) Construct a journal in the specified directory.
Journal(java.io.File pDirectory, boolean pJournalFileContent) Construct a journal in the specified directory.

Method Summary

Methods

Modifier and Type	Method and Description
long	addFile(VirtualFile pFile) Add the specified file to the journal as an add operation.
boolean	clear() Clear all the data in the persistent journal.
boolean	close() Close the persistent journal if it is open.
long	deleteFile(VirtualFile pFile) Add the specified file to the journal as a delete operation.
java.lang.String	dump() Dump the contents of the journal to a string.
void	dump(java.io.PrintWriter pWriter) Dump the contents of the journal to the specified print writer.
long	getCount() Get property count.
java.io.File	getDirectory() Get property directory.
Journal.EntryIterator	getEntryIterator() Get an iterator over the operation entries in this journal.
Journal.Entry	getLastEntry() Get property lastEntry.
java.io.OutputStream	getOutputStream(atg.vfs.VirtualPath pPath, java.io.OutputStream pOutputStream) Get an output stream for the specified path.
boolean	isOpen() Determine if the journal is currently open
static void	main(java.lang.String[] argv) Main for unit testing
boolean	open() Open the persistent journal, creating it if necessary.
long	renameFile(VirtualFile pFrom, VirtualFile pTo) Add the specified rename operation to the journal.
java.lang.String	toString() Get a string representation of this object.
long	updateFile(VirtualFile pFile) Add the specified file to the journal as an update operation.
long	updateFileLastModified(VirtualFile pFile, long pTime) Add the specified file to the journal as an update of the last modified time of the specified file.

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

INDEX_FILE_NAME

public static final java.lang.String INDEX_FILE_NAME

name of the index file

See Also:

Constant Field Values

DATA_DIRECTORY_NAME

public static final java.lang.String DATA_DIRECTORY_NAME

name of the data directory

See Also:

Constant Field Values

Constructor Detail

Journal

public Journal(java.io.File pDirectory)

Construct a journal in the specified directory. The journal does not journal file content. The journal is not ready for use until open() or create() is called.

Parameters:

pDirectory - the directory to hold journal. This must be an existing directory with read and write access.

Journal

public Journal(java.io.File pDirectory,
       boolean pJournalFileContent)

Construct a journal in the specified directory. The journal is not ready for use until open() or create() is called.

Parameters:

pDirectory - the directory to hold journal. This must be an existing directory with read and write access.

pJournalFileContent - if true then journal file content, if false just journal file operations

Method Detail

getDirectory

public java.io.File getDirectory()

Get property directory. This is the directory used to hold the journal. The journal is stored as a sparse tree in this directory.

Returns:

directory

getCount

public long getCount()

Get property count. This is the number of operations in the journal.

Returns:

count

getLastEntry

public Journal.Entry getLastEntry()

Get property lastEntry. This is the last operation in the journal.

Returns:

lastEntry

isOpen

public boolean isOpen()

Determine if the journal is currently open

Returns:

true if the journal is open, else false

open

public boolean open()
             throws JournalException

Open the persistent journal, creating it if necessary. The caller must guarantee that close() is called after calling open() even if the open() fails. If the journal already exists, it is opened. Otherwise the journal is created and opened.

Returns:

true if the journal already existed

Throws:

JournalException - if there is a problem reading the journal or if the journal is already open

addFile

public long addFile(VirtualFile pFile)
             throws JournalException

Add the specified file to the journal as an add operation.

Parameters:

pFile - the file to mark as added

Returns:

the index number of this operation in the journal. The first operation in the journal has an index of 0.

Throws:

JournalException - if there is a problem adding the operation to the journal

updateFile

public long updateFile(VirtualFile pFile)
                throws JournalException

Add the specified file to the journal as an update operation.

Parameters:

pFile - the file to mark as updated

Returns:

the index number of this operation in the journal. The first operation in the journal has an index of 0.

Throws:

JournalException - if there is a problem adding the operation to the journal

updateFileLastModified

public long updateFileLastModified(VirtualFile pFile,
                          long pTime)
                            throws java.io.IOException

Add the specified file to the journal as an update of the last modified time of the specified file.

Parameters:

pFile - the file whose last modified time has been updated

pTime - the last modified time to set

Returns:

the index number of this operation in the journal. The first operation in the journal has an index of 0.

Throws:

JournalException - if there is a problem adding the operation to the journal

java.io.IOException - if there is an I/O error setting the last modified time of the file

deleteFile

public long deleteFile(VirtualFile pFile)
                throws JournalRuntimeException

Add the specified file to the journal as a delete operation.

Parameters:

pFile - the file to mark as deleted

Returns:

the index number of this operation in the journal. The first operation in the journal has an index of 0.

Throws:

JournalRuntimeException - if there is a problem adding the operation to the journal

renameFile

public long renameFile(VirtualFile pFrom,
              VirtualFile pTo)
                throws JournalRuntimeException

Add the specified rename operation to the journal.

Parameters:

pFrom - the file being renamed

pTo - the new name of the file

Returns:

the index number of this operation in the journal. The first operation in the journal has an index of 0.

Throws:

JournalRuntimeException - if there is a problem adding the operation to the journal

close

public boolean close()
              throws JournalException

Close the persistent journal if it is open. It is okay to call this method even if the journal is not open or does not exist.

Returns:

true if the journal was found to be open and is now closed. This return value does not need to be checked, as the journal is closed once this method is called independent of the return.

Throws:

JournalException - if there is an I/O error closing the journal

getEntryIterator

public Journal.EntryIterator getEntryIterator()

Get an iterator over the operation entries in this journal. The iterator does not support modification. The journal must be open before calling this method. The iterator is only valid while the journal is open and any modifications to the journal during the iteration invalidate the iteration.

Returns:

the entry iterator

clear

public boolean clear()
              throws JournalException

Clear all the data in the persistent journal. This method destroys any existing persistent journal data. It is okay to call this method if the journal does not exist or is already empty. This method close()s the journal.

Returns:

true if the journal exists and is now cleared or false if the journal does not exist. In either case the journal contains no data if this method completes normally.

Throws:

JournalException - if there is a problem clearing the journal

dump

public void dump(java.io.PrintWriter pWriter)
          throws JournalException

Dump the contents of the journal to the specified print writer. This is mostly for debugging.

Nota Bene: this method open()s and close()s the journal.

Parameters:

pWriter - print writer to use, must not be null

Throws:

JournalException - if there is a problem reading the journal

dump

public java.lang.String dump()
                      throws JournalException

Dump the contents of the journal to a string. This is mostly for debugging.

Nota Bene: this method open()s and close()s the journal.

Returns:

the string

Throws:

JournalException - if there is a problem reading the journal

getOutputStream

public java.io.OutputStream getOutputStream(atg.vfs.VirtualPath pPath,
                                   java.io.OutputStream pOutputStream)
                                     throws java.io.IOException

Get an output stream for the specified path. Operations on the output stream are recorded in the journal as well as performed on the passed in output stream. This does not create a new entry in the journal. That must be done be the caller explicitly.

Parameters:

pPath - path of file being operated on

pOutputStream - the underlying output stream

Returns:

an output stream which passes all operations through to pOutputStream as well as journals them

Throws:

java.io.IOException - if there is I/O trouble

toString

public java.lang.String toString()

Get a string representation of this object.

Overrides:

toString in class java.lang.Object

Returns:

the string

main

public static void main(java.lang.String[] argv)
                 throws java.lang.Throwable

Main for unit testing

Throws:

java.lang.Throwable