PamguardMVC
Class PamDataBlock<Tunit extends PamDataUnit>

java.lang.Object
  PamguardMVC.PamObservable
      PamguardMVC.PamDataBlock<Tunit>

All Implemented Interfaces:

PanelOverlayDraw

Direct Known Subclasses:

whitesWhistleDetector.AbstractWhistleDataBlock, AISDataBlock, AngleDataBlock, BeakedDataBlock, BeakedExperimentDataBlock, ClickDataBlock, ClickGroupDataBlock, DepthDataBlock, LandmarkDataBlock, MapCommentDataBlock, RecyclingDataBlock, SingletonDataBlock, TerrellaDataBlock, VRDataBlock, WhistleClasificationDataBlock

public class PamDataBlock<Tunit extends PamDataUnit>
extends PamObservable

Author:

Doug Gillespie

PamDataBlocks manage the data from PamProcesses.

New data, either from external sources (sound cards, GPS, etc.) or detector output (clicks or whistles, etc.) are placed in PamDataUnits. The job of a PamDataBlock is to manage those PamDataUnits.

Processes that require the data from a PamDataBlock must implement PamObserver and subscribe as listeners to the PamDataBlock. When a new PamDataUnit is added to a data block, all listeners will be notified and sent references both to the data block and the data unit.

Each PamDatablock is also responsible for deleting old data. Since only the observers of PamDataBlocks know how much historical data is required, before deleting any data each PamDataBlock asks all the PamObservers for their required data history in milliseconds and takes the maximum value returned by all observers. The PamDataBlock will then calculate the time of the first required data unit and delete all preceding units. This operation takes place approximately once per second.

For example, a whistle detector, while searching for whistles, may only require the last two or three data units from the data block containing FFT data, but when it's found a complete whistle, it may need to go back and look at the FFT data from other channels in order to calculate a location, or it may require the raw data in order to look at the original waveform. As another example, the map panel may want to hold several hours of data in memory for display purposes.

It is essential that PamProcesses are realistic about how much data they can ask a PamDataBlock to hold - if they consistently ask for too much data to be stored, the computer will run out of memory.

See Also:

PamDataUnit, PamProcess

Field Summary

protected String	dataName
static int	ITERATOR_END
static int	MATCH_AFTER If there is not exact time match, set the iterator so that the first element it returns will be the element after the requested time.
static int	MATCH_BEFORE If there is not exact time match, set the iterator so that the first element it returns will be the element before the requested time.
static int	MATCH_EXACT Only accept an iterator for a unit that matches the time exactly
static int	MIX_DONOTHING
static int	MIX_INTODATABASE
static int	MIX_OUTOFDATABASE
protected int	naturalLifetime Natural lifetime of data in seconds.
static int	NOTIFY_NEW_DATA
static int	NOTIFY_UPDATE_DATA
protected List<Tunit>	pamDataUnits
protected PamProcess	parentProcess
static int	POSITION_AFTER Set the iterator so that a call to next() will give the first wanted element
static int	POSITION_BEFORE Set the iterator so that a call to previous() will give the first wanted element
static int	REFERENCE_ABSOLUTE When getting a DataUnit from the Datablock, get the abosulte data unit, i.e.
static int	REFERENCE_CURRENT When getting a DataUnit from the Datablock, get the current data unit, i.e.
protected int	unitsAdded
protected int	unitsRemoved
protected int	unitsUpdated

Fields inherited from class PamguardMVC.PamObservable

logging, masterClockSample, objectChanged, overlayDraw, pamObservers, pamProfiler

Constructor Summary

PamDataBlock(Class unitClass, String dataName, PamProcess parentProcess, int channelMap)
PamDataBlock constructor.

Method Summary

