Vert.x Service Proxy examples

Here you will find examples demonstrating Vert.x Service Proxies.

Service Proxies provide a way to expose services on the event bus and reducing the code required to invoke them.

In this example, we will run two verticles:

  • one provides a ProcessorService

  • the seconds one consumes it

Verticles runs on two clustered vert.x instances.

Providing a service

To provide a service, you need a service interface, an implementation and a verticle.

Service interface

The service interface is a Java interface annotated with @ProxyGen.

Compiling this class creates two other classes:

These classes are going to be used in the provider and consumer code

Service Provider

The service provider contains a verticle registering the service handler and an implementation of the service:

The service implementation is a simple Java class implementing the service interface. The only trick to know is the invocation of the given result handler:


In the verticle, the handler registration is made using:

ProxyHelper.registerService(ProcessorService.class, vertx, service, "vertx.processor");

service is the service object we register (so an instance of the ProcessorServiceImpl. The last parameter is the address on which the service can be invoked.

Alternatively, you can instantiate the generated handler:

new ProcessorServiceVertxProxyHandler(vertx, service).registerHandler("vertx.processor");

In this case, classes need to be generated beforehand, and so, requires a manual mvn compile.

Running the service provider

To run the service provider, you first need to package it with:

cd service-provider
# Install is important here as the service consumer needs the service interface class
mvn clean install

Once done, run the verticle using:

vertx run io.vertx.examples.service.ProcessorServiceVerticle \
    -cp target/service-provider-3.3.3.jar -cluster

Depending on your cluster configuration you may have to specify the cluster-host and configure Hazelcast.

Client generation

Vert.x generates the clients to use this service in the different supported languages.

Consuming a service

To consume our service, we just need a verticle that runs on a vert.x instance on the same cluster as the service provider.

The service is retrieved using:

ProcessorService service = ProcessorService.createProxy(vertx, "vertx.processor");

The second argument is the service address.

To run this verticle, package it using: mvn clean package, and run it with:

vertx run io.vertx.examples.service.consumer.ConsumerVerticle \
    -cp ../service-provider/target/service-provider-3.3.3.jar:target/service-consumer-3.3.3.jar \

Depending on your cluster configuration you may have to specify the cluster-host and configure Hazelcast.

Notice that the verticle has in its classpath the service provider verticle to access the service interface. We could have packaged the service interface in its owned packaged (alongside the generated handler and proxy).

Once launched you should see:


The service can be consumed from Java, as presented above, but also from Groovy, JavaScript and Ruby.

You can consume the ProcessorService in Groovy as shown in this Groovy verticle.

To launch this groovy verticle run:

vertx run src/main/groovy/io/vertx/examples/service/consumer/consumer_verticle.groovy  -cp ../service-provider/target/service-provider-3.3.3.jar -cluster

In JavaScript, the consuming verticle is here. To launch it, just run:

vertx run src/main/js/io/vertx/examples/service/consumer/consumer_verticle.js  -cp ../service-provider/target/service-provider-3.3.3.jar -cluster

You can also consume the service in ruby as shown here. To launch it, just run:

vertx run src/main/rb/io/vertx/examples/service/consumer/consumer_verticle.rb   -cp ../service-provider/target/service-provider-3.3.3.jar -cluster