org.apache.river.mercury

Interface EventLog

All Known Implementing Classes:

PersistentEventLog, TransientEventLog

interface EventLog

Interface implemented by event storage objects. This class encapsulates the details of reading/writing events from/to some underlying persistence mechanism. This interface 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:

1.1

Author:

Sun Microsystems, Inc.

Method Summary

Modifier and Type	Method and Description
void	add(RemoteEvent event) Writes the given RemoteEvent to the underlying storage mechanism, if possible.
void	close() Close this log and release any associated runtime resources.
void	delete() Delete associated storage resources for this log.
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.
RemoteEventData[]	readAhead(int maxEvents) Return an array of RemoteEventData with a limit of maxEvents elements.
void	remove() Effectively removes the last read event from the log.

Method Detail

init

void init()
   throws IOException

Initializes the state of this EventLog object. The required functionality can potentially throw an IOException and has therefore been separated from from object construction.

Throws:

IOException - if an I/O error occurs

add

void add(RemoteEvent event)
  throws IOException

Writes the given RemoteEvent to the underlying storage mechanism, if possible. If an IOException occurs, then the write cannot be guaranteed.

Throws:

IOException - if an I/O error occurs

next

RemoteEvent next()
          throws IOException,
                 ClassNotFoundException

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

Throws:

IOException - if an I/O error occurs

ClassNotFoundException - if a class for the serialized object could not be found

NoSuchElementException - if no event is available

isEmpty

boolean isEmpty()
         throws IOException

Returns true if this log contains no events and false otherwise.

Throws:

IOException

remove

void remove()
     throws IOException

Effectively removes the last read event from the log. It does this by advancing the read pointer to the next available event, if any.

Throws:

NoSuchElementException - if no events are available

IOException

readAhead

RemoteEventData[] readAhead(int maxEvents)
                     throws IOException,
                            ClassNotFoundException

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

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

NoSuchElementException - if no event is available

moveAhead

void moveAhead(Object cookie)
        throws IOException

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.

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.

NullPointerException - if cookie is null.

ClassCastException - if cookie is not an expected type.

close

void close()
    throws IOException

Close this log and release any associated runtime resources.

Throws:

IOException

delete

void delete()
     throws IOException

Delete associated storage resources for this log.

Throws:

IOException - if an IO error occurs