com.aquenos.cassandra.pvarchiver.server.database

Interface ChannelMetaDataDAO

All Known Implementing Classes:

ChannelMetaDataDAOImpl

public interface ChannelMetaDataDAO

Data-access object handling meta-data related to archived control-system channels. This DAO is responsible for storing channels with their configuration and information about sample buckets for these channels. However, it is not responsible for storing the actual samples.

In general, the methods provided by this class are thread-safe but do not guarantee atomicity. For example, adding and removing the same channel concurrently has undefined results. This also applies if two otherwise independent clients (on different computers) run the code concurrently. The caller has to ensure that methods are only invoked concurrently if there is no risk of such interference (e.g. because the actions affect different channels).

Author:

Sebastian Marsching

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ChannelMetaDataDAO.ChannelConfiguration Value object representing the configuration of a channel.
static class	ChannelMetaDataDAO.ChannelInformation Value object representing the general meta-data for a channel.
static class	ChannelMetaDataDAO.ChannelOperation Value object representing an operation on a channel.
static class	ChannelMetaDataDAO.SampleBucketInformation Value object representing the meta-data of a sample bucket.

Method Summary

Modifier and Type	Method and Description
ListenableFuture<Void>	createChannel(String channelName, UUID channelDataId, String controlSystemType, Set<Integer> decimationLevels, Map<Integer,Integer> decimationLevelToRetentionPeriod, boolean enabled, Map<String,String> options, UUID serverId) Creates a channel.
ListenableFuture<Void>	createChannelDecimationLevels(String channelName, UUID serverId, Set<Integer> decimationLevels, Map<Integer,Integer> decimationLevelToRetentionPeriod) Creates decimation levels for the specified channel.
ListenableFuture<Pair<Boolean,UUID>>	createPendingChannelOperation(UUID serverId, String channelName, UUID operationId, String operationType, String operationData, int ttl) Creates a pending channel operation.
ListenableFuture<Pair<Boolean,UUID>>	createPendingChannelOperationRelaxed(UUID serverId, String channelName, UUID operationId, String operationType, String operationData, int ttl) Creates a pending channel operation in a more relaxed way.
ListenableFuture<Void>	createSampleBucket(String channelName, int decimationLevel, long bucketStartTime, long bucketEndTime, Long precedingBucketStartTime, boolean isNewCurrentBucket, UUID serverId) Creates a sample bucket for a channel.
ListenableFuture<Void>	deleteChannel(String channelName, UUID serverId) Deletes a channel.
ListenableFuture<Void>	deleteChannelDecimationLevels(String channelName, UUID serverId, Set<Integer> decimationLevels) Removes decimation levels from the specified channel.
ListenableFuture<Pair<Boolean,UUID>>	deletePendingChannelOperation(UUID serverId, String channelName, UUID operationId) Deletes a pending channel operation associated with the specified server and channel.
ListenableFuture<Void>	deleteSampleBucket(String channelName, int decimationLevel, long bucketStartTime, boolean isCurrentBucket, UUID serverId) Deletes the meta-data for a sample bucket.
ListenableFuture<ChannelMetaDataDAO.ChannelInformation>	getChannel(String channelName) Returns the meta-data for the specified channel.
ListenableFuture<ChannelMetaDataDAO.ChannelConfiguration>	getChannelByServer(UUID serverId, String channelName) Returns the channel configuration for the specified channel belonging to the specified server.
ListenableFuture<? extends Iterable<ChannelMetaDataDAO.ChannelInformation>>	getChannels() Returns the meta-data for all channels.
ListenableFuture<? extends Iterable<ChannelMetaDataDAO.ChannelConfiguration>>	getChannelsByServer(UUID serverId) Returns the configuration for all channels belonging to the specified server.
ListenableFuture<ChannelMetaDataDAO.ChannelOperation>	getPendingChannelOperation(UUID serverId, String channelName) Returns the pending channel operation for the specified server and channel.
ListenableFuture<? extends Iterable<ChannelMetaDataDAO.ChannelOperation>>	getPendingChannelOperations(UUID serverId) Returns all pending channel operations for the specified server.
ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>>	getSampleBuckets(String channelName) Returns the meta data for all sample buckets for the specified channel and all decimation levels.
ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>>	getSampleBuckets(String channelName, int decimationLevel) Returns the meta data for all sample buckets for the specified channel and decimation level.
ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>>	getSampleBucketsInInterval(String channelName, int decimationLevel, long startTimeGreaterThanOrEqualTo, long startTimeLessThanOrEqualTo) Returns the meta data for the sample buckets for the specified channel and decimation level which are in the specified interval.
ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>>	getSampleBucketsInReverseOrder(String channelName, int decimationLevel, int limit) Returns the meta data for all sample buckets for the specified channel and decimation level up to the specified limit.
ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>>	getSampleBucketsNewerThan(String channelName, int decimationLevel, long startTimeGreaterThanOrEqualTo, int limit) Returns the meta data for the sample buckets for the specified channel and decimation level which have a start time later than the specified time.
ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>>	getSampleBucketsOlderThanInReverseOrder(String channelName, int decimationLevel, long startTimeLessThanOrEqualTo, int limit) Returns the meta data for the sample buckets for the specified channel and decimation level which have a start time before the specified time.
ListenableFuture<Void>	moveChannel(String channelName, UUID oldServerId, UUID newServerId) Moves a channel from one server to another.
ListenableFuture<Void>	renameChannel(String oldChannelName, String newChannelName, UUID serverId) Changes the name of a channel.
ListenableFuture<Void>	updateChannelConfiguration(String channelName, UUID serverId, Map<Integer,Integer> decimationLevelToRetentionPeriod, boolean enabled, Map<String,String> options) Updates the configuration for a channel.
ListenableFuture<Pair<Boolean,UUID>>	updatePendingChannelOperation(UUID serverId, String channelName, UUID oldOperationId, UUID newOperationId, String newOperationType, String newOperationData, int ttl) Updates an existing pending channel operation, replacing it with the specified information.
ListenableFuture<Pair<Boolean,UUID>>	updatePendingChannelOperationRelaxed(UUID serverId, String channelName, UUID oldOperationId, UUID newOperationId, String newOperationType, String newOperationData, int ttl) Updates an existing pending channel operation in a more relaxed way.

