Beginner

import io.vertx.core.AbstractVerticle;          // => Base class for all standard verticles
import io.vertx.core.Promise;                   // => Used to signal async start completion
import io.vertx.core.Vertx;                     // => Entry point: creates event loop, deploys verticles

public class MainVerticle extends AbstractVerticle {
  // => Extends AbstractVerticle to participate in Vert.x lifecycle
  // => This class runs on a single event loop thread

  @Override
  public void start(Promise<Void> startPromise) {
    // => Called once when verticle is deployed
    // => startPromise signals deployment success or failure to caller
    System.out.println("Verticle started on thread: "
      + Thread.currentThread().getName());
    // => Output: Verticle started on thread: vert.x-eventloop-thread-0
    // => Always runs on an event loop thread, never a plain Java thread

    startPromise.complete();
    // => Signals: "I finished starting up successfully"
    // => If you call startPromise.fail(cause), deployment is aborted
  }

  @Override
  public void stop(Promise<Void> stopPromise) {
    // => Called when verticle is undeployed (app shutdown or hot-reload)
    // => Use this to close resources: HTTP servers, DB connections, timers
    System.out.println("Verticle stopped");
    // => Output: Verticle stopped
    stopPromise.complete();
    // => Signal clean shutdown; callers await this before proceeding
  }

  public static void main(String[] args) {
    Vertx vertx = Vertx.vertx();
    // => Creates a new Vert.x instance with default options
    // => Starts the event loop thread pool (default: 2 * CPU cores)
    // => Only create ONE Vertx instance per JVM process

    vertx.deployVerticle(new MainVerticle())
      .onSuccess(id -> System.out.println("Deployed with ID: " + id))
      // => Output: Deployed with ID: 7a3c9f12-...
      // => Deployment ID is used to undeploy later: vertx.undeploy(id)
      .onFailure(err -> System.err.println("Deployment failed: " + err));
      // => Handles deployment errors (e.g., port already in use)
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.Vertx;
import io.vertx.core.VertxOptions;

public class EventLoopDemo extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    // WRONG - blocks the event loop (never do this)
    // Thread.sleep(5000); // => Freezes ALL event handling for 5 seconds
    // new File("data.txt").exists(); // => Blocking file I/O on event loop

    // CORRECT - non-blocking timer using Vert.x scheduler
    vertx.setTimer(2000, timerId -> {
      // => Handler fires after 2000ms on the SAME event loop thread
      // => timerId is a long you can use to cancel: vertx.cancelTimer(timerId)
      System.out.println("Timer fired after 2 seconds");
      // => Output: Timer fired after 2 seconds
      // => Event loop was FREE to handle other events during those 2 seconds
    });

    // CORRECT - periodic timer
    vertx.setPeriodic(1000, timerId -> {
      // => Handler fires every 1000ms
      System.out.println("Tick: " + System.currentTimeMillis());
      // => Output: Tick: 1741234567890 (every second)
    });

    startPromise.complete();
    // => Start completes immediately; timers fire asynchronously later
  }

  public static void main(String[] args) {
    // Enable blocked thread checker for development
    VertxOptions options = new VertxOptions()
      .setBlockedThreadCheckInterval(1000)
      // => Vert.x warns if event loop is blocked >1000ms
      // => Default is 2000ms; lower this in dev to catch accidental blocking
      .setMaxEventLoopExecuteTime(2000_000_000L);
      // => Max nanoseconds before "blocked thread" warning fires (2s default)

    Vertx vertx = Vertx.vertx(options);
    // => Creates Vertx with blocked-thread detector enabled
    vertx.deployVerticle(new EventLoopDemo());
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.DeploymentOptions;
import io.vertx.core.Promise;
import io.vertx.core.Vertx;

public class WorkerVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    System.out.println("Instance started on: "
      + Thread.currentThread().getName());
    // => Output (x4): Instance started on: vert.x-eventloop-thread-0
    //                  Instance started on: vert.x-eventloop-thread-1
    //                  Instance started on: vert.x-eventloop-thread-2
    //                  Instance started on: vert.x-eventloop-thread-3
    // => Each instance gets its own event loop thread automatically
    startPromise.complete();
  }

