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.
RogLog.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 (RogLog.Entry entry : transaction.getEntries()) {
System.out.println(((IRogJsonizable)entry.getObject()).toJsonString());
entry.dispose();
}
}


Nested Class Summary

static interface	RogLogReader.SkipCallback Callback invoked during the skip operation
static class	RogLogReader.Transaction Represents a transaction log transaction (entries grouped by application transaction)
static interface	RogLogReader.TransactionSkipCallback Callback invoked during the skip operation

Method Summary

void	close() The close method should be called on any RogLogReader to release the resources it holds.
RogLog.Stats	computeStats() Computes statistics for the log by scanning through all remaining entries.
RogLog.Entry	getEntryAt(long filePosition) Gets an entry located at the specified position in the file.
RogLog.Stats	getStats() Gets the statistics of what this reader has read so far.
RogLog	log() Return the parent log
RogLog.Entry	next() Returns the next entry in the log.
RogLogReader.Transaction	nextTransaction() Returns the next transaction in 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

next

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

Note: that usage of this message will not correctly updates transaction statistics.

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 RogLog.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

getStats

public RogLog.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 RogLog.Stats computeStats()
                          throws Exception

Computes statistics for the log by scanning through all remaining entries.

Returns:

The statistics.

Throws:

Exception - if there is an error reading the log

getEntryAt

public RogLog.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 RogLog.Entryy 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.