/*
 *  Copyright (c) 2011-2015 The original author or authors
 *  ------------------------------------------------------
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *       The Eclipse Public License is available at
 *       http://www.eclipse.org/legal/epl-v10.html
 *
 *       The Apache License v2.0 is available at
 *       http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

package io.vertx.ext.stomp;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.Vertx;
import io.vertx.core.http.ServerWebSocket;
import io.vertx.core.net.NetServer;
import io.vertx.ext.stomp.impl.StompServerImpl;

Defines a STOMP server. STOMP servers delegates to a StompServerHandler that let customize the behavior of the server. By default, it uses a handler compliant with the STOMP specification, but let you change anything. 
Author:
Clement Escoffier/**
 * Defines a STOMP server. STOMP servers delegates to a {@link StompServerHandler} that let customize the behavior of
 * the server. By default, it uses a handler compliant with the STOMP specification, but let you change anything.
 *
 * @author <a href="http://escoffier.me">Clement Escoffier</a>
 */
@VertxGen
public interface StompServer {

  
Creates a StompServer based on the default Stomp Server implementation. 
Params:
vertx –   the vert.x instance to use
options – the server options
Returns:
the created StompServer/**
   * Creates a {@link StompServer} based on the default Stomp Server implementation.
   *
   * @param vertx   the vert.x instance to use
   * @param options the server options
   * @return the created {@link StompServer}
   */
  static StompServer create(Vertx vertx, StompServerOptions options) {
    return new StompServerImpl(vertx, null, options);
  }

  
Creates a StompServer based on the default Stomp Server implementation. 
Params:
vertx –     the vert.x instance to use
netServer – the Net server used by the STOMP server
Returns:
the created StompServer/**
   * Creates a {@link StompServer} based on the default Stomp Server implementation.
   *
   * @param vertx     the vert.x instance to use
   * @param netServer the Net server used by the STOMP server
   * @return the created {@link StompServer}
   */
  static StompServer create(Vertx vertx, NetServer netServer) {
    return new StompServerImpl(vertx, netServer, new StompServerOptions());
  }

  
Creates a StompServer based on the default Stomp Server implementation. 
Params:
vertx –   the vert.x instance to use
net –     the Net server used by the STOMP server
options – the server options
Returns:
the created StompServer/**
   * Creates a {@link StompServer} based on the default Stomp Server implementation.
   *
   * @param vertx   the vert.x instance to use
   * @param net     the Net server used by the STOMP server
   * @param options the server options
   * @return the created {@link StompServer}
   */
  static StompServer create(Vertx vertx, NetServer net, StompServerOptions options) {
    return new StompServerImpl(vertx, net, options);
  }

  
Creates a StompServer based on the default Stomp Server implementation, and use the default options. 
Params:
vertx – the vert.x instance to use
Returns:
the created StompServer/**
   * Creates a {@link StompServer} based on the default Stomp Server implementation, and use the default options.
   *
   * @param vertx the vert.x instance to use
   * @return the created {@link StompServer}
   */
  static StompServer create(Vertx vertx) {
    return create(vertx, new StompServerOptions());
  }

  
Configures the StompServerHandler. You must calls this method before calling the listen() method. 
Params:
handler – the handler
Returns:
the current StompServer/**
   * Configures the {@link StompServerHandler}. You must calls this method before calling the {@link #listen()} method.
   *
   * @param handler the handler
   * @return the current {@link StompServer}
   */
  @Fluent
  StompServer handler(StompServerHandler handler);

  
Connects the STOMP server to the given port.
Params:
port – the port
Returns:
a future resolved with the listen result/**
   * Connects the STOMP server to the given port.
   *
   * @param port the port
   * @return a future resolved with the listen result
   */
  Future<StompServer> listen(int port);

  
Connects the STOMP server to the given port / interface.
Params:
port – the port
host – the interface
Returns:
a future resolved with the listen result/**
   * Connects the STOMP server to the given port / interface.
   *
   * @param port the port
   * @param host the interface
   * @return a future resolved with the listen result
   */
  Future<StompServer> listen(int port, String host);

  
Connects the STOMP server to the port / host configured in the server options.
Returns:
a future resolved with the listen result/**
   * Connects the STOMP server to the port / host configured in the server options.
   *
   * @return a future resolved with the listen result
   */
  Future<StompServer> listen();


  
Connects the STOMP server default port (61613) and network interface (0.0.0.0). Once the socket it bounds calls the given handler with the result. The result may be a failure if the socket is already used. 
Params:
handler – the handler to call with the result
Returns:
the current StompServer/**
   * Connects the STOMP server default port (61613) and network interface ({@code 0.0.0.0}). Once the socket
   * it bounds calls the given handler with the result. The result may be a failure if the socket is already used.
   *
   * @param handler the handler to call with the result
   * @return the current {@link StompServer}
   */
  @Fluent
  StompServer listen(Handler<AsyncResult<StompServer>> handler);

  
Connects the STOMP server to the given port. This method use the default host (0.0.0.0). Once the socket it bounds calls the given handler with the result. The result may be a failure if the socket is already used. 
Params:
port –    the port
handler – the handler to call with the result
Returns:
the current StompServer/**
   * Connects the STOMP server to the given port. This method use the default host ({@code 0.0.0.0}). Once the socket
   * it bounds calls the given handler with the result. The result may be a failure if the socket is already used.
   *
   * @param port    the port
   * @param handler the handler to call with the result
   * @return the current {@link StompServer}
   */
  @Fluent
  StompServer listen(int port, Handler<AsyncResult<StompServer>> handler);

  
Connects the STOMP server to the given port / interface. Once the socket it bounds calls the given handler with
the result. The result may be a failure if the socket is already used.
Params:
port –    the port
host –    the host / interface
handler – the handler to call with the result
Returns:
the current StompServer/**
   * Connects the STOMP server to the given port / interface. Once the socket it bounds calls the given handler with
   * the result. The result may be a failure if the socket is already used.
   *
   * @param port    the port
   * @param host    the host / interface
   * @param handler the handler to call with the result
   * @return the current {@link StompServer}
   */
  @Fluent
  StompServer listen(int port, String host, Handler<AsyncResult<StompServer>> handler);

  
Closes the server.
Params:
completionHandler – handler called once the server has been stopped/**
   * Closes the server.
   *
   * @param completionHandler handler called once the server has been stopped
   */
  void close(Handler<AsyncResult<Void>> completionHandler);

  
Closes the server.
/**
   * Closes the server.
   */
  Future<Void> close();

  
Checks whether or not the server is listening.
Returns:
true if the server is listening, false otherwise/**
   * Checks whether or not the server is listening.
   *
   * @return {@code true} if the server is listening, {@code false} otherwise
   */
  boolean isListening();

  
Gets the port on which the server is listening.

This is useful if you bound the server specifying 0 as port number signifying an ephemeral port.
See Also:
NetServer.actualPort()
Returns:
the port/**
   * Gets the port on which the server is listening.
   * <p/>
   * This is useful if you bound the server specifying 0 as port number signifying an ephemeral port.
   *
   * @return the port
   * @see NetServer#actualPort()
   */
  int actualPort();

  
Returns:
the server options/**
   * @return the server options
   */
  StompServerOptions options();

  
Returns:
the instance of vert.x used by the server./**
   * @return the instance of vert.x used by the server.
   */
  Vertx vertx();

  
Returns:
the StompServerHandler used by this server./**
   * @return the {@link StompServerHandler} used by this server.
   */
  StompServerHandler stompHandler();

  
Gets the Handler able to manage web socket connections. If the web socket bridge is disabled, it returns null. 
Returns:
the handler that can be passed to HttpServer.webSocketHandler(Handler<ServerWebSocket>)./**
   * Gets the {@link Handler} able to manage web socket connections. If the web socket bridge is disabled, it returns
   * {@code null}.
   *
   * @return the handler that can be passed to {@link io.vertx.core.http.HttpServer#webSocketHandler(Handler)}.
   */
  Handler<ServerWebSocket> webSocketHandler();

  
Configures the handler that is invoked every time a frame is going to be written to the "wire". It lets you log
the frames, but also adapt the frame if needed.
Params:
handler – the handler, must not be null
Returns:
the current StompServer/**
   * Configures the handler that is invoked every time a frame is going to be written to the "wire". It lets you log
   * the frames, but also adapt the frame if needed.
   *
   * @param handler the handler, must not be {@code null}
   * @return the current {@link StompServer}
   */
  @Fluent
  StompServer writingFrameHandler(Handler<ServerFrame> handler);


}