PamguardMVC
Class PamDataBlock<Tunit extends PamDataUnit>

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

All Implemented Interfaces:

PanelOverlayDraw

Direct Known Subclasses:

AbstractWhistleDataBlock, AcousticDataBlock, AISDataBlock, AngleDataBlock, BeakedDataBlock, BeakedExperimentDataBlock, DepthDataBlock, GPSDataBlock, LandmarkDataBlock, MapCommentDataBlock, NMEADataBlock, NoiseDataBlock, NoiseDataBlock, OfflineEventDataBlock, RoccaContourDataBlock, RoccaSightingDataBlock, SimObjectsDataBlock, 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

Nested Class Summary

(package private) class

PamDataBlock.OrderData

Field Summary

private boolean	acousticData
private java.util.Vector<Annotation>	annotations
private BinaryDataSource	binaryDataSource
(package private) int	channelMap
private long	currentViewDataEnd
private long	currentViewDataStart
protected java.lang.String	dataName
private boolean	isViewer
static int	ITERATOR_END
private PamObserver	lastEndUser
private int	lastRequestAnswer
private long	lastRequestEnd
private PamObserver	lastRequestObserver
private long	lastRequestStart
private boolean	linkGpsData
private int	localisationContents Flags from AbstractLocalisation to say what localisation information may be present in data in this class.
private SQLLogging	logging
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
private int	mixedDirection when Pamguard is running in mixed mode, some data are being reanalysed and are being written back into the database, others are being taken out of the database.
protected int	naturalLifetime Natural lifetime of data in seconds.
static int	NOTIFY_NEW_DATA if possible, loads old data back in from a database or other storage space.
static int	NOTIFY_UPDATE_DATA
static int	OFFLINE_DATA_CANCEL
static int	OFFLINE_DATA_INTERRUPT
static int	OFFLINE_DATA_WAIT
private java.util.Vector<OfflineDataMap>	offlineDataMaps
private PamDataBlock.OrderData	orderData
java.lang.Object	orderLock
protected java.util.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
private java.util.Vector<Tunit>	recycledUnits
private boolean	recycling Allow recycling within this data block
private int	recyclingStoreLength Max length for the recycling store.
static int	REFERENCE_ABSOLUTE When getting a DataUnit from the Datablock, get the absolute data unit, i.e.
static int	REFERENCE_CURRENT When getting a DataUnit from the Datablock, get the current data unit, i.e.
private java.util.List<Tunit>	removedItems Only used in viewer mode to store a list of items which may need to be deleted from file or the databse.
static int	REQUEST_DATA_LOADED Data loaded for requested time period.
static int	REQUEST_DATA_PARTIAL_LOAD Data partially loaded for requested time period
static int	REQUEST_EXCEPTION The request threw an exception of some sort.
static int	REQUEST_INTERRUPTED The request was interrupted (in multi thread load)
static int	REQUEST_NO_DATA No data available for offline loading.
static int	REQUEST_SAME_REQUEST this is exactly the same data as requested last time.
private java.util.Vector<PamObserver>	requestingObservers Used in offine analysis when data arebeing reloaded.
private boolean	shouldLog
(package private) javax.swing.Timer	t
private java.lang.Class	unitClass
protected int	unitsAdded
protected int	unitsRemoved
protected int	unitsUpdated

Fields inherited from class PamguardMVC.PamObservable

masterClockSample, objectChanged, overlayDraw, pamObservers, pamProfiler, totalCalls

Constructor Summary

