net.sf.jaer.eventio
Class AEFileInputStream

java.lang.Object
  java.io.InputStream
      java.io.FilterInputStream
          java.io.DataInputStream
              net.sf.jaer.eventio.AEFileInputStream

All Implemented Interfaces:

java.io.Closeable, java.io.DataInput, AEFileInputStreamInterface, InputDataFileInterface

public class AEFileInputStream
extends java.io.DataInputStream
implements AEFileInputStreamInterface

Class to stream in packets of events from binary input stream from a file recorded by AEViewer.

The file format is simple, it consists of an arbitrary number of timestamped AEs:

 int32 address
int32 timestamp

 int32 address
int32 timestamp

(Prior to version 2.0 data files, the address was a 16 bit short value.)

An optional ASCII header consisting of lines starting with '#' is skipped when opening the file and may be retrieved. No later comment lines are allowed because the rest ot the file must be pure binary data.

The first line of the header specifies the file format (for later versions). Files lacking a header are assumed to be of int16 address form.

The first line of the header has a value like "#!AER-DAT2.0". The 2.0 is the version number.

AEFileInputStream has PropertyChangeSupport via getSupport(). PropertyChangeListeners will get informed of the following events

• "position" - on any new packet of events, either by time chunk or fixed number of events chunk
• "rewind" - on file rewind
• "eof" - on end of file
• "wrappedTime" - on wrap of time timestamps. This happens every int32 us, which is about 4295 seconds which is 71 minutes. Time is negative, then positive, then negative again.
• "init" - on initial read of a file (after creating this with a file input stream). This init event is called on the initial packet read because listeners can't be added until the object is created

Author:

tobi

See Also:

AEDataFile

Nested Class Summary

class	AEFileInputStream.NonMonotonicTimeException class used to signal a backwards read from input stream
class	AEFileInputStream.WrappedTimeException Indicates that timestamp has wrapped around from most positive to most negative signed value.

Field Summary

static int	EVENT16_SIZE With new 32bits adressses, use EVENT32_SIZE, but use EVENT16_SIZE for backward compatibility with 16 bit addresses
static int	EVENT32_SIZE (new style) int addr, int timestamp
protected java.util.ArrayList<java.lang.String>	header
static int	MAX_BUFFER_SIZE_EVENTS
int	MAX_NONMONOTONIC_TIME_EXCEPTIONS_TO_PRINT

Fields inherited from class java.io.FilterInputStream

in

Constructor Summary

AEFileInputStream(java.io.File f)
Creates a new instance of AEInputStream

AEFileInputStream(java.io.FileInputStream in)
Deprecated. use the constructor with a File object so that users of this can more easily get file information

Method Summary

void	close()
AEFileInputStream	copy() copies out the part of the stream from IN to OUT markers and returns it as a new AEInputStream
AEFileInputStream	cut() cuts out the part of the stream from IN to OUT and returns it as a new AEInputStream
long	getAbsoluteStartingTimeMs() When the file is opened, the filename is parsed to try to extract the date and time the file was created from the filename.
int	getCurrentStartTimestamp()
int	getDurationUs()
java.io.File	getFile() Returns the File that is being read, or null if the instance is constructed from a FileInputStream
int	getFirstTimestamp() returns the first timestamp in the stream
float	getFractionalPosition() Returns the position as a fraction of the total number of events
java.util.ArrayList<java.lang.String>	getHeader() Gets the header strings from the file
int	getLastTimestamp()
int	getMostRecentTimestamp()
java.beans.PropertyChangeSupport	getSupport() AEFileInputStream has PropertyChangeSupport.
boolean	isNonMonotonicTimeExceptionsChecked() Checking for wrapped time exceptions can be disabled for reasons of speed or corrupted data files.
void	mark() mark the current position.
void	markIn() mark the current position as the IN point for editing.
void	markOut() mark the current position as the OUT position for editing.
protected void	parseFileFormatVersion(java.lang.String s) parses the file format version given a string with the header comment character stripped off.
void	paste(AEFileInputStream in) pastes the in stream at the IN marker into this stream
int	position() gets the current position (in events) for reading forwards, i.e., readEventForwards will read this event number.
void	position(int event) set position in events from start of file
protected void	readHeader(java.io.FileInputStream fileInputStream) reads the header comment lines.
AEPacketRaw	readPacketByNumber(int n) Uesd to read fixed size packets either forwards or backwards.
AEPacketRaw	readPacketByTime(int dt) returns an AEPacketRaw at least dt long up to the max size of the buffer or until end-of-file.
void	rewind() rewind to the start, or to the marked position, if it has been set.
void	setAbsoluteStartingTimeMs(long absoluteStartingTimeMs)
void	setCurrentStartTimestamp(int currentStartTimestamp)
void	setFile(java.io.File f) Sets the File reference but doesn't open the file
void	setFractionalPosition(float frac) Sets fractional position in events
void	setMostRecentTimestamp(int mostRecentTimestamp)
void	setNonMonotonicTimeExceptionsChecked(boolean yes) Sets whether the input stream is checked for timestamp nonmonotonicity.
long	size() gets the size of the stream in events
protected void	skipHeader() skips the header lines (if any)
java.lang.String	toString()
void	unmark() clear any marked position

