com.neeve.rog.log
Class RogLog

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

All Implemented Interfaces:

IStorePersister, IStoreReader, IStoreWriter, IRogMessageLogger

public final class RogLog
extends com.neeve.ods.impl.StorePacketPersisterBase
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.LogEmptinessExpectation, IStorePersister.LogPresenceExpectation, IStorePersister.StartupExpectation

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

IStoreWriter.LogCounters, IStoreWriter.Parameters

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

IStoreReader.ReadCallback

Field Summary

static String	PROP_AUTO_FLUSH_SIZE Property used to specify the log's auto flush size.
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_DETACHED_MESSAGE_SERIALIZATION Property used to indicate that serialization of messages logged via log(IRogMessage) should be deferred to the detached writer when operating in detached mode.
static String	PROP_FLUSH_USING_MAPPED_MEMORY Property used to indicate that flush should be performed using a memory mapped region of the log rather than via a RandomAccessFile handle
static String	PROP_INITIAL_LOG_LENGTH Property used to set the initial file length of the log in gigabytes.
static float	PROP_INITIAL_LOG_LENGTH_DEFAULT The default value for PROP_INITIAL_LOG_LENGTH.
static String	PROP_IS_PURE_MESSAGE_LOGGER Property used to indicate that this log is for message logging only.
static String	PROP_LOG_MODE Property used to indicate that mode in which the log should be opened
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_PAGE_SIZE Property used to specify the log's page size.
static String	PROP_STORE_ROOT Property used to indicate the directory in which the log should be placed.
static String	PROP_ZERO_OUT_INITIAL Property used to indicate whether the log should be zeroed out when freshly created This property is only applicable if PROP_INITIAL_LOG_LENGTH is set.

Fields inherited from class com.neeve.ods.impl.StorePacketPersisterBase

PROP_DETACHED, PROP_DETACHED_QUEUE_DEPTH, PROP_DETACHED_QUEUE_DRAINER_CPU_AFFINITIZATION_MASK, PROP_DETACHED_QUEUE_OFFER_STRATEGY, PROP_DETACHED_QUEUE_WAIT_STRATEGY, PROP_FLUSH_ON_COMMIT, PROP_SHARED

Method Summary

File	archive(File archiveFolder, String archiveId) Archives a transaction 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 using a set of properties to configure it
static RogLog	create(String name, StorePersisterDescriptor descriptor) Create a new log using a store persister descriptor to configure it.
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)
long	getAllocatedSize() Get the log file's allocated size.
RogLog.CheckpointState	getCheckpointState() Get the log's checkpoint state
long	getCompactionThreshold() Get the compaction threshold
RogLogCompactor	getCompactor() Get the log compactor
StorePersisterDescriptor	getDescriptor() Implementation of IStorePersister.getDescriptor() Note: This method will return null if the log was created directly using a property table rather than a store persister descriptor.
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()
boolean	isOpen() Implementation of IStorePersister.isOpen()
void	log(IRogMessage message) Log a message.
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	read(IStoreReader.ReadCallback cb, int flags) Implementation of IStoreReader.read(com.neeve.ods.IStoreReader.ReadCallback)
void	readMetadata(PktBuffer buffer) Implementation of IStoreReader.readMetadata(com.neeve.pkt.PktBuffer)
void	scheduleCompactionOnNextWrite() Schedule a compaction to occur on the next write
void	setCompactionThreshold(int val) Set the compaction threshold
void	setErrorHandler(IStorePersister.ErrorHandler errorHandler) Implementation of IStorePersister.setErrorHandler(com.neeve.ods.IStorePersister.ErrorHandler)
void	setIsPureMessageLogger(boolean isPureMessageLogger) Marks this RogLog as being purely for message logging purposes.
void	setStartupExpectation(IStorePersister.StartupExpectation expectation, Enum<?> value) Implementation of IStorePersister.setStartupExpectation(com.neeve.ods.IStorePersister.StartupExpectation, java.lang.Enum)
String	toString()
boolean	wasRepaired() Implementation of IStorePersister.wasRepaired()

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

getParameters, isShared, onRoleChange, sync, writeCommitEntry

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, wait, wait, wait

Methods inherited from interface com.neeve.ods.IStoreWriter

getParameters, isShared, onRoleChange, sync, writeCommitEntry

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_INITIAL_LOG_LENGTH

public static final String PROP_INITIAL_LOG_LENGTH

