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.<p>
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.<p>
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
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. <p>
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
|
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
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
|