Methods inherited from class java.io.DataInputStream

read, read, readBoolean, readByte, readChar, readDouble, readFloat, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedShort, readUTF, readUTF, skipBytes

Methods inherited from class java.io.FilterInputStream

available, mark, markSupported, read, reset, skip

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAX_NONMONOTONIC_TIME_EXCEPTIONS_TO_PRINT

public final int MAX_NONMONOTONIC_TIME_EXCEPTIONS_TO_PRINT

See Also:

Constant Field Values

MAX_BUFFER_SIZE_EVENTS

public static final int MAX_BUFFER_SIZE_EVENTS

See Also:

Constant Field Values

EVENT16_SIZE

public static final int EVENT16_SIZE

With new 32bits adressses, use EVENT32_SIZE, but use EVENT16_SIZE for backward compatibility with 16 bit addresses

See Also:

Constant Field Values

EVENT32_SIZE

public static final int EVENT32_SIZE

(new style) int addr, int timestamp

See Also:

Constant Field Values

header

protected java.util.ArrayList<java.lang.String> header

Constructor Detail

AEFileInputStream

public AEFileInputStream(java.io.FileInputStream in)
                  throws java.io.IOException

Deprecated. use the constructor with a File object so that users of this can more easily get file information

Creates a new instance of AEInputStream

Throws:

java.io.IOException

AEFileInputStream

public AEFileInputStream(java.io.File f)
                  throws java.io.IOException

Creates a new instance of AEInputStream

Parameters:

f - the file to open

Throws:

java.io.FileNotFoundException - if file doesn't exist or can't be read

java.io.IOException

Method Detail

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

readPacketByNumber

public AEPacketRaw readPacketByNumber(int n)
                               throws java.io.IOException

Uesd to read fixed size packets either forwards or backwards. Behavior in case of non-monotonic timestamps depends on setting of tim wrapping exception checking. If exception checking is enabled, then the read will terminate on the first non-monotonic timestamp.

Specified by:

readPacketByNumber in interface AEFileInputStreamInterface

Parameters:

n - the number of events to read

Returns:

a raw packet of events of a specfied number of events fires a property change "position" on every call, and a property change "wrappedTime" if time wraps around.

Throws:

java.io.IOException - if there is a problem, e.g. end of file

readPacketByTime

public AEPacketRaw readPacketByTime(int dt)
                             throws java.io.IOException

returns an AEPacketRaw at least dt long up to the max size of the buffer or until end-of-file. Events are read as long as the timestamp until (and including) the event whose timestamp is greater (for dt>0) than startTimestamp+dt, where startTimestamp is the currentStartTimestamp. currentStartTimestamp is incremented after the call by dt. Fires a property change "position" on each call. Fires property change "wrappedTime" when time wraps from positive to negative or vice versa (when playing backwards).

Non-monotonic timestamps cause warning messages to be printed (up to MAX_NONMONOTONIC_TIME_EXCEPTIONS_TO_PRINT) and packet reading is aborted when the non-monotonic timestamp is encountered. Nornally this does not cause problems except that the packet is storter in duration that called for. But when sychronized playback is enabled it causes the differnt threads to desychronize. Therefore the data files should not contain non-monotonic timestamps when sychronized playback is desired.

Specified by:

readPacketByTime in interface AEFileInputStreamInterface

Parameters:

dt - the timestamp different in units of the timestamp (usually us)

Returns:

the packet, always at least one event even if there is no event in the interval dt.

Throws:

java.io.IOException - if there is any problem

See Also:

MAX_BUFFER_SIZE_EVENTS

rewind

public void rewind()
            throws java.io.IOException

rewind to the start, or to the marked position, if it has been set. Fires a property change "position" followed by "rewind".

Specified by:

rewind in interface InputDataFileInterface

Throws:

java.io.IOException

size

public long size()

gets the size of the stream in events

Specified by:

size in interface InputDataFileInterface

Returns:

size in events

position

public void position(int event)

set position in events from start of file

Specified by:

position in interface InputDataFileInterface

Parameters:

event - the number of the event, starting with 0

position

public int position()

