com.aquenos.cassandra.pvarchiver.server.archiving

Class ArchiveConfigurationService

java.lang.Object

com.aquenos.cassandra.pvarchiver.server.archiving.ArchiveConfigurationService

All Implemented Interfaces:

DisposableBean, InitializingBean

public class ArchiveConfigurationService
extends Object
implements DisposableBean, InitializingBean

Service providing access to the archive configuration. Updates of the configuration must be performed through this service. This service takes care of ensuring that updates are performed in a safe way, taking measures to avoid concurrent operations in the cluster to interfere with each other.

Author:

Sebastian Marsching

Field Summary

Fields

Modifier and Type	Field and Description
protected org.apache.commons.logging.Log	log Logger for this class.

Constructor Summary

Constructors

Constructor and Description
ArchiveConfigurationService()

Method Summary

Modifier and Type	Method and Description
ListenableFuture<Void>	addChannel(UUID serverId, String channelName, String controlSystemType, Set<Integer> decimationLevels, Map<Integer,Integer> decimationLevelToRetentionPeriod, boolean enabled, Map<String,String> options) Adds a channel to the archive configuration.
ListenableFuture<Void>	addOrUpdateChannel(UUID serverId, String channelName, String controlSystemType, Set<Integer> decimationLevels, Map<Integer,Integer> decimationLevelToRetentionPeriod, boolean enabled, Map<String,String> options) Adds a channel to the archive configuration or updates the channel's configuration if it already exists.
void	afterPropertiesSet()
void	destroy()
ListenableFuture<Void>	moveChannel(UUID expectedOldServerId, UUID newServerId, String channelName) Moves a channel from one server to another one.
ListenableFuture<Void>	refreshChannel(UUID serverId, String channelName) Refreshes the channel on the specified server.
ListenableFuture<Void>	removeChannel(UUID expectedServerId, String channelName) Removes a channel from the archive configuration.
ListenableFuture<Void>	renameChannel(UUID expectedServerId, String oldChannelName, String newChannelName) Removes a channel from the archive configuration.
ListenableFuture<List<ArchiveConfigurationCommandResult>>	runConfigurationCommands(Iterable<? extends ArchiveConfigurationCommand> commands) Runs the specified configuration commands.
void	setArchivingService(ArchivingService archivingService) Sets the archiving service.
void	setCassandraProvider(CassandraProvider cassandraProvider) Sets the Cassandra provider that provides access to the Apache Cassandra database.
void	setChannelInformationCache(ChannelInformationCache channelInformationCache) Sets the channel information cache.
void	setChannelMetaDataDAO(ChannelMetaDataDAO channelMetaDataDAO) Sets the DAO for reading and modifying meta-data related to channels.
void	setClusterManagementService(ClusterManagementService clusterManagementService) Sets the cluster management service.
void	setControlSystemSupportRegistry(ControlSystemSupportRegistry controlSystemSupportRegistry) Sets the control-system support registry.
void	setInterNodeCommunicationService(InterNodeCommunicationService interNodeCommunicationService) Sets the inter-node communication service.
void	setMaxConcurrentArchiveConfigurationCommands(int maxConcurrentArchiveConfigurationCommands) Sets the maximum number of archive-configuration commands that are processed in parallel.
void	setServerProperties(ServerProperties serverProperties) Sets the server-specific configuration properties.
ListenableFuture<Void>	updateChannel(UUID expectedServerId, String channelName, String expectedControlSystemType, Set<Integer> decimationLevels, Set<Integer> addDecimationLevels, Set<Integer> removeDecimationLevels, Map<Integer,Integer> decimationLevelToRetentionPeriod, Boolean enabled, Map<String,String> options, Map<String,String> addOptions, Set<String> removeOptions) Updates a channel's configuration.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected final org.apache.commons.logging.Log log

Logger for this class.

Constructor Detail

ArchiveConfigurationService

public ArchiveConfigurationService()

Method Detail

setArchivingService

@Autowired
public void setArchivingService(ArchivingService archivingService)

Sets the archiving service. The reference to the archive service is used to make sure that a channel is refreshed (its configuration is reloaded), when needed. Typically, this method is called automatically by the Spring container.

Parameters:

archivingService - archiving service for this server.

setCassandraProvider

@Autowired
public void setCassandraProvider(CassandraProvider cassandraProvider)

Sets the Cassandra provider that provides access to the Apache Cassandra database. Typically, this method is called automatically by the Spring container.

Parameters:

