PamController

Class PamControlledUnit

java.lang.Object

PamController.PamControlledUnit

Direct Known Subclasses:

AcquisitionControl, AirgunControl, AISControl, AlarmControl, AmpControl, AngleControl, ArrayAccelControl, ArrayManager, AutecPhonesControl, BeakedControl, BinaryStore, ClickControl, ClipControl, DataMapControl, DBControl, DbHtControl, DecimatorControl, DepthControl, DifarControl, DStrControl, EchoController, EdgeControl, EnvelopeControl, FilterControl, FormsControl, GPSControl, IMUControl, IpiController, IshDetControl, IshLocControl, IshmaelDataControl, KernelSmoothingControl, LandmarkControl, LevelMeterControl, LikelihoodDetectionUnit, LikelihoodFFTController, ListeningControl, LocalTime, LtsaControl, MapController, MarkModule, NetworkReceiver, NetworkSender, NMEAControl, NoiseBandControl, NoiseControl, OfflineFileControl, OfflineProcessingControlledUnit, OneBandControl, PamFFTControl, PatchPanelControl, PlaybackControl, RecorderControl, RoccaControl, RWEControl, SerialLogger, SMLGainControl, SMLPingerControl, SpectrogramNoiseControl, StaticLocaliserControl, TargetMotionControl, TowedArray3DController, UserDisplayControl, UserInputController, VetoController, VRControl, WhistleClassifierControl, WhistleControl, WhistleMoanControl, WILDControl, WorkshopController, XBatLogControl

public abstract class PamControlledUnit
extends java.lang.Object

Author:

Doug Gillespie

PamControlledUnit is an abstract class that is used to contain all the information required for an actual detector, sub detection process or display within Pamguard.

See the how to make Pamguard plug-ins overview.

Each unit will probably have a PamProcess, which will do something like calculate FFT's, look for whistles, read a sound card, etc. Associated with each process there may or may not be a display or a display component (e.g. a toolbar window for controlling file playback speed, a panel to be added to a GUI, menu's for controlling the algorithm and / or the various bits of the display).

Each PamControlledUnit along with one or more PamProcesses and display units comprises a kind of mini MVC, the PamControlledUnit being the Controller, the PamProcesses and their associated data blocks the model and the display comonents the view.

Each PamProcess requires a reference to a PamControllerUnit in it's constructor, so PamProcesses can only exist within this framework.

Subclasses of PamControlledUnit should handle menu commands associated with any menu's they are responsible for and send those commands on to their processes and other display comonents as necessary.

A View in the Pamguard MVC can query for a list of PamControlledUnits, the view can then see which have a display, etc and add them to the view.

Constructor Summary

Constructors

Constructor and Description
PamControlledUnit(java.lang.String unitType, java.lang.String unitName) Constructor for a new PamControlledUnit

Method Summary

Methods

