The eventbus usage
Vert.x relies on an internal eventbus that can operate in a request/reply or a broadcast mode. For simulating a flowable (from reactive principles) we follow a pattern:
- WebHandler generates a temp address to listen for results
- WebHandler requests from DbHandler to perform action
- DbHandler replies with acknowledgement
- DbHandler sends data to temp address, multiple times.
- Header determines if it is Data, Error or completion (See below)
Flowchart
title EventBus use in KEEP participant HttpClient participant HttpListener participant WebHandler participant EventBus participant WorkerVerticles participant DbHandler opt Startup HttpListener->WebHandler: load known handlers WorkerVerticles->DbHandler: load known handlers WorkerVerticles->EventBus: Subscribe to events\nbased on tags end HttpClient->HttpListener: GET/POST/PUT\nPATCH/DELETE HttpListener->HttpListener: Validate against OpenAPI HttpListener->WebHandler: forward request\nbased on operationId note right of WebHandler: Transforms request\ngenerate Temp address WebHandler->EventBus: subscribe to TEMP address WebHandler->EventBus: forward request EventBus->WorkerVerticles: forward request WorkerVerticles->EventBus: accnowledge request EventBus->WebHandler: accnowledge request WebHandler->HttpListener: Set response headers WorkerVerticles->DbHandler: request data loop Response data DbHandler->WorkerVerticles: provide data WorkerVerticles->EventBus: publish data\nto TEMP address EventBus->WebHandler: forward data WebHandler->HttpListener: forward data HttpListener->HttpClient: chunked response end DbHandler->WorkerVerticles:End of data WorkerVerticles->EventBus: publish end\nto TEMP address EventBus->WebHandler: notify end WebHandler->EventBus: unsubscribe TEMP address WebHandler->HttpListener: notify end HttpListener->HttpClient: response end
Anatomy of our EventBus message
We make user of header values to transport the meta data. They (usually JSON) body has a “payload” property with the requested data
Initial Request Header
This are the values in the initial request sent over the EventBus using EventBus.request()
- db: The KEEP alias name of the requested database (
MAIL
for Quattro) - jwtclaim: the JWT String the user authenticated with
- appId: (Optional) Id of the calling server app
- appSecret: (Optional) secret of the calling server app
- operationId: the operationId as defined in OpenApiSpec
- replyAddress: Address the handler will listen for replies
Initial Reply
- status: could be “failure” or “success”
- cause: String with explanation of potential failure
- statuscode: suggested HTTP Response code
- ErrorClass: what type of error based on
com.hcl.domino.keep.exceptions
See also the DeliveryOpts
class
Data replies
Same like the initial reply, but more options in status
:
data
: actual data in bodycomplete
: No more data to expect, no data in bodyfailure
: as above. Things went wrong
Reactive Wrapper
To simplify the creation of handler and requesters helper classes are build, that encapsulate the process back and forth on the eventbus following the Reactive pattern. This allows for flexible pre/post processing of data sent over the eventbus.
TODO: more on the wrapper
The wrapper classes can be found in the package com.hcl.domino.keep.eventbus