void	addLocalisationContents(int localisationContents)
void	addObserver(PamObserver o) Adds a PamObserver, which will then receive notifications when data is added
void	addObserver(PamObserver o, boolean reThread)
void	addPamData(Tunit pamDataUnit) Adds a new PamDataUnit to the PamDataBlock.
void	autoSetDataBlockMixMode()
void	clearAll() Clears all PamDataUnits from memory
void	dumpBlockContents()
Tunit	findByDatabaseIndex(int databaseIndex) Find a dataunit based on it's database index.
Tunit	findDataUnit(long timeMS, int channels) Find a data unit.
Tunit	findDataUnit(long timeMS, int channels, int absStartPos) Find a unit that starts at a specific time.
protected Tunit	getAbsoluteDataUnit(int absReference) Gets a specific data unit using an absolute reference system which keeps track of data units that have been removed.
int	getChannelMap()
Tunit	getClosestUnitMillis(long startTime) Find the closest data unit to a given time.
String	getDataName()
Tunit	getDataUnit(int ref, int refType) Gets a reference to a data unit.
Tunit	getFirstUnit() Gets the first data unit stored
Tunit	getFirstUnitAfter(long timems) Return the first DataUnit that is on or after the given time
Tunit	getLastUnit() Gets the last data unit stored
ListIterator<Tunit>	getListIterator(int whereFrom)
ListIterator<Tunit>	getListIterator(long startTimeMillis, int channels, int match, int position)
ListIterator<Tunit>	getListIteratorFromEnd(long startTime, int channels, int match, int position)
ListIterator<Tunit>	getListIteratorFromStart(long startTime, int channels, int match, int position)
int	getLocalisationContents()
String	getLoggingName()
String	getLongDataName()
int	getMixedDirection()
int	getNaturalLifetime()
PamProcess	getParentProcess()
Tunit	getPreceedingUnit(ListIterator<Tunit> listIterator, long startTime) Finds the data unit before the given start time.
Tunit	getPreceedingUnit(ListIterator<Tunit> listIterator, long startTime, int channelMap) Finds the data unit before the given start time that has the same channel map.
Tunit	getPreceedingUnit(long startTime) Simple function to find the data unit at or before the given start time.
Tunit	getPreceedingUnit(long startTime, int channelMap) Simple function to find the data unit at or before the given start time that has a given channel bitmap
PamRawDataBlock	getRawSourceDataBlock()
float	getSampleRate()
PamDataBlock	getSourceDataBlock()
PamProcess	getSourceProcess()
Class	getUnitClass()
int	getUnitIndex(Tunit dataUnit)
int	getUnitsCount()
int	getUnitsCountFromTime(long countStart)
boolean	isLinkGpsData()
void	loadViewData(PamViewParameters pamViewParameters) if possible, loads old data back in from a database or other storage space.
void	masterClockUpdate(long milliSeconds, long clockSample)
void	noteNewSettings() Tell all observers of this datablock that some control parameters have changed.
void	remove()
boolean	remove(PamDataUnit aDataUnit)
protected int	removeOldUnitsS(long mastrClockSample)
protected int	removeOldUnitsT(long currentTimeMS) Removes olderPamDataUnits from memory, starting at the first unit and continuing until if finds one with data coming earlier than the given time in milliseconds.
void	setChannelMap(int channelMap)
void	setDataName(String dataName)
void	setLinkGpsData(boolean linkGpsData)
void	setLocalisationContents(int localisationContents)
void	setMixedDirection(int mixedDirection)
void	setNaturalLifetime(int naturalLifetime) Set the natural lifetime of the data if there are no observers asking to keep it for longer
void	setSampleRate(float sampleRate, boolean notify) Sets the sample rate for the block (e.g.
boolean	shouldNotify()
String	toString()
void	updatePamData(Tunit pamDataUnit, long timeMillis)

Methods inherited from class PamguardMVC.PamObservable

canDraw, clearchanged, countObservers, createKeyItem, deleteObserver, deleteObservers, drawDataUnit, findThreadedObserver, getCanLog, getCPUPercent, getCPUPercent, getHoverText, getLogging, getLongestObserver, getPamObservers, getRequiredHistory, getShouldLog, notifyObservers, notifyObservers, setChanged, SetLogging, setOverlayDraw, setShouldLog, waitForThreadedObservers

Methods inherited from class java.lang.Object

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

Field Detail

REFERENCE_ABSOLUTE

public static final int REFERENCE_ABSOLUTE

When getting a DataUnit from the Datablock, get the abosulte data unit, i.e. the unit number as would be if none had ever been deleted

See Also:

Constant Field Values

REFERENCE_CURRENT

public static final int REFERENCE_CURRENT

When getting a DataUnit from the Datablock, get the current data unit, i.e. the unit number in the current ArrayList

See Also:

Constant Field Values

MIX_DONOTHING

public static final int MIX_DONOTHING

See Also:

Constant Field Values

MIX_OUTOFDATABASE

public static final int MIX_OUTOFDATABASE

See Also:

Constant Field Values

MIX_INTODATABASE

public static final int MIX_INTODATABASE

See Also:

Constant Field Values

dataName

protected String dataName

pamDataUnits

protected List<Tunit extends PamDataUnit> pamDataUnits

parentProcess

protected PamProcess parentProcess

naturalLifetime

protected int naturalLifetime

Natural lifetime of data in seconds.

unitsRemoved

protected int unitsRemoved

unitsAdded

protected int unitsAdded

unitsUpdated

protected int unitsUpdated

NOTIFY_NEW_DATA

public static final int NOTIFY_NEW_DATA

See Also:

Constant Field Values

NOTIFY_UPDATE_DATA

public static final int NOTIFY_UPDATE_DATA

See Also:

Constant Field Values

ITERATOR_END

public static final int ITERATOR_END

See Also:

Constant Field Values

MATCH_EXACT

public static final int MATCH_EXACT

Only accept an iterator for a unit that matches the time exactly

See Also:

Constant Field Values

MATCH_BEFORE

public static final int MATCH_BEFORE

If there is not exact time match, set the iterator so that the first element it returns will be the element before the requested time.

See Also:

Constant Field Values

MATCH_AFTER

public static final int MATCH_AFTER

If there is not exact time match, set the iterator so that the first element it returns will be the element after the requested time.

See Also:

Constant Field Values

POSITION_BEFORE

public static final int POSITION_BEFORE

Set the iterator so that a call to previous() will give the first wanted element

See Also:

Constant Field Values

POSITION_AFTER

public static final int POSITION_AFTER

Set the iterator so that a call to next() will give the first wanted element

See Also:

Constant Field Values

Constructor Detail

PamDataBlock

public PamDataBlock(Class unitClass,
                    String dataName,
                    PamProcess parentProcess,
                    int channelMap)

PamDataBlock constructor.

Parameters:

unitClass - class of data unit to hold in this data block

dataName - name of data block

parentProcess - parent PamProcess

channelMap - bitmap of channels which may be represented in data units in this data block.

Method Detail

remove

public void remove()

getUnitsCount

public int getUnitsCount()

Returns:

The total number of PamDataUnits in the block

getUnitsCountFromTime

public int getUnitsCountFromTime(long countStart)

getFirstUnitAfter

public Tunit getFirstUnitAfter(long timems)

Return the first DataUnit that is on or after the given time

Parameters:

timems - Milliseconds - UTC in standard Java epoch

Returns:

a PamDataUnit or null if no data were found

findDataUnit

public Tunit findDataUnit(long timeMS,
                          int channels,
                          int absStartPos)

Find a unit that starts at a specific time. searchStart may help to speed things up, however, now that a LinkedList is used in place of a vector, it's likely that this speed increase will be small.

Parameters:

timeMS - start time of data unit

channels - channel bitmap of data unit

absStartPos - start position for search, -1 if you want to start searching backwards from the end.

Returns:

data unit (or null if nothing found)

findDataUnit

public Tunit findDataUnit(long timeMS,
                          int channels)

Find a data unit. By default, the search starts at the end of the list and works backwards on the assumption that we'll be more interested in more recent data.

Parameters:

timeMS - start time of PamDataUnit

channels - channel bitmap of PamDataUnit

Returns:

found data unit, or null.

getUnitIndex

public int getUnitIndex(Tunit dataUnit)

findByDatabaseIndex

public Tunit findByDatabaseIndex(int databaseIndex)

Find a dataunit based on it's database index. If there have been no updates, then database indexes should be in order and a fast find canbe used. If however, there have been updates, then things will not be in order so it's necessary to go through everything from start to end.

Parameters:

databaseIndex - Index to search for.

Returns:

found unit or null.

clearAll

public void clearAll()

Clears all PamDataUnits from memory

loadViewData

public void loadViewData(PamViewParameters pamViewParameters)

if possible, loads old data back in from a database or other storage space.

addPamData

public void addPamData(Tunit pamDataUnit)

Adds a new PamDataUnit to the PamDataBlock. When the data unit is added, PamObservers that have subscribed to the block will be notified.

Parameters:

pamDataUnit - Reference to a PamDataUnit

updatePamData

public void updatePamData(Tunit pamDataUnit,
                          long timeMillis)

shouldNotify

public boolean shouldNotify()

remove

public boolean remove(PamDataUnit aDataUnit)

removeOldUnitsT

protected int removeOldUnitsT(long currentTimeMS)

Removes olderPamDataUnits from memory, starting at the first unit and continuing until if finds one with data coming earlier than the given time in milliseconds.

If the data are acoustic, it trys to find the data source and looks to see how much data has been placed in the source data unit and does the calculation in samples.

Parameters:

currentTimeMS - Time in milliseconds of the first data which must be kept

Returns:

the number of units removed

removeOldUnitsS

protected int removeOldUnitsS(long mastrClockSample)

getSourceDataBlock

public PamDataBlock getSourceDataBlock()

getRawSourceDataBlock

public PamRawDataBlock getRawSourceDataBlock()

getDataUnit

public Tunit getDataUnit(int ref,
                         int refType)

Gets a reference to a data unit.

Parameters:

ref - number of the data unit

refType - REFERENCE_ABSOLUTE or REFERENCE_CURRENT

Returns:

DataUnit \n If refType is REFERENCE_ABSOLUTE then the data unit with the absolute position ref is returned (if it has not yet been deleted). This might be used to re-access a specific unit or to access the unit coming directly before or after a previously accessed unit. \n If refType is REFERENCE_CURRENT then the data unit at that position in the current ArrayList is returned.

getAbsoluteDataUnit

protected Tunit getAbsoluteDataUnit(int absReference)

Gets a specific data unit using an absolute reference system which keeps track of data units that have been removed. Returns null if the specified unit is no longer available.

Parameters:

absReference - Absolute reference to the data unit

Returns:

Requested PamDataUnit

getLastUnit

public Tunit getLastUnit()

Gets the last data unit stored

Returns:

data unit or null

getFirstUnit

public Tunit getFirstUnit()

Gets the first data unit stored

Returns:

data unit or null

getPreceedingUnit

public Tunit getPreceedingUnit(ListIterator<Tunit> listIterator,
                               long startTime)

Finds the data unit before the given start time.

This implementation is passed an iterator which has already been initialised to be at the END of the list. In this way, the calling function has access to the iterator and can access nearby elements.

Parameters:

listIterator - pre initialised ListIterator

startTime - search time in milliseconds

Returns:

data unit at or following the given time.

See Also:

ListIterator

getPreceedingUnit

public Tunit getPreceedingUnit(ListIterator<Tunit> listIterator,
                               long startTime,
                               int channelMap)

Finds the data unit before the given start time that has the same channel map.

This implementation is passed an iterator which has already been initialised to be at the END of the list. In this way, the calling function has access to the iterator and can access nearby elements.

Parameters:

listIterator - pre initialised ListIterator

startTime - search time in milliseconds

channelMap - Channel bitmap

Returns:

data unit at or following the given time.

See Also:

ListIterator

getPreceedingUnit

public Tunit getPreceedingUnit(long startTime)

Simple function to find the data unit at or before the given start time.

Parameters:

startTime - search time in milliseconds

Returns:

data unit at or following the given time.

getPreceedingUnit

public Tunit getPreceedingUnit(long startTime,
                               int channelMap)

Simple function to find the data unit at or before the given start time that has a given channel bitmap

Parameters:

startTime - search time in milliseconds

channelMap - Channel bitmap

Returns:

data unit at or following the given time.

getClosestUnitMillis

public Tunit getClosestUnitMillis(long startTime)

Find the closest data unit to a given time.

Parameters:

startTime - Start time of data unit (milliseconds)

Returns:

closest data unit

getSampleRate

public float getSampleRate()

Returns:

The sample rate of the data contained in the block

getDataName

public String getDataName()

Returns:

Name of the data in the block.

getLongDataName

public String getLongDataName()

setSampleRate

public void setSampleRate(float sampleRate,
                          boolean notify)

Sets the sample rate for the block (e.g. call this after opening a sound file and reading the sample rate from the file header or after altering sound card settings). All observers of this block (PamProcesses and some views) are notified, they in turn should tell their own output PamDataBlocks about the change.

Parameters:

sampleRate - The new sample rate in Hz.

notify - set true if Observers should be notified

masterClockUpdate

public void masterClockUpdate(long milliSeconds,
                              long clockSample)

noteNewSettings

public void noteNewSettings()

Tell all observers of this datablock that some control parameters have changed.

toString

public String toString()

Overrides:

toString in class Object

getNaturalLifetime

public int getNaturalLifetime()

Returns:

Finds the original data block, i.e. the one that has a PamProcess with no source data block.

setNaturalLifetime

public void setNaturalLifetime(int naturalLifetime)

Set the natural lifetime of the data if there are no observers asking to keep it for longer

Parameters:

naturalLifetime - in seconds (NOT milliseconds)

isLinkGpsData

public boolean isLinkGpsData()

setLinkGpsData

public void setLinkGpsData(boolean linkGpsData)

getChannelMap

public int getChannelMap()

setChannelMap

public void setChannelMap(int channelMap)

setDataName

public void setDataName(String dataName)

Parameters:

dataName - The dataName to set.

getLoggingName

public String getLoggingName()

getParentProcess

public PamProcess getParentProcess()

Returns:

Returns the parentProcess.

getSourceProcess

public PamProcess getSourceProcess()

Returns:

Returns the sourceProcess.

addObserver

public void addObserver(PamObserver o)

Description copied from class: PamObservable

Adds a PamObserver, which will then receive notifications when data is added

Overrides:

addObserver in class PamObservable

Parameters:

o - Reference to the observer

addObserver

public void addObserver(PamObserver o,
                        boolean reThread)

Overrides:

addObserver in class PamObservable

getUnitClass

public Class getUnitClass()

Returns:

Class type for the sotred data units in this data block.

autoSetDataBlockMixMode

public void autoSetDataBlockMixMode()

getMixedDirection

public int getMixedDirection()

setMixedDirection

public void setMixedDirection(int mixedDirection)

getLocalisationContents

public int getLocalisationContents()

setLocalisationContents

public void setLocalisationContents(int localisationContents)

addLocalisationContents

public void addLocalisationContents(int localisationContents)

getListIterator

public ListIterator<Tunit> getListIterator(int whereFrom)

getListIterator

public ListIterator<Tunit> getListIterator(long startTimeMillis,
                                           int channels,
                                           int match,
                                           int position)

getListIteratorFromStart

public ListIterator<Tunit> getListIteratorFromStart(long startTime,
                                                    int channels,
                                                    int match,
                                                    int position)

dumpBlockContents

public void dumpBlockContents()

getListIteratorFromEnd

public ListIterator<Tunit> getListIteratorFromEnd(long startTime,
                                                  int channels,
                                                  int match,
                                                  int position)