com.aquenos.cassandra.pvarchiver.controlsystem

Interface ControlSystemSupport<SampleType extends Sample>

Type Parameters:

SampleType - type that is implemented by all samples that are generated by this control-system support.

public interface ControlSystemSupport<SampleType extends Sample>

Interface to a control-system support module. Each control-system support has to implement this interface so that the archive server can use it. The module also has to register a ControlSystemSupportFactory which is responsible for creating the ControlSystemSupport instance when requested by the server.

Classes implementing this interface must be thread-safe. All methods might be called in parallel by different threads.

Author:

Sebastian Marsching

Field Summary

Fields

Modifier and Type	Field and Description
static int	SAMPLES_LIMIT_UNBOUNDED Number to be specified when samples should be retrieved without limiting their number.

Method Summary

Modifier and Type	Method and Description
ListenableFuture<? extends ControlSystemChannel>	createChannel(String channelName, Map<String,String> options, SampleBucketId currentBucketId, SampleListener<SampleType> sampleListener) Creates the control-system-specific support for an archived channel.
SampleDecimator<SampleType>	createSampleDecimator(String channelName, Map<String,String> options, long intervalStartTime, long intervalLength) Creates a sample decimator.
ListenableFuture<Void>	deleteSamples(SampleBucketId bucketId) Deletes all samples associated with the specified sample bucket.
void	destroy() Destroys this control-system support.
ListenableFuture<SampleWithSizeEstimate<SampleType>>	generateChannelDisabledSample(String channelName, Map<String,String> options, SampleBucketId currentBucketId) Generates a sample that indicates that the specified channel is disabled.
String	getId() Returns the identifier that uniquely identifies the control-system support module.
String	getName() Returns a short, descriptive name for this control-system support, suitable for display.
ListenableFuture<SampleBucketState>	getSampleBucketState(SampleBucketId bucketId) Returns the state of the specified sample bucket.
ListenableFuture<ObjectResultSet<SampleType>>	getSamples(SampleBucketId bucketId, long timeStampGreaterThanOrEqualTo, long timeStampLessThanOrEqualTo, int limit) Retrieves samples from the specified sample bucket.
ListenableFuture<ObjectResultSet<SampleType>>	getSamplesInReverseOrder(SampleBucketId bucketId, long timeStampGreaterThanOrEqualTo, long timeStampLessThanOrEqualTo, int limit) Retrieves samples from the specified sample bucket in reverse order (newer samples first).
void	serializeSampleToJsonV1(SampleType sample, JsonGenerator jsonGenerator) Serializes a sample in the JSON format version 1.
ListenableFuture<Void>	writeSample(SampleType sample, SampleBucketId bucketId, int newBucketSize) Writes a sample to the database.

Field Detail

SAMPLES_LIMIT_UNBOUNDED

static final int SAMPLES_LIMIT_UNBOUNDED

Number to be specified when samples should be retrieved without limiting their number.

See Also:

getSamples(SampleBucketId, long, long, int), getSamplesInReverseOrder(SampleBucketId, long, long, int), Constant Field Values

Method Detail

createChannel

ListenableFuture<? extends ControlSystemChannel> createChannel(String channelName,
                                                               Map<String,String> options,
                                                               SampleBucketId currentBucketId,
                                                               SampleListener<SampleType> sampleListener)

Creates the control-system-specific support for an archived channel. The channel should be created in an asynchronous way. Any blocking or long running operation should be performed in a separate thread that completes the returned future once it has finished.

Separate calls to this method providing the same channel name should result in separate channel instances being returned. In particular, destroying a channel instance should never destroy other channel instances with the same channel name.

The control-system support is supposed to notify the sampleListener whenever it detects that the value of the channel has changed in the control-system and the new value should be archived. It is important that the sampleListener gets the correct instance of the control-system channel passed to it. This must exactly be the instance provided by the future returned by this method because the archiving code will test for object identity when checking that a sample comes from the most recent instance of a control-system channel (and not from an instance that has been destroyed).

