com.diffusiondata.gateway.framework

Interface GatewayApplication

public interface GatewayApplication

The interface that a Gateway Framework application must implement.

This is the interface that must be implemented by a Gateway Framework application developer.

See Package Guide for full details of how to write a Gateway Framework application.

Author:

DiffusionData Limited

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	GatewayApplication.ApplicationDetails Basic details of the application.

Method Summary

Modifier and Type	Method and Description
default HybridHandler<?>	addHybrid(ServiceDefinition serviceDefinition, Publisher publisher, Subscriber subscriber, StateHandler stateHandler) Adds a hybrid service to the application.
default PollingSourceHandler	addPollingSource(ServiceDefinition serviceDefinition, Publisher publisher, StateHandler stateHandler) Adds a polling source service to the application.
default SinkHandler<?>	addSink(ServiceDefinition serviceDefinition, Subscriber subscriber, StateHandler stateHandler) Adds a sink service to the application.
default StreamingSourceHandler	addStreamingSource(ServiceDefinition serviceDefinition, Publisher publisher, StateHandler stateHandler) Adds a streaming source service to the application.
GatewayApplication.ApplicationDetails	getApplicationDetails() Returns the basic details about the application.
default void	initialize(ApplicationContext applicationContext) Called to initialize the application.
default GatewayMeterRegistry	initializeGatewayMeterRegistry(Map<String,Object> globalApplicationConfiguration) Initializes and returns an instance of GatewayMeterRegistry which should supply MeterRegistry for the application specific monitoring tool/tools.
default CompletableFuture<?>	start() Starts the application.
CompletableFuture<?>	stop() Stops the application.

Method Detail

getApplicationDetails

GatewayApplication.ApplicationDetails getApplicationDetails()
                                                     throws ApplicationConfigurationException

Returns the basic details about the application.

Such details may be built using a builder obtained from DiffusionGatewayFramework.newApplicationDetailsBuilder().

Returns:

the application details

Throws:

ApplicationConfigurationException - possibly thrown by GatewayApplication.ApplicationDetails.Builder

initialize

default void initialize(ApplicationContext applicationContext)
                 throws ApplicationConfigurationException

Called to initialize the application.

The application context which provides configuration and other resources for the application.

Details provided in ApplicationContext can be used to instantiate necessary parameters and classes as required.

This method is called by the framework when DiffusionGatewayFramework.start(GatewayApplication) method is called.

The default implementation of this method does nothing.

Parameters:

applicationContext - the application context

Throws:

ApplicationConfigurationException - to indicate a configuration failure

start

default CompletableFuture<?> start()

Starts the application.

This is called by the framework after it has successfully connected to Diffusion, allowing the application to perform any initial processing.

The default implementation of this method simply returns a completed future.

Returns:

a CompletableFuture that completes when application has successfully started.

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 application will fail to start.

addStreamingSource

default StreamingSourceHandler addStreamingSource(ServiceDefinition serviceDefinition,
                                                  Publisher publisher,
                                                  StateHandler stateHandler)
                                           throws InvalidConfigurationException

Adds a streaming source service to the application.

This will be called as a result of such a service being defined in the configuration.

This must be implemented if the application supports any source streaming services.

The application must return an instance of StreamingSourceHandler that is for the exclusive use of the service. The handler should be initialized with the provided ServiceDefinition (which includes the service parameters) and use the provided Publisher to publish streamed updates to Diffusion. It should also use the provided StateHandler to report back to the gateway framework any change in the status of the service.

The default implementation of this method throws an exception to the framework indicating that it has not been implemented.

Parameters:

serviceDefinition - the definition of the service

publisher - a reference to a publisher that the service handler can use to publish updates to Diffusion

stateHandler - to be used to report the current status of the handler to the framework or enquire upon the current ServiceState

Returns:

a service handler for the service

Throws:

InvalidConfigurationException - if one or more configuration items passed in the definition is invalid

addPollingSource

default PollingSourceHandler addPollingSource(ServiceDefinition serviceDefinition,
                                              Publisher publisher,
                                              StateHandler stateHandler)
                                       throws InvalidConfigurationException

