Core API

/**
 * Create a Vert.x instance with default options
 * @return Vertx instance
 */
static Vertx vertx();

/**
 * Create a Vert.x instance with custom options
 * @param options Configuration options for the Vertx instance
 * @return Vertx instance
 */
static Vertx vertx(VertxOptions options);

/**
 * Create a clustered Vert.x instance asynchronously
 * @param options Configuration options including cluster settings
 * @return Future that completes with clustered Vertx instance
 */
static Future<Vertx> clusteredVertx(VertxOptions options);

/**
 * Create a Vert.x builder for more complex configuration
 * @return VertxBuilder for fluent configuration
 */
static VertxBuilder builder();

interface VertxBuilder {
  VertxBuilder with(VertxOptions options);
  Vertx build();
}

/**
 * Deploy a verticle instance
 * @param verticle The verticle instance to deploy
 * @return Future that completes with deployment ID
 */
Future<String> deployVerticle(Verticle verticle);

/**
 * Deploy a verticle instance with options
 * @param verticle The verticle instance to deploy
 * @param options Deployment configuration
 * @return Future that completes with deployment ID
 */
Future<String> deployVerticle(Verticle verticle, DeploymentOptions options);

/**
 * Deploy a verticle by name/class
 * @param name Verticle name or class name
 * @return Future that completes with deployment ID
 */
Future<String> deployVerticle(String name);

/**
 * Deploy a verticle by name with options
 * @param name Verticle name or class name
 * @param options Deployment configuration
 * @return Future that completes with deployment ID
 */
Future<String> deployVerticle(String name, DeploymentOptions options);

/**
 * Undeploy a verticle
 * @param deploymentID The deployment ID returned from deployVerticle
 * @return Future that completes when undeployment is done
 */
Future<Void> undeploy(String deploymentID);

/**
 * Get all deployment IDs
 * @return Set of deployment IDs
 */
Set<String> deploymentIDs();

/**
 * Check if verticle is deployed
 * @param deploymentID The deployment ID to check
 * @return true if deployed
 */
boolean isDeployed(String deploymentID);

/**
 * Core Future interface for asynchronous operations
 */
interface Future<T> extends AsyncResult<T> {
  /**
   * Add a handler to be called when the future succeeds
   * @param handler Handler to call with the result
   * @return this Future for chaining
   */
  Future<T> onSuccess(Handler<T> handler);

  /**
   * Add a handler to be called when the future fails
   * @param handler Handler to call with the failure cause
   * @return this Future for chaining
   */
  Future<T> onFailure(Handler<Throwable> handler);

  /**
   * Add a handler to be called when the future completes (success or failure)
   * @param handler Handler to call with the AsyncResult
   * @return this Future for chaining
   */
  Future<T> onComplete(Handler<AsyncResult<T>> handler);

  /**
   * Compose this future with another future-returning function
   * @param successMapper Function to apply to successful result
   * @return New Future with composed result
   */
  <U> Future<U> compose(Function<T, Future<U>> successMapper);

  /**
   * Transform the result of this future
   * @param mapper Function to transform the result
   * @return New Future with transformed result
   */
  <U> Future<U> map(Function<T, U> mapper);

  /**
   * Recover from failure by returning another future
   * @param mapper Function to handle failure and return recovery future
   * @return New Future with recovery handling
   */
  Future<T> recover(Function<Throwable, Future<T>> mapper);

  /**
   * Transform failure to success with a default value
   * @param value Default value to use on failure
   * @return New Future that succeeds with value on failure
   */
  Future<T> otherwise(T value);

  /**
   * Apply a function regardless of success/failure
   * @param mapper Function to apply to the result
   * @return New Future with transformation applied
   */
  <U> Future<U> eventually(Function<Void, Future<U>> mapper);

  // Static factory methods
  static <T> Future<T> succeededFuture();
  static <T> Future<T> succeededFuture(T result);
  static <T> Future<T> failedFuture(Throwable t);
  static <T> Future<T> failedFuture(String message);
  static <T> Future<T> future();
  static <T> Future<T> future(Promise<T> promise);
}

/**
 * Promise interface for completing futures
 */
interface Promise<T> extends Handler<AsyncResult<T>> {
  /**
   * Complete the promise with a result
   * @param result The result
   */
  void complete(T result);

  /**
   * Complete the promise with success (no result)
   */
  void complete();