A control-system support should not throw an exception when creating a channel unless it detects a permanent problem. The archiving code will not retry creating a channel if an exception has been thrown unless the configuration for this channel is changed or the whole server goes offline and back online. Therefore, transient problems (e.g. connection problems) should be handled internally, transparently establishing the connection when the problems have been resolved.

This method is only called when archiving for a channel has been enabled in the channel's configuration. When archiving has been disabled, the generateChannelDisabledSample(String, Map, SampleBucketId) method is called instead.

Parameters:

channelName - name identifying the channel.

options - control-system-specific options associated with the channel. The interpretation of this options is up to the implementation of the control-system support.

currentBucketId - ID of the sample bucket to which raw samples for the channel are currently being written. This may be null if no samples have been written yet. The control-system support may use this information if it needs information about the sample last written before it can start operation.

sampleListener - listener that shall be notified whenever the control-system support detects that the channel's value has changed in the control-system and the new value should be archived.

Returns:

future that returns the control-system-specific channel for the specified channel name or throws an exception if the channel cannot be created.

createSampleDecimator

SampleDecimator<SampleType> createSampleDecimator(String channelName,
                                                  Map<String,String> options,
                                                  long intervalStartTime,
                                                  long intervalLength)

Creates a sample decimator. A sample decimator is responsible for creating a decimated sample for a certain period of time. This period is specified by the interval start-time and length parameters.

The actual strategy for generating a decimated sample depends on the control-system support and possibly even on the internal type of the sample. 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 the samples in the period and create a decimated sample that represents this average, possibly carrying additional information like minimum and maximum values or the standard deviation.

The sample decimator returned by this method does not have to be thread-safe. Its method may only be called by a single thread. This method however has to be thread-safe, because many sample decimators might be created and active at the same time.

This method must not block or perform any long-running actions as it might be called from time-sensitive threads.

Please refer to the description of the SampleDecimator interface for details about the contract that applies to sample decimators.

Parameters:

channelName - name identifying the channel for which samples are supposed to be decimated.

options - control-system-specific options associated with the channel. The interpretation of this options is up to the implementation of the control-system support.

intervalStartTime - start time or the period for which the created sample decimator is supposed to generate a decimated sample. The first sample passed to the sample decimator is guaranteed to have a time stamp less than or equal to this time. The start time is specified as the number of nanoseconds since epoch (January 1st, 1970, 00:00:00 UTC).

intervalLength - the length of the period for which the created sample decimator is supposed to generate a decimated sample. Together with the intervalStartTime, the intervalLength specifies the whole interval that shall be covered by the created sample decimator. This interval is [intervalStartTime, intervalStartTime + intervalLength). The length is specified in nanoseconds.

Returns:

a new sample decimator for the specified channel and period.

deleteSamples

ListenableFuture<Void> deleteSamples(SampleBucketId bucketId)

Deletes all samples associated with the specified sample bucket. This should also delete the meta-data (bucket size) associated with the bucket. Effectively, after this operation finishes, the database should be in the same state as if data for that bucket had never been written. The bucket should be deleted in an asynchronous way. Any blocking or long running operation should be performed in a separate thread that completes the returned future once it has finished.

Parameters:

bucketId - unique identifier of the sample bucket that shall be deleted.

Returns:

future that completes when the delete operation has finished or finally failed.

destroy

void destroy()

Destroys this control-system support. This method is called by the server when it does not need the control-system support any longer and thus the resources reserved by this control-system support can be released. Typically, this only happens when the server is shutdown.

generateChannelDisabledSample

ListenableFuture<SampleWithSizeEstimate<SampleType>> generateChannelDisabledSample(String channelName,
                                                                                   Map<String,String> options,
                                                                                   SampleBucketId currentBucketId)