Method Detail

createChannel

ListenableFuture<Void> createChannel(String channelName,
                                     UUID channelDataId,
                                     String controlSystemType,
                                     Set<Integer> decimationLevels,
                                     Map<Integer,Integer> decimationLevelToRetentionPeriod,
                                     boolean enabled,
                                     Map<String,String> options,
                                     UUID serverId)

Creates a channel. The channel must not exist before calling this method. Calling this method for a channel that already exists results in undefined behavior. The calling code has to ensure that the channel does not exist and no other attempt to create it is made concurrently. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

channelDataId - unique identifier associated with the data (samples) for each channel. This identifier must be different for each channel. It is used instead of the channel name when storing data, so that the channel can be renamed later without losing data.

controlSystemType - type of the control-system that provides the channel. This information is used to identify the control-system specific adapter that is used for the channel.

decimationLevels - set containing all decimation levels that exist for the channel.

decimationLevelToRetentionPeriod - map that contains the retention periods of the decimation levels to be created. The decimation levels are used as keys and the corresponding retention periods (in seconds) are stored as values. A retention period that is zero or negative means that samples for the corresponding decimation level are supposed to be retained forever.

enabled - true if the channel shall be enabled (archived), false if it should remain disabled. A disabled channel can be queried for data, but it is not archived.

options - map containing the options associated with the channel. The options are forwarded to the control-system specific adapter when registering the channel with it. The map may not contain null keys or values.

serverId - ID of the server that is responsible for the channel.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

createChannelDecimationLevels

ListenableFuture<Void> createChannelDecimationLevels(String channelName,
                                                     UUID serverId,
                                                     Set<Integer> decimationLevels,
                                                     Map<Integer,Integer> decimationLevelToRetentionPeriod)

Creates decimation levels for the specified channel. The specified channel must already exist and the specified decimation levels must not exist before calling this method. The calling code has to ensure that this preconditions are met and that no other modifications of the channel that might interfere with this change are performed concurrently. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