cassandraProvider - provider that provides a connection to the Apache Cassandra database.

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 and modifying 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.

setClusterManagementService

@Autowired
public void setClusterManagementService(ClusterManagementService clusterManagementService)

Sets the cluster management service. The cluster management service is used to get information about the cluster status. In particular, it is needed to determine the online state of servers in the cluster. Typically, this method is called automatically by the Spring container.

Parameters:

clusterManagementService - cluster manager used by the archiving server.

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.

setInterNodeCommunicationService

@Autowired
public void setInterNodeCommunicationService(InterNodeCommunicationService interNodeCommunicationService)

Sets the inter-node communication service. The inter-node communication service is needed to communicate with other servers in the cluster when updating the archive configuration.

Parameters:

interNodeCommunicationService - inter-node communication service.

setMaxConcurrentArchiveConfigurationCommands

public void setMaxConcurrentArchiveConfigurationCommands(int maxConcurrentArchiveConfigurationCommands)

Sets the maximum number of archive-configuration commands that are processed in parallel.

When many configuration commands are submitted at the same time (e.g. through the runConfigurationCommands(Iterable) method), running all these commands concurrently might not make sense because it would put a lot of load on the database, slowing it down too a point where the processing of each command takes so long that it fails with a timeout. By limiting the number of commands that are run concurrently, this can be avoided. When the limit set through this method is reached, further commands that are submitted are queued until the processing of other commands has completed. This effectively means, that at most the specified number of configuration commands is processed in parallel.

When this object is configured to use a ThrottlingCassandraProvider, this limit should be set to about four times the limit this provider has for concurrent write statements.

The default value of this setting is 64.

Parameters:

maxConcurrentArchiveConfigurationCommands - maximum number of archive-configuration commands that are processed in parallel. Must be greater than zero.

Throws:

IllegalArgumentException - if a value less than one is specified.

setServerProperties

@Autowired
public void setServerProperties(ServerProperties serverProperties)

Sets the server-specific configuration properties. These server properties are used to get the ID of this archiving server.

Parameters:

serverProperties - configuration properties used by this server.

afterPropertiesSet

public void afterPropertiesSet()
                        throws Exception

Specified by:

afterPropertiesSet in interface InitializingBean

Throws:

Exception

destroy

public void destroy()
             throws Exception

Specified by:

destroy in interface DisposableBean

Throws:

Exception

addChannel

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

Adds a channel to the archive configuration. In general, the runConfigurationCommands(Iterable) method, passing an instance of AddChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be added.

The future returned by this method might throw the following exceptions:

• ChannelAlreadyExistsException if channelName is already in use.
• IllegalArgumentException if channelName is empty or decimationLevels contains negative elements.
• NullPointerException if channelName, controlSystemType, or serverId is null or decimationLevels, decimationLevelToRetentionPeriod, or options contains null keys or values.
• PendingChannelOperationException if another operation for the specified channel is pending and thus the add operation cannot be performed.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database).

Parameters:

serverId - ID of the server to which the channel shall be added.

channelName - name of the channel to be added.

controlSystemType - string identifying the control-system support that is used for the channel.

decimationLevels - set of decimation levels that shall be created for the channel. The number identifying a decimation level represents the period between two samples (in seconds). The decimation level zero (for raw samples) is always created, even if it is not contained in the specified set. If null, only the decimation level zero is created.

decimationLevelToRetentionPeriod - map containing the mapping of decimation levels to the corresponding retention period (both in seconds). If an entry for a decimation level is missing, a retention period of zero (keep samples indefinitely) is assumed. Negative retention periods are silently converted to zero. A null reference has the same effect as an empty map (use a retention period of zero for all decimation levels).

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

options - map storing the control-system specific options for the channel. A null reference has the same effect as an empty map.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.

addOrUpdateChannel

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

Adds a channel to the archive configuration or updates the channel's configuration if it already exists. This method is very similar to addChannel(UUID, String, String, Set, Map, boolean, Map), but its future will never throw a ChannelAlreadyExistsException. In general, the runConfigurationCommands(Iterable) method, passing an instance of AddOrUpdateChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be added or updated.

The future returned by this method might throw the following exceptions:

• IllegalArgumentException if channelName is empty, decimationLevels contains negative elements, or the channel exists and the specified serverId or controlSystemType do not match the ones of the existing channel.
• NullPointerException if channelName, controlSystemType, or serverId is null or decimationLevels, decimationLevelToRetentionPeriod, or options contains null keys or values.
• PendingChannelOperationException if another operation for the specified channel is pending and thus the add-or-update operation cannot be performed.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database).