Generates a sample that indicates that the specified channel is disabled. If the sample cannot be generated immediately, it should be generated in an asynchronous way. This method must never block. When no marker sample shall be written, the future returned by this method returns null, this method itself, however, never returns null.

This method is only called when archiving for a channel has been disabled in the channel's configuration. When archiving has been enabled, the createChannel(String, Map, SampleBucketId, SampleListener) method is called instead. This method is called every time that the channel is is initialized by the archiving service. Typically, this happens every time when the server switches from the offline to the online state.

A control-system support may choose to generate a marker sample that indicates that a channel has been disabled. Such a marker sample might help in determining why there is no valid data for a certain period of time. However, a control-system support may also choose not to write such a sample (possibly based on a configuration option). In this case, the future returned by this method returns null and the archiving service does not write a sample..

Parameters:

channelName - name identifying the channel.

options - control-system-specific options associated with the channel. The interpretation of this options is up to the implementation of the control-system support.

currentBucketId - ID of the sample bucket to which raw samples for the channel are currently being written. This may be null if no samples have been written yet. The control-system support may use this information if it needs information about the sample last written for generating the marker sample.

Returns:

future that returns a sample (and its estimated size) indicating that the channel has been disabled or null if no such sample shall be written. The future throws an exception if there is an error while processing the request, typically because the specified options are invalid.

getId

String getId()

