com.sun.jini.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
 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


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.