com.aquenos.cassandra.pvarchiver.server.archiving

Class UpdateChannelCommand

java.lang.Object

com.aquenos.cassandra.pvarchiver.server.archiving.ArchiveConfigurationCommand

com.aquenos.cassandra.pvarchiver.server.archiving.UpdateChannelCommand

public final class UpdateChannelCommand
extends ArchiveConfigurationCommand

Command for updating a channel. Updating a channel results in the channel's configuration to be changed according to the requested update and the channel being refreshed with the new configuration. This command object contains all data that is needed for the remove operation. Typically, it is passed to the ArchiveConfigurationService, but it might also be sent over the network before actually being processed.

Author:

Sebastian Marsching

Nested Class Summary

Nested classes/interfaces inherited from class com.aquenos.cassandra.pvarchiver.server.archiving.ArchiveConfigurationCommand

ArchiveConfigurationCommand.Type

Constructor Summary

Constructors

Constructor and Description
UpdateChannelCommand(String channelName, String expectedControlSystemType, UUID expectedServerId, 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) Creates an "update channel" command.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj)
Set<Integer>	getAddDecimationLevels() Returns the set of decimation levels to be added.
Map<String,String>	getAddOptions() Returns the map of control-system-specific configuration options to be added.
String	getChannelName() Returns the name of the channel that shall be updated.
ArchiveConfigurationCommand.Type	getCommandType() Returns the type of the actual command type.
Set<Integer>	getDecimationLevels() Returns the set of decimation levels that shall exist for the channel after the update.
Map<Integer,Integer>	getDecimationLevelToRetentionPeriod() Returns the map mapping decimation levels to their respective retention period.
Boolean	getEnabled() Tells whether archiving for the channel shall be enabled or disabled.
String	getExpectedControlSystemType() Returns the expected control-system type of the channel.
UUID	getExpectedServerId() Returns the ID of the server which is expected to currently own the channel.
Map<String,String>	getOptions() Returns the control-system-specific configuration options for the channel.
Set<Integer>	getRemoveDecimationLevels() Returns the set of decimation levels to be removed.
Set<String>	getRemoveOptions() Returns the set of control-system-specific configuration options to be removed.
int	hashCode()
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

UpdateChannelCommand

public UpdateChannelCommand(String channelName,
                            String expectedControlSystemType,
                            UUID expectedServerId,
                            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)

Creates an "update channel" command. If the specified expectedServerId does not match the actual ID of the server that currently owns the channel or if expectedControlSystemType does not match the actual control-system type of the channel, the operation will fail.

The changes that should be made by the update can be described in a differential fashions: If a part of the configuration is not supposed to be modified, null can be passed for the respective argument to this constructor.

The set of decimation levels that shall be added and removed can be described in an explicit or in a differential fashion. For an explicit description, use the decimationLevels argument. For a differential description, use the addDecimationLevels and removeDecimationLevels arguments. Only one of the two ways to describe the change can be used at the same time. Setting both decimationLevels and either or both of addDecimationLevels and removeDecimationLevels results in an IllegalArgumentException.

If decimation levels are listed in decimationLevels or addDecimationLevels, but do not have a corresponding entry in decimationLevelToRetentionPeriod, a retention period of zero is assumed for these decimation levels, even if they already exist with a different retention period.

Like the decimation levels, the control-system-specific configuration options can also be described in an explicit or in a differential fashion. For an explicit description, use the options argument. For a differential description, use the addOptions and removeOptions arguments. Only one of the two ways to describe the change can be used at the same time. Setting both options and either or both of addOptions and removeOptions results in an IllegalArgumentException .

As a general rule, none of the maps and sets may contain null keys or values. Such an entry results in a NullPointerException.

Decimation levels may not be negative. Negative decimation levels result in an IllegalArgumentException. Negative retention periods are allowed but are silently converted to a retention period of zero.

A decimation level or control-system-specific configuration option cannot be added and removed at the same time. Any attempt to do so results in an IllegalArgumentException.

The entries in the decimationLevelToRetentionPeriod map must match the constraint that the retention period of each decimation level is greater than or equal to the retention period of the preceding decimation level (that is the decimation level with the next smaller decimation period). A violation of this constraint (for a decimation level that is not going to be removed anyway) will result in an IllegalArgumentException being thrown. However, this check cannot strictly guarantee that the whole retention-period configuration is valid unless decimationLevels is not null. If it is null existing retention period configurations that might be merged with the specified configuration could lead to a violation of the constraint. Such a violation will only be detected later when the command is actually executed, leading to an IllegalArgumentException being thrown then.

