io.vertx.core.http

## Interface HttpServer

- All Superinterfaces:
    Measured

      public interface HttpServer
      extends Measured

  An HTTP and WebSockets server.

  You receive HTTP requests by providing a `requestHandler(io.vertx.core.Handler<io.vertx.core.http.HttpServerRequest>)`. As requests arrive on the server the handler will be called with the requests.

  You receive WebSockets by providing a `webSocketHandler(io.vertx.core.Handler<io.vertx.core.http.ServerWebSocket>)`. As WebSocket connections arrive on the server, the WebSocket is passed to the handler.

  Author:
    Tim Fox

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `actualPort()` The actual port the server is listening on.
    `Future<Void>` | `close()` Close the server.
    `void` | `close(Handler<AsyncResult<Void>> completionHandler)` Like `close()` but supplying a handler that will be called when the server is actually closed (or has failed).
    `HttpServer` | `connectionHandler(Handler<HttpConnection> handler)` Set a connection handler for the server.
    `HttpServer` | `exceptionHandler(Handler<Throwable> handler)` Set an exception handler called for socket errors happening before the HTTP connection is established, e.g during the TLS handshake.
    `HttpServer` | `invalidRequestHandler(Handler<HttpServerRequest> handler)` Set a `handler` for handling invalid requests.
    `Future<HttpServer>` | `listen()` Tell the server to start listening.
    `default HttpServer` | `listen(Handler<AsyncResult<HttpServer>> listenHandler)` Like `listen()` but supplying a handler that will be called when the server is actually listening (or has failed).
    `default Future<HttpServer>` | `listen(int port)` Like `listen(int, String)` but the server will listen on host "0.0.0.0" and port specified here ignoring any value in the `HttpServerOptions` that was used when creating the server.
    `default HttpServer` | `listen(int port, Handler<AsyncResult<HttpServer>> listenHandler)` Like `listen(int)` but supplying a handler that will be called when the server is actually listening (or has failed).
    `default Future<HttpServer>` | `listen(int port, String host)` Tell the server to start listening.
    `default HttpServer` | `listen(int port, String host, Handler<AsyncResult<HttpServer>> listenHandler)` Like `listen(int, String)` but supplying a handler that will be called when the server is actually listening (or has failed).
    `Future<HttpServer>` | `listen(SocketAddress address)` Like `listen(SocketAddress, Handler)` but returns a `Future` of the asynchronous result
    `default HttpServer` | `listen(SocketAddress address, Handler<AsyncResult<HttpServer>> listenHandler)` Tell the server to start listening on the given address supplying a handler that will be called when the server is actually listening (or has failed).
    `Handler<HttpServerRequest>` | `requestHandler()`
    `HttpServer` | `requestHandler(Handler<HttpServerRequest> handler)` Set the request handler for the server to `requestHandler`.
    `ReadStream<HttpServerRequest>` | `requestStream()` Deprecated. instead use `requestHandler(Handler)`
    `default Future<Boolean>` | `updateSSLOptions(SSLOptions options)` Update the server with new SSL `options`, the update happens if the options object is valid and different from the existing options object.
    `Future<Boolean>` | `updateSSLOptions(SSLOptions options, boolean force)` Update the server with new SSL `options`, the update happens if the options object is valid and different from the existing options object.
    `default void` | `updateSSLOptions(SSLOptions options, boolean force, Handler<AsyncResult<Boolean>> handler)` Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
    `default void` | `updateSSLOptions(SSLOptions options, Handler<AsyncResult<Boolean>> handler)` Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
    `void` | `updateTrafficShapingOptions(TrafficShapingOptions options)` Update traffic shaping options `options`, the update happens if valid values are passed for traffic shaping options.
    `Handler<ServerWebSocket>` | `webSocketHandler()`
    `HttpServer` | `webSocketHandler(Handler<ServerWebSocket> handler)` Set the WebSocket handler for the server to `wsHandler`.
    `HttpServer` | `webSocketHandshakeHandler(Handler<ServerWebSocketHandshake> handler)` Set a handler for WebSocket handshake.
    `ReadStream<ServerWebSocket>` | `webSocketStream()` Deprecated. instead use `webSocketHandler(Handler)`

    - ### Methods inherited from interface io.vertx.core.metrics.Measured

      `isMetricsEnabled`

