com.aquenos.cassandra.pvarchiver.server.archiving

Class ArchiveAccessServiceImpl

java.lang.Object

com.aquenos.cassandra.pvarchiver.server.archiving.ArchiveAccessServiceImpl

All Implemented Interfaces:

ArchiveAccessService

public class ArchiveAccessServiceImpl
extends Object
implements ArchiveAccessService

Standard implementation of the ArchiveAccessService.

Author:

Sebastian Marsching

Constructor Summary

Constructors

Constructor and Description
ArchiveAccessServiceImpl()

Method Summary

Modifier and Type	Method and Description
<SampleType extends Sample> ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<SampleType>>	getSamples(ChannelMetaDataDAO.ChannelConfiguration channelConfiguration, int decimationLevel, long lowerTimeStampLimit, TimeStampLimitMode lowerTimeStampLimitMode, long upperTimeStampLimit, TimeStampLimitMode upperTimeStampLimitMode, ControlSystemSupport<SampleType> controlSystemSupport) Retrieves samples for the specified channel and decimation level.
<SampleType extends Sample> ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<SampleType>>	getSamples(ChannelMetaDataDAO.ChannelInformation channelInformation, int decimationLevel, long lowerTimeStampLimit, TimeStampLimitMode lowerTimeStampLimitMode, long upperTimeStampLimit, TimeStampLimitMode upperTimeStampLimitMode, ControlSystemSupport<SampleType> controlSystemSupport) Retrieves samples for the specified channel and decimation level.
ListenableFuture<? extends com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<? extends Sample>>	getSamples(String channelName, int decimationLevel, long lowerTimeStampLimit, TimeStampLimitMode lowerTimeStampLimitMode, long upperTimeStampLimit, TimeStampLimitMode upperTimeStampLimitMode) Retrieves samples for the specified channel and decimation level.
void	setChannelInformationCache(ChannelInformationCache channelInformationCache) Sets the channel information cache.
void	setChannelMetaDataDAO(ChannelMetaDataDAO channelMetaDataDAO) Sets the DAO for reading meta-data related to channels.
void	setControlSystemSupportRegistry(ControlSystemSupportRegistry controlSystemSupportRegistry) Sets the control-system support registry.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ArchiveAccessServiceImpl

public ArchiveAccessServiceImpl()

Method Detail

setChannelInformationCache

@Autowired
public void setChannelInformationCache(ChannelInformationCache channelInformationCache)

Sets the channel information cache. The cache is used for reading ChannelMetaDataDAO.ChannelInformation objects from the database, using an in-memory copy (if available) instead of having to read from the database every time. Typically, this method is called automatically by the Spring container.

Parameters:

channelInformationCache - channel information cache for getting ChannelMetaDataDAO.ChannelInformation objects.

setChannelMetaDataDAO

@Autowired
public void setChannelMetaDataDAO(ChannelMetaDataDAO channelMetaDataDAO)

Sets the DAO for reading meta-data related to channels. Typically, this method is called automatically by the Spring container.

Parameters:

channelMetaDataDAO - channel meta-data DAO to be used by this object.

setControlSystemSupportRegistry

@Autowired
public void setControlSystemSupportRegistry(ControlSystemSupportRegistry controlSystemSupportRegistry)

Sets the control-system support registry. The registry is used to gain access to the control-system supports available on this archiving server. Typically, this method is called automatically by the Spring container.

Parameters:

controlSystemSupportRegistry - control-system support registry for this archiving server.

getSamples

public ListenableFuture<? extends com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<? extends Sample>> getSamples(String channelName,
                                                                                                                        int decimationLevel,
                                                                                                                        long lowerTimeStampLimit,
                                                                                                                        TimeStampLimitMode lowerTimeStampLimitMode,
                                                                                                                        long upperTimeStampLimit,
                                                                                                                        TimeStampLimitMode upperTimeStampLimitMode)

Description copied from interface: ArchiveAccessService

Retrieves samples for the specified channel and decimation level. 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 are returned in the natural order of their time-stamps (ascending, older samples first).

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

Time-stamp limit mode

When specifying the same value for lowerTimeStampLimit and upperTimeStampLimit, the number of samples returned might be zero, one, or two, depending on which lowerTimeStampLimitMode and upperTimeStampLimitMode have been specified and whether a sample exactly at the specified time-stamp exists.

If a sample exactly matching the specified time-stamp exists, only this sample is returned, regardless of the specified limit modes.

If no such sample exists, but samples with a lesser and greater time-stamp exist, the number of samples returned is specified by the following table:

lowerTimeStampLimitMode	upperTimeStampLimitMode	number of samples
AT_OR_AFTER	AT_OR_BEFORE	0
AT_OR_AFTER	AT_OR_AFTER	1
AT_OR_BEFORE	AT_OR_BEFORE	1
AT_OR_BEFORE	AT_OR_AFTER	2

