/*******************************************************************************
* Copyright (c) 2011 The Board of Trustees of the Leland Stanford Junior University
* as Operator of the SLAC National Accelerator Laboratory.
* Copyright (c) 2011 Brookhaven National Laboratory.
* EPICS archiver appliance is distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
*******************************************************************************/
package org.epics.archiverappliance;
import java.io.Closeable;
/**
* An event stream is a sequence of events in temporal order.
* The events in the stream come oldest events first.
* Implementations of EventStream (<i>should</i>) try their best to support streaming data transfers.
* <div style="margin-top: 2.0em;">
* EventStreams are typically backed by objects that consume system resources (like file handles, database connections etc).
* So, clients <b>must</b> close the EventStream once they are done with it.
* We strongly encourage the use of the Java 1.7 try-with-resources for this purpose.
* <pre>
* <code>
* <span style="color:blue;">try</span>(EventStream stream = reader.getDataForPV(...)) {
* <span style="color:blue;">for</span>(Event event : stream) {
* // Do stuff.
* }
* }
* </code>
* </pre>
* </div>
* <div>
* EventStreams are typically backed by streams (InputStreams, XMLStreams, database cursors) etc.
* While there may be one or two implementations that let you get multiple iterators out of a single EventStream, this is the exception rather than the norm.
* For most implementation, assume that you can only get one iterator and once that iterator is finished, the EventStream is done.
* Again, we strongly encourage the use of the Java 1.7 try-with-resources which automatically forces this usage.
* </div>
* <div style="margin-top: 2.0em;">
* The use of Iterable<Event> permits us to use syntactic sugar of the form
* <pre>
* <code>
* <span style="color:blue;">for</span>(Event event : stream) {
* // Do stuff.
* }
* </code>
* </pre>
* However, Iterable<Event> does not permit us to throw IOExceptions.
* This is not ideal in that EventStreams are almost always backed by objects doing I/O and therefore can throw IOExceptions at all points.
* So, sometimes these are wrapped into subclasses of RuntimeException
* </div>
* @author mshankar
*
*/
public interface EventStream extends Iterable<Event>, Closeable {
public EventStreamDesc getDescription();
}