Built by Maven

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

FlowChart of our Eventbus

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

FlowChart of our Eventbus

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 body
  • complete: No more data to expect, no data in body
  • failure : 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