com.aquenos.cassandra.pvarchiver.server.archiving

Interface ChannelInformationCache

All Known Implementing Classes:

ChannelInformationCacheImpl

public interface ChannelInformationCache

Cache for ChannelMetaDataDAO.ChannelInformation objects.

Reading ChannelMetaDataDAO.ChannelInformation objects from the database is rather expensive in terms of latency, in particular if many of them are needed.

The cache can be queried through the getChannel(String), getChannels(), getChannels(UUID), and getChannelsSortedByServer() methods. All these methods throw an exception if the cache is not ready for being queried.

The getChannelAsync(String, boolean) method can be used if the database should be queried directly if the cache is not ready or if an update of the cache should be forced before returning the channel information. Due to the potential database access, this operation can take a considerable amount of time to complete and thus works in an asynchronous fashion.

The updateChannels(Iterable) method should be called when the configuration of channels has been modified. The ArchiveConfigurationService takes care of calling this method. Finally, the processUpdate(List, List, Iterable, long) method is called by remote servers if they updated their cache because of configuration changes, forwarding the updated information to this server.

Author:

Sebastian Marsching

Method Summary

Modifier and Type	Method and Description
ChannelMetaDataDAO.ChannelInformation	getChannel(String channelName) Returns the channel information for the specified channel name or null if the channel does not exist.
ListenableFuture<ChannelMetaDataDAO.ChannelInformation>	getChannelAsync(String channelName, boolean forceUpdate) Returns the channel information for the specified channel name or null if the channel does not exist.
SortedMap<String,ChannelMetaDataDAO.ChannelInformation>	getChannels() Returns a map containing all channels in the cluster.
SortedMap<String,ChannelMetaDataDAO.ChannelInformation>	getChannels(UUID serverId) Returns a map containing all channels for the specified server.
Map<UUID,SortedMap<String,ChannelMetaDataDAO.ChannelInformation>>	getChannelsSortedByServer() Returns a map containing all channels in the cluster.
ListenableFuture<Void>	processUpdate(List<ChannelMetaDataDAO.ChannelInformation> channelInformationUpdates, List<String> missingChannels, Iterable<UUID> forwardToServers, long remoteTime) Process an update that has been received from a remote server.
ListenableFuture<Void>	updateChannels(Iterable<String> channelNames) Updates the channel information for the specified channel name.

Method Detail

getChannel

ChannelMetaDataDAO.ChannelInformation getChannel(String channelName)

Returns the channel information for the specified channel name or null if the channel does not exist.

The cache works in a way that it should be updated when channels are modifies, so in general it should return up-to-date information about channels. However, due to the asynchronous nature of cache updates, it is possible that this method returns obsolete information. If it is important that the most up-to-date information is returned, the getChannelAsync(String, boolean) method should be preferred.

This method throws an IllegalStateException if the cache is not ready. Reasons for the cache not being ready might be that it has not been properly initialized yet or that updates have failed and thus the cache has been invalidated in order to avoid serving obsolete information.

Parameters:

channelName - name of the channel for which the channel information shall be retrieved.

Returns:

channel information for the specified channel name or null if the channel does not exist.

Throws:

IllegalStateException - if the cache is not ready to be queried.

NullPointerException - if channelName is null.

getChannelAsync

ListenableFuture<ChannelMetaDataDAO.ChannelInformation> getChannelAsync(String channelName,
                                                                        boolean forceUpdate)

Returns the channel information for the specified channel name or null if the channel does not exist. The operation completes asynchronously (without blocking), so the channel information is returned through a future.

If the cache is not ready to be queried, this method queries the database directly. If the forceUpdate flag is true, the database is always queried directly and the information in the cache is updated with the information retrieved from the database.

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

• NullPointerException if the channelName is null.
• RuntimeException if the database is queried and that query fails.

Parameters:

channelName - name of the channel for which the channel information shall be retrieved.

forceUpdate - true if the database shall always be queried, even if the cache is ready. false if the information from the cache should be used if the cache is ready.

Returns:

channel information for the specified channel name, exposed through a listenable future.

getChannels

SortedMap<String,ChannelMetaDataDAO.ChannelInformation> getChannels()

Returns a map containing all channels in the cluster. The channel names are used as keys and the corresponding channel information objects are stored as values.