serverId - ID of the server that is responsible for the channel.

decimationLevels - set containing the decimation levels which should be created for the specified channel. This set must not contain decimation levels that already exist for the channel.

decimationLevelToRetentionPeriod - map that contains the retention periods of the decimation levels to be created. The decimation levels are used as keys and the corresponding retention periods (in seconds) are stored as values. A retention period that is zero or negative means that samples for the corresponding decimation level are supposed to be retained forever.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

createPendingChannelOperation

ListenableFuture<Pair<Boolean,UUID>> createPendingChannelOperation(UUID serverId,
                                                                   String channelName,
                                                                   UUID operationId,
                                                                   String operationType,
                                                                   String operationData,
                                                                   int ttl)

Creates a pending channel operation. The information is stored for the specified server and channel and is automatically deleted after the ttl has passed. If another pending operation for the same server and channel already exists, the existing data is not touched. Instead, this method returns the operation ID of the existing record. This check is guaranteed to be implemented in an atomic way, even across servers. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Please refer to createPendingChannelOperationRelaxed(UUID, String, UUID, String, String, int) for a version of this method that is more resilient in case of a write timeout.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

channelName - name of the channel affected by the operation.

operationId - unique ID identifying the operation. This ID is used when deleting the operation using the deletePendingChannelOperation(UUID, String, UUID) or updating it using the updatePendingChannelOperation(UUID, String, UUID, UUID, String, String, int) .

operationType - type of the operation. The type also defines the expected format of the data passed as operationData (if any). However, the interpretation of both the type and the data is left to the code using this DAO.

operationData - data associated with the operation. The format of the data typically depends on the operationType. May be null.

ttl - time-to-live of the record (in seconds). The record is automatically deleted after the specified amount of seconds. This means that after this period of time, calls to getPendingChannelOperation(UUID, String) and getPendingChannelOperations(UUID) will not return the channel operation any longer.

Returns:

pair of a boolean and a channel operation ID exposed through a future. The boolean is true if and only if the channel operation was successfully stored for the specified server and channel. If another operation was already stored and thus the specified operation was not stored, the boolean is false and the ID of the already stored channel operation is returned as part of the pair. In case of failure, the future's get() method will throw an exception.

createPendingChannelOperationRelaxed

ListenableFuture<Pair<Boolean,UUID>> createPendingChannelOperationRelaxed(UUID serverId,
                                                                          String channelName,
                                                                          UUID operationId,
                                                                          String operationType,
                                                                          String operationData,
                                                                          int ttl)

Creates a pending channel operation in a more relaxed way. The information is stored for the specified server and channel and is automatically deleted after the ttl has passed. If another pending operation for the same server and channel already exists, the existing data is not touched. Instead, this method returns the operation ID of the existing record. This check is guaranteed to be implemented in an atomic way, even across servers. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

In contrast to the createPendingChannelOperation(UUID, String, UUID, String, String, int) method, this method does not fail directly in case of a write timeout. Instead, it checks whether a pending operation with specified data is present in the database and succeeds if it is. However, this has the effect that it is not strictly guaranteed that the record in the database has actually been created by the caller. The method will also report success if another caller (possibly in a different server process) has created the record specifying exactly the same data. When using a newly generated UUID, such an event is very unlikely.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

channelName - name of the channel affected by the operation.

operationId - unique ID identifying the operation. This ID is used when deleting the operation using the deletePendingChannelOperation(UUID, String, UUID) or updating it using the updatePendingChannelOperation(UUID, String, UUID, UUID, String, String, int) .

operationType - type of the operation. The type also defines the expected format of the data passed as operationData (if any). However, the interpretation of both the type and the data is left to the code using this DAO.

operationData - data associated with the operation. The format of the data typically depends on the operationType. May be null.

ttl - time-to-live of the record (in seconds). The record is automatically deleted after the specified amount of seconds. This means that after this period of time, calls to getPendingChannelOperation(UUID, String) and getPendingChannelOperations(UUID) will not return the channel operation any longer.

Returns:

