Implementing service handlers
A Service Handler governs how a specific service instance operates. Depending on the service modes, the Framework provides corresponding ServiceHandler interfaces. The application developer must implement a service handler class for each Service Type, the application declares.
The provided service handler interfaces in the framework are as follows:
-
StreamingSourceHandler for streaming source services
-
PollingSourceHandler for polling source services
-
SinkHandler for sink services
-
HybridHandler for hybrid services
Regardless of the type, all ServiceHandler objects have the same lifecycle and are broadly handled in a similar manner by the Framework.
ServiceHandler lifecycle
All handlers have a lifecycle governed by the common start, pause,
resume and stop methods, which are called by the framework as
appropriate. The diagram below illustrates the state changes of a service handler and service instance resulting from method calls:
start
When a service is added to the framework via the configuration file or via the Diffusion console,
the framework calls the start method of the service handler. Any operations that need to be
performed to start the service, such as connecting to the external system, should be performed in this method.
Only when this method completes successfully, and service-specific start operations are successful in the
framework, the service will be in ACTIVE state. If the method completes with an exception, then the service
will be paused with APPLICATION_ERROR pause reason.
It’s important to note that a source handler must not publish updates until the framework has called its start method.
A sink handler or a hybrid handler will not receive any updates before the start method completes successfully.
pause
A service can be paused for three different reasons:
-
REQUESTED: Used when a user requests the pause of the service via the Diffusion management console or the Gateway control REST API.
-
DISCONNECTED: Used when the service is paused due to loss of connection with the Diffusion server.
-
APPLICATION_ERROR: Used when a service reports a severe error, as described in the service status reporting or when an error occurs while the framework executes any method defined by the application or a service.
When the framework triggers the pause operation, the pause method in the service handler
will be called with the PauseReason. Depending on the pause reason, necessary measures
can be implemented in the pause method.
For example, if the pause reason is DISCONNECTED or REQUESTED, a source service
should stop consuming data from the external system. However, if the pause reason is
APPLICATION_ERROR, which might have been triggered due to loss of connection with
the external system, the actions to take might be different and depend on the
application requirements.
When a service is paused, a polling source handler will not be polled. Similarly, in a sink and hybrid service, Diffusion topics will be unsubscribed from and the sink handler will not receive any updates.
resume
A paused service can be resumed with different resume reasons:
-
REQUESTED: Used when resuming a service due to a user request via the Diffusion management console or the Gateway control REST API.
-
CONNECTED: Used when resuming a service after an active connection with the Diffusion server has been established.
-
RECOVERED: Used when resuming a service after the connection with the server was lost and is now recovered.
-
APPLICATION_RECOVERED: Used when resuming a service after the service specifies that the application error has been recovered, typically by reporting a GREEN or AMBER status, as described in the [service status reporting](xref:#reporting_service_status).
When the framework triggers the resume operation, the resume method in the service handler will be called. Depending on the resume reason, necessary measures can be implemented in the resume method. Such as, streaming source handlers may start publishing updates again. With resume, polling source handlers will be polled again, and sink handlers will start to receive updates.
If a service is already paused due to a different reason, the framework will not trigger the pause operation again (i.e., the pause method in the service handler will not be called again). Instead, the new pause reason will be recorded in the list of pause reasons. This list is used to determine whether to resume the service when a resume operation is triggered. For each reason for which the service is paused, a corresponding resume operation needs to be triggered for the service to be resumed.
For example, if a service is first paused due to APPLICATION_ERROR and then due to
DISCONNECTED, and the connection to the Diffusion server is re-established, triggering a resume
operation on the service, the service will still be in a paused state. This is because it was originally
paused due to an application error. Only when the service handler sends a GREEN status, triggering
a resume with an APPLICATION_RECOVERED reason, the service will be resumed.
However, a resume operation triggered by a user with a REQUESTED reason overrides any pause reasons
and resumes the service. In the example above, if a user explicitly resumes the service via
the Diffusion management console, the resume operation will be triggered for the service,
even though the service was originally paused due to DISCONNECTED and APPLICATION_ERROR reasons.
stop
This is the final state in the lifecycle of a service. When a service is being removed, or the application is closing down, the framework calls the stop method in the service handler. In this method, any resources associated with the service can be removed or closed. When a service is stopped, the associated service handler instance can be disposed of, as it will not be used again.
Reporting service status
When declaring service handlers for a Gateway application using the add method,
the framework passes an instance of StateHandler which can be injected into service
handlers. The injected StateHandler object is for the exclusive use of the service
handler instance being created. This object allows a service to query its current
state at any time. It also allows the handler to report its current status to the framework.
The status of each service instance is presented in the Diffusion management console.
As mentioned in the Service Status section, there are three levels of status that can be reported by the service handler to the framework: RED, GREEN, or AMBER.
Reporting RED status
...
stateHandler.reportStatus(
RED,
"Connection failure",
"Failed to connect to external system");
...The handler can report a RED status to indicate a severe error that prevents the
service from publishing or consuming data to/from Diffusion topics. For example, in case
of loss of connection to the external system. Reporting the RED status will prompt the
framework to pause the service, and the pause method of the service handler will be
called with APPLICATION_ERROR as the pause reason, allowing the service handler to
perform any necessary operations when pausing the service, such as cleaning up stale
resources.
The service will not be resumed until the handler reports a GREEN or AMBER status
using the stateHandler, or until a user explicitly invokes the resume operation.
Reporting GREEN status
...
stateHandler.reportStatus(
GREEN,
"Connection succeeded",
"Successfully connected to external system");
...The service handler can report a GREEN status to indicate normal function.
This can be done when the service starts successfully, or if the handler
had previously reported RED or AMBER. If a GREEN status is reported by the
service handler and if the handler had previously notified RED
(causing the service to be paused);
then, the framework will call the resume method of the service handler to resume
with a reason of APPLICATION_RECOVERED.
A handler must not assume that it’s resumed simply because it
notifies GREEN. It must wait for the resume method to be called.
|
Reporting AMBER status
...
stateHandler.reportStatus(
AMBER,
"Message publish Failure",
"Failed to publish message from `Xtopic` to external system");
...The handler can report an AMBER status to indicate that it is still
working, but has encountered a problem which may affect its ability to
provide a full service.
If an AMBER status is reported by the service handler and if the handler had
previously notified RED, then it is treated the same as a GREEN notification
and the resume method will be called. Otherwise, this notification is purely documentary.