gets the current position (in events) for reading forwards, i.e., readEventForwards will read this event number.

Specified by:

position in interface InputDataFileInterface

Returns:

position in events.

getFractionalPosition

public float getFractionalPosition()

Returns the position as a fraction of the total number of events

Specified by:

getFractionalPosition in interface InputDataFileInterface

Returns:

fractional position in total events

setFractionalPosition

public void setFractionalPosition(float frac)

Sets fractional position in events

Specified by:

setFractionalPosition in interface InputDataFileInterface

Parameters:

frac - 0-1 float range, 0 at start, 1 at end

getSupport

public java.beans.PropertyChangeSupport getSupport()

AEFileInputStream has PropertyChangeSupport. This support fires events on certain events such as "rewind".

mark

public void mark()
          throws java.io.IOException

mark the current position.

Specified by:

mark in interface InputDataFileInterface

Throws:

java.io.IOException - if there is some error in reading the data

markIn

public void markIn()
            throws java.io.IOException

mark the current position as the IN point for editing.

Throws:

java.io.IOException - if there is some error in reading the data

markOut

public void markOut()
             throws java.io.IOException

mark the current position as the OUT position for editing.

Throws:

java.io.IOException - if there is some error in reading the data

unmark

public void unmark()

clear any marked position

Specified by:

unmark in interface InputDataFileInterface

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.io.Closeable

Overrides:

close in class java.io.FilterInputStream

Throws:

java.io.IOException

getFirstTimestamp

public int getFirstTimestamp()

returns the first timestamp in the stream

Returns:

the timestamp

getLastTimestamp

public int getLastTimestamp()

Returns:

last timestamp in file

getDurationUs

public int getDurationUs()

Returns:

the duration of the file in us.

Assumes data file is timestamped in us. This method fails to provide a sensible value if the timestamp wwaps.

getCurrentStartTimestamp

public int getCurrentStartTimestamp()

Returns:

the present value of the startTimestamp for reading data

setCurrentStartTimestamp

public void setCurrentStartTimestamp(int currentStartTimestamp)

getMostRecentTimestamp

public int getMostRecentTimestamp()

Returns:

returns the most recent timestamp

setMostRecentTimestamp

public void setMostRecentTimestamp(int mostRecentTimestamp)

cut

public AEFileInputStream cut()

cuts out the part of the stream from IN to OUT and returns it as a new AEInputStream

Returns:

the new stream

copy

public AEFileInputStream copy()

copies out the part of the stream from IN to OUT markers and returns it as a new AEInputStream

Returns:

the new stream

paste

public void paste(AEFileInputStream in)

pastes the in stream at the IN marker into this stream

Parameters:

in - the stream to paste

skipHeader

protected void skipHeader()
                   throws java.io.IOException

skips the header lines (if any)

Throws:

java.io.IOException

readHeader

protected void readHeader(java.io.FileInputStream fileInputStream)
                   throws java.io.IOException

reads the header comment lines. Must have eventSize and chunkSizeBytes set for backwards compatiblity for files without headers to short address sizes.

Throws:

java.io.IOException

parseFileFormatVersion

protected void parseFileFormatVersion(java.lang.String s)

parses the file format version given a string with the header comment character stripped off.

See Also:

AEDataFile

getHeader

public java.util.ArrayList<java.lang.String> getHeader()

Gets the header strings from the file

Returns:

list of strings, one per line

getFile

public java.io.File getFile()

Returns the File that is being read, or null if the instance is constructed from a FileInputStream

setFile

public void setFile(java.io.File f)

Sets the File reference but doesn't open the file

getAbsoluteStartingTimeMs

public long getAbsoluteStartingTimeMs()

When the file is opened, the filename is parsed to try to extract the date and time the file was created from the filename.

Returns:

the time logging was started in ms since 1970

setAbsoluteStartingTimeMs

public void setAbsoluteStartingTimeMs(long absoluteStartingTimeMs)

isNonMonotonicTimeExceptionsChecked

public boolean isNonMonotonicTimeExceptionsChecked()

Description copied from interface: AEFileInputStreamInterface

Checking for wrapped time exceptions can be disabled for reasons of speed or corrupted data files.

Specified by:

isNonMonotonicTimeExceptionsChecked in interface AEFileInputStreamInterface

Returns:

true if exceptions are checked (default)

setNonMonotonicTimeExceptionsChecked

public void setNonMonotonicTimeExceptionsChecked(boolean yes)

Description copied from interface: AEFileInputStreamInterface

Sets whether the input stream is checked for timestamp nonmonotonicity.

Specified by:

setNonMonotonicTimeExceptionsChecked in interface AEFileInputStreamInterface

Parameters:

yes - true to check (default).