/*
* Copyright (c) 2005, 2013, 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.
*/
Provides a simple high-level Http server API, which can be used to build
embedded HTTP servers. Both "http" and "https" are supported. The API provides
a partial implementation of RFC 2616 (HTTP 1.1)
and RFC 2818 (HTTP over TLS).
Any HTTP functionality not provided by this API can be implemented by application code
using the API.
Programmers must implement the HttpHandler interface. This interface provides a callback which is invoked to handle incoming requests from clients. A HTTP request and its response is known as an exchange. HTTP exchanges are represented by the HttpExchange class. The HttpServer class is used to listen for incoming TCP connections and it dispatches requests on these connections to handlers which have been registered with the server.
A minimal Http server example is shown below:
class MyHandler implements HttpHandler {
public void handle(HttpExchange t) throws IOException {
InputStream is = t.getRequestBody();
read(is); // .. read the request body
String response = "This is the response";
t.sendResponseHeaders(200, response.length());
OutputStream os = t.getResponseBody();
os.write(response.getBytes());
os.close();
}
}
...
HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
server.createContext("/applications/myapp", new MyHandler());
server.setExecutor(null); // creates a default executor
server.start();
The example above creates a simple HttpServer which uses the calling
application thread to invoke the handle() method for incoming http
requests directed to port 8000, and to the path /applications/myapp/.
The HttpExchange class encapsulates everything an application needs to process incoming requests and to generate appropriate responses.
Registering a handler with a HttpServer creates a HttpContext object and Filter objects can be added to the returned context. Filters are used to perform automatic pre- and post-processing of exchanges before they are passed to the exchange handler.
For sensitive information, a HttpsServer can be used to process "https" requests secured by the SSL or TLS protocols. A HttpsServer must be provided with a HttpsConfigurator object, which contains an initialized SSLContext. HttpsConfigurator can be used to configure the cipher suites and other SSL operating parameters. A simple example SSLContext could be created as follows:
char[] passphrase = "passphrase".toCharArray();
KeyStore ks = KeyStore.getInstance("JKS");
ks.load(new FileInputStream("testkeys"), passphrase);
KeyManagerFactory kmf = KeyManagerFactory.getInstance("SunX509");
kmf.init(ks, passphrase);
TrustManagerFactory tmf = TrustManagerFactory.getInstance("SunX509");
tmf.init(ks);
SSLContext ssl = SSLContext.getInstance("TLS");
ssl.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);
In the example above, a keystore file called "testkeys", created with the keytool utility
is used as a certificate store for client and server certificates.
The following code shows how the SSLContext is then used in a HttpsConfigurator
and how the SSLContext and HttpsConfigurator are linked to the HttpsServer.
server.setHttpsConfigurator (new HttpsConfigurator(sslContext) {
public void configure (HttpsParameters params) {
// get the remote address if needed
InetSocketAddress remote = params.getClientAddress();
SSLContext c = getSSLContext();
// get the default parameters
SSLParameters sslparams = c.getDefaultSSLParameters();
if (remote.equals (...) ) {
// modify the default set for client x
}
params.setSSLParameters(sslparams);
// statement above could throw IAE if any params invalid.
// eg. if app has a UI and parameters supplied by a user.
}
});
Since: 1.6
/**
Provides a simple high-level Http server API, which can be used to build
embedded HTTP servers. Both "http" and "https" are supported. The API provides
a partial implementation of RFC <a href="http://www.ietf.org/rfc/rfc2616.txt">2616</a> (HTTP 1.1)
and RFC <a href="http://www.ietf.org/rfc/rfc2818.txt">2818</a> (HTTP over TLS).
Any HTTP functionality not provided by this API can be implemented by application code
using the API.
<p>
Programmers must implement the {@link com.sun.net.httpserver.HttpHandler} interface. This interface
provides a callback which is invoked to handle incoming requests from clients.
A HTTP request and its response is known as an exchange. HTTP exchanges are
represented by the {@link com.sun.net.httpserver.HttpExchange} class.
The {@link com.sun.net.httpserver.HttpServer} class is used to listen for incoming TCP connections
and it dispatches requests on these connections to handlers which have been
registered with the server.
<p>
A minimal Http server example is shown below:
<blockquote><pre>
class MyHandler implements HttpHandler {
public void handle(HttpExchange t) throws IOException {
InputStream is = t.getRequestBody();
read(is); // .. read the request body
String response = "This is the response";
t.sendResponseHeaders(200, response.length());
OutputStream os = t.getResponseBody();
os.write(response.getBytes());
os.close();
}
}
...
HttpServer server = HttpServer.create(new InetSocketAddress(8000), 0);
server.createContext("/applications/myapp", new MyHandler());
server.setExecutor(null); // creates a default executor
server.start();
</pre></blockquote>
<p>The example above creates a simple HttpServer which uses the calling
application thread to invoke the handle() method for incoming http
requests directed to port 8000, and to the path /applications/myapp/.
<p>
The {@link com.sun.net.httpserver.HttpExchange} class encapsulates everything an application needs to
process incoming requests and to generate appropriate responses.
<p>
Registering a handler with a HttpServer creates a {@link com.sun.net.httpserver.HttpContext} object and
{@link com.sun.net.httpserver.Filter}
objects can be added to the returned context. Filters are used to perform automatic pre- and
post-processing of exchanges before they are passed to the exchange handler.
<p>
For sensitive information, a {@link com.sun.net.httpserver.HttpsServer} can
be used to process "https" requests secured by the SSL or TLS protocols.
A HttpsServer must be provided with a
{@link com.sun.net.httpserver.HttpsConfigurator} object, which contains an
initialized {@link javax.net.ssl.SSLContext}.
HttpsConfigurator can be used to configure the
cipher suites and other SSL operating parameters.
A simple example SSLContext could be created as follows:
<blockquote><pre>
char[] passphrase = "passphrase".toCharArray();
KeyStore ks = KeyStore.getInstance("JKS");
ks.load(new FileInputStream("testkeys"), passphrase);
KeyManagerFactory kmf = KeyManagerFactory.getInstance("SunX509");
kmf.init(ks, passphrase);
TrustManagerFactory tmf = TrustManagerFactory.getInstance("SunX509");
tmf.init(ks);
SSLContext ssl = SSLContext.getInstance("TLS");
ssl.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);
</pre></blockquote>
<p>
In the example above, a keystore file called "testkeys", created with the keytool utility
is used as a certificate store for client and server certificates.
The following code shows how the SSLContext is then used in a HttpsConfigurator
and how the SSLContext and HttpsConfigurator are linked to the HttpsServer.
<blockquote><pre>
server.setHttpsConfigurator (new HttpsConfigurator(sslContext) {
public void configure (HttpsParameters params) {
// get the remote address if needed
InetSocketAddress remote = params.getClientAddress();
SSLContext c = getSSLContext();
// get the default parameters
SSLParameters sslparams = c.getDefaultSSLParameters();
if (remote.equals (...) ) {
// modify the default set for client x
}
params.setSSLParameters(sslparams);
// statement above could throw IAE if any params invalid.
// eg. if app has a UI and parameters supplied by a user.
}
});
</pre></blockquote>
@since 1.6
*/
package com.sun.net.httpserver;