DataAccumulationService (LSST CCS - Subsystem Commons 6.9.20 API)

java.lang.Object
- org.lsst.ccs.subsystem.common.service.DataAccumulationService

All Implemented Interfaces:

org.lsst.ccs.ServiceLifecycle, org.lsst.ccs.services.AgentService
```
public class DataAccumulationService
extends Object
implements org.lsst.ccs.services.AgentService, org.lsst.ccs.ServiceLifecycle
```
An AgentService to be used by Agents that need to accumulate historical data by retrieving the latest value from the local database.
This service is loaded and started only upon request by invoking the class static method DataAccumulationService.isNeeded() in the constructor of a class node of the Agent's component tree. This method must be invoked before the HasLifecycle::build phase; the method can be invoked multiple times. Once the service is successfully loaded it will be available via the Lookup annotations:
```
 
       @LookupField(strategy=LookupField.Strategy.TREE)
       private DataAccumulationService dataAccumulationService; 
 
```
The next step requires that all the historical data channels are registered with this service. Data registration must happen before the completion of the HasLifecycle::init phase and is done by invoking method
```
 
       dataAccumulationService.registerAccumulatedDataPath(String path);
 
```
The path provided during data registration is the same path with which the data is published.
Incremental data accumulation for a given path is requested by invoking method:
```
 
       double accumulatedValue = dataAccumulationService.accumulateData(path, increment);
 
```
where variable increment is the value to be added to the historical data. Only finite values will be used as valid increments. The method returns the overall accumulated value only if the provided increment is finite and the service was able to retrieve the historical data from the database. The method will return Double.NaN if it could not fetch the historical data value from the database or the increment itself in the case in which the increment value is not finite.
This logic is meant to prevent the publication of valid values when the service was unable to retrieve the historical data value from the database; a valid publication would, in this case, wipe out the last historical data value and reset the history.
The calling code is expected to publish the returned accumulatedValue with the same registration path with which the increment was provided for accumulation.
Once the service is started, it will try to establish a connection with the rest server on the buses to retrieve the historical baseline for all registered paths. Once all baselines have been retrieved successfully for all registered paths the service will no longer contact the rest server. On the other hand, if there is a failure to connect to the rest service, or to retrieve the data for any of the registered paths, the service will periodically attempt to fully initialize all the needed historical baselines. For any registered path without a valid database historical baseline, the incremental accumulation will be done in memory and the cumulative value is stored to file via the Persistence mechanism every time a valid incremental value is provided to the service. Upon successfully retrieving a valid historical baseline from the database, any locally persisted cumulative value will be added to the historical baseline from the database.
The service will raise two alerts at WARNING level:
- UnavailableRestServer when the service fails to connect to the rest server on the buses
- UnavailableDataFromRestServer when the historical database baseline cannot be retrieved for some of the registered paths. This alert will contain the list of channels that failed initialization
These alerts will be reset to NOMINAL when the service is back to proper operating conditions.
Author:

The LSST CCS Team

Field Summary

Fields
Modifier and Type	Field and Description
`Set<String>`	`accumulatedDataSet`
`Map<String,Double>`	`databaseBaselinesMap`
`Set<String>`	`missingBaselinesSet`
`Map<String,Double>`	`persistedBaselinesMap`

Constructor Summary

Constructors
Constructor and Description

DataAccumulationService()

Constructors
Constructor and Description
`DataAccumulationService()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`double`	`accumulateData(String path, double increment)` Add the provided value to the historical data value for the given path.
`double`	`getAccumulatedValueForPath(String path)` Returns the accumulated data value as retrieved from the database or NaN otherwise.
`String`	`getAgentServiceName()`
`Set<String>`	`getHistoricalDataNames()` Command to get the set with the paths for the accumulated data channels.
`static void`	`isNeeded()` Invoke this method from a class node constructor to request the use of this service.
`void`	`preInit()`
`void`	`preStart()`
`void`	`registerAccumulatedDataPath(String path)` Register the path for historical data that will be accumulated with this service.
`void`	`setHistoricalValueForPath(String path, double value)` Command to set the historical value for a given path.
`boolean`	`startForAgent(org.lsst.ccs.bus.data.AgentInfo agentInfo)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.lsst.ccs.ServiceLifecycle
afterBuild, afterInit, afterStart, preBuild, preShutdown