  public static void main(String[] args) {
    Vertx vertx = Vertx.vertx();

    DeploymentOptions options = new DeploymentOptions()
      .setInstances(4);
      // => Deploy 4 independent copies of WorkerVerticle
      // => Each instance runs on a separate event loop thread
      // => Vert.x load-balances event bus messages across all 4

    vertx.deployVerticle(WorkerVerticle.class.getName(), options)
      // => Use class name string for multi-instance deployments
      // => Vert.x instantiates the class 4 times via reflection
      .onSuccess(deploymentId -> {
        System.out.println("4 instances deployed: " + deploymentId);
        // => deploymentId covers all 4 instances; undeploy all with one call
      })
      .onFailure(err -> System.err.println("Failed: " + err));
  }
}

import io.vertx.core.Future;
import io.vertx.core.Promise;
import io.vertx.core.Vertx;

public class FutureDemo {

  public static void main(String[] args) {
    Vertx vertx = Vertx.vertx();

    // Create a Future manually using Promise
    Promise<String> promise = Promise.promise();
    // => Promise is the write-side; Future is the read-side
    // => Consumers get future(); producers call promise.complete/fail

    Future<String> future = promise.future();
    // => future is a handle to the eventual result

    // Register handlers BEFORE completing (safe in async world)
    future
      .map(String::toUpperCase)
      // => Transforms result: "hello" → "HELLO"
      // => map() is synchronous transformation; use compose() for async
      .onSuccess(result -> System.out.println("Result: " + result))
      // => Output: Result: HELLO
      .onFailure(err -> System.err.println("Error: " + err));

    promise.complete("hello");
    // => Triggers the chain: map → onSuccess
    // => Handlers fire asynchronously on the event loop

    // Composing multiple async operations
    fetchUser(vertx, "user-1")
      .compose(user -> fetchOrders(vertx, user))
      // => compose() chains async operations sequentially
      // => Only called if fetchUser succeeds; short-circuits on failure
      .compose(orders -> sendEmail(vertx, orders))
      // => Each step returns a Future; compose flattens the nested Future
      .onSuccess(v -> System.out.println("Email sent"))
      .onFailure(err -> System.err.println("Pipeline failed: " + err));
      // => Single failure handler for the entire chain
  }

  static Future<String> fetchUser(Vertx vertx, String id) {
    // => Simulates async user fetch (database, HTTP, etc.)
    return vertx.executeBlocking(() -> "User:" + id);
    // => executeBlocking runs on a worker thread; returns Future
  }

  static Future<String> fetchOrders(Vertx vertx, String user) {
    return vertx.executeBlocking(() -> "Orders for " + user);
    // => Simulates async order fetch
  }

  static Future<Void> sendEmail(Vertx vertx, String orders) {
    return vertx.executeBlocking(() -> {
      System.out.println("Sending email for: " + orders);
      // => Output: Sending email for: Orders for User:user-1
      return null;
      // => Returning null signals Void completion
    });
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.http.HttpServer;

public class HttpServerVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    HttpServer server = vertx.createHttpServer();
    // => Creates an HTTP server backed by Netty (not yet listening)
    // => Server uses the event loop thread of this verticle

    server.requestHandler(request -> {
      // => Handler fires for every incoming HTTP request
      // => request is HttpServerRequest: immutable view of incoming request
      System.out.println("Received: " + request.method()
        + " " + request.uri());
      // => Output: Received: GET /hello

      request.response()
        // => Get the mutable response object
        .putHeader("Content-Type", "text/plain")
        // => Set response header; called before writing body
        .end("Hello from Vert.x!");
        // => Write body and flush; MUST call end() or connection hangs
        // => After end(), response is complete; do not write more data
    });

    server.listen(8080)
      // => Bind to port 8080 on all interfaces (0.0.0.0)
      // => Returns Future<HttpServer>; bind is async
      .onSuccess(s -> {
        System.out.println("Server listening on port " + s.actualPort());
        // => Output: Server listening on port 8080
        // => actualPort() is useful when port 0 is used (OS assigns free port)
        startPromise.complete();
        // => Signal that verticle started successfully
      })
      .onFailure(startPromise::fail);
      // => If port is in use, fail deployment with the cause
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class RouterVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);
    // => Creates a new router; pass vertx instance for event bus integration
    // => Router is NOT thread-safe; create once and reuse across requests

