Vert.x Service Factory

The vert.x service factory is an implementation of VerticleFactory which deploys a verticle given a service (id) name. Notice that this factory is not directly related to vert.x service proxies, but is about facilities to deploy individual components.

The service name is used to lookup a JSON descriptor file which determines the actual verticle that is to be deployed, and can also contain deployment options for the verticle such as whether it should be run as a worker, and default config for the service.

It is useful as it decouples the service user from the actual verticle that is deployed and it allows the service to provide default deployment options and configuration.

Service identifier

The service name is simply a string - you can use anything you want, but it’s a good convention to use a reverse domain name (rather like a Java package name) so not to clash with other similar named services that might be on your classpath. E.g:

Good names: com.mycompany.services.clever-db-service, org.widgets.widget-processor
Poor names (but they are still valid): accounting-service, foo

Usage

When deploying the service use the prefix service:, this selects the service verticle factory. The verticle can be deployed programmatically e.g.:

vertx.deployVerticle("service:com.mycompany.clever-db-service", options);

Or can be deployed on the command line with:

vertx run service:com.mycompany-clever-db-service

Making it available

Vert.x picks up VerticleFactory implementations from the classpath, so you just need to make sure the vertx-service-factory jar file on the classpath. First you need to add the Maven verticle factory to your application’s classpath. If you are using a fat jar, you can use the following dependencies:

Maven (in your pom.xml):

<dependency>
 <groupId>io.vertx</groupId>
 <artifactId>vertx-service-factory</artifactId>
 <version>4.5.10</version>
</dependency>

Gradle (in your build.gradle file):

compile 'io.vertx:vertx-service-factory:4.5.10'

You can also register a VerticleFactory instances programmatically on your vertx instance using the registerVerticleFactory method:

vertx.registerVerticleFactory(new ServiceVerticleFactory());

Service descriptor

When you ask to deploy a service, the service factory first looks for a descriptor file on the classpath. The descriptor file name is given by the service name concatenated with the .json file extension.

E.g. for a service name of com.mycompany.clever-db-service it would like for a descriptor file called com.mycompany.clever-db-service.json on the classpath.

The descriptor file is simply a text file which must contain a valid JSON object. At minimum the JSON must provide a main field which determines the actual verticle that will be deployed, e.g:

{
"main": "com.mycompany.cleverdb.MainVerticle"
}

{
 "main": "app.js"
}

or you could even redirect to a different verticle factory e.g. the Maven verticle factory to dynamically load the service from Maven at run-time:

{
"main": "maven:com.mycompany:clever-db:1,2::clever-db-service"
}

The JSON can also provide an options field which maps exactly to a DeploymentOptions object.

{
 "main": "com.mycompany.cleverdb.MainVerticle",
 "options": {
   "config" : {
    "foo": "bar"
   },
   "worker": true,
   "isolationGroup": "mygroup"
 }
}

When deploying a service from a service descriptor, any fields that are specified in the descriptor, such as worker, isolationGroup, etc cannot be overridden by any deployment options passed in at deployment time.

The exception is config. Any configuration passed in at deploy time will override any corresponding fields in any config present in the descriptor file.