- - ### Method Detail

    - #### requestStream

          @Deprecated
          ReadStream<HttpServerRequest> requestStream()

      Deprecated. instead use `requestHandler(Handler)`
      Return the request stream for the server. As HTTP requests are received by the server, instances of `HttpServerRequest` will be created and passed to the stream `ReadStream.handler(io.vertx.core.Handler)`.
      Returns:
        the request stream

    - #### requestHandler

          HttpServer requestHandler(Handler<HttpServerRequest> handler)

      Set the request handler for the server to `requestHandler`. As HTTP requests are received by the server, instances of `HttpServerRequest` will be created and passed to this handler.
      Returns:
        a reference to this, so the API can be used fluently

    - #### requestHandler

          Handler<HttpServerRequest> requestHandler()

      Returns:
        the request handler

    - #### invalidRequestHandler

          HttpServer invalidRequestHandler(Handler<HttpServerRequest> handler)

      Set a `handler` for handling invalid requests. When an invalid request is received by the server this handler will be called with the request. The handler can send any HTTP response, when the response ends, the server shall close the connection. `HttpServerRequest.decoderResult()` can be used to obtain the Netty decoder result and the failure cause reported by the decoder.

      Currently this handler is only used for HTTP/1.x requests.

      When no specific handler is set, the `HttpServerRequest.DEFAULT_INVALID_REQUEST_HANDLER` is used.

      Returns:
        a reference to this, so the API can be used fluently

    - #### connectionHandler

          HttpServer connectionHandler(Handler<HttpConnection> handler)

      Set a connection handler for the server.
      The handler will always be called on the event-loop thread.
      Returns:
        a reference to this, so the API can be used fluently

    - #### exceptionHandler

          HttpServer exceptionHandler(Handler<Throwable> handler)

      Set an exception handler called for socket errors happening before the HTTP connection is established, e.g during the TLS handshake.
      Parameters:
        `handler` - the handler to set
      Returns:
        a reference to this, so the API can be used fluently

    - #### webSocketStream

          @Deprecated
          ReadStream<ServerWebSocket> webSocketStream()

      Deprecated. instead use `webSocketHandler(Handler)`
      Return the WebSocket stream for the server. If a WebSocket connect handshake is successful a new `ServerWebSocket` instance will be created and passed to the stream `ReadStream.handler(io.vertx.core.Handler)`.
      Returns:
        the WebSocket stream

    - #### webSocketHandler

          HttpServer webSocketHandler(Handler<ServerWebSocket> handler)

      Set the WebSocket handler for the server to `wsHandler`. If a WebSocket connect handshake is successful a new `ServerWebSocket` instance will be created and passed to the handler.
      Returns:
        a reference to this, so the API can be used fluently

    - #### webSocketHandshakeHandler

          HttpServer webSocketHandshakeHandler(Handler<ServerWebSocketHandshake> handler)

      Set a handler for WebSocket handshake.

      When an inbound HTTP request presents a WebSocket upgrade, this handler is called first. The handler can chose to `ServerWebSocketHandshake.accept()` or `ServerWebSocketHandshake.reject()` the request.

      Setting no handler, implicitly accepts any HTTP request connection presenting an upgrade header and upgrades it to a WebSocket.

    - #### webSocketHandler

          Handler<ServerWebSocket> webSocketHandler()

      Returns:
        the WebSocket handler

    - #### updateSSLOptions

          default Future<Boolean> updateSSLOptions(SSLOptions options)

      Update the server with new SSL `options`, the update happens if the options object is valid and different from the existing options object.

      The boolean succeeded future result indicates whether the update occurred.

      Parameters:
        `options` - the new SSL options
      Returns:
        a future signaling the update success

    - #### updateSSLOptions

          default void updateSSLOptions(SSLOptions options,
                                        Handler<AsyncResult<Boolean>> handler)

      Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
      Parameters:
        `options` - the new SSL options
        `handler` - the update handler

    - #### updateSSLOptions

          Future<Boolean> updateSSLOptions(SSLOptions options,
                                           boolean force)

      Update the server with new SSL `options`, the update happens if the options object is valid and different from the existing options object.

      The `options` object is compared using its `equals` method against the existing options to prevent an update when the objects are equals since loading options can be costly, this can happen for share TCP servers. When object are equals, setting `force` to `true` forces the update.

      The boolean succeeded future result indicates whether the update occurred.

      Parameters:
        `options` - the new SSL options
        `force` - force the update when options are equals
      Returns:
        a future signaling the update success

    - #### updateSSLOptions

          default void updateSSLOptions(SSLOptions options,
                                        boolean force,
                                        Handler<AsyncResult<Boolean>> handler)

      Like `updateSSLOptions(SSLOptions)` but supplying a handler that will be called when the update happened (or has failed).
      Parameters:
        `options` - the new SSL options
        `force` - force the update when options are equals
        `handler` - the update handler

    - #### updateTrafficShapingOptions

          void updateTrafficShapingOptions(TrafficShapingOptions options)

      Update traffic shaping options `options`, the update happens if valid values are passed for traffic shaping options. This update happens synchronously and at best effort for rate update to take effect immediately.
      Parameters:
        `options` - the new traffic shaping options

    - #### listen

          Future<HttpServer> listen()

      Tell the server to start listening. The server will listen on the port and host specified in the `HttpServerOptions` that was used when creating the server.

      The listen happens asynchronously and the server may not be listening until some time after the call has returned.

      Returns:
        a future completed with the listen operation result

    - #### listen

          default Future<HttpServer> listen(int port,
                                            String host)

      Tell the server to start listening. The server will listen on the port and host specified here, ignoring any value set in the `HttpServerOptions` that was used when creating the server.

      The listen happens asynchronously and the server may not be listening until some time after the call has returned.

      Parameters:
        `port` - the port to listen on
        `host` - the host to listen on
      Returns:
        a future completed with the listen operation result

    - #### listen

          default HttpServer listen(int port,
                                    String host,
                                    Handler<AsyncResult<HttpServer>> listenHandler)

      Like `listen(int, String)` but supplying a handler that will be called when the server is actually listening (or has failed).
      Parameters:
        `port` - the port to listen on
        `host` - the host to listen on
        `listenHandler` - the listen handler

    - #### listen

          default HttpServer listen(SocketAddress address,
                                    Handler<AsyncResult<HttpServer>> listenHandler)

      Tell the server to start listening on the given address supplying a handler that will be called when the server is actually listening (or has failed).
      Parameters:
        `address` - the address to listen on
        `listenHandler` - the listen handler

    - #### listen

          Future<HttpServer> listen(SocketAddress address)

      Like `listen(SocketAddress, Handler)` but returns a `Future` of the asynchronous result

    - #### listen

          default Future<HttpServer> listen(int port)

      Like `listen(int, String)` but the server will listen on host "0.0.0.0" and port specified here ignoring any value in the `HttpServerOptions` that was used when creating the server.
      Parameters:
        `port` - the port to listen on
      Returns:
        a future completed with the listen operation result

    - #### listen

          default HttpServer listen(int port,
                                    Handler<AsyncResult<HttpServer>> listenHandler)

      Like `listen(int)` but supplying a handler that will be called when the server is actually listening (or has failed).
      Parameters:
        `port` - the port to listen on
        `listenHandler` - the listen handler

    - #### listen

          default HttpServer listen(Handler<AsyncResult<HttpServer>> listenHandler)

      Like `listen()` but supplying a handler that will be called when the server is actually listening (or has failed).
      Parameters:
        `listenHandler` - the listen handler

    - #### close

          Future<Void> close()

      Close the server. Any open HTTP connections will be closed.

      The close happens asynchronously and the server may not be closed until some time after the call has returned.

      Returns:
        a future completed with the result

    - #### close

          void close(Handler<AsyncResult<Void>> completionHandler)

      Like `close()` but supplying a handler that will be called when the server is actually closed (or has failed).
      Parameters:
        `completionHandler` - the handler

    - #### actualPort

          int actualPort()

      The actual port the server is listening on. This is useful if you bound the server specifying 0 as port number signifying an ephemeral port
      Returns:
        the actual port the server is listening on.

Copyright © 2025 Eclipse. All rights reserved.