    router.get("/hello")
      // => Match GET /hello exactly
      .handler(this::handleHello);
      // => Method reference to handler; called for each matching request

    router.post("/echo")
      // => Match POST /echo
      .handler(ctx -> {
        // => ctx is RoutingContext: wraps request + response + user data
        ctx.response()
          .putHeader("Content-Type", "text/plain")
          .end("Echo: " + ctx.request().uri());
          // => Output body: Echo: /echo
      });

    router.get("/items")
      // => Match GET /items
      .handler(ctx -> {
        ctx.response()
          .putHeader("Content-Type", "application/json")
          .end("{\"items\": []}");
          // => Return empty JSON array (static for now)
      });

    vertx.createHttpServer()
      .requestHandler(router)
      // => Router implements Handler<HttpServerRequest>
      // => Routes request to matching handler; returns 404 if no match
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }

  private void handleHello(RoutingContext ctx) {
    // => Extracted as a method for readability and testability
    ctx.response()
      .putHeader("Content-Type", "text/plain")
      .end("Hello, World!");
      // => Output: Hello, World!
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class ParamsVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);

    // Path parameter: /users/42 → id = "42"
    router.get("/users/:id")
      // => :id captures any URL segment at that position
      // => /users/alice → id = "alice"
      // => /users/123  → id = "123"
      .handler(this::handleGetUser);

    // Multiple path parameters: /orgs/acme/repos/vertx
    router.get("/orgs/:org/repos/:repo")
      // => Captures two named segments
      .handler(ctx -> {
        String org = ctx.pathParam("org");
        // => org = "acme"
        String repo = ctx.pathParam("repo");
        // => repo = "vertx"
        ctx.response()
          .putHeader("Content-Type", "application/json")
          .end(new JsonObject()
            .put("org", org)
            .put("repo", repo)
            .encode());
          // => Output: {"org":"acme","repo":"vertx"}
      });

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }

  private void handleGetUser(RoutingContext ctx) {
    String id = ctx.pathParam("id");
    // => Retrieves named path parameter; null if param not declared on route

    // Query parameters from ?name=alice&role=admin
    String name = ctx.queryParam("name").stream().findFirst().orElse("unknown");
    // => queryParam returns List<String> (multi-value params supported)
    // => /users/42?name=alice → name = "alice"
    // => /users/42           → name = "unknown"

    String role = ctx.request().getParam("role");
    // => getParam works for both path params and query params
    // => Returns null if not present

    ctx.response()
      .putHeader("Content-Type", "application/json")
      .end(new JsonObject()
        .put("id", id)
        .put("name", name)
        .put("role", role != null ? role : "viewer")
        .encode());
    // => Output: {"id":"42","name":"alice","role":"admin"}
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;
import io.vertx.ext.web.handler.BodyHandler;

public class BodyReadVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);

    // MUST add BodyHandler before any route that reads the body
    router.route().handler(BodyHandler.create());
    // => router.route() with no args matches ALL routes/methods
    // => BodyHandler buffers the entire request body into memory
    // => Default max body size: 10MB; configure with setBodyLimit()

    router.post("/users")
      .handler(this::createUser);

    router.put("/users/:id")
      .handler(ctx -> {
        String id = ctx.pathParam("id");
        // => Extract path param before reading body
        JsonObject body = ctx.body().asJsonObject();
        // => Parse body as JSON; throws if invalid JSON
        // => ctx.body() is Buffer; asJsonObject() deserializes it

        ctx.response()
          .putHeader("Content-Type", "application/json")
          .end(new JsonObject()
            .put("updated", id)
            .put("name", body.getString("name"))
            .encode());
        // => Output: {"updated":"42","name":"Alice"}
      });

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }

  private void createUser(RoutingContext ctx) {
    JsonObject body = ctx.body().asJsonObject();
    // => Body is available because BodyHandler already ran

    if (body == null || !body.containsKey("name")) {
      // => Validate required fields before processing
      ctx.response().setStatusCode(400)
        // => 400 Bad Request for client errors
        .end("{\"error\":\"name is required\"}");
      return;
      // => Return early to stop handler execution
    }

    String name = body.getString("name");
    // => Extract string field; returns null if key absent
    int age = body.getInteger("age", 0);
    // => Extract integer with default value 0 if key absent

    ctx.response()
      .setStatusCode(201)
      // => 201 Created for successful resource creation
      .putHeader("Content-Type", "application/json")
      .end(new JsonObject()
        .put("id", "new-123")
        // => In production, use DB-generated ID
        .put("name", name)
        .put("age", age)
        .encode());
    // => Output: {"id":"new-123","name":"Alice","age":30}
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonArray;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class JsonResponseVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);

    router.get("/user")
      .handler(this::getUser);

    router.get("/users")
      .handler(this::getUsers);

    router.get("/error")
      .handler(this::errorExample);

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }

  private void getUser(RoutingContext ctx) {
    JsonObject user = new JsonObject()
      // => JsonObject: type-safe JSON object builder
      .put("id", 1)
      // => put(key, value) supports String, Integer, Long, Boolean, JsonObject, JsonArray
      .put("name", "Alice")
      .put("email", "alice@example.com")
      .put("active", true);
      // => Fluent builder: each put() returns the same JsonObject

    ctx.response()
      .putHeader("Content-Type", "application/json")
      .end(user.encode());
      // => encode() serializes to compact JSON string
      // => Output: {"id":1,"name":"Alice","email":"alice@example.com","active":true}
  }

  private void getUsers(RoutingContext ctx) {
    JsonArray users = new JsonArray()
      // => JsonArray: type-safe JSON array builder
      .add(new JsonObject().put("id", 1).put("name", "Alice"))
      // => add() appends any JSON-compatible type
      .add(new JsonObject().put("id", 2).put("name", "Bob"));
      // => Nested JsonObjects build complex structures safely

    JsonObject response = new JsonObject()
      .put("users", users)
      // => Embed JsonArray inside JsonObject
      .put("total", users.size());
      // => size() returns element count: 2

    ctx.json(response);
    // => ctx.json() is shorthand: sets Content-Type to application/json
    // => and calls response.end(jsonObject.encode()) in one call
    // => Output: {"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}],"total":2}
  }

  private void errorExample(RoutingContext ctx) {
    JsonObject error = new JsonObject()
      .put("error", "NOT_FOUND")
      .put("message", "Resource not found")
      .put("path", ctx.request().path());
      // => Include request path for debugging

    ctx.response()
      .setStatusCode(404)
      // => 404 Not Found status code
      .putHeader("Content-Type", "application/json")
      .end(error.encode());
    // => Output: {"error":"NOT_FOUND","message":"Resource not found","path":"/error"}
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class StatusCodesVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);

    router.get("/ok").handler(ctx -> sendStatus(ctx, 200, "OK"));
    // => 200 OK: successful GET/HEAD

    router.post("/created").handler(ctx -> sendStatus(ctx, 201, "Created"));
    // => 201 Created: successful resource creation (POST)

    router.get("/no-content").handler(ctx -> {
      ctx.response().setStatusCode(204).end();
      // => 204 No Content: success but no body (DELETE, some PUTs)
      // => MUST NOT include a response body with 204
    });

    router.get("/redirect").handler(ctx -> {
      ctx.response()
        .setStatusCode(301)
        // => 301 Moved Permanently: URL has changed forever
        .putHeader("Location", "/new-location")
        // => Location header tells client where to go
        .end();
        // => Body is empty for redirects
    });

    router.get("/bad-request").handler(ctx -> {
      ctx.response()
        .setStatusCode(400)
        // => 400 Bad Request: client sent malformed data
        .putHeader("Content-Type", "application/json")
        .end("{\"error\":\"Invalid input\"}");
    });

    router.get("/unauthorized").handler(ctx -> {
      ctx.response()
        .setStatusCode(401)
        // => 401 Unauthorized: missing or invalid credentials
        .putHeader("WWW-Authenticate", "Bearer realm=\"api\"")
        // => WWW-Authenticate tells client which auth scheme to use
        .end();
    });

    router.get("/forbidden").handler(ctx -> {
      ctx.response().setStatusCode(403).end("Forbidden");
      // => 403 Forbidden: authenticated but not authorized
      // => Different from 401: client IS authenticated, just lacks permission
    });

    router.get("/internal-error").handler(ctx -> {
      ctx.response().setStatusCode(500).end("Internal Server Error");
      // => 500 Internal Server Error: unexpected server failure
      // => In production, never expose stack traces in 500 responses
    });

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }

  private void sendStatus(RoutingContext ctx, int code, String body) {
    ctx.response()
      .setStatusCode(code)
      // => Default status code is 200; always set explicitly for non-200
      .putHeader("Content-Type", "text/plain")
      .putHeader("X-Request-Id", java.util.UUID.randomUUID().toString())
      // => Custom headers use X- prefix by convention (deprecated but widely used)
      // => Unique request ID helps correlate logs across services
      .end(body);
  }
}