In other words, specifying AT_OR_BEFORE for the lowerTimeStampLimitMode ensures that the lowerTimeStampLimit is always included in the time interval spanned by the returned samples. Consequently, specifying AT_OR_AFTER for the upperTimeStampLimitMode/ ensures that the upperTimeStampLimit is always included in the time interval spanned by the returned samples.

For obvious reasons, these expectations only hold if there are enough samples to span the entire interval. If the lowerTimeStampLimit is less than the time stamp of the oldest existing sample, that sample will always be the first sample being returned. Consequently, if the upperTimeStampLimit is greater than the time stamp of the newest existing sample, that sample will always be the last sample being returned.

Performance considerations

In order to get the best possible performance, AT_OR_AFTER should be preferred for the lowerTimeStampLimitMode and AT_OR_BEFORE should be preferred for the upperTimeStampLimitMode. Specifying different limit modes will result in additional queries to the database. However, using different limit modes might be preferable if samples spanning the entire specified period are needed.

Specified by:

getSamples in interface ArchiveAccessService

Parameters:

channelName - name identifying the channel for which samples shall be retrieved.

decimationLevel - decimation level (identified by its decimation period) for which samples shall be received. A decimation period of zero specifies that raw samples shall be retrieved.

lowerTimeStampLimit - lower limit of the interval for which samples shall be retrieved. The exact meaning depends on the lowerTimeStampLimitMode. This parameter must not be negative.

lowerTimeStampLimitMode - mode for the lowerTimeStampLimit. If AT_OR_BEFORE, the first sample returned has a time-stamp equal to or less than the lowerTimeStampLimit (if such a sample exists at all). If TimeStampLimitMode.AT_OR_AFTER, the first sample returned has a time-stamp equal to or greater than the lowerTimeStampLimit (if such a sample exists at all).

upperTimeStampLimit - upper limit of the interval for which samples shall be retrieved. The exact meaning depends on the upperTimeStampLimitMode. This parameter must be greater than or equal to the lowerTimeStampLimit.

upperTimeStampLimitMode - mode for the upperTimeStampLimit. If AT_OR_BEFORE, the last sample returned has a time-stamp equal to or less than the upperTimeStampLimit (if such a sample exists at all). If TimeStampLimitMode.AT_OR_AFTER, the last sample returned has a time-stamp equal to or greater than the upperTimeStampLimit (if such a sample exists at all).

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:

ArchiveAccessService.getSamples(ChannelMetaDataDAO.ChannelInformation, int, long, TimeStampLimitMode, long, TimeStampLimitMode, ControlSystemSupport)

getSamples

public <SampleType extends Sample> ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<SampleType>> getSamples(ChannelMetaDataDAO.ChannelConfiguration channelConfiguration,
                                                                                                                                    int decimationLevel,
                                                                                                                                    long lowerTimeStampLimit,
                                                                                                                                    TimeStampLimitMode lowerTimeStampLimitMode,
                                                                                                                                    long upperTimeStampLimit,
                                                                                                                                    TimeStampLimitMode upperTimeStampLimitMode,
                                                                                                                                    ControlSystemSupport<SampleType> controlSystemSupport)

Description copied from interface: ArchiveAccessService

Retrieves samples for the specified channel and decimation level. The result set containing the samples matching the query is returned through a future. If the query fails, the future throws an exception.

This method is practically identical to the getSamples method that takes a ChannelInformation argument, so all the comments regarding that method apply to this method as well. The only difference is that this method takes ChannelConfiguration argument, so that it can be used in situations where the ChannelConfiguration is directly available, but the ChannelInformation is not.

Specified by:

getSamples in interface ArchiveAccessService

Type Parameters:

SampleType - type of the sample objects from the specified controlSystemSupport.

Parameters:

channelConfiguration - channel configuration for the channel for which samples shall be retrieved.

decimationLevel - decimation level (identified by its decimation period) for which samples shall be received. A decimation period of zero specifies that raw samples shall be retrieved.

lowerTimeStampLimit - lower limit of the interval for which samples shall be retrieved. The exact meaning depends on the lowerTimeStampLimitMode. This parameter must not be negative.

lowerTimeStampLimitMode - mode for the lowerTimeStampLimit. If AT_OR_BEFORE, the first sample returned has a time-stamp equal to or less than the lowerTimeStampLimit (if such a sample exists at all). If TimeStampLimitMode.AT_OR_AFTER, the first sample returned has a time-stamp equal to or greater than the lowerTimeStampLimit (if such a sample exists at all).

upperTimeStampLimit - upper limit of the interval for which samples shall be retrieved. The exact meaning depends on the upperTimeStampLimitMode. This parameter must be greater than or equal to the lowerTimeStampLimit.

