{"id":20796736,"url":"https://github.com/vertx-howtos/service-proxy-howto","last_synced_at":"2025-10-15T14:09:14.344Z","repository":{"id":43204484,"uuid":"176793052","full_name":"vertx-howtos/service-proxy-howto","owner":"vertx-howtos","description":"Creating a Vert.x Event Bus Service with Service Proxy","archived":false,"fork":false,"pushed_at":"2024-12-09T17:38:13.000Z","size":259,"stargazers_count":3,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-06T09:17:19.556Z","etag":null,"topics":["eventbus","howto","serviceproxy","vertx"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vertx-howtos.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-20T18:21:35.000Z","updated_at":"2024-12-09T17:44:12.000Z","dependencies_parsed_at":"2022-09-04T02:10:12.401Z","dependency_job_id":null,"html_url":"https://github.com/vertx-howtos/service-proxy-howto","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fservice-proxy-howto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fservice-proxy-howto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fservice-proxy-howto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vertx-howtos%2Fservice-proxy-howto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vertx-howtos","download_url":"https://codeload.github.com/vertx-howtos/service-proxy-howto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252655006,"owners_count":21783374,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eventbus","howto","serviceproxy","vertx"],"created_at":"2024-11-17T16:28:52.918Z","updated_at":"2025-10-15T14:09:09.286Z","avatar_url":"https://github.com/vertx-howtos.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Create a Vert.x Event Bus Service with Service Proxy\n:page-permalink: /\n:page-github: vertx-howtos/service-proxy-howto\n\nThis document will show you how to bootstrap an Event Bus service using Vert.x Service Proxy module.\nAs you will see, this approach is particularly useful when you want to design and consume a service on the event bus using plain Java interfaces.\n\n== What you will build\n\nYou will build a Vert.x application that exposes and uses `BarmanService`, an Event Bus Service that generates beers and manages customer bills.\nWe are going to deploy two verticles: the `BarmanVerticle` that exposes the service and the `DrunkVerticle` that consumes the service\n\n== What you need\n\n* A text editor or IDE\n* Java 11 higher\n* Maven\n\n== Create a project\n\nHere is the content of the `pom.xml` file you should be using:\n\n[source,xml,role=\"collapsed\"]\n.Maven `pom.xml`\n----\ninclude::pom.xml[]\n----\n\nYou must import both `vertx-codegen` with `processor` classifier and `vertx-service-proxy`.\nWe are going to use `vertx-web-client` to load the beer names.\n\n== Design the `BarmanService`\n\nFirst, we must define our service interface.\nUnder the hood, a code generator analyze it and generates the event bus message handler and the proxy class.\n\nThis is the `BarmanService` interface:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/beers/BarmanService.java[]\n----\n\n\u003c1\u003e Add `@VertxGen` and `@ProxyGen` to trigger code generation\n\u003c2\u003e Define the method that generates a new beer and adds it to the bill of the customer specified.\nWhen the beer is ready, the `Future` is completed.\n\u003c3\u003e Define the method that retrieves the bill.\n\u003c4\u003e Define the method that settles the bill.\nThis is a fire and forget method.\n\u003c5\u003e Specify the method that creates a new proxy.\n`BarmanServiceVertxEBProxy` is the class name of the proxy that the code generator will create for us.\n\nThere are a couple of rules you must follow when defining the service interface.\nLook at http://vertx.io/docs/vertx-service-proxy/java/#_restrictions_for_service_interface[Restrictions for service interface] for more info.\nIn our interface, we are using a couple of primitives and `Beer`, a POJO annotated as `@DataObject`.\nIf you want to use types annotated with `DataObject` inside your interface, they must define both a constructor with only a `JsonObject` parameter and a `toJson()` method that returns a `JsonObject`.\n\nTo trigger the code generation, you must also add in the same package of the interface a `package-info.java` with `@ModuleGen` annotation:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/beers/package-info.java[]\n----\n\n== Implement the `BarmanService`\n\nNow you can implement the `BarmanService`.\n\nFor `giveMeARandomBeer()`:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/beers/impl/BarmanServiceImpl.java[tags=giveMeARandomBeer]\n----\n\n\u003c1\u003e Send a request to the https://www.craftbeernamegenerator.com[Craft Beer Name Generator Service]\n\u003c2\u003e Fail the async method if the request to external service failed\n\u003c3\u003e Create a new `Beer`\n\u003c4\u003e Add the beer to the customer bill\n\nFor `getMyBill()`:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/beers/impl/BarmanServiceImpl.java[tags=getMyBill]\n----\n\nFor `settleMyBill()`:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/beers/impl/BarmanServiceImpl.java[tags=payMyBill]\n----\n\n== Expose the service\n\nNow we can expose the service inside the `BarmanVerticle` with the `ServiceBinder` class:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/BarmanVerticle.java[]\n----\n\n\u003c1\u003e Instantiate the `BarmanServiceImpl`\n\u003c2\u003e Instantiate the `ServiceBinder`\n\u003c3\u003e Configure the service address\n\u003c4\u003e Register the service on the event bus\n\n== Use the service\n\nNow we can use the service with the generated proxy.\nFor demo purposes, we're going to use it inside another verticle called `DrunkVerticle`:\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/DrunkVerticle.java[]\n----\n\n\u003c1\u003e Instantiate the proxy\n\u003c2\u003e Let's try the first beer 🍺\n\u003c3\u003e Drinking the first one 🍻\n\u003c4\u003e Give me another one 🍺\n\u003c5\u003e Drinking the second one 🍻\n\u003c6\u003e Time to go home.\nGive me the bill\n\u003c7\u003e Pay the bill\n\n== Running the application\n\nTo run the application deploy the `BarmanVerticle` and subsequently the `DrunkVerticle`.\n\n[source,java,indent=0]\n----\ninclude::src/main/java/io/vertx/howtos/ebservice/BeersApplication.java[]\n----\n\nYou can run the application from:\n\n. your IDE, by running the `main` method from the `BeersApplication` class, or\n. with Maven: `mvn compile exec:java`\n\nYou should see something like this:\n\n----\nThe barman is ready to serve you\nGenerated a new Beer! Manticore's Shorthand Barleywine (Barleywine)\nMy first beer is a Manticore's Shorthand Barleywine and it costs 6€\nGenerated a new Beer! Fortunate Pretzel (Cream Ale)\nMy second beer is a Fortunate Pretzel and it costs 6€\nMy bill with the bar is 12€\nRemoved debt of homer\n----\n\n== Summary\n\nThis how-to explained to you:\n\n. How to design and implement an Event Bus Service using Vert.x Service Proxy, and\n. How to expose the service on the event bus, and\n. How to use the service\n\n== See also\n\n* http://vertx.io/docs/vertx-service-proxy/java/[Vert.x Service Proxy Documentation]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fservice-proxy-howto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvertx-howtos%2Fservice-proxy-howto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvertx-howtos%2Fservice-proxy-howto/lists"}