  /**
   * Fail the promise with a cause
   * @param cause The failure cause
   */
  void fail(Throwable cause);

  /**
   * Fail the promise with a message
   * @param message The failure message
   */
  void fail(String message);

  /**
   * Get the future associated with this promise
   * @return The future
   */
  Future<T> future();

  /**
   * Try to complete the promise (returns false if already completed)
   * @param result The result
   * @return true if completed, false if already completed
   */
  boolean tryComplete(T result);

  /**
   * Try to fail the promise (returns false if already completed)
   * @param cause The failure cause
   * @return true if failed, false if already completed
   */
  boolean tryFail(Throwable cause);

  // Static factory
  static <T> Promise<T> promise();
}

/**
 * Composite future for handling multiple futures
 */
interface CompositeFuture extends Future<CompositeFuture> {
  /**
   * Check if all futures succeeded
   * @return true if all succeeded
   */
  boolean isComplete();

  /**
   * Get the cause at a specific index
   * @param index The index
   * @return The cause or null
   */
  Throwable cause(int index);

  /**
   * Check if future at index succeeded
   * @param index The index
   * @return true if succeeded
   */
  boolean succeeded(int index);

  /**
   * Check if future at index failed
   * @param index The index
   * @return true if failed
   */
  boolean failed(int index);

  /**
   * Get result at specific index
   * @param index The index
   * @return The result
   */
  <T> T resultAt(int index);

  /**
   * Get all results as list
   * @return List of results
   */
  <T> List<T> list();

  // Static factory methods
  static CompositeFuture all(List<Future> futures);
  static CompositeFuture all(Future<?>... futures);
  static CompositeFuture any(List<Future> futures);  
  static CompositeFuture any(Future<?>... futures);
  static CompositeFuture join(List<Future> futures);
  static CompositeFuture join(Future<?>... futures);
}

/**
 * Get the current context if running on a Vert.x thread
 * @return Current context or null if not on Vert.x thread
 */
static Context currentContext();

/**
 * Get or create a context for the current thread
 * @return Context instance (current context or a new one)
 */
Context getOrCreateContext();

/**
 * Execution context for handlers and operations
 */
interface Context {
  /**
   * Run code on this context
   * @param action The action to run
   */
  void runOnContext(Handler<Void> action);

  /**
   * Execute blocking code on worker thread
   * @param blockingCodeHandler Handler containing blocking code
   * @param resultHandler Handler to receive the result
   */
  <T> void executeBlocking(Handler<Promise<T>> blockingCodeHandler, Handler<AsyncResult<T>> resultHandler);

  /**
   * Execute blocking code on worker thread with options
   * @param blockingCodeHandler Handler containing blocking code
   * @param ordered Whether to maintain order
   * @param resultHandler Handler to receive the result
   */
  <T> void executeBlocking(Handler<Promise<T>> blockingCodeHandler, boolean ordered, Handler<AsyncResult<T>> resultHandler);

  /**
   * Check if running on event loop context
   * @return true if on event loop
   */
  boolean isEventLoopContext();

  /**
   * Check if running on worker context
   * @return true if on worker thread
   */
  boolean isWorkerContext();

  /**
   * Check if running on multi-threaded worker context
   * @return true if on multi-threaded worker
   */
  boolean isMultiThreadedWorkerContext();

  /**
   * Put data in context-local storage
   * @param key The key
   * @param value The value
   */
  void put(String key, Object value);

  /**
   * Get data from context-local storage
   * @param key The key
   * @return The value
   */
  <T> T get(String key);

  /**
   * Remove data from context-local storage
   * @param key The key
   * @return true if removed
   */
  boolean remove(String key);

  /**
   * Get verticle configuration
   * @return Configuration JsonObject
   */
  JsonObject config();

  // Static utilities
  static boolean isOnEventLoopThread();
  static boolean isOnWorkerThread();
  static boolean isOnVertxThread();
}

/**
 * Create a one-shot timer (modern approach)
 * @param delay Delay in milliseconds
 * @return Timer instance
 */
Timer timer(long delay);

/**
 * Create a one-shot timer with time unit
 * @param delay Delay amount
 * @param unit Time unit for delay
 * @return Timer instance
 */
Timer timer(long delay, TimeUnit unit);