upperTimeStampLimitMode - mode for the upperTimeStampLimit. If AT_OR_BEFORE, the last sample returned has a time-stamp equal to or less than the upperTimeStampLimit (if such a sample exists at all). If TimeStampLimitMode.AT_OR_AFTER, the last sample returned has a time-stamp equal to or greater than the upperTimeStampLimit (if such a sample exists at all).

controlSystemSupport - control-system support for the channel for which samples shall be retrieved. The control-system support's type must match the control-system type specified by the supplied channelConfiguration.

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:

ArchiveAccessService.getSamples(String, int, long, TimeStampLimitMode, long, TimeStampLimitMode)

getSamples

public <SampleType extends Sample> ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<SampleType>> getSamples(ChannelMetaDataDAO.ChannelInformation channelInformation,
                                                                                                                                    int decimationLevel,
                                                                                                                                    long lowerTimeStampLimit,
                                                                                                                                    TimeStampLimitMode lowerTimeStampLimitMode,
                                                                                                                                    long upperTimeStampLimit,
                                                                                                                                    TimeStampLimitMode upperTimeStampLimitMode,
                                                                                                                                    ControlSystemSupport<SampleType> controlSystemSupport)

Description copied from interface: ArchiveAccessService

Retrieves samples for the specified channel and decimation level. 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 are returned in the natural order of their time-stamps (ascending, older samples first).

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

Time-stamp limit mode

When specifying the same value for lowerTimeStampLimit and upperTimeStampLimit, the number of samples returned might be zero, one, or two, depending on which lowerTimeStampLimitMode and upperTimeStampLimitMode have been specified and whether a sample exactly at the specified time-stamp exists.

If a sample exactly matching the specified time-stamp exists, only this sample is returned, regardless of the specified limit modes.

If no such sample exists, but samples with a lesser and greater time-stamp exist, the number of samples returned is specified by the following table:

lowerTimeStampLimitMode	upperTimeStampLimitMode	number of samples
AT_OR_AFTER	AT_OR_BEFORE	0
AT_OR_AFTER	AT_OR_AFTER	1
AT_OR_BEFORE	AT_OR_BEFORE	1
AT_OR_BEFORE	AT_OR_AFTER	2

In other words, specifying AT_OR_BEFORE for the lowerTimeStampLimitMode ensures that the lowerTimeStampLimit is always included in the time interval spanned by the returned samples. Consequently, specifying AT_OR_AFTER for the upperTimeStampLimitMode/ ensures that the upperTimeStampLimit is always included in the time interval spanned by the returned samples.

For obvious reasons, these expectations only hold if there are enough samples to span the entire interval. If the lowerTimeStampLimit is less than the time stamp of the oldest existing sample, that sample will always be the first sample being returned. Consequently, if the upperTimeStampLimit is greater than the time stamp of the newest existing sample, that sample will always be the last sample being returned.

Performance considerations

In order to get the best possible performance, AT_OR_AFTER should be preferred for the lowerTimeStampLimitMode and AT_OR_BEFORE should be preferred for the upperTimeStampLimitMode. Specifying different limit modes will result in additional queries to the database. However, using different limit modes might be preferable if samples spanning the entire specified period are needed.

Specified by:

getSamples in interface ArchiveAccessService

Type Parameters:

SampleType - type of the sample objects from the specified controlSystemSupport.

Parameters:

channelInformation - channel information for the channel for which samples shall be retrieved.

decimationLevel - decimation level (identified by its decimation period) for which samples shall be received. A decimation period of zero specifies that raw samples shall be retrieved.

lowerTimeStampLimit - lower limit of the interval for which samples shall be retrieved. The exact meaning depends on the lowerTimeStampLimitMode. This parameter must not be negative.

lowerTimeStampLimitMode - mode for the lowerTimeStampLimit. If AT_OR_BEFORE, the first sample returned has a time-stamp equal to or less than the lowerTimeStampLimit (if such a sample exists at all). If TimeStampLimitMode.AT_OR_AFTER, the first sample returned has a time-stamp equal to or greater than the lowerTimeStampLimit (if such a sample exists at all).

upperTimeStampLimit - upper limit of the interval for which samples shall be retrieved. The exact meaning depends on the upperTimeStampLimitMode. This parameter must be greater than or equal to the lowerTimeStampLimit.

upperTimeStampLimitMode - mode for the upperTimeStampLimit. If AT_OR_BEFORE, the last sample returned has a time-stamp equal to or less than the upperTimeStampLimit (if such a sample exists at all). If TimeStampLimitMode.AT_OR_AFTER, the last sample returned has a time-stamp equal to or greater than the upperTimeStampLimit (if such a sample exists at all).

controlSystemSupport - control-system support for the channel for which samples shall be retrieved. The control-system support's type must match the control-system type specified by the supplied channelInformation.

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:

ArchiveAccessService.getSamples(String, int, long, TimeStampLimitMode, long, TimeStampLimitMode)