PersistentEventLog (Apache River v2.2.2 API Documentation (internals))

java.lang.Object
- com.sun.jini.mercury.PersistentEventLog

All Implemented Interfaces:

EventLog
```
 class PersistentEventLog
extends Object
implements EventLog
```
Class that implements the interface for an EventLog. This class encapsulates the details of reading/writing events from/to some underlying persistence mechanism. This class makes certain assumptions. First, the next and remove methods are intended to be called in pairs. If remove is not called, then subsequent calls to next will attempt to return the same object. Calling remove essentially advances the read pointer to the next object, if any. Second, if any IOExceptions are encountered during the reading or writing of an event the associated read/write pointer is advanced past the offending event. This means that events can be lost if I/O errors are encountered.

Since:

2.0

Author:

Sun Microsystems, Inc.

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`closed` Flag that is used to determine whether or not this object has been closed.
`private File`	`controlFile` The `File` object that will maintain the control data for for this `EventLog`.
`private static int`	`CTLBLOCK_LEN` Size of control data file: 4 longs * 8 bytes per long
`private byte[]`	`ctlbuf` The in memory buffer that holds the control data
`private static String`	`CTLFILE_SUFFIX` File suffix for the control file
`private static boolean`	`debugState`
`private static long`	`DEFAULT_EVENTS_PER_LOGFILE` Default number of events per log file, if not overriden by the user
`(package private) static int`	`DEFAULT_STREAM_POOL_SIZE` Default size for the stream pool, if not overriden by the user
`private EventReader`	`eventReader` The `EventReader` used to retrieve events.
`private static long`	`eventsPerLogFile` Maximum number of event objects per log file.
`private EventWriter`	`eventWriter` The `EventWriter` used to store events
`private boolean`	`initialized` Flag that is used to determine whether or not this object has been initialized.
`private File`	`logDir` The `File` object of the event persistence directory
`private static String`	`LOGFILE_SUFFIX` File suffix for the log files
`private static int`	`maxPoolSize` Maximum limit for the number of concurrent `LogStream`s that this pool will concurrently manage.
`private long`	`nextReadPos` The read offset of the next event.
`private static Logger`	`persistenceLogger` `Logger` used for persistence-related debugging messages
`private long`	`rcount` The current number of read events.
`private long`	`rpos` The read offset into the current "read" log of the "last read" object.
`private static StreamPool`	`streamPool` The `StreamPool` reference to be used for all instances of `EventLog`.
`private Uuid`	`uuid` The associated `Uuid` for this `EventLog`.
`private long`	`wcount` The current number of written events.
`private long`	`wpos` The current write offset into the current "write" log.

Constructor Summary

Constructors
Constructor and Description

PersistentEventLog(Uuid uuid, File logDir)
Simple constructor that takes a Uuid argument and a File argument.

Constructors
Constructor and Description
`PersistentEventLog(Uuid uuid, File logDir)` Simple constructor that takes a `Uuid` argument and a `File` argument.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`add(RemoteEvent event)` Writes the given `RemoteEvent` to the underlying storage mechanism, if possible.
`private void`	`assertInvariants()` Utility method for asserting that the object invariants are valid.
`void`	`close()` Close this log and release any associated runtime resources.
`void`	`delete()` Delete associated storage resources for this log.
`private File`	`getControlFile()` Utility method for returning the `File` that contains the state information for this log.
`private File`	`getLogFile(long lognum)` Utility method for returning the `File` associated with the given `lognum`.
`private static long`	`getLogNum(long count)` Utility method for returning the log file number for the given (event) `count`.
`void`	`init()` Initializes the state of this `EventLog` object.
`boolean`	`isEmpty()` Returns `true` if this log contains no events and false otherwise.
`void`	`moveAhead(Object cookie)` Effectively removes the last set of read events from the log.
`RemoteEvent`	`next()` Return the next `RemoteEvent` to be read.
`private long`	`nextReadAheadLog(long readCount)` Advance the temporary "read" state to the next available log.
`private void`	`nextReadLog()` Advance the "read" state to the next available log.
`private void`	`nextWriteLog()` Advance the "write" state to the next available log.
`private static void`	`packLong(long val, byte[] b, int off)` Utility method for packing a `long` into a `byte` array.
`private void`	`printControlData(Logger logger, String msg)` Output state information to the given `Logger`.
`RemoteEventData[]`	`readAhead(int maxEvents)` Return an array of `RemoteEventData` with a limit of `maxEvents` elements.
`private void`	`readControlFile()` Read state information from the underlying store.
`void`	`remove()` Effectively removes the last read event from the log.
`private static void`	`removeDir(File logDir)` Attempt to delete the associated event log persistence directory.
`private void`	`stateCheck()` Asserts that the log is in a valid state.
`private static long`	`unpackLong(byte[] b, int off)` Utility method for unpacking a `long` from a `byte` array.
`private boolean`	`verifyInvariants()` Utility method for checking if the object invariants are valid.
`private void`	`writeControlFile()` Write state information to the underlying store.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - persistenceLogger
```
private static final Logger persistenceLogger
```
    Logger used for persistence-related debugging messages
  - CTLBLOCK_LEN
