Marcin Czeczko edited this page May 18, 2018 · 6 revisions

Knot.x Module

Knot.x is composed of set of Verticles. The Vert.x provides a Service Factory functionality that which deploys a Verticle given the service(id) name. It allows to deploy such verticles from different sources such as classpath, Http, Maven, etc. (see [[Service Factories|]). No matter which source of verticle was, it should be supplied with a corresponding configuration.

By default, Knot.x uses standard java service factory. It means that during a Knot.x initialization verticles are being looked up in classpath as java classes. Each module is supplied with a default configuration that can be overriden on the application config file.

As mentioned in Knot.x Deployment, the list of modules must be specified in JSON file provided as -conf parameter when starting Knot.x application.

modules = [

Each module definition has the following syntax: <alias>=[<factory>:]<verticle-name> Where:

  • is simply a convenient name of the module, used to later in the config file to indicate what module config is going to be overriden
  • : is optional and describes the name of vert.x service factory used to load the Verticle. If not specified it used java classpath to find a verticle for the given class name (see next)
  • is generally a verticle name, depending on the factory used it can be fully qualified class name (default), or just a descriptor name if used other factories (see [[Service Factories|])

When Knot.x is starting with the above configuration, we're actually asking to deploy two verticles classes io.knotx.server.KnotxServerVerticle and my.custom.ServiceVerticle.

When each Verticle starts, it uses its own default configuration, e.g. KnotxServerOptions for KnotxServerVerticle, that can be overridden in the application configuration file. Just add config section, and reference the verticle by using an alias, e.g.:

modules = [

config.server {
  options.instances = 2
  options.config {
    serverOptions.port: 6666
! Hint
When using an alias, to supply a configuration for the verticle, you can actually deploy same verticle multiple times. Then provide different configurations for each alias, e.g. two HTTP Repository Connectors, each pointing to a different HTTP locations.

See Knot.x Deployments for details how to manage your configurations.

How to create your service?

Assuming you're implementing your own Knot.x Verticle (either Knot, RepositoryConnector or Adapter following the appropriate guides).

  1. Create a configuration data object. You can follow the pattern used in KnotxerverOptions that's pretty much as follows:
@DataObject(generateConverter = true, publicConverter = false)
public class MyVerticleOptions {
   public final static int DEFAULT_SAMPLE_PARAMETER = 1234;
   private int sampleParameter;
   public MyVerticleOptions() {
   public MyVerticleOptions(MyVerticleOptions other) {
     //copy constructor impl
   public MyVerticleOptions(JsonObject obj) {
     MyVerticleOptionsConverter.fromJson(obj, this);
   public JsonObject toJson() {
       JsonObject json = new JsonObject();
       MyVerticleOptions.toJson(this, json);
       return json;
   private init() {
     //Initiate a parameter value from System props if exists, otherwise use dafault value
     this.sampleParameter = Integer.getInteger("my.sampleParam", DEFAULT_SAMPLE_PARAMETER);
   public int getSampleParameter() {
     return sampleParameter;
   //Fluent setter
   public MyVerticleOptions setSampleParameter(int param) {
     this.sampleParameter = param;
     return this;
  • JSON converters for this class will be automatically generated (during compilation) if field names follows the Vert.x Data Objects
  • Data object must have Default & Copy Constructors, Constructor from JsonObject and toJson() method
  • Any defaults in the configuration need to be implemented in this class.
  • If some of the configuration variables might need to be overridden through JVM system properties (e.g. -Dmy.sampleParam=123) use a convenient Java methods, such as Integer.getInteger("my.sampleParam) for integers (same methods available for Strings, Booleans, etc.) (See KnotxServerOptions.DEFAULT_HTTP_PORT as an example)
  • Use fluent setters
  1. Implement your verticle that way it will use your configuration data object (initialized by the config at start)
  2. After building your project, put result JAR file into the Knot.x classpath (Knot.x Deployments) and add your verticle to the starter JSON
modules = [
  1. If necessary, override the default configuration directly in starter JSON, or through JVM properties if implemented.
config.myVerticle {
  options.config {
    # My configuration or include required("includes/myVerticleConf.conf")
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.