Parameters:

serverId - ID of the server to which the channel shall be added. If the channel already exists and the server ID does not match the one of existing channel, the operation will fail.

channelName - name of the channel to be added or updated.

controlSystemType - string identifying the control-system support that is used for the channel. If the channel already exists and the specified control-system type does not match the one of the existing channel, the operation will fail.

decimationLevels - set of decimation levels that shall be created for the channel. If the channel already exists, decimation levels that currently exist but are not listed in this set are deleted. The number identifying a decimation level represents the period between two samples (in seconds). The decimation level zero (for raw samples) is always created, even if it is not contained in the specified set. If null, only the decimation level zero is created.

decimationLevelToRetentionPeriod - map containing the mapping of decimation levels to the corresponding retention period (both in seconds). If an entry for a decimation level is missing, a retention period of zero (keep samples indefinitely) is assumed. Negative retention periods are silently converted to zero. A null reference has the same effect as an empty map (use a retention period of zero for all decimation levels).

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

options - map storing the control-system specific options for the channel. A null reference has the same effect as an empty map.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.

moveChannel

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

Moves a channel from one server to another one. In general, the runConfigurationCommands(Iterable) method, passing an instance of MoveChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be moved.

The future returned by this method might throw the following exceptions:

• IllegalArgumentException if channelName is empty or the channel is not currently registered with the server identified by expectedOldServerId.
• NoSuchChannelException if channelName does not refer to an existing channel.
• NullPointerException if channelName or newServerId is null.
• PendingChannelOperationException if another operation for the specified channel is pending and thus the move operation cannot be performed.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database).

Parameters:

expectedOldServerId - if not null, the channel is only moved if it is currently registered with the specified server.

newServerId - ID of the server to which the channel shall be moved.

channelName - name identifying the channel to be moved.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.

refreshChannel

public ListenableFuture<Void> refreshChannel(UUID serverId,
                                             String channelName)

Refreshes the channel on the specified server. Refreshing a channel results in the channel to be stopped, the channel configuration being reloaded, and the channel being started again.

In general, the runConfigurationCommands(Iterable) method, passing an instance of RefreshChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be refreshed.

The future returned by this method might throw the following exceptions:

• IllegalArgumentException if channelName is empty.
• NullPointerException if channelName or serverId is null.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database or communicating with remote servers).

Parameters:

serverId - ID of the server on which the channel should be refreshed. That does not have to be the server that owns the channel. For example, after moving a channel it might still exist on the old server and refreshing will have the effect of removing it from the configuration set. If a channel is not in a servers current configuration set and the channel is not owned by the server, the server will not continue after loading the channel configuration, effectively making the refresh a no-op.

channelName - name of the channel to be refreshed.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.

removeChannel

public ListenableFuture<Void> removeChannel(UUID expectedServerId,
                                            String channelName)

Removes a channel from the archive configuration. In general, the runConfigurationCommands(Iterable) method, passing an instance of RemoveChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be removed.

The future returned by this method might throw the following exceptions:

• IllegalArgumentException if channelName is empty or the channel is not currently registered with the server identified by expectedServerId.
• NoSuchChannelException if channelName does not refer to an existing channel.
• NullPointerException if channelName is null.
• PendingChannelOperationException if another operation for the specified channel is pending and thus the remove operation cannot be performed.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database).

Parameters:

expectedServerId - if not null, the channel is only removed if it is currently registered with the specified server.

channelName - name identifying the channel to be removed.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.

renameChannel

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

Removes a channel from the archive configuration. In general, the runConfigurationCommands(Iterable) method, passing an instance of RenameChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be renamed.

The future returned by this method might throw the following exceptions:

• ChannelAlreadyExistsException if newChannelName is already in use.
• IllegalArgumentException if oldChannelName or newChannelName is empty or the channel is not currently registered with the server identified by expectedServerId.
• NoSuchChannelException if oldChannelName does not refer to an existing channel.
• NullPointerException if oldChannelName or newChannelName is null.
• PendingChannelOperationException if another operation for the specified channel is pending and thus the rename operation cannot be performed.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database).

Parameters:

expectedServerId - if not null, the channel is only renamed if it is currently registered with the specified server.

oldChannelName - old name of the channel that shall be renamed.

newChannelName - new name of the channel that shall be renamed.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.

runConfigurationCommands