- Field Detail
  - persistedBaselinesMap
```
@Persist
public volatile Map<String,Double> persistedBaselinesMap
```
  - databaseBaselinesMap
```
public volatile Map<String,Double> databaseBaselinesMap
```
  - accumulatedDataSet
```
public final Set<String> accumulatedDataSet
```
  - missingBaselinesSet
```
public final Set<String> missingBaselinesSet
```
- Constructor Detail
  - DataAccumulationService
```
public DataAccumulationService()
```
- Method Detail
  - getAgentServiceName
```
public String getAgentServiceName()
```
    Specified by:
    
    getAgentServiceName in interface org.lsst.ccs.services.AgentService
  - startForAgent
```
public boolean startForAgent(org.lsst.ccs.bus.data.AgentInfo agentInfo)
```
    Specified by:
    
    startForAgent in interface org.lsst.ccs.services.AgentService
  - isNeeded
```
public static void isNeeded()
```
    Invoke this method from a class node constructor to request the use of this service. Once this method is invoked, the service will be loaded and started during the HasLifecycle::build step.
  - preStart
```
public void preStart()
```
    Specified by:
    
    preStart in interface org.lsst.ccs.ServiceLifecycle
  - preInit
```
public void preInit()
```
    Specified by:
    
    preInit in interface org.lsst.ccs.ServiceLifecycle
  - registerAccumulatedDataPath
```
public void registerAccumulatedDataPath(String path)
```
    Register the path for historical data that will be accumulated with this service. The path is equivalent to the path with which the data is published on the buses. This method must be invoked before or during the HasLifecycle::init phase.
    
    Parameters:
    
    path - The historical data path.
  - accumulateData
```
public double accumulateData(String path,
                             double increment)
```
    Add the provided value to the historical data value for the given path. The value will be added internally and returned only if the historical value is synchronized with the value in the database. If the historical data value is not synchronized with the database we return NaN in order not to publish a value that might otherwise corrupt the historical value in the database.
    
    Parameters:
    
    path - The path of the historical data
    
    increment - The incremental value to add to the historical data
    
    Returns:
    
    The cumulative value if the data is synchronized with the database. NaN otherwise.
  - getAccumulatedValueForPath
```
public double getAccumulatedValueForPath(String path)
```
    Returns the accumulated data value as retrieved from the database or NaN otherwise.
    
    Parameters:
    
    path - The path of the accumulated data.
    
    Returns:
    
    The accumulated value from the database or NaN otherwise.
  - getHistoricalDataNames
```
@Command(type=QUERY,
         level=0,
         description="Get the set of accumulated data names")
public Set<String> getHistoricalDataNames()
```
    Command to get the set with the paths for the accumulated data channels.
    
    Returns:
    
    The set of names
  - setHistoricalValueForPath
```
@Command(description="Set the historical value for a given data path")
public void setHistoricalValueForPath(@Argument(description="Data path")
                                                                                                             String path,
                                                                                                             @Argument(description="Historical value")
                                                                                                             double value)
```
    Command to set the historical value for a given path.
    
    Parameters:
    
    path - The data path
    
    value - The historical value. This value must be finite.

Class DataAccumulationService

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.lsst.ccs.ServiceLifecycle

Field Detail

persistedBaselinesMap

databaseBaselinesMap

accumulatedDataSet

missingBaselinesSet

Constructor Detail

DataAccumulationService

Method Detail

getAgentServiceName

startForAgent

isNeeded

preStart

preInit

registerAccumulatedDataPath

accumulateData

getAccumulatedValueForPath

getHistoricalDataNames

setHistoricalValueForPath