PamguardMVC

Class PamProcess

java.lang.Object

PamguardMVC.PamProcess

All Implemented Interfaces:

PamObserver, ProcessAnnotator

Direct Known Subclasses:

AcquireNmeaData, AcquisitionProcess, AirgunProcess, AlarmProcess, AmpProcess, AngleListener, AngleProcess, ArrayAccelProcess, BeakedProcess, BinaryClickProcess, BinaryStoreProcess, ClickAlarmManager, ClickDetector, ClickTrainDetector, DbHtProcess, DBProcess, DecimatorProcess, DepthProcess, DifarProcess, DStrProcess, EchoProcess, EdgeProcess, EnvelopeProcess, FilterProcess, FormsProcess, HydrophoneProcess, IMUListener, IMUProcess, IpiProcess, IshDetFnProcess, IshLocProcess, IshPeakProcess, KernelSmoothingProcess, LikelihoodFFTProcess, LinearAverageSpectraProcess, ListeningProcess, LtsaProcess, MapProcess, MarkProcess, NetworkSendProcess, NoiseBandProcess, NoiseProcess, NormalizerProcess, OfflineFileProcess, OfflineProcessingProcess, OneBandProcess, OneBandPulseProcess, PamFFTProcess, PatchPanelProcess, PeakDetector, PlaybackProcess, ProcessAISData, ProcessHeadingData, ProcessIshmaelData, ProcessNmeaData, RecorderProcess, RoccaProcess, RoccaWhistleSelect, RWEProcess, SerialDataProcess, SMLPingerProcess, SpectralEtiProcess, SpectrogramMarkProcess, SpectrogramMedianFilter, SpectrogramNoiseProcess, StaticLocaliserProcess, TargetMotionProcess, ThresholdDetectorProcess, TowedArray3DProcess, TrackedClickLocaliser, TrackedGroupProcess, UserInputProcess, VetoProcess, VRProcess, WhistleClassifierProcess, WhistleDetector, WhistleEventDetector, WhistleLinker, WhistleToneConnectProcess, WorkshopProcess, XBatLogProcess

public abstract class PamProcess
extends java.lang.Object
implements PamObserver, ProcessAnnotator

Author:

Doug Gillespie

PamProcess is an abstract class used as a supertype for the creation of processes which either convert one type of PamData into a new type or add existing information to already existing data

All PamProcesses are Listeners and implement the Observer Class from java.util

The first PamProcess to be created will often be something which generates raw data (either by reading an input device or by reading chunks of data from a file).

Each PamProcess will require a source of data, which apart from the top level processes which acquire data, will be a PamDataBlock. The PamProcess will generally subscribe to the PamDataBlock so that it is notified of any changes (i.e. new data) being added to that block.

The PamController ...

Constructor Summary

Constructors

Constructor and Description
PamProcess(PamControlledUnit pamControlledUnit, PamDataBlock parentDataBlock)
PamProcess(PamControlledUnit pamControlledUnit, PamDataBlock parentDataBlock, java.lang.String processName)

Method Summary

Methods