Parameters:

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.

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

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 getDecimationLevelToRetentionPeriod() for details. Negative retention periods are silently converted to zero. This map must not contain negative keys. It must also not contain a mapping that violates the constraint that each decimation period must have a retention period equal to or greater than the one of the preceding (next smaller decimation period) decimation level.

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.

Throws:

IllegalArgumentException - if channelName is the empty string or any of the constraints described earlier are violated.

NullPointerException - if channelName is null or any of the argument maps and sets contains null keys or values.

Method Detail

getCommandType

public ArchiveConfigurationCommand.Type getCommandType()

Description copied from class: ArchiveConfigurationCommand

Returns the type of the actual command type. Please refer to the document in the ArchiveConfigurationCommand class or the ArchiveConfigurationCommand.Type enum for a list of types. The return value is never null .

Specified by:

getCommandType in class ArchiveConfigurationCommand

Returns:

type of this command.

getChannelName

public String getChannelName()

Returns the name of the channel that shall be updated. The value returned is never null or the empty string.

Returns:

name of the channel to be updated.

getExpectedControlSystemType

public String getExpectedControlSystemType()

Returns the expected control-system type of the channel. If null, the channel will be updated regardless of its current control-system type. If not null, the update operation will fail if the channel's actual control-system type is different.

Returns:

expected control-system type of the channel to be updated.

getExpectedServerId

public UUID getExpectedServerId()

Returns the ID of the server which is expected to currently own the channel. If null the channel will be updated regardless of which server currently owns the channel. If not null, the update operation will fail if the channel is currently registered with a different server than the specified one.

Returns:

ID of the server that is expected to currently own the channel or null if the channel should be updated regardless of the server that currently owns the channel.

getDecimationLevels

public Set<Integer> getDecimationLevels()

Returns the set of decimation levels that shall exist for the channel after the update. Each decimation level is identified by the period between two consecutive samples (in seconds). The decimation level storing raw samples is represented by a period of zero. As the decimation level for raw samples must always exist, the returned set always contains the zero element.

Decimation levels in the returned set that currently do not exist will be added when the update operation is performed. Decimation levels that currently exist but are not in the set are removed respectively.

If the returned set is null, the set of decimation levels is either not supposed to be changed or the changes are described in a differential fashion through the sets returned by getAddDecimationLevels() and getRemoveDecimationLevels(). If this method does not return null, getAddDecimationLevels() and getRemoveDecimationLevels() both return null.

The returned set does never contain null or negative elements. It is never empty, but the return value itself might be null.

Returns:

set describing the decimation levels that shall exist for the channel after the update or null if the set of decimation levels is not supposed to be changed or the change is describe in a differential fashion.

See Also:

getAddDecimationLevels(), getRemoveDecimationLevels()

getAddDecimationLevels

public Set<Integer> getAddDecimationLevels()

Returns the set of decimation levels to be added. Each decimation level is identified by the period between two consecutive samples (in seconds). The decimation level storing raw samples is represented by a period of zero. As the decimation level for raw samples must always exist, the returned set never contains the zero element.

If a decimation level specified in this set already exists before the update operation, the update operation will only change the decimation level's retention period according to the value in the map returned by getDecimationLevelToRetentionPeriod(). That map will always contain an entry for each decimation level that is contained in the set returned by this method. If not specified explicitly, the retention period will be zero.

If the returned set is null, the set of decimation levels is either not supposed to be changed or the changes are described in an explicit fashion through the set returned by getDecimationLevels(). If this method does not return null, getRemoveDecimationLevels() does not return null either and getDecimationLevels() returns null. If this method returns null, getRemoveDecimationLevels() also returns null.

The returned set does never contain null or negative elements. However, the set may be empty and the return value itself might be null. The set never contains a decimation level that is also contained in the set returned by getRemoveDecimationLevels().

Returns:

set of decimation levels that shall be added for the channel or null if the set of decimation levels is not supposed to be changed or the change is described in an explicit fashion.

See Also:

getDecimationLevels(), getRemoveDecimationLevels()

getRemoveDecimationLevels

public Set<Integer> getRemoveDecimationLevels()

Returns the set of decimation levels to be removed. Each decimation level is identified by the period between two consecutive samples (in seconds). The decimation level storing raw samples is represented by a period of zero. As the decimation level for raw samples must always exist, the returned set never contains the zero element.

If a decimation level specified in this set does not exist before the update operation, the update operation will simply skip the element.

If the returned set is null, the set of decimation levels is either not supposed to be changed or the changes are described in an explicit fashion through the set returned by getDecimationLevels(). If this method does not return null, getAddDecimationLevels() does not return null either and getDecimationLevels() returns null. If this method returns null, getAddDecimationLevels() also returns null.

The returned set does never contain null or negative elements. However, the set may be empty and the return value itself might be null. The set never contains a decimation level that is also contained in the set returned by getAddDecimationLevels().

