History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/com/sun/net/httpserver/HttpServer.java (1 of 18352 files). Show all

Unified · Split

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