Package org.eso.ias.plugin

Class Plugin

java.lang.Object
org.eso.ias.plugin.Plugin
All Implemented Interfaces:
AutoCloseable, ChangeValueListener
public class Plugin extends Object implements ChangeValueListener, AutoCloseable
The main class to write IAS plugins.

The plugin takes care of collecting, filtering and sending to the IAS core of all the monitored values.

Updates on the values of monitored point must be provided by calling updateMonitorPointValue(String, Sample).

Some terminology helps better understanding the methods and data structures:

  • sample: the value of a monitor point read from the monitored system; samples are notified to MonitoredValue
  • monitored value: the value to send to the core of the IAS is generated by the MonitoredValue by applying the user defined filtering to clean for noise

Plugin logs statistics by default at 10 minutes. The time interval (in minutes) is customizable setting "org.eso.ias.plugin.stats.frequency" java property. The logging of statistics is disabled if the time interval is lower or equal to 0. Statistics are composed of a single log at INFO level.
The generation of the statistics is done by a dedicated thread that is started only if the time interval is greater then 0.

The operational mode can be defined for the entire plugin (pluginOperationalMode) or for a specific monitor point value. If the operational mode for the plugin is set, it takes priority over the operational mode of the monitor point value (i.e. if a operational mode is set at plugin level, it will be sent as the operational mode of each monitored value independently of their settings).