Modifier and Type	Method and Description
void	addOfflineTaskGroup(OfflineTaskGroup offlineTaskGroup) Registers the offlineTaskGroup with the PamControlledUnit on instantiation.
void	addOtherRelatedMenuItems(java.awt.Frame parentFrame, javax.swing.JMenu menu, java.lang.String name)
void	addPamProcess(PamProcess pamProcess) Adds a PamProcess to the ControlledUnit
int	addRelatedMenuItems(java.awt.Frame parentFrame, javax.swing.JMenu menu, java.lang.String name)
static org.w3c.dom.Element	addXMLParameter(org.w3c.dom.Document doc, org.w3c.dom.Element paramsEl, boolean value, java.lang.String name, java.lang.String description, int accessLevel, int propagate) Add a new boolean point XML element.
static org.w3c.dom.Element	addXMLParameter(org.w3c.dom.Document doc, org.w3c.dom.Element paramsEl, double value, java.lang.String name, java.lang.String description, int accessLevel, int propagate) Add a new floating point XML element.
static org.w3c.dom.Element	addXMLParameter(org.w3c.dom.Document doc, org.w3c.dom.Element paramsEl, int value, java.lang.String name, java.lang.String description, int accessLevel, int propagate) Add a new integer point XML element.
static org.w3c.dom.Element	addXMLParameter(org.w3c.dom.Document doc, org.w3c.dom.Element paramsEl, java.lang.String value, java.lang.String name, java.lang.String description, int accessLevel, int propagate) Add a new floating point XML element.
boolean	canClose() Called before Pamguard shuts down.
boolean	canPlayViewerSound()
javax.swing.JMenuItem	createDetectionMenu(java.awt.Frame parentFrame) Create a JMenu object containing MenuItems associated with PamProcesses
javax.swing.JMenuItem	createDisplayMenu(java.awt.Frame parentFrame) Create a JMenu object containing MenuItems associated with the view
javax.swing.JMenuItem	createFileMenu(javax.swing.JFrame parentFrame)
javax.swing.JMenuItem	createHelpMenu(java.awt.Frame parentFrame)
boolean	fillXMLElement(org.w3c.dom.Document doc, org.w3c.dom.Element moduleData) Fill an XML element with data about this module.
boolean	flushDataBlockBuffers(long maxWait) Go into a wait state while any buffers in output data blocks flush through in multithread mode.
int	getFrameNumber() Get the number of the frame that side and tab panels for this module should sit on.
java.awt.Frame	getGuiFrame() Get the main frame for the GUI.
java.lang.String	getModuleSummary() Get a module summary text string for shorthand output to summary QC systems.
int	getNumOfflineTaskGroups()
int	getNumPamProcesses() Gets the total number of PamProcesses controlled by this Controller
OfflineTaskGroup	getOfflineTaskGroup(int i)
PamController	getPamController()
PamModuleInfo	getPamModuleInfo()
PamProcess	getPamProcess(int iP)
PamView	getPamView()
java.lang.Object	getShortUnitType()
PamSidePanel	getSidePanel() Gets a reference to a small panel to be displayed along the left hand edge of the main tab panel.
ClipboardCopier	getTabClipCopier()
PamTabPanel	getTabPanel() Gets a reference to a panel to be added to a view
javax.swing.JMenuBar	getTabSpecificMenuBar(java.awt.Frame parentFrame, javax.swing.JMenuBar standardMenu, PamGui pamGui) Create a tab specific menu to go with this PamControlledUnit.
java.awt.Component	getToolbarComponent() Sets the toolbar component which will be incorporated into the top toolbar whenever this controlled unit's display is selected in the main tab panel
java.lang.String	getUnitName() Returns the name of the unit
java.lang.String	getUnitType()
int	getVerboseLevel()
boolean	gotoTab()
boolean	isViewer()
void	notifyModelChanged(int changeType) General notification when the PAMGAURD model changes.
void	pamClose() Called when PAMGUARD is finally closing down so that a module may free any remaining resources (e.g.
void	pamHasStopped() Called for all controlled units after Pam acquisition has stopped
void	pamToStart() called just before data acquisition starts.
void	playViewerSound() Start playing sound in reponse to a call from the viewer top toolbar.
void	removePamProcess(PamProcess pamProcess) Removes a process.
boolean	removeUnit() Called to remove a unit.
void	rename(java.lang.String newName)
void	saveViewerData() Save data (to binary files and to database) in viewer mode.
void	setFrameNumber(int frameNumber)
void	setPamController(PamController pamController)
void	setPamModuleInfo(PamModuleInfo pamModuleInfo)
void	setPamView(PamView pamView) Called whenever the frme of a PamControlledunit changes (including at program startup).
void	setSidePanel(PamSidePanel sidePanel) Sets the side panel for the PamControlledUnit Side panels are shown down the left hand side of the main Pamguard GUI and are always visible, irrespective of which tab is being viewed on the main tabbed display.
void	setTabPanel(PamTabPanel tabPanel) Sets the tab panel for the PamControlledUnit.
void	setupControlledUnit() called for all PamControlledUnits after all units have been created.
void	stopViewerSound() Stop playing sound in response to a call from the viewer top toolbar.
void	terminalPrint(java.lang.String string, int verboseLevel) Print a line, with line feed, on the terminal if the verbose level is >= the set level for this module
void	terminalPrintln(java.lang.String string, int verboseLevel) Print a line, with linefeed, on the terminal if the verbose level is >= the set level for this module
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

PamControlledUnit

public PamControlledUnit(java.lang.String unitType,
                 java.lang.String unitName)

Constructor for a new PamControlledUnit

Parameters:

unitName - name of unit

Method Detail

getPamProcess

public PamProcess getPamProcess(int iP)

Parameters:

iP - - The index of the process

Returns:

Reference to a PamProcess or null if iP is invalid

getNumPamProcesses

public int getNumPamProcesses()

Gets the total number of PamProcesses controlled by this Controller

Returns:

The total number of PamProcesses

addPamProcess

public void addPamProcess(PamProcess pamProcess)

Adds a PamProcess to the ControlledUnit

Parameters:

pamProcess - Reference to a PamProcess

removeUnit

public boolean removeUnit()

Called to remove a unit.

Returns:

try (not used)

rename

public void rename(java.lang.String newName)

removePamProcess

public void removePamProcess(PamProcess pamProcess)

Removes a process.

Parameters:

pamProcess - process to remove

notifyModelChanged

public void notifyModelChanged(int changeType)

General notification when the PAMGAURD model changes.

Parameters:

changeType - type of change

getTabPanel

public PamTabPanel getTabPanel()

Gets a reference to a panel to be added to a view

Returns:

reference to a PamTabPanel object

See Also:

PamTabPanel, PamSidePanel

getFrameNumber

public int getFrameNumber()

Get the number of the frame that side and tab panels for this module should sit on.

Returns:

frame number.

setFrameNumber

public void setFrameNumber(int frameNumber)

getSidePanel

public PamSidePanel getSidePanel()

Gets a reference to a small panel to be displayed along the left hand edge of the main tab panel. Side panels should be small since they are always visible and any space they take will be taken from the main tab panel.

It is possible for a PamControlled unit to have a side panel without having a pamTabPanel.

Returns:

a pamSidePanel object.

See Also:

PamSidePanel, PamTabPanel

getToolbarComponent

public final java.awt.Component getToolbarComponent()

Sets the toolbar component which will be incorporated into the top toolbar whenever this controlled unit's display is selected in the main tab panel

Returns:

An AWT component to include in the toolbar.

getTabSpecificMenuBar

public javax.swing.JMenuBar getTabSpecificMenuBar(java.awt.Frame parentFrame,
                                         javax.swing.JMenuBar standardMenu,
                                         PamGui pamGui)

Create a tab specific menu to go with this PamControlledUnit.

Default is to throw back the standard menu to be used. This function should clone the standard menu and then modify the clone (usually by replacing the Display sub menu)

Parameters:

standardMenu - the standard menu for the Pam GUI.

Returns:

a complete menu bar to be shown while a particular tab is selected

createDetectionMenu

public javax.swing.JMenuItem createDetectionMenu(java.awt.Frame parentFrame)

Create a JMenu object containing MenuItems associated with PamProcesses

Parameters:

parentFrame - The owner frame of the menu

Returns:

reference to a JMenu which can be added to an existing menu or menu bar

Note that if multiple views are to use the same menu, then they should each create a new menu (by setting Create to true) the first time they call this method.

createDisplayMenu

public javax.swing.JMenuItem createDisplayMenu(java.awt.Frame parentFrame)

Create a JMenu object containing MenuItems associated with the view

Returns:

reference to a JMenu which can be added to an existing menu or menu bar

Note that if multiple views are to use the same menu, then they should each create a new menu (by setting Create to true) the first time they call this method.

setupControlledUnit

public void setupControlledUnit()

called for all PamControlledUnits after all units have been created. This is a good time for the controlled units and processes to find and check their source data and the configuration generally since most onjects (i.e. output data blocks) should be in place

pamToStart

public void pamToStart()

called just before data acquisition starts. Note that PamObservers get a call to setSampleRate anyway so this mainly needs to be used for display elements that may need their scales adjusted before startup.

pamHasStopped

public void pamHasStopped()

Called for all controlled units after Pam acquisition has stopped

canClose

public boolean canClose()

Called before Pamguard shuts down. Rather than returning false, this function can be used as a final oportunity to save settings, write to the database, etc.

Returns:

true if OK for Pamguard to shut down, false otherwise.

getUnitName

public java.lang.String getUnitName()

Returns the name of the unit

Returns:

the name of the unit

getUnitType

public java.lang.String getUnitType()

addOtherRelatedMenuItems

public void addOtherRelatedMenuItems(java.awt.Frame parentFrame,
                            javax.swing.JMenu menu,
                            java.lang.String name)

addRelatedMenuItems

public int addRelatedMenuItems(java.awt.Frame parentFrame,
                      javax.swing.JMenu menu,
                      java.lang.String name)

gotoTab

public boolean gotoTab()

getPamView

public PamView getPamView()

getGuiFrame

public java.awt.Frame getGuiFrame()

Get the main frame for the GUI. In some cases the view may not have been created, so go straight to the main one.

Returns:

frame.

setPamView

public void setPamView(PamView pamView)

Called whenever the frme of a PamControlledunit changes (including at program startup).

Parameters:

pamView -

createHelpMenu

public javax.swing.JMenuItem createHelpMenu(java.awt.Frame parentFrame)

createFileMenu

public javax.swing.JMenuItem createFileMenu(javax.swing.JFrame parentFrame)

Parameters:

parentFrame - parent frame for the menu

Returns:

the file menu item

setSidePanel

public void setSidePanel(PamSidePanel sidePanel)

Sets the side panel for the PamControlledUnit Side panels are shown down the left hand side of the main Pamguard GUI and are always visible, irrespective of which tab is being viewed on the main tabbed display.

Side panels are generally used to display summary information for the PamControlledUnit or to provide quick access controls.

Parameters:

sidePanel - Reference to a PamSidePanel object

See Also:

PamSidePanel

setTabPanel

public void setTabPanel(PamTabPanel tabPanel)

Sets the tab panel for the PamControlledUnit. A tab panel may contain graphics or tables to display information of any type.

Parameters:

tabPanel -

getPamModuleInfo

public PamModuleInfo getPamModuleInfo()

Returns:

Returns the pamModuleInfo.

setPamModuleInfo

public void setPamModuleInfo(PamModuleInfo pamModuleInfo)

Parameters:

pamModuleInfo - The pamModuleInfo to set.

getTabClipCopier

public ClipboardCopier getTabClipCopier()

getPamController

public PamController getPamController()

Returns:

the pamController

setPamController

public void setPamController(PamController pamController)

Parameters:

pamController - the pamController to set

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

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.

fillXMLElement

public final boolean fillXMLElement(org.w3c.dom.Document doc,
                     org.w3c.dom.Element moduleData)

Fill an XML element with data about this module.

this is expected to only include parameters which are required for real time data collection on remote platforms using a stand alone, no GUI pamguard version.

Parameters:

doc -

moduleData - XML element to fill.

Returns:

false if this module has no data of interest, otherwise just add data to the element.

addXMLParameter

public static org.w3c.dom.Element addXMLParameter(org.w3c.dom.Document doc,
                                  org.w3c.dom.Element paramsEl,
                                  double value,
                                  java.lang.String name,
                                  java.lang.String description,
                                  int accessLevel,
                                  int propagate)

Add a new floating point XML element. Each element will have a number of attributes in a common format.

Parameters:

doc - XML document root

paramsEl - parent element

value - value for new element

name - name for new element

description - description for new element

editable - will be visible in web interface

propagate - determines how setting may propagate to other configuration files.

Returns:

new element.

addXMLParameter

public static org.w3c.dom.Element addXMLParameter(org.w3c.dom.Document doc,
                                  org.w3c.dom.Element paramsEl,
                                  int value,
                                  java.lang.String name,
                                  java.lang.String description,
                                  int accessLevel,
                                  int propagate)

Add a new integer point XML element. Each element will have a number of attributes in a common format.

Parameters:

doc - XML document root

paramsEl - parent element

value - value for new element

name - name for new element

description - description for new element

editable - will be visible in web interface

propagate - determines how setting may propagate to other configuration files.

Returns:

new element.

addXMLParameter

public static org.w3c.dom.Element addXMLParameter(org.w3c.dom.Document doc,
                                  org.w3c.dom.Element paramsEl,
                                  java.lang.String value,
                                  java.lang.String name,
                                  java.lang.String description,
                                  int accessLevel,
                                  int propagate)

Add a new floating point XML element. Each element will have a number of attributes in a common format.

Parameters:

doc - XML document root

paramsEl - parent element

value - value for new element

name - name for new element

description - description for new element

editable - will be visible in web interface

propagate - determines how setting may propagate to other configuration files.

Returns:

new element.

addXMLParameter

public static org.w3c.dom.Element addXMLParameter(org.w3c.dom.Document doc,
                                  org.w3c.dom.Element paramsEl,
                                  boolean value,
                                  java.lang.String name,
                                  java.lang.String description,
                                  int accessLevel,
                                  int propagate)

Add a new boolean point XML element. Each element will have a number of attributes in a common format.

Parameters:

doc - XML document root

paramsEl - parent element

value - value for new element

name - name for new element

description - description for new element

editable - will be visible in web interface

propagate - determines how setting may propagate to other configuration files.

Returns:

new element.

flushDataBlockBuffers

public boolean flushDataBlockBuffers(long maxWait)

Go into a wait state while any buffers in output data blocks flush through in multithread mode.

this has been placed in each controlled unit so that it can be overriedden if if necessary.

Parameters:

maxWait - max wait time in seconds

Returns:

true if all flushed, false if the wait tiem was exceeded.

canPlayViewerSound

public boolean canPlayViewerSound()

Returns:

true if this module can play sound in reponse to a play command from the top toolbar.

playViewerSound

public void playViewerSound()

Start playing sound in reponse to a call from the viewer top toolbar.

stopViewerSound

public void stopViewerSound()

Stop playing sound in response to a call from the viewer top toolbar.

pamClose

public void pamClose()

Called when PAMGUARD is finally closing down so that a module may free any remaining resources (e.g. files or COMM ports).

addOfflineTaskGroup

public void addOfflineTaskGroup(OfflineTaskGroup offlineTaskGroup)

Registers the offlineTaskGroup with the PamControlledUnit on instantiation.

Parameters:

offlineTaskGroup -

getNumOfflineTaskGroups

public int getNumOfflineTaskGroups()

Returns:

the number of offlineTaskGroups

getOfflineTaskGroup

public OfflineTaskGroup getOfflineTaskGroup(int i)

Returns:

the iTH offlineTaskGroup

getModuleSummary

public java.lang.String getModuleSummary()

Get a module summary text string for shorthand output to summary QC systems.

Returns:

module summary string - goings on since the last call to this function

getShortUnitType

public java.lang.Object getShortUnitType()

Returns:

a shortened version of the unit type for use in module summary strings.

isViewer

public boolean isViewer()

Returns:

the isViewer

terminalPrintln

public void terminalPrintln(java.lang.String string,
                   int verboseLevel)

Print a line, with linefeed, on the terminal if the verbose level is >= the set level for this module

Parameters:

string - string t print

verboseLevel - verbose level

terminalPrint

public void terminalPrint(java.lang.String string,
                 int verboseLevel)

Print a line, with line feed, on the terminal if the verbose level is >= the set level for this module

Parameters:

string - string t print

verboseLevel - verbose level

getVerboseLevel

public int getVerboseLevel()

Returns:

a verbose level for terminalPrint and terminalPrintln