Modifier and Type	Method and Description
long	absMillisecondsToSamples(long millis) Convert a time in milli seconds to a number of samples.
long	absSamplesToMilliseconds(long samples) Convert am ADC sample number to a millisecond time.
void	addOutputDataBlock(PamDataBlock outputDataBlock) Adds an additional PamDataBlock to the process
void	changedThreading() Function that gets called in every process (or all processes that are listed in PamControlledUnits) and re-sets up the data source using the correct threading model.
void	clearOldData() Clears all data from all output data blocks of this process.
void	createAnnotations(boolean notifyDownstream)
void	destroyProcess() Called from the PamControlled unit when a PamControlled unit is removed from the model.
void	fillXMLElement(org.w3c.dom.Document doc, org.w3c.dom.Element processData, int procId) Fill in XML data for a specific process.
boolean	flushDataBlockBuffers(long maxWait) Work through all the output datablocks and wait for their internal buffers to flush through.
PamDataBlock	getAncestorDataBlock(java.lang.Class unitDataType) Useful function to go back through the chain of data blocks and data units upstream of this process and look for a data block which has a particular data type.
ProcessAnnotation	getAnnotation(PamDataBlock pamDataBlock, int annotation) Get an Annotation
int	getChainPosition()
double	getCpuPercent()
int	getNumAnnotations(PamDataBlock pamDataBlock)
int	getNumOutputDataBlocks()
java.lang.String	getObserverName()
PamObserver	getObserverObject()
int	getOfflineData(PamDataBlock dataBlock, PamObserver endUser, long startMillis, long endMillis, RequestCancellationObject cancellationObject) Request offline data.
PamDataBlock	getOutputDataBlock(int block) Each process may produce multiple data blocks.
java.util.ArrayList<PamDataBlock>	getOutputDataBlocks() Get the full list of output datablocks - used in logger forms so they can all be mapped easily once created.
PamControlledUnit	getPamControlledUnit()
PamDataBlock	getParentDataBlock()
PamProcess	getParentProcess()
java.lang.String	getProcessName()
PamRawDataBlock	getRawSourceDataBlock(float sampleRate) Find the absolute source of raw audio data if one exists
long	getRequiredDataHistory(PamObservable o, java.lang.Object arg)
float	getSampleRate()
PamDataBlock<PamDataUnit>	getSourceDataBlock() find the absolute source of data, if one exists.
PamProcess	getSourceProcess()
boolean	isCanMultiThread()
void	makePamProcess(PamControlledUnit pamControlledUnit, PamDataBlock parentDataBlock, java.lang.String processName)
void	masterClockUpdate(long timeMilliseconds, long sampleNumber)
void	newData(PamObservable o, PamDataUnit arg)
void	noteNewSettings()
void	notifyModelChanged(int changeType)
abstract void	pamStart() Called for each process to tell it to start (may not be necessary for processes which are listening for data anyway).
abstract void	pamStop() Stops the process.
void	prepareProcess() Called for each process before any of them receive the PamStart command
void	processNewBuoyData(BuoyStatusDataUnit dataUnit, PamDataUnit dataUnit2)
long	relMillisecondsToSamples(double millis) Convert a number of milliseconds to a number of samples.
long	relSamplesToMilliseconds(long samples) Convert a number of samples into a number of milliseconds
void	removeAllDataBlocks() Remove all data blocks from a process.
void	removeObservable(PamObservable observable) Called when a PamDataBlock observed by this PamProcess is removed.
void	removeOutputDatablock(PamDataBlock outputDataBlock)
void	resetDataBlocks() reset datablocks.
void	saveViewerData() Save data (to binary files and to database) in viewer mode.
void	setCanMultiThread(boolean canMultiThread)
void	setParentDataBlock(PamDataBlock newParentDataBlock) Set a parent data block with the default options of rethreading if set
void	setParentDataBlock(PamDataBlock newParentDataBlock, boolean reThread) Set a parent data block for the process with the option to rethread the data exchange process.
void	setProcessName(java.lang.String processName)
void	setSampleRate(float sampleRate, boolean notify) New sample rate
void	setupProcess() called for every process once the systemmodel has been created.
java.lang.String	toString()
void	update(PamObservable o, PamDataUnit arg) Informs the PamObserver that new data have been added to the Observable class
void	updateData(PamObservable o, PamDataUnit arg)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PamProcess

public PamProcess(PamControlledUnit pamControlledUnit,
          PamDataBlock parentDataBlock)

Parameters:

pamControlledUnit - Reference to the PamControlledUnit containing this process (PamProcesses can only exist within PamControlledUnits, but a PamControlledUnit can contain multiple PamProcesses)

parentDataBlock - Source data block for this process (can be null for raw data input devices)

PamProcess

public PamProcess(PamControlledUnit pamControlledUnit,
          PamDataBlock parentDataBlock,
          java.lang.String processName)

Method Detail

getObserverObject

public PamObserver getObserverObject()

Specified by:

getObserverObject in interface PamObserver

Returns:

the actual observer. In most cases concrete classes will just return 'this' in response. The exception is the Threaded observer, which will return the single thread observer.

destroyProcess

public void destroyProcess()

Called from the PamControlled unit when a PamControlled unit is removed from the model. Offers an opportunity to disconnect individual processed from the rest of the model. May be necessary to override to clean up some processes.

removeAllDataBlocks

public void removeAllDataBlocks()

Remove all data blocks from a process.

makePamProcess

public void makePamProcess(PamControlledUnit pamControlledUnit,
                  PamDataBlock parentDataBlock,
                  java.lang.String processName)

getParentDataBlock

public PamDataBlock getParentDataBlock()

Returns:

Returns the parentDataBlock.

getParentProcess

public PamProcess getParentProcess()

getAncestorDataBlock

public PamDataBlock getAncestorDataBlock(java.lang.Class unitDataType)

Useful function to go back through the chain of data blocks and data units upstream of this process and look for a data block which has a particular data type. For instance, you may want the raw audio data upstream of FFT data. This may not be the data input to the FFT source, since you may be looking at some secondary FFT data source (smoothed, or noise suppressed spectrogram data for instance).

Parameters:

unitDataType - class type of data in the sought after data block (e.g. RawDataUnit.class

Returns:

reference to data block or null if none found

See Also:

PamDataBlock

setParentDataBlock

public void setParentDataBlock(PamDataBlock newParentDataBlock)

Set a parent data block with the default options of rethreading if set

Parameters:

newParentDataBlock - source data block.

setParentDataBlock

public void setParentDataBlock(PamDataBlock newParentDataBlock,
                      boolean reThread)

Set a parent data block for the process with the option to rethread the data exchange process. This is overridden to false if the main PAMGUARD option to rethread is off.

Parameters:

newParentDataBlock - source data block

reThread - rethread if multithreading is enabled.

createAnnotations

public final void createAnnotations(boolean notifyDownstream)

changedThreading

public void changedThreading()

Function that gets called in every process (or all processes that are listed in PamControlledUnits) and re-sets up the data source using the correct threading model. All this actually involves is resubscribing to the same data since everything else is handled in setParentDataBlock;

setProcessName

public void setProcessName(java.lang.String processName)

Parameters:

processName - Sets the name of the process

getProcessName

public java.lang.String getProcessName()

Returns:

Name of the PamProcess

getObserverName

public java.lang.String getObserverName()

Specified by:

getObserverName in interface PamObserver

setSampleRate

public void setSampleRate(float sampleRate,
                 boolean notify)

Description copied from interface: PamObserver

New sample rate

Specified by:

setSampleRate in interface PamObserver

notify - Notify other PamObservers and PamObservables in the chain.

masterClockUpdate

public void masterClockUpdate(long timeMilliseconds,
                     long sampleNumber)

Specified by:

masterClockUpdate in interface PamObserver

relSamplesToMilliseconds

public long relSamplesToMilliseconds(long samples)

Convert a number of samples into a number of milliseconds

Parameters:

samples - Number of ADC samples

Returns:

equivalent number of milliseconds

absSamplesToMilliseconds

public long absSamplesToMilliseconds(long samples)

Convert am ADC sample number to a millisecond time. This function was re-written on 11/11/08 to deal with problems of sound card clocks not running at same speed as PC clock, so milliseconds from PC clock and milliseconds based on samples would drift apart. This new system bases the calculation on the times of the most recently received data unit.

Parameters:

samples - sample number (from start of run)

Returns:

Millisecond time (UTC milliseconds from the epoch - the standard Java way)

absMillisecondsToSamples

public long absMillisecondsToSamples(long millis)

Convert a time in milli seconds to a number of samples.

Parameters:

millis - Current time in milliseconds (UTC millseconds from the epoch - the standard Java way)

Returns:

ADC Samples since the run start.

See Also:

relMillisecondsToSamples(double)

relMillisecondsToSamples

public long relMillisecondsToSamples(double millis)

Convert a number of milliseconds to a number of samples.

Parameters:

millis - number of milliseconds

Returns:

number of ADC samples corresponding to millis milliseconds.

See Also:

absMillisecondsToSamples(long)

noteNewSettings

public void noteNewSettings()

Specified by:

noteNewSettings in interface PamObserver

getSampleRate

public float getSampleRate()

Returns:

The sample rate in the process

getSourceProcess

public PamProcess getSourceProcess()

Returns:

The original data source process, i.e. the one reading the soundcard or the file, the one that doesn't have a parentDataBlock

getSourceDataBlock

public PamDataBlock<PamDataUnit> getSourceDataBlock()

find the absolute source of data, if one exists. i.e. the data output of a process that has no data input.

If this is called from within acquisition, it will return null

It there is no raw data source, i.e. if the type is not PamRawDataBlock, then return null.

Returns:

a PamRawDataBlock or null

getRawSourceDataBlock

public PamRawDataBlock getRawSourceDataBlock(float sampleRate)

Find the absolute source of raw audio data if one exists

Returns:

a PamRawDataBlock or null

getChainPosition

public int getChainPosition()

getOutputDataBlock

public PamDataBlock getOutputDataBlock(int block)

Each process may produce multiple data blocks. This returns the reference to a specific block

Parameters:

block - Index of the required block

Returns:

PamDataBlock

getNumOutputDataBlocks

public int getNumOutputDataBlocks()

Returns:

Total number of PamDataBlocks created by this process

addOutputDataBlock

public void addOutputDataBlock(PamDataBlock outputDataBlock)

Adds an additional PamDataBlock to the process

Parameters:

outputDataBlock - Reference to a PamDataBlock

removeOutputDatablock

public void removeOutputDatablock(PamDataBlock outputDataBlock)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

clearOldData

public void clearOldData()

Clears all data from all output data blocks of this process.
This gets called from the main controller at the start of operations. Can be overridden in some classes which don't want to delete existing data or they can set the clearAtStart flag in any data block.

resetDataBlocks

public void resetDataBlocks()

reset datablocks. Mostly concerned with setting timing counts in row data which may need a bit of an extra kick when handling networked data.

prepareProcess

public void prepareProcess()

Called for each process before any of them receive the PamStart command

getRequiredDataHistory

public long getRequiredDataHistory(PamObservable o,
                          java.lang.Object arg)

Specified by:

getRequiredDataHistory in interface PamObserver

Parameters:

o - PamObservable class requiring the data

arg - optional argument from PamObservable

Returns:

time in milliseconds requried by data held in PamObservable

update

public final void update(PamObservable o,
          PamDataUnit arg)

Description copied from interface: PamObserver

Informs the PamObserver that new data have been added to the Observable class

Specified by:

update in interface PamObserver

Parameters:

o - Reference to the Observable (a PamDataBlock)

arg - Reference to the new PamDataUnit

newData

public void newData(PamObservable o,
           PamDataUnit arg)

updateData

public void updateData(PamObservable o,
              PamDataUnit arg)

setupProcess

public void setupProcess()

called for every process once the systemmodel has been created. this is a good time to check out and find input data blocks and similar tasks.

getCpuPercent

public double getCpuPercent()

pamStart

public abstract void pamStart()

Called for each process to tell it to start (may not be necessary for processes which are listening for data anyway).

pamStop

public abstract void pamStop()

Stops the process.

removeObservable

public void removeObservable(PamObservable observable)

Called when a PamDataBlock observed by this PamProcess is removed.

Specified by:

removeObservable in interface PamObserver

getPamControlledUnit

public PamControlledUnit getPamControlledUnit()

getAnnotation

public ProcessAnnotation getAnnotation(PamDataBlock pamDataBlock,
                              int annotation)

Description copied from interface: ProcessAnnotator

Get an Annotation

Specified by:

getAnnotation in interface ProcessAnnotator

Parameters:

pamDataBlock - Annotated datablock

annotation - annotation number

Returns:

Annotation

getNumAnnotations

public int getNumAnnotations(PamDataBlock pamDataBlock)

Specified by:

getNumAnnotations in interface ProcessAnnotator

Parameters:

pamDataBlock - Annotated datablock

Returns:

the number of annotations

notifyModelChanged

public void notifyModelChanged(int changeType)

setCanMultiThread

public void setCanMultiThread(boolean canMultiThread)

Parameters:

canMultiThread - the canMultiThread to set

isCanMultiThread

public boolean isCanMultiThread()

Returns:

the canMultiThread

saveViewerData

public void saveViewerData()

Save data (to binary files and to database) in viewer mode.

This gets called automatically on system exit and can also be called from the file menu.

getOfflineData

public int getOfflineData(PamDataBlock dataBlock,
                 PamObserver endUser,
                 long startMillis,
                 long endMillis,
                 RequestCancellationObject cancellationObject)

Request offline data.

This will be called from a PamDatablock in offline viewer mode from requestOfflineData(PamObserver observer, long startMillis, long endMillis).

this is used to request data from upstream processes, e.g. o get raw data to turn into FFT data units to go to the spectrogram display (possible going via decimators and any other processes before spitting out the right data.

Parameters:

dataBlock - data block making the request.

endUser - observer which made the original data request.

startMillis - start time in milliseconds

endMillis - end time in milliseconds.

cancellationObject -

Returns:

true if request can be satisfied (or partially satisfied).

fillXMLElement

public final void fillXMLElement(org.w3c.dom.Document doc,
                  org.w3c.dom.Element processData,
                  int procId)

Fill in XML data for a specific process.

filling is split into two parts. First this Finalised function fills in basic data about the process, it then calls fillXMLParameters which will add more module specific information.

Parameters:

doc - xml document

processData - xml element to add datato

flushDataBlockBuffers

public boolean flushDataBlockBuffers(long maxWait)

Work through all the output datablocks and wait for their internal buffers to flush through.

This is used when stopping PAMGUARD to ensure that all data complete processing before anything else happens.

Parameters:

maxWait - maxWait time in milliseconds.

Returns:

true if successful, or false if there was a timeout.

processNewBuoyData

public void processNewBuoyData(BuoyStatusDataUnit dataUnit,
                      PamDataUnit dataUnit2)

getOutputDataBlocks

public java.util.ArrayList<PamDataBlock> getOutputDataBlocks()

Get the full list of output datablocks - used in logger forms so they can all be mapped easily once created.

Returns:

the outputDataBlocks