pair of a boolean and a channel operation ID exposed through a future. The boolean is true if the channel operation was successfully stored for the specified server and channel. If another operation was already stored and thus the specified operation was not stored, the boolean is false and the ID of the already stored channel operation is returned as part of the pair. The boolean might also be true if a channel operation specifying exactly the same data (operation ID, type, and data) has been created before and is thus already present in the database. In case of failure, the future's get() method will throw an exception.

createSampleBucket

ListenableFuture<Void> createSampleBucket(String channelName,
                                          int decimationLevel,
                                          long bucketStartTime,
                                          long bucketEndTime,
                                          Long precedingBucketStartTime,
                                          boolean isNewCurrentBucket,
                                          UUID serverId)

Creates a sample bucket for a channel. This only registers the meta-data and does not store any actual samples. If isNewCurrentBucket is true, the newly created bucket is considered the current bucket to which new samples for the specified decimation level should be added. This means that the stored meta-data is updated so that future queries returning a ChannelMetaDataDAO.ChannelConfiguration object for the channel will contain a reference to this bucket. If precedingBucketStartTime is not null, the end time of the specified preceding bucket is updated with the start time of the new bucket minus one. This is useful when a bucket is appended because the existing, preceding bucket will naturally end just before the start of the new bucket. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel for which a sample bucket shall be added.

decimationLevel - decimation level for which a sample bucket shall be added.

bucketStartTime - start time of the new bucket. The start time must be less than or equal to the time of the first sample supposed to be stored in the bucket. It must be strictly greater than the time of the most recent sample stored in the preceding bucket.

bucketEndTime - end time of the new bucket. The end time must be greater than or equal to the time of the last sample stored in the bucket. It must be strictly less than the the start time of any following bucket (if there is one).

precedingBucketStartTime - start time of the (existing) preceding sample bucket. If not null, the end time of that bucket is updated with the specified bucketStartTime minus one.

isNewCurrentBucket - true if the bucket shall be used for samples added to the specified decimation level. This implies that this is the most recent bucket and there are no following buckets at the time being. false if this bucket shall not be used for new samples. This is only useful if a bucket preceding the already existing buckets is added and will contain samples that are older than the already existing samples.

serverId - ID of the server which is responsible for the channel. This may be null if isNewCurrentBucket is false.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

deleteChannel

ListenableFuture<Void> deleteChannel(String channelName,
                                     UUID serverId)

Deletes a channel. The channel must exist and be associated with the specified server before calling this method. Calling this method for a channel that does not exist or that is associated with a different server results in undefined behavior. the calling code has to ensure that these preconditions are met and no other attempt to modify the channel are made concurrently. This method only deletes the meta-data for this channel. The calling code should delete all samples for the channel before calling this method because these samples will not be accessible any longer after deleting the meta-data. Any pending channel operation stored for the channel is not affected by this method. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

serverId - ID of the server which is currently responsible for the channel.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

deleteChannelDecimationLevels

ListenableFuture<Void> deleteChannelDecimationLevels(String channelName,
                                                     UUID serverId,
                                                     Set<Integer> decimationLevels)

Removes decimation levels from the specified channel. The specified channel must exist and belong to the specified server before calling this method. The calling code has to ensure that this preconditions are met and that no other modifications of the channel that might interfere with this change are performed concurrently. This method also deletes all meta-data for the sample buckets of the specified decimation levels, but it does not delete the actual samples. The calling code should delete those samples before calling this method because they will not be accessible any longer after the meta-data is deleted. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

serverId - ID of the server that is responsible for the channel.

decimationLevels - set containing the decimation levels which should be removed from the specified channel.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

deletePendingChannelOperation

ListenableFuture<Pair<Boolean,UUID>> deletePendingChannelOperation(UUID serverId,
                                                                   String channelName,
                                                                   UUID operationId)

Deletes a pending channel operation associated with the specified server and channel. If the pending operation stored for the specified server and channel has a different ID, it is not deleted. Instead, this method returns the ID of the stored record. This check is guaranteed to be implemented in an atomic way, even across servers. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

channelName - name of the channel affected by the operation.

operationId - unique ID identifying the operation. This is the ID that was specified when creating or updating the channel operation.

Returns:

pair of a boolean and a channel operation ID exposed through a future. The boolean is true if and only if the specified channel operation was deleted or there was no channel operation stored for the specified server and channel. If a different channel operation was stored for the specified server and channel, the boolean is false and the ID of the stored channel operation is returned as part of the pair. In case of failure, the future's get() method will throw an exception.

deleteSampleBucket

ListenableFuture<Void> deleteSampleBucket(String channelName,
                                          int decimationLevel,
                                          long bucketStartTime,
                                          boolean isCurrentBucket,
                                          UUID serverId)

Deletes the meta-data for a sample bucket. The bucket is identified by its start time. If the bucket is the current bucket for the specified decimation level, the corresponding flag must be set. This ensures that the respective current bucket ID in the ChannelMetaDataDAO.ChannelConfiguration is reset to null. When modifying the current bucket ID, the calling code has to ensure that no other concurrent changes are applied to the current bucket ID for the specified channel and decimation level. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel to which the sample bucket belongs.

decimationLevel - decimation level containing the sample bucket. A decimation level is identified by the number of seconds between two samples. All decimation levels except the zero decimation level, which stores raw data, have fixed periods between samples.

bucketStartTime - start time of the sample bucket.

isCurrentBucket - true if the bucket is the current bucket for the specified decimation level. This has the consequence that the decimation level's current bucket ID is reset to null. If false, the current bucket ID is not touched.

serverId - ID of the server which is currently responsible for the channel. If isCurrentBucket is false , this parameter is not used and may be null.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

getChannel

ListenableFuture<ChannelMetaDataDAO.ChannelInformation> getChannel(String channelName)

Returns the meta-data for the specified channel. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

Returns:

general meta-data for the specified channel exposed through a future. If no such channel exists, the future's get method returns null. In case of failure, the future's get() method will throw an exception.

getChannelByServer

ListenableFuture<ChannelMetaDataDAO.ChannelConfiguration> getChannelByServer(UUID serverId,
                                                                             String channelName)

Returns the channel configuration for the specified channel belonging to the specified server. The configuration is the meta-data associated with the channel that is needed by a server when initializing the channel. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

serverId - ID of the server responsible for the channel.

channelName - name identifying the requested channel.

Returns:

configuration for the specified channel exposed through a future. If no such channel exists, the future's get method returns null. In case of failure, the future's get() method will throw an exception.

getChannels

ListenableFuture<? extends Iterable<ChannelMetaDataDAO.ChannelInformation>> getChannels()

Returns the meta-data for all channels. The information is returned in no particular order. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Returns:

general meta-data for all channels exposed through a future. In case of failure, the future's get() method will throw an exception.

getChannelsByServer

ListenableFuture<? extends Iterable<ChannelMetaDataDAO.ChannelConfiguration>> getChannelsByServer(UUID serverId)

Returns the configuration for all channels belonging to the specified server. The configuration is the meta-data associated with the channel that is needed by a server when initializing the channel. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

serverId - ID of the server for which the channels shall be retrieved.

Returns:

configuration for all channels belonging to the specified server, exposed through a future. In case of failure, the future's get() method will throw an exception.

getPendingChannelOperation

ListenableFuture<ChannelMetaDataDAO.ChannelOperation> getPendingChannelOperation(UUID serverId,
                                                                                 String channelName)

Returns the pending channel operation for the specified server and channel. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

channelName - name of the channel affected by the operation.

Returns:

pending channel operation for the specified server and channel exposed through a future. If no such operation has been stored (or it has already been deleted), the future's get method returns null. In case of failure, the future's get() method will throw an exception.

getPendingChannelOperations

ListenableFuture<? extends Iterable<ChannelMetaDataDAO.ChannelOperation>> getPendingChannelOperations(UUID serverId)

Returns all pending channel operations for the specified server. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

Returns:

all pending channel operations for the specified server exposed through a future. In case of failure, the future's get() method will throw an exception.

getSampleBuckets

ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>> getSampleBuckets(String channelName)

Returns the meta data for all sample buckets for the specified channel and all decimation levels. No particular order is guaranteed. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

channelName - name identifying the channel for which all sample buckets shall be returned.

Returns:

meta-data for all sample buckets for the specified channel and all decimation levels exposed through a future. In case of failure, the future's get() method will throw an exception.

getSampleBuckets

ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>> getSampleBuckets(String channelName,
                                                                                                                                       int decimationLevel)

Returns the meta data for all sample buckets for the specified channel and decimation level. The sample buckets are sorted by their start time in ascending order. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

channelName - name identifying the channel for which the sample buckets shall be returned.

decimationLevel - decimation level for which the sample buckets shall be returned. A decimation level is identified by the number of seconds between two samples. All decimation levels except the zero decimation level, which stores raw data, have fixed periods between samples.

Returns:

meta-data for all sample buckets for the specified channel and decimation level exposed through a future. In case of failure, the future's get() method will throw an exception.

getSampleBucketsInInterval

ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>> getSampleBucketsInInterval(String channelName,
                                                                                                                                                 int decimationLevel,
                                                                                                                                                 long startTimeGreaterThanOrEqualTo,
                                                                                                                                                 long startTimeLessThanOrEqualTo)

Returns the meta data for the sample buckets for the specified channel and decimation level which are in the specified interval. Only those sample buckets that have a start time that is in the specified interval are returned. The sample buckets are sorted by their start time in ascending order. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

channelName - name identifying the channel for which the sample buckets shall be returned.

decimationLevel - decimation level for which the sample buckets shall be returned. A decimation level is identified by the number of seconds between two samples. All decimation levels except the zero decimation level, which stores raw data, have fixed periods between samples.

startTimeGreaterThanOrEqualTo - lower limit for the start time (inclusive).

startTimeLessThanOrEqualTo - upper limit for the start time (inclusive).

Returns:

meta-data for the sample buckets for the specified channel, decimation level, and interval exposed through a future. In case of failure, the future's get() method will throw an exception.

getSampleBucketsInReverseOrder

ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>> getSampleBucketsInReverseOrder(String channelName,
                                                                                                                                                     int decimationLevel,
                                                                                                                                                     int limit)

Returns the meta data for all sample buckets for the specified channel and decimation level up to the specified limit. The sample buckets are sorted by their start time in descending order. At maximum, the specified number of sample buckets is returned. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

channelName - name identifying the channel for which the sample buckets shall be returned.

decimationLevel - decimation level for which the sample buckets shall be returned. A decimation level is identified by the number of seconds between two samples. All decimation levels except the zero decimation level, which stores raw data, have fixed periods between samples.

limit - maximum number of sample buckets which should be included in the result. If there are more buckets, only the first limit buckets are returned.

Returns:

meta-data for all sample buckets for the specified channel and decimation level exposed through a future. In case of failure, the future's get() method will throw an exception.

getSampleBucketsNewerThan

ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>> getSampleBucketsNewerThan(String channelName,
                                                                                                                                                int decimationLevel,
                                                                                                                                                long startTimeGreaterThanOrEqualTo,
                                                                                                                                                int limit)

Returns the meta data for the sample buckets for the specified channel and decimation level which have a start time later than the specified time. At maximum, the specified number of sample buckets is returned. The sample buckets are sorted by their start time in ascending order. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

channelName - name identifying the channel for which the sample buckets shall be returned.

decimationLevel - decimation level for which the sample buckets shall be returned. A decimation level is identified by the number of seconds between two samples. All decimation levels except the zero decimation level, which stores raw data, have fixed periods between samples.

startTimeGreaterThanOrEqualTo - lower limit for the start time (inclusive).

limit - maximum number of sample buckets which should be included in the result. If there are more buckets, only the first limit buckets are returned.

Returns:

meta-data for the sample buckets for the specified channel, decimation level, and interval exposed through a future. In case of failure, the future's get() method will throw an exception.

getSampleBucketsOlderThanInReverseOrder

ListenableFuture<com.aquenos.cassandra.pvarchiver.common.ObjectResultSet<ChannelMetaDataDAO.SampleBucketInformation>> getSampleBucketsOlderThanInReverseOrder(String channelName,
                                                                                                                                                              int decimationLevel,
                                                                                                                                                              long startTimeLessThanOrEqualTo,
                                                                                                                                                              int limit)