import io.vertx.core.json.JsonArray;
import io.vertx.core.json.JsonObject;
import java.util.Map;

public class JsonObjectDemo {

  public static void main(String[] args) {
    // Building from a Map
    JsonObject fromMap = new JsonObject(Map.of(
      "id", 1,
      "name", "Alice"
    ));
    // => fromMap = {"id":1,"name":"Alice"}

    // Parsing from a JSON string
    JsonObject parsed = new JsonObject("{\"score\":98,\"grade\":\"A\"}");
    // => parsed = {"score":98,"grade":"A"}
    // => Throws DecodeException if string is not valid JSON

    // Safe typed access
    String name = fromMap.getString("name");
    // => name = "Alice"; returns null if key absent

    int id = fromMap.getInteger("id");
    // => id = 1; throws NullPointerException if key absent (use default overload)

    int score = parsed.getInteger("score", 0);
    // => score = 98; second arg is default value if key absent
    // => Safe alternative to getInteger("score")

    // Nested objects
    JsonObject nested = new JsonObject()
      .put("user", new JsonObject()
        .put("address", new JsonObject()
          .put("city", "Jakarta")));
    // => {"user":{"address":{"city":"Jakarta"}}}

    String city = nested.getJsonObject("user")
      .getJsonObject("address")
      .getString("city");
    // => city = "Jakarta"
    // => Chain getJsonObject() calls to navigate nested structure

    // Working with arrays
    JsonObject withArray = new JsonObject()
      .put("tags", new JsonArray().add("java").add("vertx"));
    // => {"tags":["java","vertx"]}

    JsonArray tags = withArray.getJsonArray("tags");
    // => tags = ["java","vertx"]

    String firstTag = tags.getString(0);
    // => firstTag = "java"
    // => getXxx(int index) for array element access

    // Merging objects
    JsonObject base = new JsonObject().put("a", 1).put("b", 2);
    JsonObject override = new JsonObject().put("b", 99).put("c", 3);
    JsonObject merged = base.mergeIn(override);
    // => merged = {"a":1,"b":99,"c":3}
    // => mergeIn is destructive: modifies base in place and returns it

    // Converting to Map
    Map<String, Object> asMap = merged.getMap();
    // => Regular Java Map; useful for frameworks expecting Map<String, Object>

    System.out.println(merged.encodePrettily());
    // => encodePrettily() outputs indented JSON for logging/debugging
    // => Output:
    // => {
    // =>   "a" : 1,
    // =>   "b" : 99,
    // =>   "c" : 3
    // => }
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.StaticHandler;

public class StaticFilesVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);