All the information is served from the cache. The cache works in a way that it should be updated when channels are modifies, so in general it should return up-to-date information about channels. However, due to the asynchronous nature of cache updates, it is possible that this method returns obsolete information.

This method throws an IllegalStateException if the cache is not ready. Reasons for the cache not being ready might be that it has not been properly initialized yet or that updates have failed and thus the cache has been invalidated in order to avoid serving obsolete information.

Returns:

map containing all channels that exist in the cluster.

Throws:

IllegalStateException - if the cache is not ready to be queried.

getChannels

SortedMap<String,ChannelMetaDataDAO.ChannelInformation> getChannels(UUID serverId)

Returns a map containing all channels for the specified server. The channel names are used as keys and the corresponding channel information objects are stored as values. If the specified server is unknown, an empty map is returned.

All the information is served from the cache. The cache works in a way that it should be updated when channels are modifies, so in general it should return up-to-date information about channels. However, due to the asynchronous nature of cache updates, it is possible that this method returns obsolete information.

This method throws an IllegalStateException if the cache is not ready. Reasons for the cache not being ready might be that it has not been properly initialized yet or that updates have failed and thus the cache has been invalidated in order to avoid serving obsolete information.

Parameters:

serverId - id of the server for which the channels shall be returned.

Returns:

map containing all channels for the specified server.

Throws:

IllegalStateException - if the cache is not ready to be queried.

NullPointerException - if the serverId is null.

getChannelsSortedByServer

Map<UUID,SortedMap<String,ChannelMetaDataDAO.ChannelInformation>> getChannelsSortedByServer()

Returns a map containing all channels in the cluster. The channels are aggregated by their associated server, having one map for each server ID.

All the information is served from the cache. The cache works in a way that it should be updated when channels are modifies, so in general it should return up-to-date information about channels. However, due to the asynchronous nature of cache updates, it is possible that this method returns obsolete information.

This method throws an IllegalStateException if the cache is not ready. Reasons for the cache not being ready might be that it has not been properly initialized yet or that updates have failed and thus the cache has been invalidated in order to avoid serving obsolete information.

Returns:

map containing all channels that exist in the cluster aggregated by server. The returned map contains an entry for each known server that has at least one channel. Each of this entries has a map as its value that maps channel names to the corresponding channel information objects.

Throws:

IllegalStateException - if the cache is not ready to be queried.

processUpdate

ListenableFuture<Void> processUpdate(List<ChannelMetaDataDAO.ChannelInformation> channelInformationUpdates,
                                     List<String> missingChannels,
                                     Iterable<UUID> forwardToServers,
                                     long remoteTime)

Process an update that has been received from a remote server. This method should only be called by remote servers (through the corresponding web-service API). It updates the cache with the information supplied in the request, merging the entries in the cache with the entries from the update. The cache is updated synchronously, but the servers specified in forwardToServers are notified asynchronously.

The notification of other servers works in a cascaded way: Only a limited number of servers from the specified list are notified directly. Those servers are in turn asked to notify a subset of the remaining servers. This way, each server only has to handle a limited number of notifications, even if the cluster is very large.

The returned future throws a NullPointerException if channelInformationUpdates, missingChannels, or forwardToServers is null or they contain null elements.

Parameters:

channelInformationUpdates - updated channel-information objects.

missingChannels - channels that are missing now (the channel information is null - typically because the channel has been deleted).

forwardToServers - list of servers which should be notified with the information from the update.

remoteTime - time stamp (as returned by System.currentTimeMillis() of the point in time before the channel information that is sent with this update was retrieved from the database. This information is used when resolving conflicting updates for the same channel.

Returns:

listenable future that finishes when the cache has been updated and all servers have been notified (or the notification attempts have failed).

updateChannels

ListenableFuture<Void> updateChannels(Iterable<String> channelNames)

Updates the channel information for the specified channel name. This method does not only update the local cache but also forwards the updated information to all remote servers by calling their processUpdate(List, List, Iterable, long) method with the updated information.

This method is intended for the ArchiveConfigurationService which calls it when it modifies channel configurations.

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

• NullPointerException if the channelNames is null or contains null elements.
• RuntimeException if one of the database queries needed for the update fails.

Parameters:

channelNames - names of the channels to be updated.

Returns:

listenable future that completes when the local cache has been updated and the update has been forwarded to the remote servers.