```
private static final int CTLBLOCK_LEN
```
    Size of control data file: 4 longs * 8 bytes per long
    
    See Also:
    Constant Field Values
  - CTLFILE_SUFFIX
```
private static final String CTLFILE_SUFFIX
```
    File suffix for the control file
    
    See Also:
    Constant Field Values
  - LOGFILE_SUFFIX
```
private static final String LOGFILE_SUFFIX
```
    File suffix for the log files
    
    See Also:
    Constant Field Values
  - DEFAULT_EVENTS_PER_LOGFILE
```
private static final long DEFAULT_EVENTS_PER_LOGFILE
```
    Default number of events per log file, if not overriden by the user
    
    See Also:
    Constant Field Values
  - eventsPerLogFile
```
private static final long eventsPerLogFile
```
    Maximum number of event objects per log file. The default is used unless overridden by eventsPerLogProperty.
    
    See Also:
    Constant Field Values
  - DEFAULT_STREAM_POOL_SIZE
```
static final int DEFAULT_STREAM_POOL_SIZE
```
    Default size for the stream pool, if not overriden by the user
    
    See Also:
    Constant Field Values
  - maxPoolSize
```
private static final int maxPoolSize
```
    Maximum limit for the number of concurrent LogStreams that this pool will concurrently manage. The default is used unless overridden by streamPoolSizeProperty.
    
    See Also:
    Constant Field Values
  - streamPool
```
private static final StreamPool streamPool
```
    The StreamPool reference to be used for all instances of EventLog.
  - uuid
```
private Uuid uuid
```
    The associated Uuid for this EventLog.
  - wcount
```
private long wcount
```
    The current number of written events.
  - rcount
```
private long rcount
```
    The current number of read events.
  - wpos
```
private long wpos
```
    The current write offset into the current "write" log.
  - rpos
```
private long rpos
```
    The read offset into the current "read" log of the "last read" object.
  - nextReadPos
```
private long nextReadPos
```
    The read offset of the next event. This gets updated to rpos once remove is called (indicating that the last event read was successful).
  - eventReader
```
private EventReader eventReader
```
    The EventReader used to retrieve events.
  - eventWriter
```
private EventWriter eventWriter
```
    The EventWriter used to store events
  - logDir
```
private File logDir
```
    The File object of the event persistence directory
  - controlFile
```
private File controlFile
```
    The File object that will maintain the control data for for this EventLog.
  - ctlbuf
```
private byte[] ctlbuf
```
    The in memory buffer that holds the control data
  - initialized
```
private boolean initialized
```
    Flag that is used to determine whether or not this object has been initialized.
  - closed
```
private boolean closed
```
    Flag that is used to determine whether or not this object has been closed.
  - debugState
```
private static final boolean debugState
```
    See Also:
    Constant Field Values
- Constructor Detail
  - PersistentEventLog
```
PersistentEventLog(Uuid uuid,
                  File logDir)
```
    Simple constructor that takes a Uuid argument and a File argument. These arguments are simply assigned to the appropriate internal fields.
    
    Throws:
    
    IllegalArgumentException - if any of the arguments are null
- Method Detail
  - init
```
public void init()
          throws IOException
```
    Description copied from interface: EventLog
    
    Initializes the state of this EventLog object. The required functionality can potentially throw an IOException and has therefore been separated from from object construction.
    
    Specified by:
    
    init in interface EventLog
    
    Throws:
    
    IOException - if an I/O error occurs
  - add
```
public void add(RemoteEvent event)
         throws IOException
```
    Description copied from interface: EventLog
    
    Writes the given RemoteEvent to the underlying storage mechanism, if possible. If an IOException occurs, then the write cannot be guaranteed.
    
    Specified by:
    
    add in interface EventLog
    
    Throws:
    
    IOException - if an I/O error occurs
  - next
```
public RemoteEvent next()
                 throws IOException,
                        ClassNotFoundException
```
    Description copied from interface: EventLog
    
    Return the next RemoteEvent to be read. Note that next is meant to be used in conjunction with remove. Subsequent calls to next will return the same event until remove is called, which actually updates the read pointer to the next event (indicating that the previously read event was successfully processed).
    
    Specified by:
    
    next in interface EventLog
    
    Throws:
    
    IOException - if an I/O error occurs
    
    ClassNotFoundException - if a class for the serialized object could not be found
  - readAhead
