SampleDecimator (Cassandra PV Archiver Control System API 3.0.2 API)

Type Parameters:

SampleType - type that is implemented by all samples that are passed to this sample decimator and that is also implemented by the sample generated by this sample decimator. Typically, this is the sample type used by the control-system support that provides the implementation of this interface.

All Known Implementing Classes:

AbstractSampleDecimator, AbstractStatefulSampleDecimator
```
public interface SampleDecimator<SampleType extends Sample>
```
Stateful utility that decimates samples. The sample decimator is responsible for generating decimated samples when one or more decimation levels exist for a channel. For each decimated sample that is going to be generated, a new sample decimator is created by calling the control-system support's createSampleDecimator method.

Unlike most components provided by a control-system support, the sample decimator does not have to be thread-safe. The archiver creates a new sample decimator for each decimated sample that is supposed to be generated and only uses this sample decimator from a single thread.

The methods provided by this interface must not block or perform any long-running actions because they might be called from time-sensitive threads.

The contract between the archiver and the control-system support specifies that the sample decimator is used in the following way and order:
1. The sample decimator is created by calling ControlSystemSupport.createSampleDecimator(String, java.util.Map, long, long) .
2. The sample decimator's processSample(Sample) method is called with a sample that has a time stamp less than or equal to the start time of the interval. This way, the sample decimator always knows the channel's state right from the beginning of the interval.
3. The processSample(Sample) method is called for each additional sample that is present in the interval. The samples are passed in the order of their time-stamps.
4. When the last sample in the interval (that has a time-stamp strictly less than the interval's start time plus length) has been passed, the buildDecimatedSample() method is called.
5. Finally, the archiver calls the getDecimatedSample() and getDecimatedSampleEstimatedSize() methods to get the generated decimated sample and its estimated size. After that, the sample decimator is not used any longer.
The samples passed to processSample(Sample) may be raw samples (that were received from the control-system support through a SampleListener). However, they may also be decimated samples if the channel has several decimation levels and the decimated sample for such a level is supposed to be generated. In this case, the samples passed to this sample decimator may be decimated samples from a decimation level with a shorter decimation period. The archiver may only use samples from another decimation level instead of raw samples when the decimation periods are compatible, meaning that the decimation period of the decimation for which this decimator is supposed to generate a sample is an integer multiple of the decimation period of the decimation level of the samples that are passed.

The sample returned by the getDecimatedSample() method must always have a time stamp that is equal to the interval start-time that was specified when the sample decimator was created. Returning a sample with a different time-stamp is considered an error.

The actual implementation of how samples are decimated can vary significantly between different control-system supports or even depend on the internal sample type and thus on the channel or the channel's configuration. For example, a simple implementation might always choose the sample right at the beginning of the period, thus simply decimating the samples. A more complex implementation might calculate the average of all samples and create a decimated sample that represents this average, possibly carrying additional information like minimum and maximum values or the standard deviation.

Implementations that use a different strategy for generating decimated samples depending on the channel's configuration should consider that typically, decimated samples are generated and stored over a prolonged period. If the configuration is changed within this period, the strategy for generating the decimated samples might also change, leading to a situation in which some of the decimated samples have been generated using one algorithm and other decimated samples have been generated using a different algorithm. It is completely legal for a control-system support to exhibit such behavior, but in this case it also has to be able to deal with such data when processing samples.
Author:

Sebastian Marsching

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`buildDecimatedSample()` Builds the decimated sample.
`String`	`getChannelName()` Returns the name of the channel for which this sample decimator decimates samples.
`SampleType`	`getDecimatedSample()` Returns the decimated sample that has been generated by `buildDecimatedSample()`.
`int`	`getDecimatedSampleEstimatedSize()` Returns the estimated size of the decimated sample.
`long`	`getIntervalLength()` Returns the length of the period for which this sample decimator generates a decimated sample.
`long`	`getIntervalStartTime()` Returns the start time of the period for which this sample decimator generated a decimated sample.
`void`	`processSample(SampleType sample)` Processes a sample, updating the internal state with the information from the sample.

- Method Detail
  - buildDecimatedSample
```
void buildDecimatedSample()
```
    Builds the decimated sample. This method must only be called after processSample(Sample) has been called at least once. It must be called before calling getDecimatedSample() or getDecimatedSampleEstimatedSize(). processSample(Sample) must not be called again after calling this method and this method must only be called once. This method may throw an IllegalStateException if the specified call order is violated. However, there is no guarantee that such an exception is thrown.
  - getChannelName
```
String getChannelName()
```
    Returns the name of the channel for which this sample decimator decimates samples. The returned channel name is the name that was specified when this sample decimator was created.
    
    Returns:
    
    name identifying the channel covered by this sample decimator.
  - getDecimatedSample
```
SampleType getDecimatedSample()
```
    Returns the decimated sample that has been generated by buildDecimatedSample(). This sample has the time stamp of the interval start as specified by getIntervalStartTime(). This method must only be called after calling buildDecimatedSample(). This method may throw an IllegalStateException if the specified call order is violated. However, there is no guarantee that such an exception is thrown.
    
    Returns:
    
    sample that has been generated from the samples passed to processSample(Sample).
  - getDecimatedSampleEstimatedSize
```
int getDecimatedSampleEstimatedSize()
```
    Returns the estimated size of the decimated sample. This is the size that the sample is expected to have when it is serialized into the database. The size is specified in bytes.
    
    This information is used by the archiving code to keep track of the total size of the samples that are stored inside a bucket. As storing too much (or too little) data in a single bucket has an impact on performance, the archiving code will decide to start a new bucket when a certain size has been reached. Therefore, this estimate should be as accurate as possible.
    
    This method must only be called after calling buildDecimatedSample(). This method may throw an IllegalStateException if the specified call order is violated. However, there is no guarantee that such an exception is thrown.
    
    Returns:
    
    estimated size of the decimated sample (returned by getDecimatedSample()) in bytes.
  - getIntervalLength
```
long getIntervalLength()
```
    Returns the length of the period for which this sample decimator generates a decimated sample. The length is specified in nanoseconds. The returned length is the length that was specified when this sample decimator was created.
    
    The period covered by this sample decimator is specified by the interval [start time, start + length).
    
    Returns:
    
    length of the period covered by this sample decimator (in nanosconds).
  - getIntervalStartTime
```
long getIntervalStartTime()
```
    Returns the start time of the period for which this sample decimator generated a decimated sample. The start time is specified as the number of nanoseconds since epoch (January 1st, 1970, 00:00:00 UTC). The returned start time is the time that was specified when this sample decimator was created.
    
    The period covered by this sample decimator is specified by the interval [start time, start + length).
    
    Returns:
    
    start time of the period covered by this sample decimator.
  - processSample
```
void processSample(SampleType sample)
```
    Processes a sample, updating the internal state with the information from the sample. This method must be called for every sample that is is in the interval specified by the start time and length (as returned by getIntervalStartTime() and getIntervalLength()).
    
    The first sample passed to this method must have a time stamp that is less than or equal to the interval start-time. This method must be called at least once before calling buildDecimatedSample(). It must not be called after calling buildDecimatedSample(). This method may throw an IllegalStateException if the specified call order is violated. However, there is no guarantee that such an exception is thrown.
    
    Parameters:
    
    sample - sample that shall be processed, updating the sample decimator's internal state.

Interface SampleDecimator<SampleType extends Sample>

Method Summary

Method Detail

buildDecimatedSample

getChannelName

getDecimatedSample

getDecimatedSampleEstimatedSize

getIntervalLength

getIntervalStartTime

processSample