The collected monitor points and alarms pass through the filtering and are finally sent to the BSDB where they will be processed by the DASUs. Monitor points and alarms are sent on change and periodically if their values did not change (@see #autoSendRefreshRate).

Support for replication:
The same plugin can be replicated over different identical instances for example to collect monitor points and alarms from identical devices. The user defined parts must know to which specific device to connect for each replicated plugin. To replicate a plugin, only one JSON configuration file is needed and the number of the instance must be passed in the constructor. The plugin will transparently map the monitor point by properly setting their IDs as defined in ReplicatedIdsMapper.
The advantage is that only one JSON configuration must be written for all the replicated instances reducing the effort in configuring and reducing the risk of errors.

Implementation note: internally the IDs of the monitor points are those read from the configuration: the IDs are changed just before sending to the BSDB in monitoredValueUpdated(ValueToSend). Only the ID of the plugin is changed at build time.

Author:
acaproni

  • Field Details

    • LOG_STATS_DETAILED_PROPNAME

      public static final String LOG_STATS_DETAILED_PROPNAME
      The name of the property to let the plugin provide detailed statistics
      See Also:

    • LOG_STATS_FREQUENCY_PROPNAME

      public static final String LOG_STATS_FREQUENCY_PROPNAME
      The name of the property to let the plugin publish logs about frequency
      See Also:

    • defaultStatsGeneratorFrequency

      public static final int defaultStatsGeneratorFrequency
      The default number of minutes to write logs with statistics
      See Also:

    • SCHEDULED_POOL_SIZE_PROPNAME

      public static final String SCHEDULED_POOL_SIZE_PROPNAME
      The property to let the use set the number of threads in the scheduled thread executor
      See Also:

    • defaultSchedExecutorPoolSize

      public static final int defaultSchedExecutorPoolSize
      The default number of threads in the core is a bit less of the number of available CPUs. The task executed by those threads is to get values of monitored values applying filters and push the values to send in a queue (the sending will be done by another thread), so it is a pure calculation. This number should give us a proper CPU usage without stealing all the available resources in the server.

    • schedExecutorPoolSize

      public static final int schedExecutorPoolSize
      The number of threads in the scheduled pool executor that get filtered values out of the monitored values

    • threadFactory

      protected static final ThreadFactory threadFactory
      The thread factory for the plugin

    • schedExecutorSvc

      protected static final ScheduledExecutorService schedExecutorSvc
      The scheduled executor service

    • pluginId

      public final String pluginId
      The ID of the plugin

    • pluginIdentifier

      public final org.eso.ias.types.Identifier pluginIdentifier
      The identifier of the plugin

    • AUTO_SEND_TI_PROPNAME

      public static final String AUTO_SEND_TI_PROPNAME
      The property to set the auto-send time interval (in seconds)
      See Also:

    • defaultAutoSendRefreshRate

      public static final int defaultAutoSendRefreshRate
      The default value of the auto-send refresh rate
      See Also:

    • autoSendRefreshRate

      public final int autoSendRefreshRate
      The refresh rate to automatically send the last values of the monitor points even if did not change

    • monitoredSystemId

      public final String monitoredSystemId
      The identifier of the system monitored by this plugin The name of the monitored system is not affected by replication because the user defined implementation getting monitor points from a device knows better the proper name to use. For example a plugin getting values from an ALMA antenna could use monitoredSystemId like DA45 or PM04

  • Constructor Details

    • Plugin

      public Plugin(String id, String monitoredSystemId, Collection<ValueDao> values, Properties props, MonitorPointSender sender, String defaultFilter, String defaultFilterOptions, int refreshRate, int hbFrequency, org.eso.ias.heartbeat.HbProducer hbProducer)
      Build a non templated plugin with the passed parameters.
      Parameters:
      id - The Identifier of the plugin
      monitoredSystemId - : the identifier of the monitored system
      values - the monitor point values
      props - The user defined properties
      sender - The publisher of monitor point values to the IAS core
      defaultFilter - the default filter (can be null) to apply if there is not filter set in the value
      defaultFilterOptions - the options for the default filter (can be null)
      refreshRate - The auto-send time interval in seconds
      hbFrequency - the frequency (seconds) to periodically publish HBs
      hbProducer - the publisher of HBs

    • Plugin

      public Plugin(String id, String monitoredSystemId, Collection<ValueDao> values, Properties props, MonitorPointSender sender, String defaultFilter, String defaultFilterOptions, int refreshRate, Integer instanceNumber, int hbFrequency, org.eso.ias.heartbeat.HbProducer hbProducer)
      Build a plugin with the passed parameters.
      Parameters:
      id - The Identifier of the plugin
      monitoredSystemId - : the identifier of the monitored system
      values - the monitor point values
      props - The user defined properties
      sender - The publisher of monitor point values to the IAS core
      defaultFilter - the default filter (can be null) to apply if there is not filter set in the value
      defaultFilterOptions - the options for the default filter (can be null)
      refreshRate - The auto-send time interval in seconds
      hbFrequency - the frequency of the heartbeat in seconds
      instanceNumber - the number of the instance if the plugin is replicated, null if not replicated
      hbFrequency - the frequency (seconds) to periodically publish HBs
      hbProducer - the publisher of HBs

    • Plugin

      public Plugin(String id, String monitoredSystemId, Collection<ValueDao> values, Properties props, MonitorPointSender sender, String defaultFilter, String defaultFilterOptions, int refreshRate, Integer instanceNumber, int hbFrequency, org.eso.ias.heartbeat.HbProducer hbProducer, CommandManager cmdManager)
      Build a plugin with the passed parameters. This constructor allows to use the passed monitor point sender and HB producer that might or might not publish data to kafka topics. A feature useful for testing.
      Parameters:
      id - The Identifier of the plugin
      monitoredSystemId - : the identifier of the monitored system
      values - the monitor point values
      props - The user defined properties
      sender - The publisher of monitor point values to the IAS core
      defaultFilter - the default filter (can be null) to apply if there is not filter set in the value
      defaultFilterOptions - the options for the default filter (can be null)
      refreshRate - The auto-send time interval in seconds
      hbFrequency - the frequency of the heartbeat in seconds
      instanceNumber - the number of the instance if the plugin is replicated, null if not replicated
      hbFrequency - the frequency (seconds) to periodically publish HBs
      hbProducer - the publisher of HBs
      cmdManager - The command manager to handle command (can be null if command management not desired)

    • Plugin

      public Plugin(PluginFileConfig config)
      Build the plugins with the configuration read from the passed configuration. Kafka publishers and consumers are built built by the constructor and connects to the kafka servers whose URL is in the configuration file
      Parameters:
      config - The configuration of the plugin

    • Plugin

      public Plugin(IasDao iasConfig, PluginConfigDao pluginConfig)
      Constructor with the IAS and Plugin cofiguration read from the IAS CDB
      Parameters:
      iasConfig - The global configuration of the IAS
      pluginConfig - The configuration of the plugin

    • Plugin

      public Plugin(String id, String monitoredSystemId, Collection<ValueDao> values, Properties props, String servers, String defaultFilter, String defaultFilterOptions, int refreshRate, Integer instanceNumber, int hbFrequency)
      Build a plugin with the passed parameters. It connects to the kafka servers for sending monitor points, HBs and get commands.
      Parameters:
      id - The Identifier of the plugin
      monitoredSystemId - : the identifier of the monitored system
      values - the monitor point values
      props - The user defined properties
      servers - The url of kafka servers ( SERVER:PORT, server2:port2...)
      defaultFilter - the default filter (can be null) to apply if there is not filter set in the value
      defaultFilterOptions - the options for the default filter (can be null)
      refreshRate - The auto-send time interval in seconds
      hbFrequency - the frequency of the heartbeat in seconds
      instanceNumber - the number of the instance if the plugin is replicated, null if not replicated
      hbFrequency - the frequency (seconds) to periodically publish HBs

    • Plugin

      public Plugin(PluginFileConfig config, MonitorPointSender sender, Integer instanceNumber, org.eso.ias.heartbeat.HbProducer hbProducer, CommandManager cmdManager)
      Build a replicated plugin from the passed configuration.
      Parameters:
      config - The plugin coinfiguration
      sender - The publisher of monitor point values to the IAS core
      instanceNumber - the number of the instance if the plugin is replicated, null if not replicated
      hbProducer - the publisher of HBs
      cmdManager - The command manager to handle command (can be null if command managemrent not desired)

  • Method Details

    • start

      public void start() throws PublisherException
      This method must be called at the beginning to acquire the needed resources.
      Throws:
      PublisherException - In case of error initializing the publisher or the command manager

    • close

      public void close()
      This method must be called when finished using the object to free the allocated resources.
      Specified by:
      close in interface AutoCloseable

    • shutdownExecutorSvc

      public void shutdownExecutorSvc()
      This method must be called when finished using the executor service to free the allocated resources.

    • updateMonitorPointValue

      public void updateMonitorPointValue(String mPointID, Object value) throws PluginException
      A new value of a monitor point has been provided by the monitored system: the value must be sent to to the monitor point with the given ID for filtering.
      Parameters:
      mPointID - The ID of the monitored point to submit the sample to
      value - the new not null value to submit to the monitored point
      Throws:
      PluginException - if adding the sample failed

    • updateMonitorPointValue

      public void updateMonitorPointValue(String mPointID, Sample sample) throws PluginException
      A new value of a monitor point (a new sample) has been provided by the monitored system: the value must be sent to to the monitor point with the given ID for filtering.
      Parameters:
      mPointID - The ID of the monitored point to submit the sample to
      sample - the new sample to submit to the monitored point
      Throws:
      PluginException - if adding the sample failed

    • putMonitoredPoint

      public int putMonitoredPoint(MonitoredValue mPoint) throws PluginException
      Adds a monitored point to the plugin managed map of monitor points.

      The same monitor point (or if you prefer, 2 monitor points with the same ID ) cannot be added to the map.

      Parameters:
      mPoint - The monitored point to add to the map
      Returns:
      the number of monitor points managed by the plugin
      Throws:
      PluginException - if a monitor point with the given id is already in the map

    • monitoredValueUpdated

      public void monitoredValueUpdated(ValueToSend value)
      A monitor point value has been updated and must be forwarded to the core of the IAS.

      If the plugin is replicated, the ID of the value is changed before publishing.

      Specified by:
      monitoredValueUpdated in interface ChangeValueListener
      Parameters:
      value - The value to send to the core of the IAS
      See Also:

    • setMonitorPointRefreshRate

      public long setMonitorPointRefreshRate(String mPointId, long newRefreshRate) throws PluginException
      Change the refresh rate of the monitor point with the passed ID.

      The new refresh rate is bounded by a minimum (MonitoredValue.minAllowedSendRate)

      Parameters:
      mPointId - The not null nor empty ID of a monitored point
      newRefreshRate - the requested new refresh rate
      Returns:
      the refresh rate effectively set for the monitored value
      Throws:
      PluginException - if the monitored value with the passed ID does not exist

    • enableMonitorPointPeriodicNotification

      public void enableMonitorPointPeriodicNotification(String mPointId, boolean enable) throws PluginException
      Enable or disable the periodic sending of notifications.
      Parameters:
      mPointId - The ID of the monitor point to enable or disable
      enable - if true enables the periodic sending;
      Throws:
      PluginException - if the monitored value with the passed ID does not exist

    • getScheduledExecutorService

      public static ScheduledExecutorService getScheduledExecutorService()
      Returns:
      the scheduled executor

    • getThreadFactory

      public static ThreadFactory getThreadFactory()
      Returns:
      the threadFactory

    • setPluginOperationalMode

      public void setPluginOperationalMode(OperationalMode opMode)
      Set the operational mode of the plugin overriding the operational mode set in the monitor point values
      Parameters:
      opMode - The not null operational mode of the plugin
      See Also:
      • pluginOperationalMode

    • unsetPluginOperationalMode

      public void unsetPluginOperationalMode()
      Unset the plugin operational mode so that the operational mode of each monitor point value is sent to the core of the IAS.

    • getPluginOperationalMode

      public Optional<OperationalMode> getPluginOperationalMode()
      Return the operational mode of the plugin.
      Returns:
      the operational mode of the plugin.

    • setOperationalMode

      public OperationalMode setOperationalMode(String mPointId, OperationalMode opMode) throws PluginException
      Set the operational mode of a monitor point value.

      Note that this value is effectively sent to the core of the IAS only if not overridden by the plugin operational mode

      Parameters:
      mPointId - the ID of the monitor point to set the operation mode
      opMode - The not null operational mode to set
      Returns:
      The old operational mode of the monitor point
      Throws:
      PluginException - if the monitored value with the passed ID does not exist
      See Also:
      • pluginOperationalMode