PamDataBlock(java.lang.Class unitClass, java.lang.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	addOfflineDataMap(OfflineDataMap offlineDataMap) Adds a new offline datamap to the data block
void	addPamData(Tunit pamDataUnit) Adds a new PamDataUnit to the PamDataBlock.
private void	addRequestingObserver(PamObserver observer) Add observer to requesting observer list which is used to distribute data to selected observers when it's reloaded in offline viewer mode.
void	autoSetDataBlockMixMode()
void	clearAll() Clears all PamDataUnits from memory
void	clearDeletedList()
private int	createAllAnnotations() Gets all the annotations from the parent process and all upstream processes.
int	createAnnotations(PamDataBlock sourceData, Annotator newAnnotations) Copies all annotations over from the source DataBlock, then adds in the new ones from the new datablock.
int	createAnnotations(PamDataBlock sourceData, Annotator newAnnotations, boolean notifyDownstream) Copies all annotations over from the source DataBlock, then adds in the new ones from the new datablock.
void	dumpBlockContents()
Annotation	findAnnotation(Annotation template) Finds an annotation with the same type and name as the template annotation
Annotation	findAnnotation(java.lang.String type, java.lang.String name) Finds an annotation with the given type and name
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.
private Tunit	findDataUnitBackwards(long timeMS, int channels)
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.
java.util.Vector<Annotation>	getAnnotations()
BinaryDataSource	getBinaryDataSource()
boolean	getCanLog()
int	getChannelMap()
Tunit	getClosestUnitMillis(long startTime) Find the closest data unit to a given time.
private Tunit	getCurrentDataUnit(int ref)
long	getCurrentViewDataEnd()
long	getCurrentViewDataStart()
double	getDataGain(int iChan) Return the gain applied to any data created into this datablock.
java.lang.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
java.util.ListIterator<Tunit>	getListIterator(int whereFrom)
java.util.ListIterator<Tunit>	getListIterator(long startTimeMillis, int channels, int match, int position)
java.util.ListIterator<Tunit>	getListIteratorFromEnd(long startTime, int channels, int match, int position)
java.util.ListIterator<Tunit>	getListIteratorFromStart(long startTime, int channels, int match, int position)
int	getLocalisationContents()
SQLLogging	getLogging()
java.lang.String	getLoggingName()
java.lang.String	getLongDataName()
int	getMixedDirection()
int	getNaturalLifetime()
int	getNaturalLifetimeMillis()
long	getNextDataStart(long timeMillis) Get the next data start point.
int	getNumOfflineDataMaps()
int	getOfflineData(PamObserver observer, PamObserver endUser, long startMillis, long endMillis) Gets data for offline display, playback, etc.
int	getOfflineData(PamObserver observer, PamObserver endUser, long startMillis, long endMillis, boolean allowRepeats) Gets data for offline display, playback, etc.
OfflineDataMap	getOfflineDataMap(int iMap)
OfflineDataMap	getOfflineDataMap(OfflineDataStore dataSource)
boolean	getOrderStatus()
PamProcess	getParentProcess()
Tunit	getPreceedingUnit(java.util.ListIterator<Tunit> listIterator, long startTime) Finds the data unit before the given start time.
Tunit	getPreceedingUnit(java.util.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
long	getPrevDataEnd(long timeMillis) Get the previous data end point.
OfflineDataMap	getPrimaryDataMap() Get the data map which has the most data in it
PamRawDataBlock	getRawSourceDataBlock()
Tunit	getRecycledUnit() Gets a recycled data unit if one is available.
int	getRecyclingStoreLength()
java.util.List<Tunit>	getRemovedItems()
float	getSampleRate()
SaveRequirements	getSaveRequirements(OfflineDataStore dataStore) Work out some basic information about the elements that need saving from these data.
boolean	getShouldLog(PamDataUnit pamDataUnit)
PamDataBlock	getSourceDataBlock()
PamProcess	getSourceProcess()
java.lang.Class	getUnitClass()
int	getUnitIndex(Tunit dataUnit)
int	getUnitsCount()
int	getUnitsCountFromTime(long countStart)
boolean	isLinkGpsData()
boolean	isRecycling()
boolean	loadViewerData(long dataStart, long dataEnd) Instruction from the viewer scroll manager to load new data.
void	masterClockUpdate(long milliSeconds, long clockSample)
void	noteNewSettings() Tell all observers of this datablock that some control parameters have changed.
void	notifyModelChanged(int changeType) Receive notifications from the main PamController.
private void	notifyOfflineObservers(Tunit pamDataUnit)
void	orderOfflineData(PamObserver dataObserver, LoadObserver loadObserver, long startMillis, long endMillis, int interrupt) Similar functionality to getOfflineData, but this will launch a separate worker thread to do the actual work getting the data.
void	orderOfflineData(PamObserver dataObserver, LoadObserver loadObserver, long startMillis, long endMillis, int interrupt, boolean allowRepeats) Similar functionality to getOfflineData, but this will launch a separate worker thread to do the actual work getting the data.
void	remove()
boolean	remove(Tunit aDataUnit)
private void	removeOfflineDataMap(OfflineDataStore dataSource) remove a no longer needed offline data map.
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.
private void	removeRequestingObserver(PamObserver observer) Remove observer from requesting observer list which is used to distribute data to selected observers when it's reloaded in offline viewer mode.
boolean	saveViewerData() Saves data in this data block in offline viewer mode.
private Tunit	searchFirstUnitAfter(long timems) Search through data units, starting at the last on the assumption that we'll be more interested in more recent data.
void	setBinaryDataSource(BinaryDataSource binaryDataSource)
void	setChannelMap(int channelMap)
void	setDataName(java.lang.String dataName)
void	setLinkGpsData(boolean linkGpsData)
void	setLocalisationContents(int localisationContents)
void	SetLogging(SQLLogging logging)
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	setNaturalLifetimeMillis(int naturalLifetime)
void	setRecycling(boolean recycling)
void	setRecyclingStoreLength(int recyclingStoreLength)
void	setSampleRate(float sampleRate, boolean notify) Sets the sample rate for the block (e.g.
void	setShouldLog(boolean shouldLog)
private boolean	shouldDelete()
boolean	shouldNotify()
private Tunit	slowFindByDatabaseIndex(int databaseIndex) Search all units in reverse order.
java.lang.String	toString()
void	updatePamData(Tunit pamDataUnit, long timeMillis)

Methods inherited from class PamguardMVC.PamObservable

canDraw, clearchanged, countObservers, createKeyItem, deleteObserver, deleteObservers, drawDataUnit, findThreadedObserver, getCPUPercent, getCPUPercent, getHoverText, getLongestObserver, getPamObservers, getRequiredHistory, notifyObservers, notifyObservers, setChanged, setOverlayDraw, 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 absolute 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

mixedDirection

private int mixedDirection

when Pamguard is running in mixed mode, some data are being reanalysed and are being written back into the database, others are being taken out of the database.

These flags tell each individual datablock what it should do.

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 java.lang.String dataName

REQUEST_NO_DATA

public static final int REQUEST_NO_DATA

No data available for offline loading.

See Also:

Constant Field Values

REQUEST_DATA_LOADED

public static final int REQUEST_DATA_LOADED

Data loaded for requested time period.

See Also:

Constant Field Values

REQUEST_DATA_PARTIAL_LOAD

public static final int REQUEST_DATA_PARTIAL_LOAD

Data partially loaded for requested time period

See Also:

Constant Field Values

REQUEST_SAME_REQUEST

public static final int REQUEST_SAME_REQUEST

this is exactly the same data as requested last time.

This flag will be used with one of the other three.

See Also:

Constant Field Values

REQUEST_INTERRUPTED

public static final int REQUEST_INTERRUPTED

The request was interrupted (in multi thread load)

See Also:

Constant Field Values

REQUEST_EXCEPTION

public static final int REQUEST_EXCEPTION

The request threw an exception of some sort.

See Also:

Constant Field Values

pamDataUnits

protected java.util.List<Tunit extends PamDataUnit> pamDataUnits

removedItems

private java.util.List<Tunit extends PamDataUnit> removedItems

Only used in viewer mode to store a list of items which may need to be deleted from file or the databse.

isViewer

private boolean isViewer

parentProcess

protected PamProcess parentProcess

binaryDataSource

private BinaryDataSource binaryDataSource

localisationContents

private int localisationContents

Flags from AbstractLocalisation to say what localisation information may be present in data in this class. This is the maximum data which are likely to be found within each data unit and are NOT a guarantee that individul data units will have that level of localisation content.

requestingObservers

private java.util.Vector<PamObserver> requestingObservers

Used in offine analysis when data arebeing reloaded. this list gets used to distribute data beingloaded from upstream processes.

naturalLifetime

protected int naturalLifetime

Natural lifetime of data in seconds.

unitsRemoved

protected int unitsRemoved

unitsAdded

protected int unitsAdded

unitsUpdated

protected int unitsUpdated

channelMap

int channelMap

linkGpsData

private boolean linkGpsData

unitClass

private java.lang.Class unitClass

acousticData

private boolean acousticData

recycling

private boolean recycling

Allow recycling within this data block

recyclingStoreLength

private int recyclingStoreLength

Max length for the recycling store.

recycledUnits

private java.util.Vector<Tunit extends PamDataUnit> recycledUnits

t

javax.swing.Timer t

currentViewDataStart

private long currentViewDataStart

currentViewDataEnd

private long currentViewDataEnd

NOTIFY_NEW_DATA

public static final int NOTIFY_NEW_DATA

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

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

annotations

private java.util.Vector<Annotation> annotations

offlineDataMaps

private java.util.Vector<OfflineDataMap> offlineDataMaps

logging

private SQLLogging logging

shouldLog

private boolean shouldLog

OFFLINE_DATA_INTERRUPT

public static final int OFFLINE_DATA_INTERRUPT

See Also:

Constant Field Values

OFFLINE_DATA_WAIT

public static final int OFFLINE_DATA_WAIT

See Also:

Constant Field Values

OFFLINE_DATA_CANCEL

public static final int OFFLINE_DATA_CANCEL

See Also:

Constant Field Values

orderData

private volatile PamDataBlock.OrderData orderData

orderLock

public java.lang.Object orderLock

lastRequestAnswer

private int lastRequestAnswer

lastRequestStart

private long lastRequestStart

lastRequestEnd

private long lastRequestEnd

lastRequestObserver

private PamObserver lastRequestObserver

lastEndUser

private PamObserver lastEndUser

Constructor Detail

PamDataBlock

public PamDataBlock(java.lang.Class unitClass,
                    java.lang.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

shouldDelete

private boolean shouldDelete()

remove

public void remove()

getUnitsCount

public int getUnitsCount()

Returns:

The total number of PamDataUnits in the block

getUnitsCountFromTime

public int getUnitsCountFromTime(long countStart)

getRemovedItems

public java.util.List<Tunit> getRemovedItems()

Returns:

the removedItems list

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)

findDataUnitBackwards

private Tunit findDataUnitBackwards(long timeMS,
                                    int channels)

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.

slowFindByDatabaseIndex

private Tunit slowFindByDatabaseIndex(int databaseIndex)

Search all units in reverse order.

Parameters:

databaseIndex - Database index to search for

Returns:

found unit

searchFirstUnitAfter

private Tunit searchFirstUnitAfter(long timems)

Search through data units, starting at the last on the assumption that we'll be more interested in more recent data.

Parameters:

timems - search time

Returns:

found data unit or null

clearAll

public void clearAll()

Clears all PamDataUnits from memory

In viewer mode, data are also re-saved.

getCurrentViewDataStart

public long getCurrentViewDataStart()

Returns:

the start time of data currently loaded by the viewer.

getCurrentViewDataEnd

public long getCurrentViewDataEnd()

Returns:

the end time of data currently loaded by the viewer.

loadViewerData

public boolean loadViewerData(long dataStart,
                              long dataEnd)

Instruction from the viewer scroll manager to load new data.

Parameters:

dataStart - data start time in millis

dataEnd - data end time in millis.

saveViewerData

public boolean saveViewerData()

Saves data in this data block in offline viewer mode.

Returns:

true if data found and saved.

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

notifyOfflineObservers

private void notifyOfflineObservers(Tunit pamDataUnit)

updatePamData

public void updatePamData(Tunit pamDataUnit,
                          long timeMillis)

shouldNotify

public boolean shouldNotify()

remove

public boolean remove(Tunit 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 tries 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)

getRecycledUnit

public Tunit getRecycledUnit()

Gets a recycled data unit if one is available.

Returns:

recycled unit, or null

getSourceDataBlock

public PamDataBlock getSourceDataBlock()

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

getCurrentDataUnit

private Tunit getCurrentDataUnit(int ref)

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(java.util.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(java.util.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 java.lang.String getDataName()

Returns:

Name of the data in the block.

getLongDataName

public java.lang.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. Modified July 09 to make sure it doesn't loop through itself when using threaded observers.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getNaturalLifetime

public int getNaturalLifetime()

Returns:

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

setNaturalLifetimeMillis

public void setNaturalLifetimeMillis(int naturalLifetime)

getNaturalLifetimeMillis

public int getNaturalLifetimeMillis()

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()

getDataGain

public double getDataGain(int iChan)

Return the gain applied to any data created into this datablock.

Example 1: The amplifier module will just return it's gain

Example 2: The FFT module will return the loss due to windowing the data.

To convert to dB use 20*log10(Math.abs(getDataGain()));

Parameters:

iChan - channel number

Returns:

gain as a factor (to allow for negative gains)

setChannelMap

public void setChannelMap(int channelMap)

setDataName

public void setDataName(java.lang.String dataName)

Parameters:

dataName - The dataName to set.

getLoggingName

public java.lang.String getLoggingName()

getParentProcess

public PamProcess getParentProcess()

Returns:

Returns the parentProcess.

getSourceProcess

public PamProcess getSourceProcess()

Returns:

Returns the sourceProcess.

getRawSourceDataBlock

public PamRawDataBlock getRawSourceDataBlock()

addObserver

public void addObserver(PamObserver o)

Description copied from class: PamObservable

Adds a PamObserver, which will then receive notifications when data is added. This is for single thread ops only

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 java.lang.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 java.util.ListIterator<Tunit> getListIterator(int whereFrom)

getListIterator

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

getListIteratorFromStart

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

dumpBlockContents

public void dumpBlockContents()

getListIteratorFromEnd

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

getAnnotations

public java.util.Vector<Annotation> getAnnotations()

createAllAnnotations

private int createAllAnnotations()

Gets all the annotations from the parent process and all upstream processes.

Returns:

total number of annotations

createAnnotations

public int createAnnotations(PamDataBlock sourceData,
                             Annotator newAnnotations)

Copies all annotations over from the source DataBlock, then adds in the new ones from the new datablock.

Parameters:

sourceData - source Datablock

newAnnotations - source of new annotations

Returns:

total number of annotations

createAnnotations

public int createAnnotations(PamDataBlock sourceData,
                             Annotator newAnnotations,
                             boolean notifyDownstream)

Copies all annotations over from the source DataBlock, then adds in the new ones from the new datablock.

Parameters:

sourceData - source Datablock

newAnnotations - source of new annotations

notifydownstream - notify downstream modules.

Returns:

total number of annotations

findAnnotation

public Annotation findAnnotation(java.lang.String type,
                                 java.lang.String name)

Finds an annotation with the given type and name

Parameters:

type - annotation type

name - annotation name

Returns:

annotation object

findAnnotation

public Annotation findAnnotation(Annotation template)

Finds an annotation with the same type and name as the template annotation

Parameters:

template - template annotation

Returns:

annotation object

setRecycling

public void setRecycling(boolean recycling)

Parameters:

recycling - the recycling to set

isRecycling

public boolean isRecycling()

Returns:

the recycling

setRecyclingStoreLength

public void setRecyclingStoreLength(int recyclingStoreLength)

Parameters:

recyclingStoreLength - the recyclingStoreLength to set

getRecyclingStoreLength

public int getRecyclingStoreLength()

Returns:

the recyclingStoreLength

notifyModelChanged

public void notifyModelChanged(int changeType)

Receive notifications from the main PamController.

Parameters:

changeType -

setBinaryDataSource

public void setBinaryDataSource(BinaryDataSource binaryDataSource)

Parameters:

siterBinaryDataSource - the siterBinaryDataSource to set

getBinaryDataSource

public BinaryDataSource getBinaryDataSource()

Returns:

the siterBinaryDataSource

SetLogging

public void SetLogging(SQLLogging logging)

getLogging

public SQLLogging getLogging()

getCanLog

public final boolean getCanLog()

getShouldLog

public boolean getShouldLog(PamDataUnit pamDataUnit)

setShouldLog

public final void setShouldLog(boolean shouldLog)

addOfflineDataMap

public void addOfflineDataMap(OfflineDataMap offlineDataMap)

Adds a new offline datamap to the data block

Note that there may be several maps from different types of storage (although only one should have anything in it in a sensible world).

It's also possible that these will be recreated during a run, and we don't want two of the same type in the same datablock, so check that there isn't already one and remove it

Parameters:

offlineDataMap -

getNumOfflineDataMaps

public int getNumOfflineDataMaps()

Returns:

the number of different offline data maps

getOfflineDataMap

public OfflineDataMap getOfflineDataMap(int iMap)

Parameters:

iMap - index of map (see getNumOfflineDataMaps)

Returns:

an OfflineDataMap from that index in the list.

getOfflineDataMap

public OfflineDataMap getOfflineDataMap(OfflineDataStore dataSource)

Parameters:

dataSource - an offline data source (e.g. binaray storage, database storage, etc.

Returns:

the offline data map for a specific OfflineDataSource or null

getPrimaryDataMap

public OfflineDataMap getPrimaryDataMap()

Get the data map which has the most data in it

Returns:

a data map

removeOfflineDataMap

private void removeOfflineDataMap(OfflineDataStore dataSource)

remove a no longer needed offline data map.

Parameters:

dataSource - data source (e.g. binary, database, raw data, etc.

getSaveRequirements

public SaveRequirements getSaveRequirements(OfflineDataStore dataStore)

Work out some basic information about the elements that need saving from these data.

Parameters:

dataStore - data source that want's to save the data.

Returns:

an object of information

orderOfflineData

public void orderOfflineData(PamObserver dataObserver,
                             LoadObserver loadObserver,
                             long startMillis,
                             long endMillis,
                             int interrupt)

Similar functionality to getOfflineData, but this will launch a separate worker thread to do the actual work getting the data. The worker thread will call getOfflineData.

getOfflineData will probably (if not overridden) be sending data to the update member function of the observer, but from the worker thread. Once it's complete, it will send a message to say that data are loaded.

It's possible that the user will do something which causes this to be called again before the previous thread completed execution, in which case there are three options:

OFFLINE_DATA_INTERRUPT - previous thread will be terminated

OFFLINE_DATA_WAIT - wait for previous thread to terminate, then start this load

OFFLINE_DATA_CANCEL - give up and return

Parameters:

dataObserver - observer of the loaded data

loadObserver - observer to get status information on the load.

startMillis - data start time in imilliseconds

endMillis - data end time in milliseconds.

interrupt - interrupt options.

orderOfflineData

public void orderOfflineData(PamObserver dataObserver,
                             LoadObserver loadObserver,
                             long startMillis,
                             long endMillis,
                             int interrupt,
                             boolean allowRepeats)

Similar functionality to getOfflineData, but this will launch a separate worker thread to do the actual work getting the data. The worker thread will call getOfflineData.

getOfflineData will probably (if not overridden) be sending data to the update member function of the observer, but from the worker thread. Once it's complete, it will send a message to say that data are loaded.

It's possible that the user will do something which causes this to be called again before the previous thread completed execution, in which case there are three options:

OFFLINE_DATA_INTERRUPT - previous thread will be terminated

OFFLINE_DATA_WAIT - wait for previous thread to terminate, then start this load

OFFLINE_DATA_CANCEL - give up and return

Parameters:

dataObserver - observer of the loaded data

loadObserver - observer to get status information on the load.

startMillis - data start time in imilliseconds

endMillis - data end time in milliseconds.

interrupt - interrupt options.

allowRepeats - allow repeated loads of exactly the same data.

getOrderStatus

public boolean getOrderStatus()

Returns:

true if an order for data is currently still being processed.

getOfflineData

public int getOfflineData(PamObserver observer,
                          PamObserver endUser,
                          long startMillis,
                          long endMillis)

Gets data for offline display, playback, etc.

This is used to get data from some upstream process which is quite different to the function loadViewerData(...) which loads data directly associated with this data block.

For example, this might be called in the FFT data block by the spectrogram which wants some data to display. The FFT data block does not have this data, so it passes the request up to it's process which will in turn pass the request on until it reaches a module which is capable of loading data into data units and sending them back down the line.

Thsi will not cause the same data to be reloaded for the same observer a second time - use the full version with extra paramter if you need this.

Parameters:

observer - data observer which will receive the data

startMillis - start time in milliseconds

endMillis - end time in milliseconds

allowRepeats - allow the same data to be loaded a second time.

Returns:

true if request satisfied or partially satisfied.

getOfflineData

public int getOfflineData(PamObserver observer,
                          PamObserver endUser,
                          long startMillis,
                          long endMillis,
                          boolean allowRepeats)

Gets data for offline display, playback, etc.

This is used to get data from some upstream process which is quite different to the function loadViewerData(...) which loads data directly associated with this data block.

For example, this might be called in the FFT data block by the spectrogram which wants some data to display. The FFT data block does not have this data, so it passes the request up to it's process which will in turn pass the request on until it reaches a module which is capable of loading data into data units and sending them back down the line.

Parameters:

observer - data observer which will receive the data

startMillis - start time in milliseconds

endMillis - end time in milliseconds

allowRepeats - allow the same data to be loaded a second time.

Returns:

true if request satisfied or partially satisfied.

addRequestingObserver

private void addRequestingObserver(PamObserver observer)

Add observer to requesting observer list which is used to distribute data to selected observers when it's reloaded in offline viewer mode.

Parameters:

observer - observer

removeRequestingObserver

private void removeRequestingObserver(PamObserver observer)

Remove observer from requesting observer list which is used to distribute data to selected observers when it's reloaded in offline viewer mode.

Parameters:

observer - observer

clearDeletedList

public void clearDeletedList()

getNextDataStart

public long getNextDataStart(long timeMillis)

Get the next data start point. i.e. the time of the start of a map point which is > timeMillis

Parameters:

timeMillis - current time in milliseconds

Returns:

start time of the next data start.

getPrevDataEnd

public long getPrevDataEnd(long timeMillis)

Get the previous data end point. i.e. the time of the end of a map point which is < timeMillis

Parameters:

timeMillis - current time in milliseconds

Returns:

start time of the next data start.