com.neeve.rog.log
Class RogLog

java.lang.Object
  com.neeve.root.RootObject
      com.neeve.ods.OdsObject
          com.neeve.ods.impl.StorePacketJournaller
              com.neeve.rog.log.RogLog

All Implemented Interfaces:

IStoreJournallingPersister, IStoreJournallingWriter, IStorePersister, IStoreReader, IStoreWriter, IRogMessageLogger

public final class RogLog
extends com.neeve.ods.impl.StorePacketJournaller
implements IStorePersister, IRogMessageLogger

The ROG transaction log

Nested Class Summary

static class	RogLog.CheckpointState Enumerates the state of entries being checkpointed in the log
static class	RogLog.Entry Represents a transaction log entry Threading:RogLog.Entrys are not safe for concurrent access by multiple threads.
static class	RogLog.Stats Holds transaction log statistics.

Nested classes/interfaces inherited from interface com.neeve.ods.IStorePersister

IStorePersister.ErrorHandler, IStorePersister.Type

Nested classes/interfaces inherited from interface com.neeve.ods.IStoreJournallingPersister

IStoreJournallingPersister.LogEmptinessExpectation, IStoreJournallingPersister.LogPresenceExpectation, IStoreJournallingPersister.StartupExpectation

Nested classes/interfaces inherited from interface com.neeve.ods.IStoreJournallingWriter

IStoreJournallingWriter.JournallingParameters, IStoreJournallingWriter.LogCounters

Nested classes/interfaces inherited from interface com.neeve.ods.IStoreReader

IStoreReader.ReadCallback

Field Summary

static String	PROP_AUTO_REPAIR Property used to indicate whether should attempt to repair files on open.
static String	PROP_CDC_ENABLED Property used to indicate whether CDC is enabled on the log If CDC is not enabled, then a CDC processor run on a log will not dispatch any events.
static String	PROP_COMPACTION_THRESHOLD Property used to indicate the log compaction threshold The log compaction threshold is the size (in megabytes) that triggers a log compaction.
static String	PROP_LOG_SCAVENGE_POLICY Property used to indicate policy used to scavenge logs A log with number N is considered a candidate for scavenging when N < live log number and N < CDC log number.
static String	PROP_MAX_COMPACTION_WINDOW_SIZE Property used to indicate the max log compaction window size The log compaction window is the approximate maximum size (in megabytes) rounded up to the end of the nearest checkpoint that a compact operation uses to determine how many log entries it will hold in memory.
static String	PROP_STORE_ROOT Property used to indicate the directory in which the log should be placed.

Method Summary

File	archive(File archiveFolder, String archiveId) Archives a log's files to the specified folder, using the given archive id.
RogLogRepository	asRepository() Return the log as a query repository
String	backupLog(boolean shrinkToSize) Backup a persister's log file.
static String	backupLog(String logName, Properties props, boolean shrinkToSize) Convenience method for backing up a log file.
void	close() Implementation of IStorePersister.close() and IRogMessageLogger.open()
static RogLog	create(String name) Create a new log.
static RogLog	create(String name, Properties props) Create a new log.
RogLogCdcProcessor	createCdcProcessor(IRogChangeDataCaptureHandler handler) Create a log CDC processor.
RogLogReader	createReader() Create a reader of the live log file.
RogLogReader	createReader(int logNumber) Create a private reader of the numbered log file.
void	delete() Delete a log file and associated metadata files
void	fail() Force fail the log.
void	fail(Exception cause) Force fail the log.
static void	failOpen(boolean val) Force fail the next open.
void	flush(boolean sync) Implementation of IRogMessageLogger.flush(boolean)
RogLog.CheckpointState	getCheckpointState() Get the log's checkpoint state
RogLogCompactor	getCompactor() Get the log compactor
boolean	getContainsInboundMessages() Get if a log is configured for inbound messages logging.
boolean	getContainsOutboundMessages() Get if a log is configured for outbound messages logging.
IStorePersister.ErrorHandler	getErrorHandler() Implementation of IStorePersister.getErrorHandler()
File	getLogFile() Get the underlying log file
com.eaio.uuid.UUID	getLogUUID() Get the log UUID.
RogLogMetadata	getMetadata() Get the log metadata
File	getMetadataFile() Get the underlying log metadata file
String	getName() Implementation of IStorePersister.getName() and IRogMessageLogger.getName()
long	getSize() Get the log file size.
IStorePersisterStats	getStats() Implementation of IStorePersister.getStats()
IStorePersister.Type	getType() Implementation of IStorePersister.getType()
boolean	isOpen() Implementation of IStorePersister.isOpen()
void	log(IRogMessage message) Implementation of IRogMessageLogger.log(IRogMessage)
void	log(IRogMessage message, boolean commitEnd) Implementation of IRogMessageLogger.log(IRogMessage, boolean)
void	open() Implementation of IStorePersister.open(com.neeve.pkt.PktBuffer, boolean) and IRogMessageLogger.open()
void	open(PktBuffer serializedMetadata, boolean truncateLive) Implementation of IStorePersister.open(PktBuffer, boolean)
void	read(IStoreReader.ReadCallback cb) Implementation of IStoreReader.read(com.neeve.ods.IStoreReader.ReadCallback)
void	readMetadata(PktBuffer buffer) Implementation of IStoreReader.readMetadata(com.neeve.pkt.PktBuffer)
void	setContainsInboundMessages(boolean containsInbound) Implementation of IRogMessageLogger.setContainsInboundMessages(boolean)
void	setContainsOutboundMessages(boolean containsOutbound) Implementation of IRogMessageLogger.setContainsOutboundMessages(boolean)
void	setErrorHandler(IStorePersister.ErrorHandler errorHandler) Implementation of IStorePersister.setErrorHandler(com.neeve.ods.IStorePersister.ErrorHandler)
void	setStartupExpectation(IStoreJournallingPersister.StartupExpectation expectation, Enum<?> value) Implementation of IStorePersister.setStartupExpectation(com.neeve.ods.IStoreJournallingPersister.StartupExpectation, java.lang.Enum)
boolean	wasRepaired() Implementation of IStoreJournallingPersister.wasRepaired()