Returns the identifier that uniquely identifies the control-system support module. This identifier is used in various places (e.g. when referring to a specific control system in the database or when configuring a channel. The identifier should be all lower-case, only contain ASCII characters, digits and underscores (_), and start with a character. For example, "my_control_system" is a valid identifier.

Returns:

identifier that uniquely identifies the control system supported by this support module.

getName

String getName()

Returns a short, descriptive name for this control-system support, suitable for display. This name might be used to identify the control-system type when displaying a selection to the user. Thus, the name should be short but descriptive and unique (e.g. "My Control System").

Returns:

short, descriptive name for this control-system support for displaying purposes.

getSampleBucketState

ListenableFuture<SampleBucketState> getSampleBucketState(SampleBucketId bucketId)

Returns the state of the specified sample bucket. The state stores information about the total size of the samples currently stored in the bucket and about the time stamp of the latest sample stored in the bucket. The bucket should be retrieved in an asynchronous way. Any blocking or long running operation should be performed in a separate thread that completes the returned future once it has finished.

Parameters:

bucketId - unique identifier of the bucket for which the meta data shall be received.

Returns:

future that eventually provides the meta data for the specified sample bucket and throws an exception when the retrieval operation has finally failed. If no meta-data is stored for the specified bucket, this should not result in an exception or null value to be returned. Instead, the returned bucket state should specify a bucket size of zero and a time stamp of zero for the latest sample.

getSamples

ListenableFuture<ObjectResultSet<SampleType>> getSamples(SampleBucketId bucketId,
                                                         long timeStampGreaterThanOrEqualTo,
                                                         long timeStampLessThanOrEqualTo,
                                                         int limit)

Retrieves samples from the specified sample bucket. The result set containing the samples matching the query is returned through a future. If the query fails, the future throws an exception.

The process for retrieving samples may (and typically will) be iterative, meaning that samples are not retrieved all at once but gradually as they are read from the result set. For this reason, retrieving samples from the result set can fail with an exception, even if the future completed successfully.

The samples in the bucket that have a time-stamp between timeStampGreaterThanOrEqualTo and timeStampLessThanOrEqualTo (both inclusive) are returned. The returned samples are ordered by the natural order of their time-stamps (ascending, older samples first). If there are more samples in the specified interval than the specified limit, only the first limit samples are returned. If limit is negative, the number of samples returned is unbounded.

Calls to this method should not block. Instead, this method should quickly return a future that completes when a longer running operation has completed in the background.

Parameters:

bucketId - identifier of the sample bucket from which the samples shall be retrieved.

timeStampGreaterThanOrEqualTo - lower limit of the time interval (inclusive) for which samples shall be retrieved.

timeStampLessThanOrEqualTo - upper limit of the time interval (inclusive) for which samples shall be retrieved.

limit - maximum number of samples that shall be retrieved. If the number of samples shall not be bounded, SAMPLES_LIMIT_UNBOUNDED should be specified.

Returns:

future returning a result set which iterates over the samples matching the specified criteria. If there is an error, the future may throw an exception or the sample set returned by the future may throw an exception.

See Also:

getSamplesInReverseOrder(SampleBucketId, long, long, int)

getSamplesInReverseOrder

ListenableFuture<ObjectResultSet<SampleType>> getSamplesInReverseOrder(SampleBucketId bucketId,
                                                                       long timeStampGreaterThanOrEqualTo,
                                                                       long timeStampLessThanOrEqualTo,
                                                                       int limit)

Retrieves samples from the specified sample bucket in reverse order (newer samples first). The result set containing the samples matching the query is returned through a future. If the query fails, the future throws an exception.

The process for retrieving samples may (and typically will) be iterative, meaning that samples are not retrieved all at once but gradually as they are read from the result set. For this reason, retrieving samples from the result set can fail with an exception, even if the future completed successfully.

The samples in the bucket that have a time-stamp between timeStampGreaterThanOrEqualTo and timeStampLessThanOrEqualTo (both inclusive) are returned. The returned samples are ordered by the inverse natural order of their time-stamps (descending, newer samples first). If there are more samples in the specified interval than the specified limit, only the first limit samples are returned. If limit is negative, the number of samples returned is unbounded.

Calls to this method should not block. Instead, this method should quickly return a future that completes when a longer running operation has completed in the background.

Parameters:

bucketId - identifier of the sample bucket from which the samples shall be retrieved.

timeStampGreaterThanOrEqualTo - lower limit of the time interval (inclusive) for which samples shall be retrieved.

timeStampLessThanOrEqualTo - upper limit of the time interval (inclusive) for which samples shall be retrieved.

limit - maximum number of samples that shall be retrieved. If the number of samples shall not be bounded, SAMPLES_LIMIT_UNBOUNDED should be specified.

Returns:

future returning a result set which iterates over the samples matching the specified criteria. If there is an error, the future may throw an exception or the sample set returned by the future may throw an exception.

See Also:

getSamples(SampleBucketId, long, long, int)

serializeSampleToJsonV1

void serializeSampleToJsonV1(SampleType sample,
                             JsonGenerator jsonGenerator)
                      throws IOException

Serializes a sample in the JSON format version 1. This method should perform the serialization by making exactly one call to one of the methods provided by JsonV1SampleSerializer. This will help to ensure that the serialization format matches the specification expected by a client.

Parameters:

sample - sample to be serialized. This sample has been provided by this control-system support, so it is guaranteed to be of the correct type.

jsonGenerator - JSON generator to which the serialized form of the sample shall be written.

Throws:

IOException - if such an exception is thrown by the jsonGenerator.

writeSample

ListenableFuture<Void> writeSample(SampleType sample,
                                   SampleBucketId bucketId,
                                   int newBucketSize)

Writes a sample to the database. The sample shall be appended to the specified sample bucket and the sample bucket's meta-data is supposed to be update to reflect the new bucket size. The sample is guaranteed to be a sample provided by this control-system support, so the control-system support can be sure that it will only get asked to write samples of types it supports. The sample should be written in an asynchronous way. Any blocking or long running operation should be performed in a separate thread that completes the returned future once it has finished.

Parameters:

sample - sample that shall be written. This sample has been provided by this control-system support, so it is guaranteed to be of the correct type.

bucketId - unique identifier of the bucket to which the sample shall be appended.

newBucketSize - new size of the sample bucket. The calling code takes care of calculating the updated bucket size, so the control-system support can simply save the supplied number.

Returns:

future that completes when the sample has been written and that throws an exception when the write operation has finally failed.