public ListenableFuture<List<ArchiveConfigurationCommandResult>> runConfigurationCommands(Iterable<? extends ArchiveConfigurationCommand> commands)

Runs the specified configuration commands. Basically, this method provides the same functions as the addChannel(UUID, String, String, Set, Map, boolean, Map), addOrUpdateChannel(UUID, String, String, Set, Map, boolean, Map) , moveChannel(UUID, UUID, String), removeChannel(UUID, String), renameChannel(UUID, String, String), and updateChannel(UUID, String, String, Set, Set, Set, Map, Boolean, Map, Map, Set) methods. However, it aggregates operations that require communication with other servers in a way that reduces the number of network requests. Therefore, it should be preferred over the aforementioned methods when multiple operations shall be performed.

The future returned by this method only throws an exception if a problem that affects all of the commands is detected. Problems with individual commands results in a ArchiveConfigurationCommandResult that indicates failure for the respective command. The future returned by this method might throw the following exceptions:

• NullPointerException if commands is null or contains null elements.
• RuntimeException if an unexpected error occurs that affects all commands (e.g. problems when accessing the database).

The list returned by the future returned by this method contains the results for the configuration commands in the same or in which the command were passed to this method.

Parameters:

commands - commands to be executed.

Returns:

future that completes when all operation triggered by the commands have finished. If the one of the operation fails, the corresponding ArchiveConfigurationCommandResult will indicate failure. If a problem prevents the execution of all of the commands, the future might throw an exception.

updateChannel

public ListenableFuture<Void> updateChannel(UUID expectedServerId,
                                            String channelName,
                                            String expectedControlSystemType,
                                            Set<Integer> decimationLevels,
                                            Set<Integer> addDecimationLevels,
                                            Set<Integer> removeDecimationLevels,
                                            Map<Integer,Integer> decimationLevelToRetentionPeriod,
                                            Boolean enabled,
                                            Map<String,String> options,
                                            Map<String,String> addOptions,
                                            Set<String> removeOptions)

Updates a channel's configuration. In general, the runConfigurationCommands(Iterable) method, passing an instance of UpdateChannelCommand, should be preferred over this method because it provides better performance when making configuration changes that affect different servers. However, this method can be used for convenience if only a single channel is to be changed.

The future returned by this method might throw the following exceptions:

• IllegalArgumentException if channelName is empty, decimationLevels contains negative elements, expectedServerId specifies a different server than the one with which the channel is currently registered, or expectedControlSystemType, different from the control-system type of the existing channel, or if a constraint of the UpdateChannelCommand(...). constructor is violated. This exception is also thrown when the requested update would violate the constraint that each decimation level must have a retention period that is equal to or greater than the retention period of the preceding (shorter decimation period) level.
• NoSuchChannelException if channelName does not refer to an existing channel.
• NullPointerException if channelName is null or any of the sets or maps contains null keys or values.
• PendingChannelOperationException if another operation for the specified channel is pending and thus the update operation cannot be performed.
• RuntimeException if an unexpected error occurs (e.g. problems when accessing the database).

This method passes all its parameters to the constructor of the UpdateChannelCommand and then runs this command. Therefore, the future returned by this method will throw any exception thrown by the constructor of the UpdateChannelCommand or thrown when running the command.

Parameters:

expectedServerId - if not null, the update operation will fail if the channel is currently registered with a different server than the specified one.

channelName - name of the channel to be updated.

expectedControlSystemType - if not null, the update operation will fail if the channel's actual control-system type is different.

decimationLevels - set of decimation levels that shall exist for the channel after the update. May only be specified if both addDecimationLevels and removeDecimationLevels are null.

addDecimationLevels - set of decimation levels to be added. May only be specified if decimationLevels is null.

removeDecimationLevels - set of decimation levels to be removed. May only be specified if decimationLevels is null.

decimationLevelToRetentionPeriod - map mapping decimation levels to their respective retention period. Decimation levels specified in this map will have their retention periods updated with the specified values. However, decimation levels not explicitly specified in this map might also have their retention period reset to zero. Refer to the description of UpdateChannelCommand.getDecimationLevelToRetentionPeriod() for details.

enabled - whether archiving for the channel shall be enabled or disabled.

options - control-system-specific configuration options. May only be specified if both addOptions and removeOptions are null.

addOptions - control-system-specific configuration options to be added. May only be specified if options is null .

removeOptions - control-system-specific configuration options to be removed. May only be specified if options is null.

Returns:

future that completes when the operation has finished. If the operation fails, the future will throw an exception.