Methods inherited from class com.neeve.ods.impl.StorePacketJournaller

commit, getJournallingParameters, isShared, onRoleChange, recordPersisterMetadata, recordPut, recordRemove, recordSend, recordUpdate, sync

Methods inherited from class com.neeve.root.RootObject

getChecked, getThreaded, getTracer, setChecked, setTracer

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.neeve.ods.IStoreJournallingWriter

getJournallingParameters

Methods inherited from interface com.neeve.ods.IStoreWriter

commit, isShared, onRoleChange, recordPersisterMetadata, recordPut, recordRemove, recordSend, recordUpdate, sync

Field Detail

PROP_STORE_ROOT

public static final String PROP_STORE_ROOT

Property used to indicate the directory in which the log should be placed.

See Also:

Constant Field Values

PROP_AUTO_REPAIR

public static final String PROP_AUTO_REPAIR

Property used to indicate whether should attempt to repair files on open.

See Also:

Constant Field Values

PROP_CDC_ENABLED

public static final String PROP_CDC_ENABLED

Property used to indicate whether CDC is enabled on the log

If CDC is not enabled, then a CDC processor run on a log will not dispatch any events. If CDC is not enabled on a log and then reenabled later, CDC will start from the live log at the time the CDC is enabled. If a compaction occurred while CDC was disabled, then the change events that occurred during that time will be lost.

See Also:

Constant Field Values

PROP_COMPACTION_THRESHOLD

public static final String PROP_COMPACTION_THRESHOLD

Property used to indicate the log compaction threshold

The log compaction threshold is the size (in megabytes) that triggers a log compaction. The act of compacting a log will compact as many complete checkpoints in the log and switch the live log over to the compacted log. A threshold value of <= 0 disables live log compaction.

See Also:

Constant Field Values

PROP_MAX_COMPACTION_WINDOW_SIZE

public static final String PROP_MAX_COMPACTION_WINDOW_SIZE

Property used to indicate the max log compaction window size

The log compaction window is the approximate maximum size (in megabytes) rounded up to the end of the nearest checkpoint that a compact operation uses to determine how many log entries it will hold in memory. The more entries the compactor can hold in memory while performing a compaction, the more efficient the compact operation will be.

Note: The minimum compaction window is a checkpoint. Therefore, if the system is configured such that a checkpooint covers entries that cumulatively exceeds the value of this parameter, then this parameter will not reduce the compaction memory usage - the compator will load the entire checkpoint into memory when performing the checkpoint operation. Note: When calculating memory needed by the compaction operation, one should multiply this parameter by a factor of 2 i.e. the memory used by compaction will be twice the memory specified via this parameter

See Also:

Constant Field Values

PROP_LOG_SCAVENGE_POLICY

public static final String PROP_LOG_SCAVENGE_POLICY

Property used to indicate policy used to scavenge logs

