org.wali

Interface WriteAheadRepository<T>

Type Parameters:

T - the type of Record this repository is for

All Known Implementing Classes:

MinimalLockingWriteAheadLog

public interface WriteAheadRepository<T>

A WriteAheadRepository is used to persist state that is otherwise kept in-memory. The Repository does not provide any query capability except to allow the data to be recovered upon restart of the system.

A WriteAheadRepository operates by writing every update to an Edit Log. On restart, the data can be recovered by replaying all of the updates that are found in the Edit Log. This can, however, eventually result in very large Edit Logs, which can both take up massive amounts of disk space and take a long time to recover. In order to prevent this, the Repository provides a Checkpointing capability. This allows the current in-memory state of the Repository to be flushed to disk and the Edit Log to be deleted, thereby compacting the amount of space required to store the Repository. After a Checkpoint is performed, modifications are again written to an Edit Log. At this point, when the system is to be restored, it is restored by first loading the Checkpointed version of the Repository and then replaying the Edit Log.

All implementations of WriteAheadRepository use one or more partitions to manage their Edit Logs. An implementation may require exactly one partition or may allow many partitions.

Method Summary

Modifier and Type	Method and Description
int	checkpoint() Compacts the contents of the Repository so that rather than having a Snapshot and an Edit Log indicating many Updates to the Snapshot, the Snapshot is updated to contain the current state of the Repository, and the edit log is purged.
java.util.Set<java.lang.String>	getRecoveredSwapLocations() Recovers all External Swap locations that were persisted.
java.util.Collection<T>	recoverRecords() Recovers all records from the persisted state.
void	shutdown() Causes the repository to checkpoint and then close any open resources.
int	update(java.util.Collection<T> records, boolean forceSync) Updates the repository with the specified Records.

Method Detail

update

int update(java.util.Collection<T> records,
           boolean forceSync)
    throws java.io.IOException

Updates the repository with the specified Records. The Collection must not contain multiple records with the same ID

Parameters:

records - the records to update

forceSync - specifies whether or not the Repository forces the data to be flushed to disk. If false, the data may be stored in Operating System buffers, which improves performance but could cause loss of data if power is lost or the Operating System crashes

Returns:

the index of the Partition that performed the update

Throws:

java.io.IOException - if failure to update repo

java.lang.IllegalArgumentException - if multiple records within the given Collection have the same ID, as specified by Record#getId() method

recoverRecords

java.util.Collection<T> recoverRecords()
                                throws java.io.IOException

Recovers all records from the persisted state. This method must be called before any updates are issued to the Repository.

Returns:

recovered records

Throws:

java.io.IOException - if failure to read from repo

java.lang.IllegalStateException - if any updates have been issued against this Repository before this method is invoked

getRecoveredSwapLocations

java.util.Set<java.lang.String> getRecoveredSwapLocations()
                                                   throws java.io.IOException

Recovers all External Swap locations that were persisted. If this method is to be called, it must be called AFTER recoverRecords() and BEFORE update.

Returns:

swap location

Throws:

java.io.IOException - if failure reading swap locations

checkpoint

int checkpoint()
        throws java.io.IOException

Compacts the contents of the Repository so that rather than having a Snapshot and an Edit Log indicating many Updates to the Snapshot, the Snapshot is updated to contain the current state of the Repository, and the edit log is purged.

Returns:

the number of records that were written to the new snapshot

Throws:

java.io.IOException - if failure during checkpoint

shutdown

void shutdown()
       throws java.io.IOException

Causes the repository to checkpoint and then close any open resources.

Throws:

java.io.IOException - if failure to shutdown cleanly