Package org.epics.archiverappliance

Interface EventStream

All Superinterfaces:
AutoCloseable, Closeable, Iterable<Event>
All Known Subinterfaces:
ETLBulkStream, ETLPBByteStream
All Known Implementing Classes:
ArchiverValuesHandler, ArrayListCollectorEventStream, ArrayListEventStream, ArrayListEventStreamWithPositionedIterator, CSVEventStream, CurrentThreadWorkerEventStream, EmptyEventStream, FileBackedPBEventStream, FillsCollectorEventStream, InputStreamBackedEventStream, MergeDedupEventStream, MergeDedupWithCallablesEventStream, MultiFilePBEventStream, SimulationEventStream, SummaryStatsCollectorEventStream, TimeSpanLimitEventStream
public interface EventStream extends Iterable<Event>, Closeable
An event stream is a sequence of events in temporal order. The events in the stream come oldest events first. Implementations of EventStream (should) try their best to support streaming data transfers.
EventStreams are typically backed by objects that consume system resources (like file handles, database connections etc). So, clients must 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. 
 
  try(EventStream stream = reader.getDataForPV(...)) {
   for(Event event : stream) {
   // Do stuff.
   }
 }
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.
The use of Iterable<Event> permits us to use syntactic sugar of the form 
 
   for(Event event : stream) {
   // Do stuff.
   }
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
Author:
mshankar