com.aquenos.cassandra.pvarchiver.server.internode

Interface InterNodeCommunicationService

All Known Implementing Classes:

InterNodeCommunicationServiceImpl

public interface InterNodeCommunicationService

Service providing access to other nodes in the archiving cluster. This server can be used to send commands to other nodes when communication between two (or more) nodes is required in order to perform an operation. The service contacts the other server directly through the end-point URL published in the database. This way, a communication link between two servers can be established without having to poll the database constantly.

When an instance of this service has been fully initialized and is ready for operation, it emits an InterNodeCommunicationServiceInitializedEvent. Typically, such an even is pubished through the application context in which the service is running. The initialization status can also be queried through the isInitialized() method.

Author:

Sebastian Marsching

Method Summary

Modifier and Type	Method and Description
ListenableFuture<List<ChannelStatus>>	getArchivingStatus(String targetBaseUrl) Queries a remote server for its archiving status.
ListenableFuture<ChannelStatus>	getArchivingStatusForChannel(String targetBaseUrl, String channelName) Queries a remote server for the archiving status of one of its channels.
ListenableFuture<Long>	getCurrentSystemTime(String targetBaseUrl) Queries a remote server for its current system time (as returned by System.currentTimeMillis()).
boolean	isInitialized() Tells whether this communication service has initialized completely and is ready for operation.
ListenableFuture<List<ArchiveConfigurationCommandResult>>	runArchiveConfigurationCommands(String targetBaseUrl, List<? extends ArchiveConfigurationCommand> commands) Runs a list of archive-configuration commands on the specified remote server.
ListenableFuture<Void>	updateChannelInformation(String targetBaseUrl, List<ChannelMetaDataDAO.ChannelInformation> channelInformationUpdates, List<String> missingChannels, List<UUID> forwardToServers, long timeStamp) Updates the channel information cache of a remote server.

Method Detail

getArchivingStatus

ListenableFuture<List<ChannelStatus>> getArchivingStatus(String targetBaseUrl)

Queries a remote server for its archiving status. If the request is not successful, the returned future will throw one of the following exceptions:

• NullPointerException if targetBaseUrl is null.
• RuntimeException if the communication with the target server fails (e.g. the target server does not respond or responds with an invalid response).

The returned future returns a list containing the status of all channels known by the target server. The list is never null, but it might be empty if the target server does not have any channels. The channels are ordered by the natural order of their names.

Parameters:

targetBaseUrl - base URL on which the target server shall be contacted. Must not include a trailing slash.

Returns:

future that completes when the response from the server has been received. On success, the future will return a list of the status of all the channels of the target server. On failure, the future will throw an exception.

getArchivingStatusForChannel

ListenableFuture<ChannelStatus> getArchivingStatusForChannel(String targetBaseUrl,
                                                             String channelName)

Queries a remote server for the archiving status of one of its channels. If the request is not successful, the returned future will throw one of the following exceptions:

• IllegalArgumentException if channelNameis empty.
• NullPointerException if targetBaseUrl or channelName is null.
• RuntimeException if the communication with the target server fails (e.g. the target server does not respond or responds with an invalid response).

The returned future returns null if the specified channel is not known by the target server's archiving service (e.g. because it does not exist or is registered with a different server).

Parameters:

targetBaseUrl - base URL on which the target server shall be contacted. Must not include a trailing slash.

channelName - name of the channel to be queried.

Returns:

future that completes when the response from the server has been received. On success, the future will return the status of the queried channel or null if the channel is not known by the target server. On failure, the future will throw an exception.

getCurrentSystemTime

ListenableFuture<Long> getCurrentSystemTime(String targetBaseUrl)

Queries a remote server for its current system time (as returned by System.currentTimeMillis()). If the request is not successful, the returned future will throw one of the following exceptions:

• NullPointerException if targetBaseUrl is null.
• RuntimeException if the communication with the target server fails (e.g. the target server does not respond or responds with an invalid response).

Parameters:

targetBaseUrl - base URL on which the target server shall be contacted. Must not include a trailing slash.

Returns:

future that completes when the response from the server has been received. On success, the future will return the current system time on the queried server. On failure, the future will throw an exception.

isInitialized

boolean isInitialized()

Tells whether this communication service has initialized completely and is ready for operation. The communication service is ready as soon as all of its dependencies are ready.

When this service changes to the initialized state, it publishes an InterNodeCommunicationServiceInitializedEvent to the application context.

Returns:

true if initialization has completed and this communication service can be used, false otherwise.

runArchiveConfigurationCommands

ListenableFuture<List<ArchiveConfigurationCommandResult>> runArchiveConfigurationCommands(String targetBaseUrl,
                                                                                          List<? extends ArchiveConfigurationCommand> commands)

Runs a list of archive-configuration commands on the specified remote server. If the execution of individual commands on the target server fails, the corresponding ArchiveConfigurationCommandResult will reflect this error. However, if the whole communication process fails, the future returned by this method will throw one of the following exceptions:

• NullPointerException if targetBaseUrl or commands is null or commands contains null elements.
• RuntimeException if the communication with the target server fails (e.g. the target server does not respond or responds with an unexpected error).

Parameters:

targetBaseUrl - base URL on which the target server shall be contacted. Must not include a trailing slash.

commands - list of commands that shall be sent to the target server.

Returns:

future that completes when the whole operation has finished. On success, the future will return a list of ArchiveConfigurationCommandResults that are returned in the same order as the commands specified in commands . If one or several individual commands fail, the corresponding result will reflect this failure. However, if the whole operation fails due to an unexpected problem, the future will throw an exception.

updateChannelInformation

ListenableFuture<Void> updateChannelInformation(String targetBaseUrl,
                                                List<ChannelMetaDataDAO.ChannelInformation> channelInformationUpdates,
                                                List<String> missingChannels,
                                                List<UUID> forwardToServers,
                                                long timeStamp)

Updates the channel information cache of a remote server. The specified updates are sent to the remote server and it is asked to also notify the servers listed in forwardToServers. On failure, the future returned by this method throws one of the following exceptions:

• NullPointerException if targetBaseUrl, channelInformationUpdates, or missingChannels is null or channelInformationUpdates, missingChannels, or forwardToServers contains null elements.
• RuntimeException if the communication with the target server fails (e.g. the target server does not respond or responds with an unexpected error).

Parameters:

targetBaseUrl - base URL on which the target server shall be contacted. Must not include a trailing slash.

channelInformationUpdates - updated channel information objects.

missingChannels - names of channels that are now missing (the channel information is null, which typically means that they have been deleted).

forwardToServers - servers to which the target server should forward this update. This parameter may be null if the target server shall not forward this update.

timeStamp - time stamp (as returned by System.currentTimeMillis()) of the point in time right before the information that is part of this update was retrieved from the database. This information is used for conflict resolution on the target server.

Returns:

future that completes when the operation has finished. On failure, the future throws an exception.