Package PamController

Class PamControlledUnit

java.lang.Object
PamController.PamControlledUnit
All Implemented Interfaces:
SettingsNameProvider
Direct Known Subclasses:
AirgunControl, AISControl, AlarmControl, AmpControl, AngleControl, ArrayAccelControl, ArrayManager, ArraySensorControl, ArraySidePanelControl, AudioMothControl, AutecPhonesControl, AzigramControl, BackupManager, BeamformControl, BeamFormerBaseControl, BearingLocaliserControl, BinaryStore, CBLocaliserControl, CepstrumControl, ClickControl, ClickTrainControl, ClipControl, CommandManager, CPODControl2, DataMapControl, DBControl, DbHtControl, DecimatorControl, DepthControl, DetectionGroupControl, DifarControl, DLControl, EffortControl, EnvelopeControl, FilterControl, FormsControl, GPLControlledUnit, GPSControl, GridbaseControl, Group3DLocaliserControl, IMUControl, IshDetControl, IshLocControl, IshmaelDataControl, KernelSmoothingControl, LandmarkControl, LevelMeterControl, LikelihoodDetectionUnit, LikelihoodFFTController, LinePlotControl, ListeningControl, LocalTime, LtsaControl, Map3DControl, MapController, MapGroupLocaliserControl, MarkModule, MetaDataContol, MeygenTurbine, MTClassifierControl, NetworkReceiver, NetworkSender, NMEAControl, NoiseBandControl, NoiseControl, OfflineFileControl, OfflineProcessingControlledUnit, OneBandControl, PamFFTControl, PatchPanelControl, PlaybackControl, PrintScreenControl, QAControl, RavenControl, RawInputControlledUnit, RecorderControl, RoccaControl, RockBlockControl, RWEControl, SpectrogramNoiseControl, STToolsControl, TargetMotionControl, TethysControl, TowedArray3DController, UserDisplayControl, UserDisplayControlFX, UserInputController, VetoController, VRControl, WhistleClassifierControl, WhistleControl, WhistleMoanControl

public abstract class PamControlledUnit extends Object implements SettingsNameProvider
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 Details

    • PamControlledUnit

      public PamControlledUnit(String unitType, String unitName)
      Constructor for a new PamControlledUnit
      Parameters:
      unitName - name of unit
    • PamControlledUnit

      public PamControlledUnit(PamConfiguration pamConfiguration, String unitType, String unitName)
  • Method Details

    • 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 PamConrolledUnit
      Parameters:
      pamProcess - Reference to a PamProcess
    • addPamProcess

      public void addPamProcess(int procIndex, PamProcess pamProcess)
      Adds a PamProcess to the PamConrolledUnit at a specified position in the process list.
      Parameters:
      procIndex - process index
      pamProcess - process
    • removeUnit

      public boolean removeUnit()
      Called to remove a unit.
      Returns:
      try (not used)
    • rename

      public void rename(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:
    • 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:
    • getToolbarComponent

      public final 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.
    • setToolbarComponent

      public void setToolbarComponent(Component toolbarComponent)
      Set the toolbar component which will be incorporated into the top toolbar whenever this controlled unit's display is selected in the main tab panel
      Parameters:
      toolbarComponent - An AWT component to include in the toolbar.
    • getTabSpecificMenuBar

      public JMenuBar getTabSpecificMenuBar(Frame parentFrame, 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 JMenuItem createDetectionMenu(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 JMenuItem createDisplayMenu(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 String getUnitName()
      Returns the name of the unit
      Specified by:
      getUnitName in interface SettingsNameProvider
      Returns:
      the name of the unit
    • getUnitType

      public String getUnitType()
    • addOtherRelatedMenuItems

      public void addOtherRelatedMenuItems(Frame parentFrame, JMenu menu, String name)
    • addRelatedMenuItems

      public int addRelatedMenuItems(Frame parentFrame, JMenu menu, String name)
    • gotoTab

      public boolean gotoTab()
    • getPamView

      @Deprecated public PamView getPamView()
      Deprecated.
      Get the GUI associated with this module. However, this may return null, so if you want a frame to use for a dialog, better to use PamController.getGuiFrame() which handles null automatically.
      Returns:
    • getGuiFrame

      public 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 JMenuItem createHelpMenu(Frame parentFrame)
    • createFileMenu

      public JMenuItem createFileMenu(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:
    • 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 String toString()
      Overrides:
      toString in class 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.

    • 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 response 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 String getModuleSummary()
      Get a module summary text string for shorthand output to anyting wanting a short summary of data state / numbers of detections.
      You should not override this version of the function, but instead override getModuleSummary(boolean clear) which allows for optional clearing of summary data.
      Returns:
      module summary string - goings on since the last call to this function
    • getModuleSummary

      public String getModuleSummary(boolean clear)
      Get a module summary text string for shorthand output to anyting wanting a short summary of data state / numbers of detections.
      Parameters:
      clear - clear data after generating string, so that counts of detections, etc. start again from 0.
      Returns:
      module summary string - goings on since the last call to this function
    • tellModule

      public String tellModule(String command)
      Handle a module specific command sent by the tellmodule command.
      Parameters:
      command - command line (stripped of the command and the module type and name)
      Returns:
      response to command
    • getShortUnitType

      public Object getShortUnitType()
      Returns:
      a shortened version of the unit type for use in module summary strings.
    • isViewer

      public boolean isViewer()
      Returns:
      the isViewer
    • isNetRx

      public boolean isNetRx()
    • terminalPrintln

      public void terminalPrintln(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
    • terminalPrint

      public void terminalPrint(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
    • getGUI

      public PamControlledUnitGUI getGUI(int flag)
      Get the GUI for the PAMControlled unit. This has multiple GUI options which are instantiated depending on the view type.
      Parameters:
      flag - . The GUI type flag defined in PAMGuiManager.
      Returns:
      the GUI for the PamControlledUnit unit.
    • getModuleStatusManager

      public ModuleStatusManager getModuleStatusManager()
      Returns:
      the moduleStatusManager
    • setModuleStatusManager

      public void setModuleStatusManager(ModuleStatusManager moduleStatusManager)
      Parameters:
      moduleStatusManager - the moduleStatusManager to set
    • getModuleStatus

      public ModuleStatus getModuleStatus()
      Quick convenient way of getting the module status.
      Returns:
      Module Status or null if no status manager present.
    • getOfflineState

      public int getOfflineState()
      Get the offline state of this module. This can generally be idle, but can be a higher state when map making at startup and when running an offline task.
      Returns:
    • getBackupInformation

      public BackupInformation getBackupInformation()
    • getInstanceIndex

      public int getInstanceIndex()
      Get the instance number for this PamcontrolledUnit. This is simply a count of units of this class that have previously been created .
      Returns:
      the instanceIndex
    • getPlugin

      public PamPluginInterface getPlugin()
      Get detail if this is a plugin.
      Returns:
      plugin detail, or null if it's not a plugin.
    • getPamConfiguration

      public PamConfiguration getPamConfiguration()
      The PamConfiguration holds the master list of modules which form part of a configuration. It should be accessed to find list of datablocks, etc. rather than doing everything through PAMController whenever possible.
      Returns:
      the pamConfiguration
    • isInMainConfiguration

      public boolean isInMainConfiguration()
      Is this module in the main configuration. If it isn't then it's probably a dummy config used in the batch processor or for importing / exporting configs, so it should be stopped from doing too much !
      Returns:
    • setPamConfiguration

      public void setPamConfiguration(PamConfiguration pamConfiguration)
      Parameters:
      pamConfiguration - the pamConfiguration to set