public interface ServiceHandler
A service handler is a user implementation of the back end requirements of a
specific configured service (an instance of a ServiceType).
A service handler can be a source handler which
publishes updates to Diffusion, a sink handler which
receives updates from Diffusion for publishing to some back end sink, or a
HybridHandler which can both consume from Diffusion topics and
publish back to Diffusion topics.
| Modifier and Type | Interface and Description |
|---|---|
static class |
ServiceHandler.PauseReason
The reason that a service is being paused.
|
static class |
ServiceHandler.ResumeReason
The reason that a service is being resumed.
|
| Modifier and Type | Method and Description |
|---|---|
CompletableFuture<?> |
pause(ServiceHandler.PauseReason reason)
Notification that the service has been paused.
|
CompletableFuture<?> |
resume(ServiceHandler.ResumeReason reason)
Notification that the service is being resumed.
|
default CompletableFuture<?> |
start()
Start the service.
|
default CompletableFuture<?> |
stop()
Stop the service.
|
default CompletableFuture<?> start()
This may be used for any initial connection requirements. It is called once and once only by the framework to prepare the service.
The default implementation of this method simply returns a completed
future although it should always be implemented for
StreamingSourceHandlers to enable updates to start being
streamed.
A SourceHandler or (@link HybridHandler} must not start
publishing updates until this has been called and completes successfully.
A source or hybrid handler publishes updates using the Publisher
provided to it when it was created.
If the task completes successfully, the CompletableFuture result should be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture should complete exceptionally.
If the completable future completes exceptionally or any
exception is thrown, the service will be started in a
PAUSED state
CompletableFuture<?> pause(ServiceHandler.PauseReason reason)
This will be called if there has been a user request (i.e. from the
Diffusion Console) to pause the service, or if the framework has detected
that the service needs to be paused (e.g. because the framework has lost
its connection with the Diffusion server), or if an application error has
occurred. The reason will indicate the precise
reason.
If this is called then a StreamingSourceHandler or
HybridHandler must stop publishing updates, a
PollingSourceHandler will no longer be polled for updates, and a
SinkHandler will no longer receive any updates until
resume(com.diffusiondata.gateway.framework.ServiceHandler.ResumeReason) is called.
reason - the reason that the service is being pausedIf the task completes successfully, the CompletableFuture result should be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture should complete exceptionally.
If the completable future completes exceptionally or any exception is thrown, regardless of the failure, the service will be paused and the exception will be logged.
CompletableFuture<?> resume(ServiceHandler.ResumeReason reason)
This will be called if the service was paused for any reason and it may now be resumed. It may have been paused by user request, because the service reported an error or because the framework lost connection to the Diffusion server.
The reason provided will be the last outstanding
reason to resume. For example, if there was a user request to pause a
service and that service later reported a RED status, followed by a GREEN status
then unless the user had since requested resume then the service would
remain paused. Only when the user resume is requested would this method
be called with a reason of REQUESTED.
reason - gives the reason that the service is being resumedIf the task completes successfully, the CompletableFuture result should be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture should complete exceptionally.
If the completable future completes exceptionally or any
exception is thrown, the service will be paused with
ServiceHandler.PauseReason.APPLICATION_ERROR reason and exception
logged.
default CompletableFuture<?> stop()
This will be called when a request has been received from the Diffusion management console to remove the service, or when the whole application is being stopped. It will only be called once.
This may be used to disconnect from any back end resources.
After this has been called no further interactions with the handler will occur and no further interactions with the framework are permitted.
The default implementation of this method simply returns a completed
future, although it should always be implemented for
StreamingSourceHandlers to prevent further publishing to
Diffusion.
If the task completes successfully, the CompletableFuture result will be null. The result type is any rather than Void to provide forward compatibility with future iterations of this API that may provide a non-null result with a more specific result type.
If the task fails, the CompletableFuture should complete exceptionally.
If the completable future completes exceptionally or any exception is thrown the service will still be stopped and the exception will be logged.
Copyright © 2024 DiffusionData Limited. All rights reserved.