Returns:

set of decimation levels that shall be removed from the channel or null if the set of decimation levels is not supposed to be changed or the change is described in an explicit fashion.

See Also:

getAddDecimationLevels(), getDecimationLevels()

getDecimationLevelToRetentionPeriod

public Map<Integer,Integer> getDecimationLevelToRetentionPeriod()

Returns the map mapping decimation levels to their respective retention period. Each map entry has a retention level as its key and the respective retention period (in seconds) as its value. Each decimation level is identified by the period between two consecutive samples (in seconds). The decimation level storing raw samples is represented by a period of zero. A retention period of zero indicates that samples for the respective decimation level shall be kept indefinitely.

If either of the sets returned by getDecimationLevels() and getAddDecimationLevels() is not null and not empty, this map is guaranteed to contain an entry for each decimation level in the returned set. If no retention period for the respective decimation level was specified when creating this command, this map will contain a retention period of zero for the respective decimation level. This map may also contain entries for decimation levels that are not to be added but already exist. In this case, the decimation levels' retention periods will be updated according to their entries in this map. If this map contains an entry for a decimation level that does not exist and is not to be added, the entry is simply skipped.

If this method returns null, the retention periods are not supposed to be changed. However, this method will never return null, if getDecimationLevels() or getAddDecimationLevels() do not return null.

The returned map does never contain null keys or values and the values are never negative. However, the map may be empty and the return value itself might be null.

It is also guaranteed that the retention period of each decimation level is greater than or equal to the retention period of the preceding decimation level (that is the decimation level with the next smaller decimation period). However, this only guarantees that the whole retention-period configuration is valid when getDecimationLevels() does not return null and thus all retention periods will be updated with the values from this map. Otherwise, the entries from this map might get merged with existing entries, leading to invalid retention periods. Such a situation can only be detected when the update is actually applied, then leading to an exception.

Returns:

map mapping decimation levels to their respective retention periods.

See Also:

getAddDecimationLevels(), getDecimationLevels()

getEnabled

public Boolean getEnabled()

Tells whether archiving for the channel shall be enabled or disabled. If true, archiving is supposed to be enabled. If false, archiving is supposed to be disabled. If null, the channel's current enabled state will not be changed.

Returns:

flag indicating the channel's future enabled state or null if the enabled state is not supposed to be changed.

getOptions

public Map<String,String> getOptions()

Returns the control-system-specific configuration options for the channel. If not null, the channel's options are replaced with the options in this map. Options that currently exist for the channel but that do not exist in the returned map are removed when the channel is updated.

If the returned map is null, the control-system-specific configuration options for the channel are either not supposed to be changed or the changes are described in a differential fashion through the map returned by getAddOptions() and the set returned by getRemoveOptions(). If this method does not return null, getAddOptions() and getRemoveOptions() both return null.

The returned map does never contain null keys or values. However, the map may be empty and the return value itself might be null.

Returns:

map with control-system-specific configuration options that shall replace the channel's current configuration options or null if the configuration options are not supposed to be changed or the change is described in a differential fashion.

See Also:

getAddOptions(), getRemoveOptions()

getAddOptions

public Map<String,String> getAddOptions()

Returns the map of control-system-specific configuration options to be added. If a configuration option specified in this map already exists before the update operation, the update operation will simply update the option's value to match the value in this map.

If the returned map is null, the channel's control-system-specific configuration options are either not supposed to be changed or the changes are described in an explicit fashion through the map returned by getOptions(). If this method does not return null, getRemoveOptions() does not return null either and getOptions() returns null. If this method returns null, getRemoveOptions() also returns null.

The returned map does never contain null keys or values. However, the map may be empty and the return value itself might be null. The map never contains a configuration option that is also contained in the set returned by getRemoveOptions().

Returns:

map of control-system-specific configuration options to be added or null if the configurations options are not supposed to be changed or the change is described explicitly.

See Also:

getOptions(), getRemoveOptions()

getRemoveOptions

public Set<String> getRemoveOptions()

Returns the set of control-system-specific configuration options to be removed. If an option specified in this set does not exist before the update operation, the update operation will simply skip the element.

If the returned set is null, the channel's control-system-specific configuration options are either not supposed to be changed or the changes are described in an explicit fashion through the map returned by getOptions(). If this method does not return null, getAddOptions() does not return null either and getOptions() returns null. If this method returns null, getAddOptions() also returns null.

The returned set does never contain null elements. However, the set may be empty and the return value itself might be null. The set never contains a configuration option that is also contained in the map returned by getAddOptions().

Returns:

set of control-system-specific configuration options to be removed or null if the configurations options are not supposed to be changed or the change is described explicitly.

See Also:

getAddOptions(), getOptions()

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object