/*

 * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package com.sun.net.httpserver;

import java.net.*;

import java.io.*;

import java.nio.*;

import java.security.*;

import java.nio.channels.*;

import java.util.*;

import java.util.concurrent.*;

import javax.net.ssl.*;

import com.sun.net.httpserver.spi.HttpServerProvider;

/**

 * This class implements a simple HTTP server. A HttpServer is bound to an IP address

 * and port number and listens for incoming TCP connections from clients on this address.

 * The sub-class {@link HttpsServer} implements a server which handles HTTPS requests.

 * <p>

 * One or more {@link HttpHandler} objects must be associated with a server

 * in order to process requests. Each such HttpHandler is registered

 * with a root URI path which represents the

 * location of the application or service on this server. The mapping of a handler

 * to a HttpServer is encapsulated by a {@link HttpContext} object. HttpContexts

 * are created by calling {@link #createContext(String,HttpHandler)}.

 * Any request for which no handler can be found is rejected with a 404 response.

 * Management of threads can be done external to this object by providing a

 * {@link java.util.concurrent.Executor} object. If none is provided a default

 * implementation is used.

 * <p>

 * <a name="mapping_description"></a>

 * <b>Mapping request URIs to HttpContext paths</b><p>

 * When a HTTP request is received,

 * the appropriate HttpContext (and handler) is located by finding the context

 * whose path is the longest matching prefix of the request URI's path.

 * Paths are matched literally, which means that the strings are compared

 * case sensitively, and with no conversion to or from any encoded forms.

 * For example. Given a HttpServer with the following HttpContexts configured.<p>

 * <table >

 * <tr><td><i>Context</i></td><td><i>Context path</i></td></tr>

 * <tr><td>ctx1</td><td>"/"</td></tr>

 * <tr><td>ctx2</td><td>"/apps/"</td></tr>

 * <tr><td>ctx3</td><td>"/apps/foo/"</td></tr>

 * </table>

 * <p>

 * the following table shows some request URIs and which, if any context they would

 * match with.<p>

 * <table>

 * <tr><td><i>Request URI</i></td><td><i>Matches context</i></td></tr>

 * <tr><td>"http://foo.com/apps/foo/bar"</td><td>ctx3</td></tr>

 * <tr><td>"http://foo.com/apps/Foo/bar"</td><td>no match, wrong case</td></tr>

 * <tr><td>"http://foo.com/apps/app1"</td><td>ctx2</td></tr>

 * <tr><td>"http://foo.com/foo"</td><td>ctx1</td></tr>

 * </table>

 * <p>

 * <b>Note about socket backlogs</b><p>

 * When binding to an address and port number, the application can also specify an integer

 * <i>backlog</i> parameter. This represents the maximum number of incoming TCP connections

 * which the system will queue internally. Connections are queued while they are waiting to

 * be accepted by the HttpServer. When the limit is reached, further connections may be

 * rejected (or possibly ignored) by the underlying TCP implementation. Setting the right

 * backlog value is a compromise between efficient resource usage in the TCP layer (not setting

 * it too high) and allowing adequate throughput of incoming requests (not setting it too low).

 * @since 1.6

 */

public abstract class HttpServer {

    /**

     */

    protected HttpServer () {

    }

    /**

     * creates a HttpServer instance which is initially not bound to any local address/port.

     * The HttpServer is acquired from the currently installed {@link HttpServerProvider}

     * The server must be bound using {@link #bind(InetSocketAddress,int)} before it can be used.

     * @throws IOException

     */

    public static HttpServer create () throws IOException {

        return create (null, 0);

    }

    /**

     * Create a <code>HttpServer</code> instance which will bind to the

     * specified {@link java.net.InetSocketAddress} (IP address and port number)

     *

     * A maximum backlog can also be specified. This is the maximum number of

     * queued incoming connections to allow on the listening socket.

     * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.

     * The HttpServer is acquired from the currently installed {@link HttpServerProvider}

     *

     * @param addr the address to listen on, if <code>null</code> then bind() must be called

     *  to set the address

     * @param backlog the socket backlog. If this value is less than or equal to zero,

     *          then a system default value is used.

     * @throws BindException if the server cannot bind to the requested address,

     *          or if the server is already bound.

     * @throws IOException

     */

    public static HttpServer create (

        InetSocketAddress addr, int backlog

    ) throws IOException {

        HttpServerProvider provider = HttpServerProvider.provider();

        return provider.createHttpServer (addr, backlog);

    }