Returns the meta data for the sample buckets for the specified channel and decimation level which have a start time before the specified time. At maximum, the specified number of sample buckets is returned. The sample buckets are sorted by their start time in descending order. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

The iterable returned by the future is only safe for iterating once. Subsequent requests to create an iterator might result in the new iterator only returning the elements that have not been returned by a previously created iterator yet. Besides, the iterator might block while iterating, waiting for additional elements to arrive from the network.

Parameters:

channelName - name identifying the channel for which the sample buckets shall be returned.

decimationLevel - decimation level for which the sample buckets shall be returned. A decimation level is identified by the number of seconds between two samples. All decimation levels except the zero decimation level, which stores raw data, have fixed periods between samples.

startTimeLessThanOrEqualTo - upper limit for the start time.

limit - maximum number of sample buckets which should be included in the result. If there are more buckets, only the first limit buckets are returned.

Returns:

meta-data for the sample buckets for the specified channel, decimation level, and interval exposed through a future. In case of failure, the future's get() method will throw an exception.

moveChannel

ListenableFuture<Void> moveChannel(String channelName,
                                   UUID oldServerId,
                                   UUID newServerId)

Moves a channel from one server to another. The channel must exist and be associated with the specified server before calling this method. Calling this method for a channel that does not exists yet or is associated with a different server results in undefined behavior. The calling code has to ensure that these preconditions are met and no other attempts to modify the channel are made concurrently. This operation does not affect any pending channel operations stored for the specified channel. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

oldServerId - ID of the server which is currently responsible for the channel.

newServerId - ID of the server which is supposed to be responsible for the channel after the move operation finishes.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

renameChannel

ListenableFuture<Void> renameChannel(String oldChannelName,
                                     String newChannelName,
                                     UUID serverId)

Changes the name of a channel. This effectively copies all meta-data for the channel (and its sample buckets) and removes the data for the old name. This operation is not atomic. This means that the calling code has to ensure that no concurrent modifications are made to the channel (including the creation or deletion of sample buckets) under both its old and new name. If no channel with the specified old name exists or if a channel with the specified new name already exists, the behavior is undefined. This operation does not affect any pending channel operations stored for the specified channel. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

oldChannelName - old name identifying the existing channel.

newChannelName - new name that identifies the channel after the rename operation finishes.

serverId - ID of the server responsible for the channel.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

updateChannelConfiguration

ListenableFuture<Void> updateChannelConfiguration(String channelName,
                                                  UUID serverId,
                                                  Map<Integer,Integer> decimationLevelToRetentionPeriod,
                                                  boolean enabled,
                                                  Map<String,String> options)

Updates the configuration for a channel. The calling code has to ensure that the specified channel exists and is associated with the specified server. Otherwise, the behavior of this method is undefined. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Parameters:

channelName - name identifying the channel.

serverId - ID of the server responsible for the channel.

decimationLevelToRetentionPeriod - map that contains the retention periods of the decimation levels that shall be updated. The decimation levels are used as keys and the corresponding retention periods (in seconds) are stored as values. A retention period that is zero or negative means that samples for the corresponding decimation level are supposed to be retained forever. This map may only contain the retention level for decimation periods that have been created previously. If it contains information for a decimation level that does not exist, the behavior is undefined. However, if this map does not contain information for an existing decimation level, the retention period of this decimation level is simply not changed.

enabled - true if archiving shall be enabled for the channel, false if it shall be disabled.

options - control-system specific configuration options for the channel. The map may not contain null keys or values.

Returns:

future that can be used to check whether this operation finished and whether it was successful. In case of failure, the future's get() method will throw an exception.

updatePendingChannelOperation

ListenableFuture<Pair<Boolean,UUID>> updatePendingChannelOperation(UUID serverId,
                                                                   String channelName,
                                                                   UUID oldOperationId,
                                                                   UUID newOperationId,
                                                                   String newOperationType,
                                                                   String newOperationData,
                                                                   int ttl)

Updates an existing pending channel operation, replacing it with the specified information. If there is no pending channel operation matching the specified server, channel, and operation ID, no data is modified. Instead, this method returns the ID of the channel operation stored for the specified server and channel (if any). This check is guaranteed to be implemented in an atomic way, even across servers. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