```
public RemoteEventData[] readAhead(int maxEvents)
                            throws IOException,
                                   ClassNotFoundException
```
    Description copied from interface: EventLog
    
    Return an array of RemoteEventData with a limit of maxEvents elements. Note that readAhead is meant to be used in conjunction with moveAhead. Subsequent calls to readAhead with the same argument value will return the same set of events until moveAhead is called, which actually updates the read pointer to the next unread event (indicating that the previously read events were successfully processed).
    
    Specified by:
    
    readAhead in interface EventLog
    
    Parameters:
    maxEvents - maximum number of events/elements to return
    
    Throws:
    
    IOException - if an I/O error occurs
    
    ClassNotFoundException - if a class for the serialized object could not be found
  - isEmpty
```
public boolean isEmpty()
                throws IOException
```
    Description copied from interface: EventLog
    
    Returns true if this log contains no events and false otherwise.
    
    Specified by:
    
    isEmpty in interface EventLog
    
    Throws:
    
    IOException
  - remove
```
public void remove()
            throws IOException
```
    Description copied from interface: EventLog
    
    Effectively removes the last read event from the log. It does this by advancing the read pointer to the next available event, if any.
    
    Specified by:
    
    remove in interface EventLog
    
    Throws:
    
    IOException
  - moveAhead
```
public void moveAhead(Object cookie)
               throws IOException
```
    Description copied from interface: EventLog
    
    Effectively removes the last set of read events from the log. It does this by advancing the read pointer to the next available event after the event associated with the provided cookie object.
    
    Specified by:
    
    moveAhead in interface EventLog
    
    Parameters:
    cookie - object associated with event to read past. This object should have been obtained from a call to getCookie() on a RemoteEventData object obtained from a call to readAhead on this event log.
    
    Throws:
    
    IOException - if there was a problem advancing the read pointer.
  - close
```
public void close()
           throws IOException
```
    Description copied from interface: EventLog
    
    Close this log and release any associated runtime resources.
    
    Specified by:
    
    close in interface EventLog
    
    Throws:
    
    IOException
  - delete
```
public void delete()
            throws IOException
```
    Description copied from interface: EventLog
    
    Delete associated storage resources for this log.
    
    Specified by:
    
    delete in interface EventLog
    
    Throws:
    
    IOException - if an IO error occurs
  - removeDir
```
private static void removeDir(File logDir)
```
    Attempt to delete the associated event log persistence directory.
  - nextReadLog
```
private void nextReadLog()
```
    Advance the "read" state to the next available log.
  - nextReadAheadLog
```
private long nextReadAheadLog(long readCount)
```
    Advance the temporary "read" state to the next available log.
  - nextWriteLog
```
private void nextWriteLog()
```
    Advance the "write" state to the next available log.
  - printControlData
```
private void printControlData(Logger logger,
                    String msg)
```
    Output state information to the given Logger. This is intended for debugging purposes only.
  - writeControlFile
```
private void writeControlFile()
                       throws IOException
```
    Write state information to the underlying store.
    
    Throws:
    
    IOException
  - readControlFile
```
private void readControlFile()
                      throws IOException
```
    Read state information from the underlying store.
    
    Throws:
    
    IOException
  - packLong
```
private static void packLong(long val,
            byte[] b,
            int off)
```
    Utility method for packing a long into a byte array.
  - unpackLong
```
private static long unpackLong(byte[] b,
              int off)
```
    Utility method for unpacking a long from a byte array.
  - getLogFile
```
private File getLogFile(long lognum)
```
    Utility method for returning the File associated with the given lognum.
  - getControlFile
```
private File getControlFile()
```
    Utility method for returning the File that contains the state information for this log.
  - getLogNum
```
private static long getLogNum(long count)
```
    Utility method for returning the log file number for the given (event) count.
  - stateCheck
```
private void stateCheck()
                 throws IOException
```
    Asserts that the log is in a valid state.
    
    Throws:
    
    IOException - if the log is in an invalid state
  - verifyInvariants
```
private boolean verifyInvariants()
```
    Utility method for checking if the object invariants are valid.
  - assertInvariants
```
private void assertInvariants()
```
    Utility method for asserting that the object invariants are valid.
    
    Throws:
    
    InternalMailboxException - if the invariants aren't valid

Class PersistentEventLog

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

persistenceLogger

CTLBLOCK_LEN

CTLFILE_SUFFIX

LOGFILE_SUFFIX

DEFAULT_EVENTS_PER_LOGFILE

eventsPerLogFile

DEFAULT_STREAM_POOL_SIZE

maxPoolSize

streamPool

uuid

wcount

rcount

wpos

rpos

nextReadPos

eventReader

eventWriter

logDir

controlFile

ctlbuf

initialized

closed

debugState

Constructor Detail

PersistentEventLog

Method Detail

init

add

next

readAhead

isEmpty

remove

moveAhead

close

delete

removeDir

nextReadLog

nextReadAheadLog

nextWriteLog

printControlData

writeControlFile

readControlFile

packLong

unpackLong

getLogFile

getControlFile

getLogNum

stateCheck

verifyInvariants

assertInvariants