/**
 * Set a one-shot timer (legacy)
 * @param delay Delay in milliseconds
 * @param handler Handler to call when timer fires
 * @return Timer ID for cancellation
 */
long setTimer(long delay, Handler<Long> handler);

/**
 * Set a periodic timer
 * @param delay Delay between executions in milliseconds
 * @param handler Handler to call on each execution
 * @return Timer ID for cancellation
 */
long setPeriodic(long delay, Handler<Long> handler);

/**
 * Set a periodic timer with initial delay
 * @param initialDelay Initial delay before first execution
 * @param delay Delay between subsequent executions
 * @param handler Handler to call on each execution
 * @return Timer ID for cancellation
 */
long setPeriodic(long initialDelay, long delay, Handler<Long> handler);

/**
 * Cancel a timer
 * @param id Timer ID returned from setTimer or setPeriodic
 * @return true if cancelled
 */
boolean cancelTimer(long id);

/**
 * Timer interface for advanced timer operations
 */
interface Timer {
  /**
   * Cancel this timer
   * @return Future that completes when cancelled
   */
  Future<Void> cancel();
}

/**
 * Basic verticle interface
 */
interface Verticle {
  /**
   * Get the Vertx instance
   * @return The Vertx instance
   */
  Vertx getVertx();

  /**
   * Initialize the verticle
   * @param vertx The Vertx instance
   * @param context The context
   */
  void init(Vertx vertx, Context context);

  /**
   * Start the verticle
   * @return Future that completes when started
   */
  Future<Void> start();

  /**
   * Stop the verticle
   * @return Future that completes when stopped
   */
  Future<Void> stop();
}

/**
 * Abstract base class for verticles
 */
abstract class AbstractVerticle implements Verticle {
  protected Vertx vertx;
  protected Context context;

  /**
   * Start the verticle (default implementation does nothing)
   * @return Succeeded future
   */
  public Future<Void> start() {
    return Future.succeededFuture();
  }

  /**
   * Stop the verticle (default implementation does nothing)
   * @return Succeeded future
   */
  public Future<Void> stop() {
    return Future.succeededFuture();
  }
}

/**
 * Create a named worker executor
 * @param name Name of the worker pool
 * @return WorkerExecutor instance
 */
WorkerExecutor createSharedWorkerExecutor(String name);

/**
 * Create a named worker executor with pool size
 * @param name Name of the worker pool
 * @param poolSize Size of the worker pool
 * @return WorkerExecutor instance
 */
WorkerExecutor createSharedWorkerExecutor(String name, int poolSize);

/**
 * Worker executor for custom blocking operations
 */
interface WorkerExecutor extends Measured, Closeable {
  /**
   * Execute blocking code on worker thread
   * @param blockingCodeHandler Handler containing blocking code
   * @param resultHandler Handler to receive the result
   */
  <T> void executeBlocking(Handler<Promise<T>> blockingCodeHandler, Handler<AsyncResult<T>> resultHandler);

  /**
   * Execute blocking code with ordering control
   * @param blockingCodeHandler Handler containing blocking code
   * @param ordered Whether to maintain order
   * @param resultHandler Handler to receive the result
   */
  <T> void executeBlocking(Handler<Promise<T>> blockingCodeHandler, boolean ordered, Handler<AsyncResult<T>> resultHandler);

  /**
   * Close the worker executor
   * @return Future that completes when closed
   */
  Future<Void> close();
}

/**
 * Close the Vertx instance
 * @return Future that completes when closed
 */
Future<Void> close();

/**
 * Set a default exception handler for the Vertx instance
 * @param handler Exception handler or null to unset
 * @return this Vertx instance
 */
Vertx exceptionHandler(Handler<Throwable> handler);

/**
 * Get the current exception handler
 * @return Current exception handler or null if none set
 */
Handler<Throwable> exceptionHandler();

/**
 * Check if native transport is enabled
 * @return true if native transport is available and enabled
 */
boolean isNativeTransportEnabled();

/**
 * Get the cause why native transport is not available (if applicable)
 * @return Throwable explaining why native transport is unavailable, or null if available
 */
Throwable unavailableNativeTransportCause();

/**
 * Check if this Vertx instance is clustered
 * @return true if clustered
 */
boolean isClustered();

/**
 * Configuration options for Vertx instance
 */
