1 /*
   2  * Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.net.httpserver;
  27 
  28 import java.net.*;
  29 import java.io.*;
  30 import java.nio.*;
  31 import java.security.*;
  32 import java.nio.channels.*;
  33 import java.util.*;
  34 import java.util.concurrent.*;
  35 import javax.net.ssl.*;
  36 import com.sun.net.httpserver.spi.HttpServerProvider;
  37 
  38 /**
  39  * This class implements a simple HTTP server. A HttpServer is bound to an IP address
  40  * and port number and listens for incoming TCP connections from clients on this address.
  41  * The sub-class {@link HttpsServer} implements a server which handles HTTPS requests.
  42  * <p>
  43  * One or more {@link HttpHandler} objects must be associated with a server
  44  * in order to process requests. Each such HttpHandler is registered
  45  * with a root URI path which represents the
  46  * location of the application or service on this server. The mapping of a handler
  47  * to a HttpServer is encapsulated by a {@link HttpContext} object. HttpContexts
  48  * are created by calling {@link #createContext(String,HttpHandler)}.
  49  * Any request for which no handler can be found is rejected with a 404 response.
  50  * Management of threads can be done external to this object by providing a
  51  * {@link java.util.concurrent.Executor} object. If none is provided a default
  52  * implementation is used.
  53  * <p>
  54  * <a id="mapping_description"></a>
  55  * <b>Mapping request URIs to HttpContext paths</b><p>
  56  * When a HTTP request is received,
  57  * the appropriate HttpContext (and handler) is located by finding the context
  58  * whose path is the longest matching prefix of the request URI's path.
  59  * Paths are matched literally, which means that the strings are compared
  60  * case sensitively, and with no conversion to or from any encoded forms.
  61  * For example. Given a HttpServer with the following HttpContexts configured.
  62  * <table class="striped"><caption style="display:none">description</caption>
  63  * <thead>
  64  * <tr><th scope="col"><i>Context</i></th><th scope="col"><i>Context path</i></th></tr>
  65  * </thead>
  66  * <tbody>
  67  * <tr><th scope="row">ctx1</th><td>"/"</td></tr>
  68  * <tr><th scope="row">ctx2</th><td>"/apps/"</td></tr>
  69  * <tr><th scope="row">ctx3</th><td>"/apps/foo/"</td></tr>
  70  * </tbody>
  71  * </table>
  72  * <p>
  73  * the following table shows some request URIs and which, if any context they would
  74  * match with.
  75  * <table class="striped"><caption style="display:none">description</caption>
  76  * <thead>
  77  * <tr><th scope="col"><i>Request URI</i></th><th scope="col"><i>Matches context</i></th></tr>
  78  * </thead>
  79  * <tbody>
  80  * <tr><th scope="row">"http://foo.com/apps/foo/bar"</th><td>ctx3</td></tr>
  81  * <tr><th scope="row">"http://foo.com/apps/Foo/bar"</th><td>no match, wrong case</td></tr>
  82  * <tr><th scope="row">"http://foo.com/apps/app1"</th><td>ctx2</td></tr>
  83  * <tr><th scope="row">"http://foo.com/foo"</th><td>ctx1</td></tr>
  84  * </tbody>
  85  * </table>
  86  * <p>
  87  * <b>Note about socket backlogs</b><p>
  88  * When binding to an address and port number, the application can also specify an integer
  89  * <i>backlog</i> parameter. This represents the maximum number of incoming TCP connections
  90  * which the system will queue internally. Connections are queued while they are waiting to
  91  * be accepted by the HttpServer. When the limit is reached, further connections may be
  92  * rejected (or possibly ignored) by the underlying TCP implementation. Setting the right
  93  * backlog value is a compromise between efficient resource usage in the TCP layer (not setting
  94  * it too high) and allowing adequate throughput of incoming requests (not setting it too low).
  95  * @since 1.6
  96  */
  97 
  98 public abstract class HttpServer {
  99 
 100     /**
 101      */
 102     protected HttpServer () {
 103     }
 104 
 105     /**
 106      * creates a HttpServer instance which is initially not bound to any local address/port.
 107      * The HttpServer is acquired from the currently installed {@link HttpServerProvider}
 108      * The server must be bound using {@link #bind(InetSocketAddress,int)} before it can be used.
 109      * @throws IOException
 110      */
 111     public static HttpServer create () throws IOException {
 112         return create (null, 0);
 113     }
 114 
 115     /**
 116      * Create a <code>HttpServer</code> instance which will bind to the
 117      * specified {@link java.net.InetSocketAddress} (IP address and port number)
 118      *
 119      * A maximum backlog can also be specified. This is the maximum number of
 120      * queued incoming connections to allow on the listening socket.
 121      * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.
 122      * The HttpServer is acquired from the currently installed {@link HttpServerProvider}
 123      *
 124      * @param addr the address to listen on, if <code>null</code> then bind() must be called
 125      *  to set the address
 126      * @param backlog the socket backlog. If this value is less than or equal to zero,
 127      *          then a system default value is used.
 128      * @throws BindException if the server cannot bind to the requested address,
 129      *          or if the server is already bound.
 130      * @throws IOException
 131      */
 132 
 133     public static HttpServer create (
 134         InetSocketAddress addr, int backlog
 135     ) throws IOException {
 136         HttpServerProvider provider = HttpServerProvider.provider();
 137         return provider.createHttpServer (addr, backlog);
 138     }
 139 
 140     /**
 141      * Binds a currently unbound HttpServer to the given address and port number.
 142      * A maximum backlog can also be specified. This is the maximum number of
 143      * queued incoming connections to allow on the listening socket.
 144      * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.
 145      * @param addr the address to listen on
 146      * @param backlog the socket backlog. If this value is less than or equal to zero,
 147      *          then a system default value is used.
 148      * @throws BindException if the server cannot bind to the requested address or if the server
 149      *          is already bound.
 150      * @throws NullPointerException if addr is <code>null</code>
 151      */
 152     public abstract void bind (InetSocketAddress addr, int backlog) throws IOException;
 153 
 154     /**
 155      * Starts this server in a new background thread. The background thread
 156      * inherits the priority, thread group and context class loader
 157      * of the caller.
 158      */
 159     public abstract void start () ;
 160 
 161     /**
 162      * sets this server's {@link java.util.concurrent.Executor} object. An
 163      * Executor must be established before {@link #start()} is called.
 164      * All HTTP requests are handled in tasks given to the executor.
 165      * If this method is not called (before start()) or if it is
 166      * called with a <code>null</code> Executor, then
 167      * a default implementation is used, which uses the thread
 168      * which was created by the {@link #start()} method.
 169      * @param executor the Executor to set, or <code>null</code> for  default
 170      *          implementation
 171      * @throws IllegalStateException if the server is already started
 172      */
 173     public abstract void setExecutor (Executor executor);
 174 
 175 
 176     /**
 177      * returns this server's Executor object if one was specified with
 178      * {@link #setExecutor(Executor)}, or <code>null</code> if none was
 179      * specified.
 180      * @return the Executor established for this server or <code>null</code> if not set.
 181      */
 182     public abstract Executor getExecutor () ;
 183 
 184     /**
 185      * stops this server by closing the listening socket and disallowing
 186      * any new exchanges from being processed. The method will then block
 187      * until all current exchange handlers have completed or else when
 188      * approximately <i>delay</i> seconds have elapsed (whichever happens
 189      * sooner). Then, all open TCP connections are closed, the background
 190      * thread created by start() exits, and the method returns.
 191      * Once stopped, a HttpServer cannot be re-used.
 192      *
 193      * @param delay the maximum time in seconds to wait until exchanges have finished.
 194      * @throws IllegalArgumentException if delay is less than zero.
 195      */
 196     public abstract void stop (int delay);
 197 
 198     /**
 199      * Creates a HttpContext. A HttpContext represents a mapping from a
 200      * URI path to a exchange handler on this HttpServer. Once created, all requests
 201      * received by the server for the path will be handled by calling
 202      * the given handler object. The context is identified by the path, and
 203      * can later be removed from the server using this with the {@link #removeContext(String)} method.
 204      * <p>
 205      * The path specifies the root URI path for this context. The first character of path must be
 206      * '/'. <p>
 207      * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>
 208      * to HttpContext instances.
 209      * @param path the root URI path to associate the context with
 210      * @param handler the handler to invoke for incoming requests.
 211      * @throws IllegalArgumentException if path is invalid, or if a context
 212      *          already exists for this path
 213      * @throws NullPointerException if either path, or handler are <code>null</code>
 214      */
 215     public abstract HttpContext createContext (String path, HttpHandler handler) ;
 216 
 217     /**
 218      * Creates a HttpContext without initially specifying a handler. The handler must later be specified using
 219      * {@link HttpContext#setHandler(HttpHandler)}.  A HttpContext represents a mapping from a
 220      * URI path to an exchange handler on this HttpServer. Once created, and when
 221      * the handler has been set, all requests
 222      * received by the server for the path will be handled by calling
 223      * the handler object. The context is identified by the path, and
 224      * can later be removed from the server using this with the {@link #removeContext(String)} method.
 225      * <p>
 226      * The path specifies the root URI path for this context. The first character of path must be
 227      * '/'. <p>
 228      * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>
 229      * to HttpContext instances.
 230      * @param path the root URI path to associate the context with
 231      * @throws IllegalArgumentException if path is invalid, or if a context
 232      *          already exists for this path
 233      * @throws NullPointerException if path is <code>null</code>
 234      */
 235     public abstract HttpContext createContext (String path) ;
 236 
 237     /**
 238      * Removes the context identified by the given path from the server.
 239      * Removing a context does not affect exchanges currently being processed
 240      * but prevents new ones from being accepted.
 241      * @param path the path of the handler to remove
 242      * @throws IllegalArgumentException if no handler corresponding to this
 243      *          path exists.
 244      * @throws NullPointerException if path is <code>null</code>
 245      */
 246     public abstract void removeContext (String path) throws IllegalArgumentException ;
 247 
 248     /**
 249      * Removes the given context from the server.
 250      * Removing a context does not affect exchanges currently being processed
 251      * but prevents new ones from being accepted.
 252      * @param context the context to remove
 253      * @throws NullPointerException if context is <code>null</code>
 254      */
 255     public abstract void removeContext (HttpContext context) ;
 256 
 257     /**
 258      * returns the address this server is listening on
 259      * @return the address/port number the server is listening on
 260      */
 261     public abstract InetSocketAddress getAddress() ;
 262 }