Please refer to updatePendingChannelOperationRelaxed(UUID, String, UUID, UUID, String, String, int) for a version of this method that is more resilient in case of a write timeout.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

channelName - name of the channel affected by the operation.

oldOperationId - ID of the operation that shall be replaced with the specified new information. The replacement is only made if the ID of the stored operation matched the specified ID.

newOperationId - ID of the operation that shall replace the stored operation. This may (but does not have to) be the same ID as the one of the old (previously stored) operation.

newOperationType - type of the new operation. The type also defines the expected format of the data passed as newOperationData (if any). However, the interpretation of both the type and the data is left to the code using this DAO.

newOperationData - data associated with the new operation. The format of the data typically depends on the newOperationType. May be null.

ttl - time-to-live of the record (in seconds). The record is automatically deleted after the specified amount of seconds. This means that after this period of time, calls to getPendingChannelOperation(UUID, String) and getPendingChannelOperations(UUID) will not return the channel operation any longer.

Returns:

pair of a boolean and a channel operation ID exposed through a future. The boolean is true if and only if the channel operation was successfully updated with the specified information. If the ID of the operation stored for the server and channel was different from the specified ID, the boolean is false and the ID of the already stored operation is returned as part of the pair. If there was no operation stored for the specified server and channel, the boolean is false, but there is no channel operation ID in the pair (the corresponding field is null).

updatePendingChannelOperationRelaxed

ListenableFuture<Pair<Boolean,UUID>> updatePendingChannelOperationRelaxed(UUID serverId,
                                                                          String channelName,
                                                                          UUID oldOperationId,
                                                                          UUID newOperationId,
                                                                          String newOperationType,
                                                                          String newOperationData,
                                                                          int ttl)

Updates an existing pending channel operation in a more relaxed way. If there is no pending channel operation matching the specified server, channel, and operation ID, no data is modified. Instead, this method returns the ID of the channel operation stored for the specified server and channel (if any). This check is guaranteed to be implemented in an atomic way, even across servers. The operation is performed in an asynchronous way so that it will not block for network communication. The result of the operation can be checked through the returned future.

In contrast to the updatePendingChannelOperation(UUID, String, UUID, UUID, String, String, int) method, this method does not fail directly in case of a write timeout. Instead, it checks whether a pending operation with specified updated data is present in the database and succeeds if it is. However, this has the effect that it is not strictly guaranteed that the record in the database has actually been updated by the caller. The method will also report success if another caller (possibly in a different server process) has created or update the record specifying exactly the same data. When using a newly generated UUID as the newOperationId or a UUID that is only used by the calling thread, such an event is very unlikely.

Parameters:

serverId - ID of the server that is affected by the operation. This most often is (but does not have to be) the server responsible for the affected channel.

channelName - name of the channel affected by the operation.

oldOperationId - ID of the operation that shall be replaced with the specified new information. The replacement is only made if the ID of the stored operation matched the specified ID.

newOperationId - ID of the operation that shall replace the stored operation. This may (but does not have to) be the same ID as the one of the old (previously stored) operation.

newOperationType - type of the new operation. The type also defines the expected format of the data passed as newOperationData (if any). However, the interpretation of both the type and the data is left to the code using this DAO.

newOperationData - data associated with the new operation. The format of the data typically depends on the newOperationType. May be null.

ttl - time-to-live of the record (in seconds). The record is automatically deleted after the specified amount of seconds. This means that after this period of time, calls to getPendingChannelOperation(UUID, String) and getPendingChannelOperations(UUID) will not return the channel operation any longer.

Returns:

pair of a boolean and a channel operation ID exposed through a future. The boolean is true if the channel operation was successfully updated with the specified information. The boolean might also be true if a channel operation specifying exactly the same data (new operation ID, type, and data) has been created before and is thus already present in the database. If the ID of the operation stored for the server and channel was different from the specified ID, the boolean is false and the ID of the already stored operation is returned as part of the pair. If there was no operation stored for the specified server and channel, the boolean is false, but there is no channel operation ID in the pair (the corresponding field is null).