1 /*
2 * Copyright (c) 2005, 2013, 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 name="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>
63 * <tr><td><i>Context</i></td><td><i>Context path</i></td></tr>
64 * <tr><td>ctx1</td><td>"/"</td></tr>
65 * <tr><td>ctx2</td><td>"/apps/"</td></tr>
66 * <tr><td>ctx3</td><td>"/apps/foo/"</td></tr>
67 * </table>
68 * <p>
69 * the following table shows some request URIs and which, if any context they would
70 * match with.
71 * <table>
72 * <tr><td><i>Request URI</i></td><td><i>Matches context</i></td></tr>
73 * <tr><td>"http://foo.com/apps/foo/bar"</td><td>ctx3</td></tr>
74 * <tr><td>"http://foo.com/apps/Foo/bar"</td><td>no match, wrong case</td></tr>
75 * <tr><td>"http://foo.com/apps/app1"</td><td>ctx2</td></tr>
76 * <tr><td>"http://foo.com/foo"</td><td>ctx1</td></tr>
77 * </table>
78 * <p>
79 * <b>Note about socket backlogs</b><p>
80 * When binding to an address and port number, the application can also specify an integer
81 * <i>backlog</i> parameter. This represents the maximum number of incoming TCP connections
82 * which the system will queue internally. Connections are queued while they are waiting to
83 * be accepted by the HttpServer. When the limit is reached, further connections may be
84 * rejected (or possibly ignored) by the underlying TCP implementation. Setting the right
85 * backlog value is a compromise between efficient resource usage in the TCP layer (not setting
86 * it too high) and allowing adequate throughput of incoming requests (not setting it too low).
87 * @since 1.6
88 */
89
90 @jdk.Exported
91 public abstract class HttpServer {
92
93 /**
94 */
95 protected HttpServer () {
96 }
97
98 /**
99 * creates a HttpServer instance which is initially not bound to any local address/port.
100 * The HttpServer is acquired from the currently installed {@link HttpServerProvider}
101 * The server must be bound using {@link #bind(InetSocketAddress,int)} before it can be used.
102 * @throws IOException
103 */
104 public static HttpServer create () throws IOException {
105 return create (null, 0);
106 }
107
108 /**
109 * Create a <code>HttpServer</code> instance which will bind to the
110 * specified {@link java.net.InetSocketAddress} (IP address and port number)
111 *
112 * A maximum backlog can also be specified. This is the maximum number of
113 * queued incoming connections to allow on the listening socket.
114 * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.
115 * The HttpServer is acquired from the currently installed {@link HttpServerProvider}
116 *
117 * @param addr the address to listen on, if <code>null</code> then bind() must be called
118 * to set the address
119 * @param backlog the socket backlog. If this value is less than or equal to zero,
120 * then a system default value is used.
121 * @throws BindException if the server cannot bind to the requested address,
122 * or if the server is already bound.
123 * @throws IOException
124 */
125
126 public static HttpServer create (
127 InetSocketAddress addr, int backlog
128 ) throws IOException {
129 HttpServerProvider provider = HttpServerProvider.provider();
130 return provider.createHttpServer (addr, backlog);
131 }
132
133 /**
134 * Binds a currently unbound HttpServer to the given address and port number.
135 * A maximum backlog can also be specified. This is the maximum number of
136 * queued incoming connections to allow on the listening socket.
137 * Queued TCP connections exceeding this limit may be rejected by the TCP implementation.
138 * @param addr the address to listen on
139 * @param backlog the socket backlog. If this value is less than or equal to zero,
140 * then a system default value is used.
141 * @throws BindException if the server cannot bind to the requested address or if the server
142 * is already bound.
143 * @throws NullPointerException if addr is <code>null</code>
144 */
145 public abstract void bind (InetSocketAddress addr, int backlog) throws IOException;
146
147 /**
148 * Starts this server in a new background thread. The background thread
149 * inherits the priority, thread group and context class loader
150 * of the caller.
151 */
152 public abstract void start () ;
153
154 /**
155 * sets this server's {@link java.util.concurrent.Executor} object. An
156 * Executor must be established before {@link #start()} is called.
157 * All HTTP requests are handled in tasks given to the executor.
158 * If this method is not called (before start()) or if it is
159 * called with a <code>null</code> Executor, then
160 * a default implementation is used, which uses the thread
161 * which was created by the {@link #start()} method.
162 * @param executor the Executor to set, or <code>null</code> for default
163 * implementation
164 * @throws IllegalStateException if the server is already started
165 */
166 public abstract void setExecutor (Executor executor);
167
168
169 /**
170 * returns this server's Executor object if one was specified with
171 * {@link #setExecutor(Executor)}, or <code>null</code> if none was
172 * specified.
173 * @return the Executor established for this server or <code>null</code> if not set.
174 */
175 public abstract Executor getExecutor () ;
176
177 /**
178 * stops this server by closing the listening socket and disallowing
179 * any new exchanges from being processed. The method will then block
180 * until all current exchange handlers have completed or else when
181 * approximately <i>delay</i> seconds have elapsed (whichever happens
182 * sooner). Then, all open TCP connections are closed, the background
183 * thread created by start() exits, and the method returns.
184 * Once stopped, a HttpServer cannot be re-used.
185 *
186 * @param delay the maximum time in seconds to wait until exchanges have finished.
187 * @throws IllegalArgumentException if delay is less than zero.
188 */
189 public abstract void stop (int delay);
190
191 /**
192 * Creates a HttpContext. A HttpContext represents a mapping from a
193 * URI path to a exchange handler on this HttpServer. Once created, all requests
194 * received by the server for the path will be handled by calling
195 * the given handler object. The context is identified by the path, and
196 * can later be removed from the server using this with the {@link #removeContext(String)} method.
197 * <p>
198 * The path specifies the root URI path for this context. The first character of path must be
199 * '/'. <p>
200 * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>
201 * to HttpContext instances.
202 * @param path the root URI path to associate the context with
203 * @param handler the handler to invoke for incoming requests.
204 * @throws IllegalArgumentException if path is invalid, or if a context
205 * already exists for this path
206 * @throws NullPointerException if either path, or handler are <code>null</code>
207 */
208 public abstract HttpContext createContext (String path, HttpHandler handler) ;
209
210 /**
211 * Creates a HttpContext without initially specifying a handler. The handler must later be specified using
212 * {@link HttpContext#setHandler(HttpHandler)}. A HttpContext represents a mapping from a
213 * URI path to an exchange handler on this HttpServer. Once created, and when
214 * the handler has been set, all requests
215 * received by the server for the path will be handled by calling
216 * the handler object. The context is identified by the path, and
217 * can later be removed from the server using this with the {@link #removeContext(String)} method.
218 * <p>
219 * The path specifies the root URI path for this context. The first character of path must be
220 * '/'. <p>
221 * The class overview describes how incoming request URIs are <a href="#mapping_description">mapped</a>
222 * to HttpContext instances.
223 * @param path the root URI path to associate the context with
224 * @throws IllegalArgumentException if path is invalid, or if a context
225 * already exists for this path
226 * @throws NullPointerException if path is <code>null</code>
227 */
228 public abstract HttpContext createContext (String path) ;
229
230 /**
231 * Removes the context identified by the given path from the server.
232 * Removing a context does not affect exchanges currently being processed
233 * but prevents new ones from being accepted.
234 * @param path the path of the handler to remove
235 * @throws IllegalArgumentException if no handler corresponding to this
236 * path exists.
237 * @throws NullPointerException if path is <code>null</code>
238 */
239 public abstract void removeContext (String path) throws IllegalArgumentException ;
240
241 /**
242 * Removes the given context from the server.
243 * Removing a context does not affect exchanges currently being processed
244 * but prevents new ones from being accepted.
245 * @param context the context to remove
246 * @throws NullPointerException if context is <code>null</code>
247 */
248 public abstract void removeContext (HttpContext context) ;
249
250 /**
251 * returns the address this server is listening on
252 * @return the address/port number the server is listening on
253 */
254 public abstract InetSocketAddress getAddress() ;
255 }