    // API routes before static handler
    router.get("/api/health")
      .handler(ctx -> ctx.response().end("OK"));
      // => API routes defined first take priority over static handler

    // Serve static files from "webroot" directory (default)
    router.route("/static/*")
      // => Match all paths under /static/
      .handler(StaticHandler.create());
      // => Looks for files in src/main/resources/webroot/ on classpath
      // => GET /static/index.html → serves webroot/index.html
      // => GET /static/js/app.js → serves webroot/js/app.js
      // => Returns 404 if file not found

    // Serve from a custom filesystem path
    router.route("/assets/*")
      .handler(StaticHandler.create("/var/www/assets"));
      // => Absolute filesystem path; useful for user-uploaded content

    // SPA (Single Page Application) fallback
    router.get("/*")
      .handler(StaticHandler.create()
        .setIndexPage("index.html")
        // => Serve index.html for unknown paths (SPA client-side routing)
        .setCachingEnabled(true)
        // => Set Cache-Control headers for browser caching
        .setMaxAgeSeconds(3600));
        // => Cache files for 1 hour (3600 seconds)

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> {
        System.out.println("Static server started on port 8080");
        // => Output: Static server started on port 8080
        startPromise.complete();
      })
      .onFailure(startPromise::fail);
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class ErrorHandlingVerticle extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);

    // Route that intentionally fails
    router.get("/fail")
      .handler(ctx -> {
        ctx.fail(500, new RuntimeException("Something went wrong"));
        // => ctx.fail(statusCode, cause) triggers the failure handler
        // => Stops current handler chain and routes to failure handler
        // => Do NOT call ctx.response().end() after ctx.fail()
      });

    router.get("/not-found")
      .handler(ctx -> {
        ctx.fail(404);
        // => Fail with status code only (no exception)
        // => Useful for business-logic "not found" scenarios
      });

    // Per-route error handler (only catches failures from this route)
    router.get("/guarded")
      .handler(ctx -> {
        throw new IllegalArgumentException("Bad input");
        // => Uncaught exception is automatically caught by Vert.x
        // => Converted to ctx.fail(500, exception)
      })
      .failureHandler(ctx -> {
        // => failureHandler is chained after the main handler
        // => Only fires for failures from THIS route
        ctx.response()
          .setStatusCode(ctx.statusCode())
          .end("Route-specific error: " + ctx.failure().getMessage());
        // => ctx.failure() returns the Throwable that caused failure
        // => ctx.statusCode() returns the HTTP status set by ctx.fail()
      });

    // Global failure handler - catches all unhandled failures
    router.errorHandler(500, this::handleInternalError);
    // => errorHandler(statusCode, handler) registers for specific status code
    router.errorHandler(404, ctx -> {
      ctx.json(new JsonObject()
        .put("error", "NOT_FOUND")
        .put("path", ctx.request().path()));
      // => Structured 404 response for all unmatched routes
    });

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }

  private void handleInternalError(RoutingContext ctx) {
    Throwable cause = ctx.failure();
    // => Retrieves the root exception; null if fail(code) with no exception

    System.err.println("Internal error: " + cause);
    // => Log the full exception for debugging
    // => NEVER expose stack traces in API responses

    ctx.response()
      .setStatusCode(500)
      .putHeader("Content-Type", "application/json")
      .end(new JsonObject()
        .put("error", "INTERNAL_ERROR")
        .put("message", "An unexpected error occurred")
        .encode());
    // => Sanitized error response; no internal details
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;
import io.vertx.ext.web.handler.BodyHandler;

public class CustomExceptionsVerticle extends AbstractVerticle {

  // Custom exception hierarchy
  static class ApiException extends RuntimeException {
    private final int statusCode;
    // => HTTP status code this exception maps to
    private final String errorCode;
    // => Machine-readable error code for API clients

    ApiException(int statusCode, String errorCode, String message) {
      super(message);
      this.statusCode = statusCode;
      // => Store as field for the failure handler to read
      this.errorCode = errorCode;
    }

    int getStatusCode() { return statusCode; }
    // => Accessor for failure handler

    String getErrorCode() { return errorCode; }
  }

  static class NotFoundException extends ApiException {
    NotFoundException(String resource, String id) {
      super(404, "NOT_FOUND", resource + " with id=" + id + " not found");
      // => Pre-fills status 404 and error code for this domain event
    }
  }

  static class ValidationException extends ApiException {
    ValidationException(String field, String reason) {
      super(400, "VALIDATION_ERROR", "Field '" + field + "': " + reason);
    }
  }

  @Override
  public void start(Promise<Void> startPromise) {
    Router router = Router.router(vertx);
    router.route().handler(BodyHandler.create());

    router.get("/users/:id").handler(ctx -> {
      String id = ctx.pathParam("id");
      if ("999".equals(id)) {
        throw new NotFoundException("User", id);
        // => Vert.x catches unchecked exceptions and calls ctx.fail(500, ex)
        // => But our failure handler reads the actual status from the exception
      }
      ctx.json(new JsonObject().put("id", id).put("name", "Alice"));
    });

    router.post("/users").handler(ctx -> {
      JsonObject body = ctx.body().asJsonObject();
      if (body == null || !body.containsKey("email")) {
        throw new ValidationException("email", "is required");
      }
      ctx.response().setStatusCode(201)
        .json(new JsonObject().put("created", true));
    });

    // Global handler for all ApiExceptions
    router.errorHandler(500, ctx -> {
      Throwable ex = ctx.failure();
      // => Check if this is our custom exception
      if (ex instanceof ApiException apiEx) {
        // => Java 16+ pattern matching instanceof
        ctx.response()
          .setStatusCode(apiEx.getStatusCode())
          // => Use domain-specific status code, not the default 500
          .putHeader("Content-Type", "application/json")
          .end(new JsonObject()
            .put("error", apiEx.getErrorCode())
            .put("message", ex.getMessage())
            .encode());
      } else {
        ctx.response().setStatusCode(500)
          .end("{\"error\":\"INTERNAL_ERROR\"}");
      }
    });

    vertx.createHttpServer()
      .requestHandler(router)
      .listen(8080)
      .onSuccess(s -> startPromise.complete())
      .onFailure(startPromise::fail);
  }
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.Vertx;
import io.vertx.core.eventbus.EventBus;
import io.vertx.core.eventbus.Message;

public class EventBusDemo extends AbstractVerticle {

  @Override
  public void start(Promise<Void> startPromise) {
    EventBus eb = vertx.eventBus();
    // => Obtain the event bus; shared across all verticles in the same Vertx instance

    // Register a consumer on an address
    eb.consumer("users.create", this::handleCreateUser);
    // => "users.create" is the address (any string; convention: domain.action)
    // => Only ONE consumer receives each point-to-point message
    // => Multiple consumers on same address → round-robin delivery

    // Send a message with a reply handler
    eb.request("users.create", new io.vertx.core.json.JsonObject()
      .put("name", "Bob")
      .put("email", "bob@example.com"))
      // => request() sends point-to-point AND expects a reply
      // => Blocks until reply arrives or timeout expires (default: 30s)
      .onSuccess(reply -> {
        System.out.println("Reply: " + reply.body());
        // => Output: Reply: {"id":"new-42","name":"Bob"}
      })
      .onFailure(err -> System.err.println("No reply: " + err));

    // Fire-and-forget: no reply expected
    eb.send("notifications.email", "Welcome to Vert.x!");
    // => send() delivers to ONE consumer; does not wait for reply
    // => If no consumer exists, message is silently dropped

    startPromise.complete();
  }

  private void handleCreateUser(Message<io.vertx.core.json.JsonObject> msg) {
    io.vertx.core.json.JsonObject data = msg.body();
    // => msg.body() returns the message payload; type parameter ensures compile-time safety
    System.out.println("Creating user: " + data.getString("name"));
    // => Output: Creating user: Bob

    // Simulate user creation
    io.vertx.core.json.JsonObject created = new io.vertx.core.json.JsonObject()
      .put("id", "new-42")
      .put("name", data.getString("name"));

    msg.reply(created);
    // => Send reply back to the requester
    // => Only valid when sender used request(); ignored for send()
  }
}