    /**

     * Binds a currently unbound HttpServer to the given address and port number.

     * A maximum backlog can also be specified. This is the maximum number of

     * queued incoming connections to allow on the listening socket.

     * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.

     * @param addr the address to listen on

     * @param backlog the socket backlog. If this value is less than or equal to zero,

     *          then a system default value is used.

     * @throws BindException if the server cannot bind to the requested address or if the server

     *          is already bound.

     * @throws NullPointerException if addr is <code>null</code>

     */

    public abstract void bind (InetSocketAddress addr, int backlog) throws IOException;

    /**

     * Starts this server in a new background thread. The background thread

     * inherits the priority, thread group and context class loader

     * of the caller.

     */

    public abstract void start () ;

    /**

     * sets this server's {@link java.util.concurrent.Executor} object. An

     * Executor must be established before {@link #start()} is called.

     * All HTTP requests are handled in tasks given to the executor.

     * If this method is not called (before start()) or if it is

     * called with a <code>null</code> Executor, then

     * a default implementation is used, which uses the thread

     * which was created by the {@link #start()} method.

     * @param executor the Executor to set, or <code>null</code> for  default

     *          implementation

     * @throws IllegalStateException if the server is already started

     */

    public abstract void setExecutor (Executor executor);

    /**

     * returns this server's Executor object if one was specified with

     * {@link #setExecutor(Executor)}, or <code>null</code> if none was

     * specified.

     * @return the Executor established for this server or <code>null</code> if not set.

     */

    public abstract Executor getExecutor () ;

    /**

     * stops this server by closing the listening socket and disallowing

     * any new exchanges from being processed. The method will then block

     * until all current exchange handlers have completed or else when

     * approximately <i>delay</i> seconds have elapsed (whichever happens

     * sooner). Then, all open TCP connections are closed, the background

     * thread created by start() exits, and the method returns.

     * Once stopped, a HttpServer cannot be re-used. <p>

     *

     * @param delay the maximum time in seconds to wait until exchanges have finished.

     * @throws IllegalArgumentException if delay is less than zero.

     */

    public abstract void stop (int delay);

    /**

     * Creates a HttpContext. A HttpContext represents a mapping from a

     * URI path to a exchange handler on this HttpServer. Once created, all requests

     * received by the server for the path will be handled by calling

     * the given handler object. The context is identified by the path, and

     * can later be removed from the server using this with the {@link #removeContext(String)} method.

     * <p>

     * The path specifies the root URI path for this context. The first character of path must be

     * '/'. <p>

     * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>

     * to HttpContext instances.

     * @param path the root URI path to associate the context with

     * @param handler the handler to invoke for incoming requests.

     * @throws IllegalArgumentException if path is invalid, or if a context

     *          already exists for this path

     * @throws NullPointerException if either path, or handler are <code>null</code>

     */

    public abstract HttpContext createContext (String path, HttpHandler handler) ;

    /**

     * Creates a HttpContext without initially specifying a handler. The handler must later be specified using

     * {@link HttpContext#setHandler(HttpHandler)}.  A HttpContext represents a mapping from a

     * URI path to an exchange handler on this HttpServer. Once created, and when

     * the handler has been set, all requests

     * received by the server for the path will be handled by calling

     * the handler object. The context is identified by the path, and

     * can later be removed from the server using this with the {@link #removeContext(String)} method.

     * <p>

     * The path specifies the root URI path for this context. The first character of path must be

     * '/'. <p>

     * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>

     * to HttpContext instances.

     * @param path the root URI path to associate the context with

     * @throws IllegalArgumentException if path is invalid, or if a context

     *          already exists for this path

     * @throws NullPointerException if path is <code>null</code>

     */

    public abstract HttpContext createContext (String path) ;

    /**

     * Removes the context identified by the given path from the server.

     * Removing a context does not affect exchanges currently being processed

     * but prevents new ones from being accepted.

     * @param path the path of the handler to remove

     * @throws IllegalArgumentException if no handler corresponding to this

     *          path exists.

     * @throws NullPointerException if path is <code>null</code>

     */

    public abstract void removeContext (String path) throws IllegalArgumentException ;

    /**

     * Removes the given context from the server.

     * Removing a context does not affect exchanges currently being processed

     * but prevents new ones from being accepted.

     * @param context the context to remove

     * @throws NullPointerException if context is <code>null</code>

     */

    public abstract void removeContext (HttpContext context) ;

    /**

     * returns the address this server is listening on

     * @return the address/port number the server is listening on

     */

    public abstract InetSocketAddress getAddress() ;

}