/*
 * 
 * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
 * 
 * The contents of this file are subject to the Sun Community Source
 * License v3.0/Jini Technology Specific Attachment v 1.0 (the
 * "License"). You may not use this file except in compliance with the
 * License. You may obtain a copy of the License at
 * http://wwws.sun.com/software/jini/licensing/SCSL3_JiniTSA1.html.
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 * 
 * The Reference Code is Jini Technology Core Platform code, v2.0. The
 * Developer of the Reference Code is Sun Microsystems, Inc.
 * 
 * Contributor(s): Sun Microsystems, Inc.
 * 
 * The contents of this file comply with the Jini Technology Core
 * Platform Compatibility Kit, v2.0A.
 * 
 * Tester(s): Sun Microsystems, Inc.
 * 
 * Test Platform(s):
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Solaris(TM)SPARC/x86
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Linux (Intel x86)
 * Java 2 SDK, Standard Edition, Version 1.4.2_03 for Windows (Intel Platform)
 * 
 */
package com.sun.jini.mercury;

import net.jini.id.Uuid;

import java.io.IOException;
import java.util.NoSuchElementException;

import net.jini.core.event.RemoteEvent;

/**
 * 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 <tt>next</tt> and
 * <tt>remove</tt> methods are intended to be called in pairs. If 
 * <tt>remove</tt> is not called, then subsequent calls to <tt>next</tt> 
 * will attempt to return the same object. Calling <tt>remove</tt> 
 * essentially advances the read pointer to the next object, if any. 
 * Second, if any <tt>IOExceptions</tt> 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.
 *
 * @author Sun Microsystems, Inc.
 *
 * @since 1.1
 */

interface EventLog {

    /**
     * Initializes the state of this <tt>EventLog</tt> object.
     * The required functionality can potentially throw an 
     * <tt>IOException</tt> and has therefore been separated from
     * from object construction.
     *
     * @exception IOException if an I/O error occurs
     */
    void init() throws IOException; 
    
    /**
     * Writes the given <tt>RemoteEvent</tt> to the underlying
     * storage mechanism, if possible. If an <tt>IOException</tt>
     * occurs, then the write cannot be guaranteed.
     *
     * @exception IOException if an I/O error occurs
     */
    void add(RemoteEvent event) throws IOException;
    
    /**
     * Return the next <tt>RemoteEvent</tt> to be read. Note that
     * <tt>next</tt> is meant to be used in conjunction with 
     * <tt>remove</tt>. Subsequent calls to <tt>next</tt> will
     * return the same event until <tt>remove</tt> is called, which
     * actually updates the read pointer to the next event (indicating
     * that the previously read event was successfully processed).
     *
     * @exception IOException if an I/O error occurs
     *
     * @exception ClassNotFoundException if a class for the serialized
     *                object could not be found
     *
     * @exception NoSuchElementException if no event is available 
     */
    RemoteEvent next() throws IOException, ClassNotFoundException;
        
    /**
     * Returns <tt>true</tt> if this log contains no events and
     * false otherwise.
     */
    boolean isEmpty() 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.
     *
     * @exception NoSuchElementException if no events are available
     */
    void remove() throws IOException;
    
    /**
     * Close this log and release any associated runtime resources.
     */
    void close() throws IOException;
    
    /**
     * Delete associated storage resources for this log.
     * 
     * @exception IOException if an IO error occurs
     */
    void delete() throws IOException;
    
}