Adds a polling source service to the application.

This will be called as a result of such a service being defined in the configuration.

This must be implemented if the application supports any source polling services.

The application must return an instance of PollingSourceHandler that is for the exclusive use of the service. The handler should be initialized with the provided ServiceDefinition (which includes the service parameters) and use the provided Publisher to publish updates to Diffusion when polled It should also use the provided StateHandler to report back to the gateway framework any change in the status of the service.

The default implementation of this method throws an exception to the framework indicating that it has not been implemented.

Parameters:

serviceDefinition - the definition of the service

publisher - a publisher to be used to publish to Diffusion when polled

stateHandler - to be used to report the current status of the handler to the framework or enquire upon the current ServiceState

Returns:

a service handler for the service

Throws:

InvalidConfigurationException - if one or more configuration items passed in the definition is invalid

addSink

default SinkHandler<?> addSink(ServiceDefinition serviceDefinition,
                               Subscriber subscriber,
                               StateHandler stateHandler)
                        throws InvalidConfigurationException

Adds a sink service to the application.

This will be called as a result of such a service being defined in the configuration.

This must be implemented if the application supports any sink services.

The application must return an instance of SinkHandler that is for the exclusive use of the service. The handler should be initialized with the provided ServiceDefinition (which includes the service parameters) and use the provided StateHandler to report back to the gateway framework any change in the status of the service.

The default implementation of this method throws an exception to the framework indicating that it has not been implemented.

Parameters:

serviceDefinition - the definition of the service

subscriber - a subscriber to be used to subscribe to Diffusion topics.

See SinkServiceProperties.Builder#autoSubscribe(boolean)

stateHandler - to be used to report the current status of the handler to the framework or enquire upon the current ServiceState

Returns:

a service handler for the service

Throws:

InvalidConfigurationException - if one or more configuration items passed in the definition is invalid

addHybrid

default HybridHandler<?> addHybrid(ServiceDefinition serviceDefinition,
                                   Publisher publisher,
                                   Subscriber subscriber,
                                   StateHandler stateHandler)
                            throws InvalidConfigurationException

Adds a hybrid service to the application.

This will be called as a result of such a service being defined in the configuration.

This must be implemented if the application supports any hybrid services.

The application must return an instance of HybridHandler that is for the exclusive use of the service. The handler should be initialized with the provided ServiceDefinition (which includes the service parameters) and use the provided Publisher to publish streamed updates to Diffusion. It should also use the provided StateHandler to report back to the gateway framework any change in the status of the service.

The default implementation of this method throws an exception to the framework indicating that it has not been implemented.

Parameters:

serviceDefinition - the definition of the service

publisher - a reference to a publisher that the hybrid handler can use to publish updates to Diffusion

subscriber - a subscriber to be used to subscribe to Diffusion topics.

See SinkServiceProperties.Builder#autoSubscribe(boolean)

stateHandler - to be used to report the current status of the handler to the framework or enquire upon the current ServiceState

Returns:

a hybrid service handler for the service

Throws:

InvalidConfigurationException - if one or more configuration items passed in the definition is invalid

stop

CompletableFuture<?> stop()

Stops the application.

This is called by the framework to indicate that it is to close down. This allows the application to free any resources and tidy up.

The framework would have called the ServiceHandler.stop() method on each service handler before calling this.

The service will not be restarted once stopped.

Returns:

a CompletableFuture that completes when application has successfully stopped.

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, regardless of this exception, the exception will be logged and the application will terminate.

initializeGatewayMeterRegistry

default GatewayMeterRegistry initializeGatewayMeterRegistry(Map<String,Object> globalApplicationConfiguration)

Initializes and returns an instance of GatewayMeterRegistry which should supply MeterRegistry for the application specific monitoring tool/tools.

By default, null is returned, which means no metrics will be produced by the framework.

Parameters:

globalApplicationConfiguration - the configured global parameters for the application. Set to null if metrics are not enabled in the global framework configuration.

Returns:

GatewayMeterRegistry with application specific monitoring tool's MeterRegistry.

See Also:

GatewayMeterRegistry.getMeterRegistry()