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:

IEventSource, IStorePersister, IStoreReader, IStoreWriter, IRogMessageLogger

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

The ROG transaction log

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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.IterativeReader, IStoreReader.ReadCallback

Field Summary

Fields

Modifier and Type	Field and Description
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_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_BACKUP_RETENTION_COUNT Property used to indicate the maximum number of log backups to retain
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_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_TRANSACTIONAL_INTEGRITY_CHECK Property used to indicate whether to do a transactional integrity check of the log on open
static boolean	PROP_TRANSACTIONAL_INTEGRITY_CHECK_DEFAULT The default value for PROP_TRANSACTIONAL_INTEGRITY_CHECK.
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

Modifier and Type	Method and Description
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 (in bytes).
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()
IEventHandler	getEventHandler() Get a persister's event handler.
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()
IStoreReader.IterativeReader	iterativeReader(int flags) Implementation of IStoreReader.iterativeReader(int)
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, boolean) and IRogMessageLogger.open()
void	open(boolean concurrentReadWrite) Implementation of IStorePersister.open(boolean)
void	open(PktBuffer serializedMetadata, boolean truncateLive) Implementation of IStorePersister.open(PktBuffer, boolean)
void	open(PktBuffer serializedMetadata, boolean truncateLive, boolean concurrentReadWrite) Implementation of IStorePersister.open(PktBuffer, boolean)
boolean	read(IStoreReader.ReadCallback cb) Implementation of IStoreReader.read(com.neeve.ods.IStoreReader.ReadCallback)
boolean	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	setEventHandler(IEventHandler eventHandler) Set a persister's event handler.
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_TRANSACTIONAL_INTEGRITY_CHECK

public static final String PROP_TRANSACTIONAL_INTEGRITY_CHECK

Property used to indicate whether to do a transactional integrity check of the log on open

See Also:

Constant Field Values

PROP_TRANSACTIONAL_INTEGRITY_CHECK_DEFAULT

public static final boolean PROP_TRANSACTIONAL_INTEGRITY_CHECK_DEFAULT

The default value for PROP_TRANSACTIONAL_INTEGRITY_CHECK.

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_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_LOG_BACKUP_RETENTION_COUNT

public static final String PROP_LOG_BACKUP_RETENTION_COUNT

Property used to indicate the maximum number of log backups to retain

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 (in bytes).

Returns:

the compaction threshold in bytes.

setCompactionThreshold

public final void setCompactionThreshold(int val)

Set the compaction threshold.

Parameters:

val - The compaction threshold to set in megabytes. 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 fully qualified 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,
                       boolean concurrentReadWrite)
                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.

concurrentReadWrite - If true, the log is opened in a manner that permits for concurrent read/write to occur on the log.

Throws:

Exception

open

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

Implementation of IStorePersister.open(PktBuffer, boolean)

Specified by:

open in interface IStorePersister

Throws:

Exception

open

public final void open(boolean concurrentReadWrite)
                throws Exception

Implementation of IStorePersister.open(boolean)

Specified by:

open in interface IStorePersister

Parameters:

concurrentReadWrite - If true, the log is opened in a manner that permits for concurrent read/write to occur on the log.

Invoking this method is equivalent to invoking open(null, false, concurrentReadWrite)

Throws:

Exception

open

public final void open()
                throws Exception

Implementation of IStorePersister.open(com.neeve.pkt.PktBuffer, boolean, 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 IEventSource

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

setEventHandler

public final void setEventHandler(IEventHandler eventHandler)

Description copied from interface: IStorePersister

Set a persister's event handler.

Specified by:

setEventHandler in interface IStorePersister

Parameters:

eventHandler - The event handler for the persister.

getEventHandler

public IEventHandler getEventHandler()

Description copied from interface: IStorePersister

Get a persister's event handler.

Specified by:

getEventHandler 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 final 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

iterativeReader

public final IStoreReader.IterativeReader iterativeReader(int flags)
                                                   throws Exception

Implementation of IStoreReader.iterativeReader(int)

Specified by:

iterativeReader in interface IStoreReader

Parameters:

flags - Flags that qualify read operations.

Throws:

Exception

read

public final boolean 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.

Returns:

Returns true if the full log has been read and false if the read was suspended by the callback

Throws:

Exception

read

public final boolean 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.

Returns:

Returns true if the full log has been read and false if the read was suspended by the callback

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.

Note that only one CDC processor can be created per log.

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