com.solace.messaging.util

Interface AsyncLifecycleControl

All Known Subinterfaces:

DirectMessagePublisher, DirectMessageReceiver, MessagePublisher, MessageQueueBrowser, MessageReceiver, PersistentMessagePublisher, PersistentMessageReceiver, RequestReplyMessagePublisher, RequestReplyMessageReceiver

@ProviderType
public interface AsyncLifecycleControl

An interface for asynchronous control-service lifecycle operations, such as start and terminate.

See also: CompletableFuture for Asynchronous Programming in Java 8

Since:

1.0

Method Summary

Modifier and Type	Method and Description
<T> CompletableFuture<T>	startAsync() Asynchronously starts service for consuming/publishing operations.
<T> void	startAsync(CompletionListener<T> startListener) Asynchronously starts service for consuming/publishing operations using a callback for completion notification.
void	terminateAsync(CompletionListener<Void> terminationListener, long gracePeriod) Asynchronously terminates (gracefully) the service for consuming/publishing operations using a callback for a completion notification.
CompletableFuture<Void>	terminateAsync(long gracePeriod) Asynchronously terminates (gracefully) the service for consuming/publishing operations.

Method Detail

startAsync

<T> CompletableFuture<T> startAsync()
                             throws PubSubPlusClientException,
                                    IllegalStateException

Asynchronously starts service for consuming/publishing operations. In order to operate normally, this method needs to be called on a service instance. If the service is started or in the process of being started, this operation has no effect.

This method is an idempotent operation when no another connect/disconnect operation is ongoing.

Returns:

a future state of the start request that can complete successfully or fail.

Throws:

PubSubPlusClientException - if the messaging service will not start in the future

IllegalStateException - if the method has been invoked at an illegal or inappropriate time

Since:

1.0

startAsync

<T> void startAsync(CompletionListener<T> startListener)
             throws PubSubPlusClientException,
                    IllegalStateException

Asynchronously starts service for consuming/publishing operations using a callback for completion notification. In order to operate normally, this method needs to be called on a service instance. If the service is started or in the process of being started, this operation has no effect.

Type Parameters:

T - the type of response returned on a successful start operation

Parameters:

startListener - the callback for future notifications about the completion of the start process

Throws:

IllegalStateException - if the method has been invoked at an illegal or inappropriate time

PubSubPlusClientException - if the messaging service will not start in the future

Since:

1.0

terminateAsync

void terminateAsync(CompletionListener<Void> terminationListener,
                    long gracePeriod)
             throws PubSubPlusClientException,
                    IllegalStateException

Asynchronously terminates (gracefully) the service for consuming/publishing operations using a callback for a completion notification. Only way to resume service operation after this method asynchronously completes will be to recreate the service instance.

This method is idempotent.

Graceful shutdown is designed to make a best-effort to prevent loss of the in-flight or cached data during shutdown.

Attempt to call this method renders service instance permanently terminated, even if the terminationListener callback was notified of an exception.

Parameters:

gracePeriod - the termination grace period, which is the amount of time given to finish regular tasks before the non-graceful interruption of duties takes place, in milliseconds. A valid value is > 1.

terminationListener - the callback for future notifications about the completion of the termination process

Throws:

PubSubPlusClientException - if the service will not be possible to terminate in the future

IllegalStateException - if the method has been invoked at an illegal or inappropriate time for some another reason

Since:

1.0

terminateAsync

CompletableFuture<Void> terminateAsync(long gracePeriod)
                                throws PubSubPlusClientException,
                                       IllegalStateException

Asynchronously terminates (gracefully) the service for consuming/publishing operations. Only way to resume service operation after this method asynchronously completes will be to recreate the service instance.

This method is idempotent.

Graceful shutdown is designed to make a best-effort to prevent loss of the in-flight or cached data during shutdown.

Attempt to call this method renders service instance permanently terminated, even if this method completes exceptionally.

Returned CompletableFuture can be finished with PubSubPlusClientException.IncompleteMessageDeliveryException when some incomplete processed messages are discovered.

Parameters:

gracePeriod - the termination grace period, which is the amount of time given to finish regular tasks before the non-graceful interruption of duties takes place, in milliseconds. A valid value is > 1.

Returns:

the future state of termination

Throws:

PubSubPlusClientException - if the service will not be possible to terminate in the future

IllegalStateException - if the method has been invoked at an illegal or inappropriate time for some another reason

Since:

1.0