/*
 * Copyright (c) 2011-2017 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.http;

import io.vertx.codegen.annotations.CacheReturn;
import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.core.AsyncResult;
import io.vertx.core.Handler;
import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.metrics.Measured;
import io.vertx.core.net.SocketAddress;
import io.vertx.core.streams.ReadStream;

An HTTP and WebSockets server.
 You receive HTTP requests by providing a requestHandler. As requests arrive on the server the handler will be called with the requests. 
 You receive WebSockets by providing a websocketHandler. As WebSocket connections arrive on the server, the WebSocket is passed to the handler. 
Author:
Tim Fox/**
 * An HTTP and WebSockets server.
 * <p>
 * You receive HTTP requests by providing a {@link #requestHandler}. As requests arrive on the server the handler
 * will be called with the requests.
 * <p>
 * You receive WebSockets by providing a {@link #websocketHandler}. As WebSocket connections arrive on the server, the
 * WebSocket is passed to the handler.
 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
@VertxGen
public interface HttpServer extends Measured {

  
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(Handler). 
Returns:
the request stream/**
   * Return the request stream for the server. As HTTP requests are received by the server,
   * instances of {@link HttpServerRequest} will be created and passed to the stream {@link io.vertx.core.streams.ReadStream#handler(io.vertx.core.Handler)}.
   *
   * @return the request stream
   */
  @CacheReturn
  ReadStream<HttpServerRequest> requestStream();

  
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/**
   * Set the request handler for the server to {@code requestHandler}. As HTTP requests are received by the server,
   * instances of {@link HttpServerRequest} will be created and passed to this handler.
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer requestHandler(Handler<HttpServerRequest> handler);

  
Returns:
 the request handler/**
   * @return  the request handler
   */
  @GenIgnore
  Handler<HttpServerRequest> requestHandler();

  
Set a connection handler for the server.
Returns:
a reference to this, so the API can be used fluently/**
   * Set a connection handler for the server.
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer connectionHandler(Handler<HttpConnection> handler);

  
Set an exception handler called for socket errors happening before the HTTP connection
is established, e.g during the TLS handshake.
Params:
handler – the handler to set
Returns:
a reference to this, so the API can be used fluently/**
   * Set an exception handler called for socket errors happening before the HTTP connection
   * is established, e.g during the TLS handshake.
   *
   * @param handler the handler to set
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer exceptionHandler(Handler<Throwable> 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(Handler). 
Returns:
the websocket stream/**
   * Return the websocket stream for the server. If a websocket connect handshake is successful a
   * new {@link ServerWebSocket} instance will be created and passed to the stream {@link io.vertx.core.streams.ReadStream#handler(io.vertx.core.Handler)}.
   *
   * @return the websocket stream
   */
  @CacheReturn
  ReadStream<ServerWebSocket> websocketStream();

  
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/**
   * Set the websocket handler for the server to {@code wsHandler}. If a websocket connect handshake is successful a
   * new {@link ServerWebSocket} instance will be created and passed to the handler.
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer websocketHandler(Handler<ServerWebSocket> handler);

  
Returns:
the websocketHandler/**
   * @return the websocketHandler
   */
  @GenIgnore
  Handler<ServerWebSocket> websocketHandler();

  
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 reference to this, so the API can be used fluently/**
   * Tell the server to start listening. The server will listen on the port and host specified in the
   * {@link io.vertx.core.http.HttpServerOptions} that was used when creating the server.
   * <p>
   * The listen happens asynchronously and the server may not be listening until some time after the call has returned.
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer listen();

  
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.
Params:
port –  the port to listen on
host –  the host to listen on
Returns:
a reference to this, so the API can be used fluently/**
   * Tell the server to start listening. The server will listen on the port and host specified here,
   * ignoring any value set in the {@link io.vertx.core.http.HttpServerOptions} that was used when creating the server.
   * <p>
   * The listen happens asynchronously and the server may not be listening until some time after the call has returned.
   *
   * @param port  the port to listen on
   * @param host  the host to listen on
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer listen(int port, String host);

  
Like listen(int, String) but supplying a handler that will be called when the server is actually listening (or has failed). 
Params:
port –  the port to listen on
host –  the host to listen on
listenHandler –  the listen handler/**
   * Like {@link #listen(int, String)} but supplying a handler that will be called when the server is actually
   * listening (or has failed).
   *
   * @param port  the port to listen on
   * @param host  the host to listen on
   * @param listenHandler  the listen handler
   */
  @Fluent
  HttpServer listen(int port, String host, 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).
Params:
address – the address to listen on
listenHandler –  the listen handler/**
   * 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).
   *
   * @param address the address to listen on
   * @param listenHandler  the listen handler
   */
  @Fluent
  HttpServer listen(SocketAddress address, Handler<AsyncResult<HttpServer>> listenHandler);

  
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. 
Params:
port –  the port to listen on
Returns:
a reference to this, so the API can be used fluently/**
   * Like {@link #listen(int, String)} but the server will listen on host "0.0.0.0" and port specified here ignoring
   * any value in the {@link io.vertx.core.http.HttpServerOptions} that was used when creating the server.
   *
   * @param port  the port to listen on
   *
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  HttpServer listen(int port);

  
Like listen(int) but supplying a handler that will be called when the server is actually listening (or has failed). 
Params:
port –  the port to listen on
listenHandler –  the listen handler/**
   * Like {@link #listen(int)} but supplying a handler that will be called when the server is actually listening (or has failed).
   *
   * @param port  the port to listen on
   * @param listenHandler  the listen handler
   */
  @Fluent
  HttpServer listen(int port, Handler<AsyncResult<HttpServer>> listenHandler);

  
Like listen but supplying a handler that will be called when the server is actually listening (or has failed). 
Params:
listenHandler –  the listen handler/**
   * Like {@link #listen} but supplying a handler that will be called when the server is actually listening (or has failed).
   *
   * @param listenHandler  the listen handler
   */
  @Fluent
  HttpServer listen(Handler<AsyncResult<HttpServer>> listenHandler);

  
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.
/**
   * Close the server. Any open HTTP connections will be closed.
   * <p>
   * The close happens asynchronously and the server may not be closed until some time after the call has returned.
   */
  void close();

  
Like close but supplying a handler that will be called when the server is actually closed (or has failed). 
Params:
completionHandler –  the handler/**
   * Like {@link #close} but supplying a handler that will be called when the server is actually closed (or has failed).
   *
   * @param completionHandler  the handler
   */
  void close(Handler<AsyncResult<Void>> completionHandler);

  
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./**
   * 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
   *
   * @return the actual port the server is listening on.
   */
  int actualPort();
}