Journal (ATG Java API)

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

All Methods Static Methods Instance Methods Concrete 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

Class Journal

Nested Class Summary

Field Summary

Fields inherited from interface atg.vfs.journal.ResourceConstants

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CLASS_VERSION

INDEX_FILE_NAME

DATA_DIRECTORY_NAME

Constructor Detail

Journal

Journal

Method Detail

getDirectory

getCount

getLastEntry

isOpen

open

addFile

updateFile

updateFileLastModified

deleteFile

renameFile

close

getEntryIterator

clear

dump

dump

getOutputStream

toString

main