The Vert.x EventBus is the nervous system of Domino REST API. 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:
- When the HttpListener receives a request from the HttpClient, it forwards it to the WebHandler based on the OperationId.
- The WebHandler generates a temporary address to listen for results and forwards the request to the EventBus.
- The EventBus relays the request to the WorkerVerticle.
- The WorkerVerticle sends an acknowledgment to the EventBus and requests the DbHandler to perform an action.
- The DbHandler sends data to the temporary address in batches, until all the data is sent to the HttpListener.
- The HttpClient starts interacting with data as soon as it receives it. The data is received in batches.
- The header determines if it is Data, Error, or completion. (See below.)
- Once all the data is sent, the DbHandler sends 'end of data' notification back to the EventBus.
title EventBus use in KEEP
HttpListener->WebHandler: load known handlers
WorkerVerticles->DbHandler: load known handlers
WorkerVerticles->EventBus: Subscribe to events\nbased on tags
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: acknowledge request
EventBus->WebHandler: acknowledge 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
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 the EventBus message
EventBus uses header values to transport the meta data. The body (usually JSON) has a "payload" property with the requested data.
Initial request header
Below are the values in the initial request sent over the EventBus
- db: The Domino REST API alias name of the requested database (
- 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
- status: Could be "failure" or "success"
- cause: String with explanation of potential failure
- statuscode: Suggested HTTP Response code
- ErrorClass: Type of error based on
See also the
Data reply is similar to the initial reply but with more options in
data: Actual data in body
complete: No more data to expect, no data in body
failure: as above, stating what went wrong
To simplify the creation of handler and requesters, helper classes are built. They 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