- Direct Known Subclasses:
HttpsServer
HttpServer
is bound to an IP address
and port number and listens for incoming TCP connections from clients on this address.
The sub-class HttpsServer
implements a server which handles HTTPS requests.
One or more HttpHandler
objects must be associated with a server
in order to process requests. Each such HttpHandler
is registered with
a root URI path which represents the location of the application or service
on this server. The mapping of a handler to a HttpServer
is
encapsulated by a HttpContext
object. HttpContexts are created by
calling createContext(String,HttpHandler)
.
Any request for which no handler can be found is rejected with a 404 response.
Management of threads can be done external to this object by providing a
Executor
object. If none is provided a default
implementation is used.
Mapping request URIs to HttpContext paths
When a HTTP request is received, the appropriate HttpContext
(and handler) is located by finding the context whose path is the longest
matching prefix of the request URI's path. Paths are matched literally,
which means that the strings are compared case sensitively, and with no
conversion to or from any encoded forms. For example, given a HttpServer
with the following HttpContexts configured:
Context | Context path |
---|---|
ctx1 | "/" |
ctx2 | "/apps/" |
ctx3 | "/apps/foo/" |
The following table shows some request URIs and which, if any context they would match with:
Request URI | Matches context |
---|---|
"http://foo.com/apps/foo/bar" | ctx3 |
"http://foo.com/apps/Foo/bar" | no match, wrong case |
"http://foo.com/apps/app1" | ctx2 |
"http://foo.com/foo" | ctx1 |
Note about socket backlogs
When binding to an address and port number, the application can also
specify an integer backlog parameter. This represents the maximum
number of incoming TCP connections which the system will queue internally.
Connections are queued while they are waiting to be accepted by the
HttpServer
. When the limit is reached, further connections may be
rejected (or possibly ignored) by the underlying TCP implementation. Setting
the right backlog value is a compromise between efficient resource usage in
the TCP layer (not setting it too high) and allowing adequate throughput of
incoming requests (not setting it too low).
- Since:
- 1.6
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
bind
(InetSocketAddress addr, int backlog) Binds a currently unboundHttpServer
to the given address and port number.static HttpServer
create()
Creates aHttpServer
instance which is initially not bound to any local address/port.static HttpServer
create
(InetSocketAddress addr, int backlog) Create aHttpServer
instance which will bind to the specifiedInetSocketAddress
(IP address and port number).static HttpServer
create
(InetSocketAddress addr, int backlog, String path, HttpHandler handler, Filter... filters) Creates anHttpServer
instance with an initial context.abstract HttpContext
createContext
(String path) Creates a HttpContext without initially specifying a handler.abstract HttpContext
createContext
(String path, HttpHandler handler) Creates aHttpContext
.abstract InetSocketAddress
Returns the address this server is listening onabstract Executor
Returns this server'sExecutor
object if one was specified withsetExecutor(Executor)
, ornull
if none was specified.abstract void
removeContext
(HttpContext context) Removes the given context from the server.abstract void
removeContext
(String path) Removes the context identified by the given path from the server.abstract void
setExecutor
(Executor executor) Sets this server'sExecutor
object.abstract void
start()
Starts this server in a new background thread.abstract void
stop
(int delay) Stops this server by closing the listening socket and disallowing any new exchanges from being processed.
-
Constructor Details
-
HttpServer
protected HttpServer()Constructor for subclasses to call.
-
-
Method Details
-
create
Creates aHttpServer
instance which is initially not bound to any local address/port. TheHttpServer
is acquired from the currently installedHttpServerProvider
. The server must be bound usingbind(InetSocketAddress,int)
before it can be used.- Returns:
- an instance of
HttpServer
- Throws:
IOException
- if an I/O error occurs
-
create
Create aHttpServer
instance which will bind to the specifiedInetSocketAddress
(IP address and port number). A maximum backlog can also be specified. This is the maximum number of queued incoming connections to allow on the listening socket. Queued TCP connections exceeding this limit may be rejected by the TCP implementation. TheHttpServer
is acquired from the currently installedHttpServerProvider
- Parameters:
addr
- the address to listen on, ifnull
thenbind(InetSocketAddress, int)
must be called to set the addressbacklog
- the socket backlog. If this value is less than or equal to zero, then a system default value is used- Returns:
- an instance of
HttpServer
- Throws:
IOException
- if an I/O error occursBindException
- if the server cannot bind to the requested address, or if the server is already bound
-
create
public static HttpServer create(InetSocketAddress addr, int backlog, String path, HttpHandler handler, Filter... filters) throws IOException Creates anHttpServer
instance with an initial context.The server is created with an initial context that maps the URI
path
to the exchangehandler
. The initial context is created as if by an invocation ofcreateContext(path)
. Thefilters
, if any, are added to the initial context, in the order they are given. The returned server is not started so can be configured further if required.The server instance will bind to the given
InetSocketAddress
.A maximum backlog can also be specified. This is the maximum number of queued incoming connections to allow on the listening socket. Queued TCP connections exceeding this limit may be rejected by the TCP implementation. The HttpServer is acquired from the currently installed
HttpServerProvider
.- Parameters:
addr
- the address to listen on, ifnull
thenbind
must be called to set the addressbacklog
- the socket backlog. If this value is less than or equal to zero, then a system default value is usedpath
- the root URI path of the context, must be absolutehandler
- the HttpHandler for the contextfilters
- the Filters for the context, optional- Returns:
- the HttpServer
- Throws:
BindException
- if the server cannot bind to the addressIOException
- if an I/O error occursIllegalArgumentException
- if path is invalidNullPointerException
- if any of:path
,handler
,filters
, or any element offilters
, arenull
- Since:
- 18
-
bind
Binds a currently unboundHttpServer
to the given address and port number. A maximum backlog can also be specified. This is the maximum number of queued incoming connections to allow on the listening socket. Queued TCP connections exceeding this limit may be rejected by the TCP implementation.- Parameters:
addr
- the address to listen onbacklog
- the socket backlog. If this value is less than or equal to zero, then a system default value is used- Throws:
BindException
- if the server cannot bind to the requested address or if the server is already boundNullPointerException
- if addr isnull
IOException
-
start
public abstract void start()Starts this server in a new background thread. The background thread inherits the priority, thread group and context class loader of the caller. -
setExecutor
Sets this server'sExecutor
object. AnExecutor
must be established beforestart()
is called. All HTTP requests are handled in tasks given to the executor. If this method is not called (beforestart()
) or if it is called with anull Executor
, then a default implementation is used, which uses the thread which was created by thestart()
method.- Parameters:
executor
- theExecutor
to set, ornull
for default implementation- Throws:
IllegalStateException
- if the server is already started
-
getExecutor
Returns this server'sExecutor
object if one was specified withsetExecutor(Executor)
, ornull
if none was specified.- Returns:
- the
Executor
established for this server ornull
if not set.
-
stop
public abstract void stop(int delay) Stops this server by closing the listening socket and disallowing any new exchanges from being processed. The method will then block until all current exchange handlers have completed or else when approximately delay seconds have elapsed (whichever happens sooner). Then, all open TCP connections are closed, the background thread created bystart()
exits, and the method returns. Once stopped, aHttpServer
cannot be re-used.- Parameters:
delay
- the maximum time in seconds to wait until exchanges have finished- Throws:
IllegalArgumentException
- if delay is less than zero
-
createContext
Creates aHttpContext
. AHttpContext
represents a mapping from a URI path to a exchange handler on thisHttpServer
. Once created, all requests received by the server for the path will be handled by calling the given handler object. The context is identified by the path, and can later be removed from the server using this with theremoveContext(String)
method.The path specifies the root URI path for this context. The first character of path must be '/'.
The class overview describes how incoming request URIs are mapped to HttpContext instances.
- API Note:
- The path should generally, but is not required to, end with '/'.
If the path does not end with '/', eg such as with
"/foo"
then this would match requests with a path of"/foobar"
or"/foo/bar"
. - Parameters:
path
- the root URI path to associate the context withhandler
- the handler to invoke for incoming requests- Returns:
- an instance of
HttpContext
- Throws:
IllegalArgumentException
- if path is invalid, or if a context already exists for this pathNullPointerException
- if either path, or handler arenull
-
createContext
Creates a HttpContext without initially specifying a handler. The handler must later be specified usingHttpContext.setHandler(HttpHandler)
. AHttpContext
represents a mapping from a URI path to an exchange handler on thisHttpServer
. Once created, and when the handler has been set, all requests received by the server for the path will be handled by calling the handler object. The context is identified by the path, and can later be removed from the server using this with theremoveContext(String)
method.The path specifies the root URI path for this context. The first character of path must be '/'.
The class overview describes how incoming request URIs are mapped to
HttpContext
instances.- API Note:
- The path should generally, but is not required to, end with '/'.
If the path does not end with '/', eg such as with
"/foo"
then this would match requests with a path of"/foobar"
or"/foo/bar"
. - Parameters:
path
- the root URI path to associate the context with- Returns:
- an instance of
HttpContext
- Throws:
IllegalArgumentException
- if path is invalid, or if a context already exists for this pathNullPointerException
- if path isnull
-
removeContext
Removes the context identified by the given path from the server. Removing a context does not affect exchanges currently being processed but prevents new ones from being accepted.- Parameters:
path
- the path of the handler to remove- Throws:
IllegalArgumentException
- if no handler corresponding to this path exists.NullPointerException
- if path isnull
-
removeContext
Removes the given context from the server. Removing a context does not affect exchanges currently being processed but prevents new ones from being accepted.- Parameters:
context
- the context to remove- Throws:
NullPointerException
- if context isnull
-
getAddress
Returns the address this server is listening on- Returns:
- the
InetSocketAddress
the server is listening on
-