class VertxOptions {
  VertxOptions setEventLoopPoolSize(int eventLoopPoolSize);
  VertxOptions setWorkerPoolSize(int workerPoolSize);
  VertxOptions setInternalBlockingPoolSize(int internalBlockingPoolSize);
  VertxOptions setBlockedThreadCheckInterval(long blockedThreadCheckInterval);
  VertxOptions setMaxEventLoopExecuteTime(long maxEventLoopExecuteTime);
  VertxOptions setMaxWorkerExecuteTime(long maxWorkerExecuteTime);
  VertxOptions setWarningExceptionTime(long warningExceptionTime);
  VertxOptions setHAEnabled(boolean haEnabled);
  VertxOptions setHAGroup(String haGroup);
  VertxOptions setQuorumSize(int quorumSize);
  VertxOptions setFileResolverCachingEnabled(boolean fileResolverCachingEnabled);
  VertxOptions setMetricsOptions(MetricsOptions metricsOptions);
  VertxOptions setTracingOptions(TracingOptions tracingOptions);
}

/**
 * Configuration options for verticle deployment
 */
class DeploymentOptions {
  DeploymentOptions setConfig(JsonObject config);
  DeploymentOptions setWorker(boolean worker);
  DeploymentOptions setInstances(int instances);
  DeploymentOptions setIsolationGroup(String isolationGroup);
  DeploymentOptions setIsolatedClasses(List<String> isolatedClasses);
  DeploymentOptions setExtraClasspath(List<String> extraClasspath);
  DeploymentOptions setThreadingModel(ThreadingModel threadingModel);
  DeploymentOptions setHa(boolean ha);
  DeploymentOptions setRedeploy(boolean redeploy);
  DeploymentOptions setWorkerPoolName(String workerPoolName);
  DeploymentOptions setWorkerPoolSize(int workerPoolSize);
  DeploymentOptions setMaxWorkerExecuteTime(long maxWorkerExecuteTime);
}

/**
 * Threading models for verticle execution
 */
enum ThreadingModel {
  EVENT_LOOP,    // Execute on event loop thread (default)
  WORKER,        // Execute on worker thread
  VIRTUAL_THREAD // Execute on virtual thread (Java 19+)
}

/**
 * Generic handler interface
 */
@FunctionalInterface
interface Handler<E> {
  void handle(E event);
}

/**
 * Result of asynchronous operation
 */
interface AsyncResult<T> {
  T result();
  Throwable cause();
  boolean succeeded();
  boolean failed();
  <U> AsyncResult<U> map(Function<T, U> mapper);
  <U> AsyncResult<U> map(U value);
  AsyncResult<T> otherwise(Function<Throwable, T> mapper);
  AsyncResult<T> otherwise(T value);
  <U> AsyncResult<U> otherwiseEmpty();
}

/**
 * Base exception for Vert.x operations
 */
class VertxException extends RuntimeException {
  public VertxException(String message);
  public VertxException(String message, Throwable cause);
  public VertxException(Throwable cause);
}

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Future;

public class TimerExample extends AbstractVerticle {
  
  @Override
  public Future<Void> start() {
    // Set a one-shot timer
    vertx.setTimer(1000, id -> {
      System.out.println("Timer fired!");
    });
    
    // Set a periodic timer
    long periodicId = vertx.setPeriodic(2000, id -> {
      System.out.println("Periodic timer: " + id);
    });
    
    // Cancel after 10 seconds
    vertx.setTimer(10000, id -> {
      vertx.cancelTimer(periodicId);
      System.out.println("Periodic timer cancelled");
    });
    
    return Future.succeededFuture();
  }
}

Future<String> future1 = getUserName(userId);
Future<String> future2 = getUserEmail(userId);

CompositeFuture.all(future1, future2)
  .compose(composite -> {
    String name = composite.resultAt(0);
    String email = composite.resultAt(1);
    return saveUserProfile(name, email);
  })
  .onSuccess(profile -> System.out.println("Profile saved: " + profile))
  .onFailure(err -> System.err.println("Failed: " + err.getMessage()));

vertx.executeBlocking(promise -> {
  // This runs on worker thread
  try {
    String result = someBlockingOperation();
    promise.complete(result);
  } catch (Exception e) {
    promise.fail(e);
  }
}, result -> {
  // This runs on event loop
  if (result.succeeded()) {
    System.out.println("Result: " + result.result());
  } else {
    System.err.println("Failed: " + result.cause().getMessage());
  }
});