Vert.x - Services Proxy

Java Conceptuel Diagram

codegen.output : where the non Java classes / non resources are stored (mandatory) - the processors requires this option to know where to place them codegen.output.: relocate the output of to another directory
  • codegen.generators : a comma separated list of generators, each expression is a regex, allow to filter undesired generators
  • -proc: {none,only} : Controls whether annotation processing and/or compilation is done.
    • -proc:none means that compilation takes place without annotation processing.
    • -proc:only means that only annotation processing is done, without any subsequent compilation.
  • You write your service as a Java interface and annotate it with the @ProxyGen annotation
public interface SomeDatabaseService {

 // A couple of static factory methods to create the instances (respectively implementation and proxy
 // Create is used when you deploy a vertical (ie you deploy the service)
  static SomeDatabaseService create(arguments ..., Handler<AsyncResult<DatabaseServiceInterface>> readyHandler) {
    // The SomeDatabaseServiceImpl  class is an implementation class that you are creating
    return new SomeDatabaseServiceImpl(argument, readyHandler);
 // Proxy is used when you use/test the service as server client code
 static SomeDatabaseService createProxy(Vertx vertx, String address) {
   // The SomeDatabaseServiceVertxEBProxy class is generated by the annotation processor
   return new SomeDatabaseServiceVertxEBProxy(vertx, address);

// Actual service operations here...
SomeDatabaseService doSomething(Arguments ..., Handler<AsyncResult<YourReturnType>> resultHandler);

  • You give code generation metadata in the file where groupPackage is the package of the generated class.
@ModuleGen(name = "database", groupPackage = "net.bytle.api.db")
package net.bytle.api.db;

import io.vertx.codegen.annotations.ModuleGen;
In the start method of a verticle, you will use the static factory create method of the interface to deploy your service (ie 1 service = 1 verticle)
SomeServiceInterface.create(argument, ready -> {
  if (ready.succeeded()) {
	// ready result is the implementation (ie SomeServiceInterfaceImpl instance)
	ServiceBinder binder = new ServiceBinder(vertx).setAddress(IP_QUEUE_NAME);
	binder.register(SomeServiceInterface.class, ready.result());
  } else {;
The proxy is used in every server call to the service.
SomeDatabaseService service = SomeDatabaseService.createProxy(vertx,

// Save some data in the database - this time using the proxy
service.doSomething(Arguments ..., res2 -> {
  if (res2.succeeded()) {
    // done
In a unit, you would:
  • deploy your verticle (service)
  • and instantiate your service proxy (that you can use in every test)
  public void prepare(TestContext context) throws InterruptedException {
    vertx = Vertx.vertx();

    JsonObject conf = new JsonObject() 
      .put(DatabaseVerticle.KEY_JDBC_URL, "jdbc:hsqldb:mem:testdb;shutdown=true")
      .put(DatabaseVerticle.KEY_JDBC_MAX_POOL_SIZE, 4);

      new DatabaseVerticle(), // The service
      new DeploymentOptions().setConfig(conf),
        id -> { 
           // the deployment was successful, you get the deployment id (no needed)
           // but you can instantiate your service proxy
           service = DatabaseServiceInterface.createProxy(vertx, DatabaseVerticle.IP_QUEUE_NAME)) // The service proxy


Discover More
Java Conceptuel Diagram
Vert.x - SQL

SQL in Vertx known as Data Access : - connection pool, asynchronous API - - JDBC compliant database using an asynchronous...
Java Conceptuel Diagram
Vert.x - Shell

A Vert.x Shell provides a remotely accessible shell available via Telnet, SSH that provides a variety of commands for interacting live with Vert.x services A Vert.x Shell can be provided via the deployment...

Share this page:
Follow us:
Task Runner