com.neeve.rog.log

Class RogLogReader

java.lang.Object

com.neeve.rog.log.RogLogReader

public final class RogLogReader
extends Object

The transaction log reader.

The transaction log reader allows one to read through a log's 'entries'. The reader allows the user to do a 'raw' read of the log entries or a 'transactional' read of the log. A raw read returns individual entries from the log while a transactional read returns sets of entries logically grouped by application transaction. The following code samples illustrate how to do a raw and transactional read of a log and print out the logged objects as JSON strings.

Raw Read Sample
// Create and open a log
RogLog log = RogLog.create("ems");
log.open();

// Create a log reader
RogLogReader reader = log.createReader();

// Register message/object factories.
reader.registerFactory([user's X message/object factory])

// Read and print entry objects as JSON strings.
RogLogReader.Entry entry;
reader.rewind();
while ((entry = reader.next()) != null) {
System.out.println(((IRogJsonizable)entry.getObject()).toJsonString());
entry.dispose();
}


Transactional Read Sample
// Create and open a log
RogLog log = RogLog.create("ems");
log.open();

// Create a log reader
RogLogReader reader = log.createReader();

// Register message/object factories.
reader.registerFactory([user's X message/object factory])

// Read and print entry objects as JSON strings.
RogLogReader.Transaction transaction;
reader.rewind();
while ((transaction = reader.nextTransaction()) != null) {
for (RogLogReader.Entry entry : transaction.getEntries()) {
System.out.println(((IRogJsonizable)entry.getObject()).toJsonString());
entry.dispose();
}
}


Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RogLogReader.Entry Represents a log entry Threading:RogLogReader.Entrys are not safe for concurrent access by multiple threads.
static interface	RogLogReader.ReadCallback Callback invoked during the read operation
static interface	RogLogReader.SkipCallback Callback invoked during the skip operation
static class	RogLogReader.Stats Holds log statistics.
static class	RogLogReader.Transaction Represents a log transaction (entries grouped by application transaction)
static interface	RogLogReader.TransactionSkipCallback Callback invoked during the skip operation

Method Summary

Modifier and Type	Method and Description
void	close() The close method should be called on any RogLogReader to release the resources it holds.
RogLogReader.Stats	computeStats() Computes statistics for the log by scanning through all entries.
RogLogReader.Entry	getEntryAt(long filePosition) Gets an entry located at the specified position in the file.
long	getFilePosition() Get the current file position
RogLogReader.Stats	getStats() Gets the statistics of what this reader has read so far.
RogLog	log() Return the parent log
RogLogReader.Entry	next() Returns the next entry in the log.
RogLogReader.Transaction	nextTransaction() Returns the next transaction in the log.
RogLogReader	read(int count, RogLogReader.ReadCallback cb) Reads a specified number of entries from the log
static void	registerFactory(Object factory) Register a factory.
RogLogReader	rewind() Rewinds the reader, and resets its statistics
void	seek(long pos) Positions the reader at the given file position, and resets its statistics.
void	setLazyDeserialization(boolean lazyDeserialization) Sets whether or not objects are eagerly deserialized as they are read from the log.
RogLogReader	skip(int count, RogLogReader.SkipCallback cb) Skips a certain number of objects in the log.
RogLogReader	skipTransaction(int count, RogLogReader.TransactionSkipCallback cb) Skips a certain number of transactions in the log.

Methods inherited from class java.lang.Object

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

Method Detail

registerFactory

public static final void registerFactory(Object factory)

Register a factory.

Parameters:

factory - The factory to register.

Threading:

This method is not safe for concurrent access by multiple threads with itself or any of the other engine methods.

setLazyDeserialization

public void setLazyDeserialization(boolean lazyDeserialization)

Sets whether or not objects are eagerly deserialized as they are read from the log. Lazy deserialization results in faster scans of the log but can hold more memory since the objects must be held in serialized form.

Parameters:

lazyDeserialization - The lazy deserialization setting.

log

public final RogLog log()

Return the parent log

read

public final RogLogReader read(int count,
                               RogLogReader.ReadCallback cb)

Reads a specified number of entries from the log

Parameters:

count - The number of entries to read

next

public final RogLogReader.Entry next()
                              throws Exception

Returns the next entry in the log.

This method returns the next complete log entry. The method returns null if no more entries are in the log.

Throws:

Exception

nextTransaction

public final RogLogReader.Transaction nextTransaction()
                                               throws Exception

Returns the next transaction in the log.

This method returns the next complete transaction in the log. The method returns null if no more transactions are in the log.

Throws:

Exception

skip

public final RogLogReader skip(int count,
                               RogLogReader.SkipCallback cb)
                        throws IOException

Skips a certain number of objects in the log.

Throws:

IOException

skipTransaction

public final RogLogReader skipTransaction(int count,
                                          RogLogReader.TransactionSkipCallback cb)
                                   throws Exception

Skips a certain number of transactions in the log.

Throws:

Exception

seek

public final void seek(long pos)
                throws IOException

Positions the reader at the given file position, and resets its statistics. The position given should be one returned by RogLogReader.Entry.getFilePosition() The reposition will attempt to validate that the position is a valid log position, and if it is not the current file pointer will be left untouched.

Parameters:

pos - The position

Throws:

IOException

rewind

public final RogLogReader rewind()
                          throws IOException

Rewinds the reader, and resets its statistics

Throws:

IOException

getFilePosition

public final long getFilePosition()

Get the current file position

getStats

public RogLogReader.Stats getStats()

Gets the statistics of what this reader has read so far.

Note

Transaction related statistics are NOT reliable if a skip method has been called since the last reset of the this reader.

Returns:

The statistics.

computeStats

public RogLogReader.Stats computeStats()
                                throws Exception

Computes statistics for the log by scanning through all entries.

Returns:

The statistics.

Throws:

Exception - if there is an error reading the log

This method rewinds the log to the beginning and computes stats for the whole log

getEntryAt

public RogLogReader.Entry getEntryAt(long filePosition)
                              throws Exception

Gets an entry located at the specified position in the file.

Parameters:

filePosition - The file position from which to read.

Returns:

The RogLogReader.Entry at the given position or null if there is no entry at the given position.

Throws:

Exception - If there is an error reading a packet from the specified position.

This method does not update file pointers and may be called in interleaved with calls to next() or nextTransaction().

close

public final void close()
                 throws Exception

The close method should be called on any RogLogReader to release the resources it holds. If a reader is created via RogLog.createReader() with a value of false, A caller must close the reader when finished with it to release underlying resources since a non shared reader hold it own file handle.

Throws:

Exception - If there is an error closing the reader.