Property used to set the initial file length of the log in gigabytes.

The initial length of the recovery log this can be set to the maximum size to which the log is expected to grow to avoid costs with growing the file.

See Also:

Constant Field Values

PROP_INITIAL_LOG_LENGTH_DEFAULT

public static final float PROP_INITIAL_LOG_LENGTH_DEFAULT

The default value for PROP_INITIAL_LOG_LENGTH.

See Also:

Constant Field Values

PROP_ZERO_OUT_INITIAL

public static final String PROP_ZERO_OUT_INITIAL

Property used to indicate whether the log should be zeroed out when freshly created

This property is only applicable if PROP_INITIAL_LOG_LENGTH is set. If set to true, then the log is zeroed out after initial creation.

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 is 'Delete'

See Also:

Constant Field Values

PROP_IS_PURE_MESSAGE_LOGGER

public static final String PROP_IS_PURE_MESSAGE_LOGGER

Property used to indicate that this log is for message logging only.

See Also:

Constant Field Values

PROP_DETACHED_MESSAGE_SERIALIZATION

public static final String PROP_DETACHED_MESSAGE_SERIALIZATION

Property used to indicate that serialization of messages logged via log(IRogMessage) should be deferred to the detached writer when operating in detached mode.

See Also:

Constant Field Values

PROP_LOG_MODE

public static final String PROP_LOG_MODE

Property used to indicate that mode in which the log should be opened

See Also:

Constant Field Values

PROP_FLUSH_USING_MAPPED_MEMORY

public static final String PROP_FLUSH_USING_MAPPED_MEMORY

Property used to indicate that flush should be performed using a memory mapped region of the log rather than via a RandomAccessFile handle

See Also:

Constant Field Values

PROP_AUTO_FLUSH_SIZE

public static final String PROP_AUTO_FLUSH_SIZE

Property used to specify the log's auto flush size.

See Also:

Constant Field Values

PROP_PAGE_SIZE

public static final String PROP_PAGE_SIZE

Property used to specify the log's page size.

See Also:

Constant Field Values

Method Detail

create

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

Create a new log using a set of properties to configure it

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, (Properties)null)

Throws:

OdsException

create

public static final RogLog create(String name,
                                  StorePersisterDescriptor descriptor)
                           throws OdsException

Create a new log using a store persister descriptor to configure it.

Parameters:

name - The name of the log

descriptor - The store persister descriptor used to configure the log

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

getCompactionThreshold

public final long getCompactionThreshold()

Get the compaction threshold

setCompactionThreshold

public final void setCompactionThreshold(int val)

Set the compaction threshold

Parameters:

val - The compaction threshold to set in gigabytes. A value of 0 will switch off compaction

Threading:

This method can be invoked fron any thread

scheduleCompactionOnNextWrite

public final void scheduleCompactionOnNextWrite()

Schedule a compaction to occur on the next write

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 persister's transaction log 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(IStorePersister.StartupExpectation expectation,
                                        Enum<?> value)

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

Specified by:

setStartupExpectation in interface IStorePersister

setIsPureMessageLogger

public final void setIsPureMessageLogger(boolean isPureMessageLogger)

Marks this RogLog as being purely for message logging purposes.

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

getDescriptor

public final StorePersisterDescriptor getDescriptor()

Implementation of IStorePersister.getDescriptor()

Note: This method will return null if the log was created directly using a property table rather than a store persister descriptor.

Specified by:

getDescriptor 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 IStorePersister.wasRepaired()

Specified by:

wasRepaired in interface IStorePersister

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

read

public final void read(IStoreReader.ReadCallback cb,
                       int flags)
                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.

flags - Flags that qualify read operations.

Throws:

Exception

log

public final void log(IRogMessage message)

Log a message.

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.

This method returns the amount of space used in the log file, including data that is buffered for write, but not yet flushed.

Returns:

Returns the log's log file size.

Throws:

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

getAllocatedSize

public final long getAllocatedSize()

Get the log file's allocated size.

This method returns the actual size of the log file currently allocated. This call differs from getSize() in that this value may be greater if the log has been preallocated to a larger size.

Returns:

Returns the log's log file size.

Throws:

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

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 transaction log's files to the specified folder, using the given archive id.

Parameters:

archiveFolder - The folder to which to archive this transaction log's 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 transaction log is not in a state where it can be archived (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

toString

public String toString()

Overrides:

toString in class Object