A log with number N is considered a candidate for scavenging when N < live log number and N < CDC log number. This parameter specifies how such logs need to be scavenged. Currently, the only permissible value if 'Delete'

See Also:

Constant Field Values

Method Detail

create

public static final RogLog create(String name,
                                  Properties props)
                           throws OdsException

Create a new log.

Parameters:

name - The name of the log

props - Properties to configure the log.

Throws:

OdsException

create

public static final RogLog create(String name)
                           throws OdsException

Create a new log.

This method calls create(name, null)

Throws:

OdsException

failOpen

public static final void failOpen(boolean val)

Force fail the next open.

backupLog

public static final String backupLog(String logName,
                                     Properties props,
                                     boolean shrinkToSize)
                              throws Exception

Convenience method for backing up a log file.

Parameters:

logName - The log file name

props - The log properties

shrinkToSize - If the log should be shrinked down to size.

Returns:

The name of the backed up file.

Throws:

Exception - If ther is an error backing up the log

getLogFile

public final File getLogFile()

Get the underlying log file

getMetadataFile

public final File getMetadataFile()

Get the underlying log metadata file

getMetadata

public final RogLogMetadata getMetadata()

Get the log metadata

delete

public final void delete()
                  throws IOException

Delete a log file and associated metadata files

Throws:

IOException

backupLog

public final String backupLog(boolean shrinkToSize)
                       throws Exception

Backup a persister's log file.

Parameters:

shrinkToSize - Specifies whether the backed up file should be shrunk to the amount of space actually used in the file.

Returns:

Returns the backup file name.

Throws:

IllegalStateException - Thrown if this method is invoked after the persister has been opened.

This method backs up the journalling persister's log (journal) file. The method first shrinks the log to the amount of space actually used in the log (only if shrinkToSize is set to true) and then renames the log to a log named by appending the current date and time to the log file name. The backup file name is returned by the method.

Exception

setStartupExpectation

public final void setStartupExpectation(IStoreJournallingPersister.StartupExpectation expectation,
                                        Enum<?> value)

Implementation of IStorePersister.setStartupExpectation(com.neeve.ods.IStoreJournallingPersister.StartupExpectation, java.lang.Enum)

Specified by:

setStartupExpectation in interface IStorePersister

setContainsInboundMessages

public final void setContainsInboundMessages(boolean containsInbound)

Implementation of IRogMessageLogger.setContainsInboundMessages(boolean)

Specified by:

setContainsInboundMessages in interface IRogMessageLogger

Parameters:

containsInbound - Whether or not the persister will contain inbound messages.

getContainsInboundMessages

public final boolean getContainsInboundMessages()

Get if a log is configured for inbound messages logging.

Returns:

Whether the log is configured for inbound messages logging.

setContainsOutboundMessages

public final void setContainsOutboundMessages(boolean containsOutbound)

Implementation of IRogMessageLogger.setContainsOutboundMessages(boolean)

Specified by:

setContainsOutboundMessages in interface IRogMessageLogger

Parameters:

containsOutbound - Whether or not the persister will contain outbound messages.

getContainsOutboundMessages

public final boolean getContainsOutboundMessages()

Get if a log is configured for outbound messages logging.

Returns:

Whether the log is configured for outbound messages logging.

open

public final void open(PktBuffer serializedMetadata,
                       boolean truncateLive)
                throws Exception

Implementation of IStorePersister.open(PktBuffer, boolean)

Specified by:

open in interface IStorePersister

Parameters:

serializedMetadata - Serialized form of the metadata to use for the log being opened. A value of null indicates that the existing metadata be used for the log and, if any metadata does not exist, then start with a fresh metadata object

truncateLive - If true, then the live log file is truncated during open. If metadata is supplied to this method, then the live log is determined from that metadata.

Throws:

Exception

open

public final void open()
                throws Exception

Implementation of IStorePersister.open(com.neeve.pkt.PktBuffer, boolean) and IRogMessageLogger.open()

Specified by:

open in interface IStorePersister

Specified by:

open in interface IRogMessageLogger

Throws:

Exception

getLogUUID

public final com.eaio.uuid.UUID getLogUUID()

Get the log UUID.

Returns:

The UUID for this log file.

getCheckpointState

public final RogLog.CheckpointState getCheckpointState()

Get the log's checkpoint state

isOpen

public final boolean isOpen()

Implementation of IStorePersister.isOpen()

Specified by:

isOpen in interface IStorePersister

getName

public final String getName()

Implementation of IStorePersister.getName() and IRogMessageLogger.getName()

Specified by:

getName in interface IStorePersister

Specified by:

getName in interface IRogMessageLogger

getType

public final IStorePersister.Type getType()

Implementation of IStorePersister.getType()

Specified by:

getType in interface IStorePersister

setErrorHandler

public final void setErrorHandler(IStorePersister.ErrorHandler errorHandler)

Implementation of IStorePersister.setErrorHandler(com.neeve.ods.IStorePersister.ErrorHandler)

Specified by:

setErrorHandler in interface IStorePersister

getErrorHandler

public final IStorePersister.ErrorHandler getErrorHandler()

Implementation of IStorePersister.getErrorHandler()

Specified by:

getErrorHandler in interface IStorePersister

getStats

public final IStorePersisterStats getStats()

Implementation of IStorePersister.getStats()

Specified by:

getStats in interface IStorePersister

wasRepaired

public final boolean wasRepaired()

Implementation of IStoreJournallingPersister.wasRepaired()

Specified by:

wasRepaired in interface IStoreJournallingPersister

readMetadata

public void readMetadata(PktBuffer buffer)

Implementation of IStoreReader.readMetadata(com.neeve.pkt.PktBuffer)

Specified by:

readMetadata in interface IStoreReader

Parameters:

buffer - The buffer to read the (serialized form of) metadata into

read

public final void read(IStoreReader.ReadCallback cb)
                throws Exception

Implementation of IStoreReader.read(com.neeve.ods.IStoreReader.ReadCallback)

Specified by:

read in interface IStoreReader

Parameters:

cb - The callback used to return the read entries to the caller.

Throws:

Exception

log

public final void log(IRogMessage message)

Implementation of IRogMessageLogger.log(IRogMessage)

Specified by:

log in interface IRogMessageLogger

Parameters:

message - The message to log.

log

public final void log(IRogMessage message,
                      boolean commitEnd)

Implementation of IRogMessageLogger.log(IRogMessage, boolean)

Specified by:

log in interface IRogMessageLogger

Parameters:

message - The message to log.

commitEnd - Indicates whether to mark this log entry as the end of an application commit leg.

flush

public final void flush(boolean sync)

Implementation of IRogMessageLogger.flush(boolean)

Specified by:

flush in interface IRogMessageLogger

Parameters:

sync - Indicates if the flush should sync to the durable media

createReader

public final RogLogReader createReader()
                                throws Exception

Create a reader of the live log file.

Returns:

A RogLogReader instance.

Throws:

Exception - If there is an error creating the RogLogReader

createReader

public final RogLogReader createReader(int logNumber)
                                throws Exception

Create a private reader of the numbered log file.

Returns:

A private RogLogReader instance.

Throws:

Exception - If there is an error creating the RogLogReader

This method creates a private log reader of a specific numbered log file.

createCdcProcessor

public final RogLogCdcProcessor createCdcProcessor(IRogChangeDataCaptureHandler handler)
                                            throws Exception

Create a log CDC processor.

Returns:

A CDC processor that can be used to fetch compacted log entries.

Throws:

Exception - If there is an error creating the RogLogReader

getSize

public final long getSize()

Get the log file size.

Returns:

Returns the log's log file size.

Throws:

IllegalStateException - Thrown if this method is invoked before the log has been opened.

This method returns the amount of space used in the log file.

fail

public final void fail(Exception cause)

Force fail the log.

Specified by:

fail in interface IStorePersister

Parameters:

cause - The cause of the failure.

CAUTION: This method is only for testing purposes and should not be invoked outside of test frameworks.

This method invokes the error handler if installed and marks the log has failed. This will cause all subsequent commits or syncs to immediately fail with a runtime exception.

fail

public final void fail()

Force fail the log.

This method invokes the following:

fail(new OdsException("force failed by user"))

Specified by:

fail in interface IStorePersister

asRepository

public final RogLogRepository asRepository()

Return the log as a query repository

getCompactor

public final RogLogCompactor getCompactor()

Get the log compactor

archive

public final File archive(File archiveFolder,
                          String archiveId)
                   throws IOException

Archives a log's files to the specified folder, using the given archive id.

Parameters:

archiveFolder - The folder to which to archive this logs files.

archiveId - The archive id with which to suffix archived files.

Returns:

The archived log file

Throws:

IOException - If there is an error creating the backup files.

IllegalStateException - If the log is not in an archivable state (e.g. open)

close

public final void close()

Implementation of IStorePersister.close() and IRogMessageLogger.open()

Specified by:

close in interface IStorePersister

Specified by:

close in interface IRogMessageLogger