- an optional IP address (the default is the wildcard address)
- a TCP port number.
- a TCP backlog.
- the number of threads the server may use to handle requests. The server uses a fixed thread pool because embedded web servers are typically lightly loaded, so it is better to keep the configuration simple.
- An instance of
EmbeddedWebServer.SSLSetup
. When null, the server will use HTTP and when non-null, the server will run HTTPS. While there are defaults (suitable for testing), one can provide a number of SSL options explicitly. Typically, one will need a keystore containing a certificate. To create one using keytool run it with options similar to the following:
to import this certificate into a trust store, run a command similar to the following:keytool -genkey -keyalg EC -groupname secp256r1 \ -sigalg SHA256withECDSA -keystore ks.jks \ -keypass changeit -storepass changeit \ -dname CN=HOST -alias NAME -validity 365
Generally for testing, one will need to provide both a keystore and a trust store (which is not needed if the certificate was signed by a certificate authority).keytool -keystore ks.jks -alias thelio -exportcert \ -storepass changeit -rfc \ | keytool -importcert -alias NAME -keystore ts.jks \ -keypass changeit -storepass changeit -noprompt
After an EmbeddedWebServer is constructed, handlers for HTTP
requests have to be added to the server. This is done by creating
a "context" that that contains an optional authenticator and an
HttpHandler
that is responsible for processing
requests. This context is in turn associated with a
prefix—the initial portion of the path component of a URL or
URI. A specific HTTP handler, FileHandler
is part of the
current package and takes care of header processing associated with
retrieving static resources (ones that do not change with time and
do not require a URL query component). FileHandler
is
controlled by an instance of the class WebMap
, and All
subclasses of WebMap
are expected to support a
single-argument constructor that will be used for initialization,
as described in the documentation for WebMap
.
Creating contexts and adding them to an EmbeddedWebServer is handled by the following methods:
add(String,Class,Object,com.sun.net.httpserver.Authenticator,boolean,boolean,boolean)
, which creates an instance ofFileHandler
, specifying a subclass ofWebMap
by class.add(String,String,Object,com.sun.net.httpserver.Authenticator,boolean,boolean,boolean)
, which creates an instance ofFileHandler
, specifying a subclass ofWebMap
by class name.add(String,com.sun.net.httpserver.HttpHandler,com.sun.net.httpserver.Authenticator)
, whose arguments contain an instance ofHttpHandler
.
When a URL is processed, the handler with the longest matching prefix is used.
For the simplest cases—just displaying static web pages—one can configure a server by just using the "add" methods that take a WebMap's class name or class as an argument. The argument passed to WebMap's constructor (the Object following the class name or class) depends on the type of WebMap. For those in the BZDev package, these arguments are as follows:
- for the class
org.bzdev.ejws.maps.DirWebMap
, the argument used to create the web map is aFile
representing a directory. The file handler will look for a file in that directory or a subdirectory with a name consisting of a requested URL's path with the prefix removed. - for the class
org.bzdev.ejws.maps.RedirectWebMap
, the argument used to create the web map can be either a URL or a String. The file handler will provide an HTTP redirect to the URL obtained by resolving the argument against a requested URL's path with the prefix removed. - for the class
org.bzdev.ejws.maps.ResourceWebMap
, the argument is a String representing the initial portion of a a resource name. The file handler will read a system resource whose path is the argument, followed by a requested URL's path with the prefix removed. - for the class
org.bzdev.ejws.maps.URLWebMap
, the argument is either a URL, a String, or an instance of URLWebMap.Params.The file handler will resolve the requested path, excluding the prefix, against this URL and use the resulting URL to find the object to return. This is similar to a redirect, except that the EmbeddedWebServer will return the object to the entity requesting it. - for the class
org.bzdev.ejws.maps.ZipWebMap
, the argument is either a String giving a file name or a File. The file must be either a ZIP file, WAR file, or JAR file. The file handler will provide an entry whose name is the path of the requested URL with the prefix removed from that path.
Finally, the method start()
will start
the web server and the methods stop(int)
or shutdown(int)
will stop the server
calling shutdown will prevent the server from being
restarted—instead a new server will have to be created.
If the port number provided to a constructor is zero, the system will allocate a port number, choosing one that is not currently in use. This is useful for applications that will automatically open a browser but where the web pages displayed are not intended for public use (i.e., others would generally not be interested in seeing those pages). Setting the port to zero does not provide privacy - it just avoids conflicts between applications that might inadvertently choose the same port number. For example, an application with an embedded manual might bring up a browser to display the manual, using all the features of a web browser, including javascript.
Warning: For HTTPS one needs a large pool size because of what
appears to be a bug in the openjdk-11 SSL implementation that leads
to an ever increasing number of connections in the TCP CLOSE-WAIT
state. This happens sporadically, and when it does, the number of
available threads drops. Until this bug is fixed, the class
{org.bzdev.net.CloseWaitService} can be used to remove dormant
connections in the CLOSE-WAIT state. This command, however, uses
the program ss
, which appears to be available only on
Linux systems. For non-Linux systems, EmbeddedWebServer using HTTPS
should be used only for testing. The bug does not seem to occur
with HTTP, which seems to rule out a bug in the ejws package.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Configure an HTTPS server.static class
Setup parameters for an secure-socket server. -
Constructor Summary
ConstructorsConstructorDescriptionEmbeddedWebServer
(int port) Constructor for a wildcard IP address with a default backlog and a default number of threads for HTTP servers.EmbeddedWebServer
(int port, int backlog) Constructor for a wildcard IP address with a default number of threads for HTTP servers.EmbeddedWebServer
(int port, int backlog, int nthreads) Constructor for a wildcard IP address for HTTP servers.EmbeddedWebServer
(int port, int backlog, int nthreads, CertManager certManager) Constructor for a wildcard IP address using a certificate manager.EmbeddedWebServer
(int port, int backlog, int nthreads, EmbeddedWebServer.SSLSetup sslSetup) Constructor for a wildcard IP address.EmbeddedWebServer
(int port, int backlog, CertManager certManager) Constructor for a wildcard IP address with a default number of threads using a certificate manager.EmbeddedWebServer
(int port, int backlog, EmbeddedWebServer.SSLSetup sslSetup) Constructor for a wildcard IP address with a default number of threads.EmbeddedWebServer
(int port, CertManager certManager) Constructor for a wildcard IP address with a default backlog and a default number of threads, using a certificate manager.EmbeddedWebServer
(int port, EmbeddedWebServer.SSLSetup sslSetup) Constructor for a wildcard IP address with a default backlog and a default number of threads.EmbeddedWebServer
(InetAddress addr, int port, int backlog, int nthreads) Constructor for HTTP servers.EmbeddedWebServer
(InetAddress addr, int port, int backlog, int nthreads, CertManager certManager) Constructor using aCertManager
.EmbeddedWebServer
(InetAddress addr, int port, int backlog, int nthreads, EmbeddedWebServer.SSLSetup sslSetup) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionvoid
add
(String p, HttpHandler handler, Authenticator authenticator) Add a context to the server.void
add
(String p, Class<? extends WebMap> clazz, Object arg, Authenticator authenticator, boolean nowebxml, boolean displayDir, boolean hideWebInf) Add a context to the server given a subclass of WebMap.void
add
(String p, String className, Object arg, Authenticator authenticator, boolean nowebxml, boolean displayDir, boolean hideWebInf) Add a context to the server given the name of a WebMap subclass.boolean
Add a filter to the HTTP context associated with a path.boolean
addSessionFilter
(String path, boolean withState) Add a session manager for a path.boolean
addSessionFilter
(String path, HttpSessionOps sessionOps) Add a session-manager filter for a path, specifying an implementation that maps sessions to states.boolean
Determine if this web server has added a prefix.Return the address for this web server.Get a list of the Internet addresses that this embedded web server uses.Get the authenticator associated with a prefix.getCertificates
(String... aliases) Get Certificates.Get an HtppHandler if it is an instance ofFileHandler
.Get the HttpHandler associated with a prefix.int
getPort()
Return the port for this web server.Determine which prefixes have been configured for this web server.Get the WebMap associated with a prefix.boolean
isServerAddressAndPort
(InetAddress addr, int port) Determine if an address and port is one associated with this server.void
Modify the setup configuration for an HTTPS server using a configuredCertManager
.void
Modify the setup configuration for an HTTPS server.static HttpHandler
newHttpHandler
(String className, Object arg) Create a new HttpHandler.static WebMap
Create a new WebMap.boolean
Remove a context.boolean
Determine if the server is running.void
setErrorOutput
(Appendable err) Set the error output for errors that terminate an executor thread.void
Set up an ExecutorService factory.void
setRootColors
(String color, String bgcolor, String linkColor, String visitedColor) Set the colors used by a RootHandler.boolean
setTracer
(String p, Appendable tracer) Set an Appendable for tracing.boolean
setTracer
(String p, Appendable tracer, boolean stacktrace) Set an Appendable for tracing, optionally with a stack trace for exceptions.void
setWarningMode
(boolean value) Set warning mode.void
setWarningMode
(boolean value, String serverName, Appendable errout) Set warning mode specifying an output.void
shutdown
(int delay) Shutdown the web server.void
start()
Start the web server.void
stop
(int delay) Stop the web server.boolean
Determine if this server uses HTTP or HTTPS.
-
Constructor Details
-
EmbeddedWebServer
Constructor for a wildcard IP address with a default backlog and a default number of threads.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portsslSetup
- the configuration for an HTTPS server; null for HTTP- Throws:
Exception
- an error occurred.
-
EmbeddedWebServer
Constructor for a wildcard IP address with a default backlog and a default number of threads, using a certificate manager. ACertManager
is an alternative toEmbeddedWebServer.SSLSetup
that allows certificates to be automatically obtained and renewed.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portcertManager
- theCertManager
.- Throws:
Exception
- an error occurred.
-
EmbeddedWebServer
Constructor for a wildcard IP address with a default backlog and a default number of threads for HTTP servers.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated port- Throws:
Exception
- an error occurred.
-
EmbeddedWebServer
public EmbeddedWebServer(int port, int backlog, EmbeddedWebServer.SSLSetup sslSetup) throws Exception Constructor for a wildcard IP address with a default number of threads.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)sslSetup
- the configuration for an HTTPS server; null for HTTP- Throws:
Exception
- an error occurred.
-
EmbeddedWebServer
Constructor for a wildcard IP address with a default number of threads using a certificate manager. ACertManager
is an alternative toEmbeddedWebServer.SSLSetup
that allows certificates to be automatically obtained and renewed.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)certManager
- theCertManager
.- Throws:
Exception
- an error occurred.
-
EmbeddedWebServer
Constructor for a wildcard IP address with a default number of threads for HTTP servers. ACertManager
is an alternative toEmbeddedWebServer.SSLSetup
that allows certificates to be automatically obtained and renewed.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)- Throws:
Exception
- an error occurred.
-
EmbeddedWebServer
public EmbeddedWebServer(int port, int backlog, int nthreads, EmbeddedWebServer.SSLSetup sslSetup) throws Exception Constructor for a wildcard IP address.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)nthreads
- the number of threads the server will usesslSetup
- the configuration for an HTTPS server; null for HTTP- Throws:
Exception
- an error occurred
-
EmbeddedWebServer
public EmbeddedWebServer(int port, int backlog, int nthreads, CertManager certManager) throws Exception Constructor for a wildcard IP address using a certificate manager. ACertManager
is an alternative toEmbeddedWebServer.SSLSetup
that allows certificates to be automatically obtained and renewed.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)nthreads
- the number of threads the server will usecertManager
- theCertManager
.- Throws:
Exception
- an error occurred
-
EmbeddedWebServer
Constructor for a wildcard IP address for HTTP servers.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)nthreads
- the number of threads the server will use- Throws:
Exception
- an error occurred
-
EmbeddedWebServer
public EmbeddedWebServer(InetAddress addr, int port, int backlog, int nthreads, EmbeddedWebServer.SSLSetup sslSetup) Constructor.- Parameters:
addr
- the Internet address for this server; null for the wildcard addressWarning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
port
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)nthreads
- the number of threads the server will usesslSetup
- the configuration for an HTTPS server; null for HTTP
-
EmbeddedWebServer
public EmbeddedWebServer(InetAddress addr, int port, int backlog, int nthreads, CertManager certManager) throws IOException Constructor using aCertManager
. ACertManager
is an alternative toEmbeddedWebServer.SSLSetup
that allows certificates to be automatically obtained and renewed.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
addr
- the Internet address for this server; null for the wildcard addressport
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)nthreads
- the number of threads the server will usecertManager
- theCertManager
.- Throws:
IOException
- an IO Exception occurred when accessing a key store.
-
EmbeddedWebServer
Constructor for HTTP servers.Warning: this constructor will create a bound socket. For some JDK/JRE implementations, the binding cannot be removed unless the server is actually started.
- Parameters:
addr
- the Internet address for this server; null for the wildcard addressport
- the TCP port number for a server; 0 for a system-allocated portbacklog
- the TCP backlog (maximum number of pending connections)nthreads
- the number of threads the server will use- Throws:
IOException
- an IO Exception occurred when accessing a key store.
-
-
Method Details
-
usesHTTPS
public boolean usesHTTPS()Determine if this server uses HTTP or HTTPS.- Returns:
- true if this server uses HTTPS; false if this server uses HTTP
-
getPort
public int getPort()Return the port for this web server. This is the port number passed to a constructor unless that number is zero (which indicates that the system will pick a port number to use).- Returns:
- the port
-
getAddress
Return the address for this web server. The value returned is a socket address: an internet address combined with a port number. This method is provided because some constructors do not explicitly provide the address.- Returns:
- the address
-
setWarningMode
public void setWarningMode(boolean value) Set warning mode.- Parameters:
value
- true if warnings are turned on; false otherwise
-
setWarningMode
Set warning mode specifying an output.- Parameters:
value
- true if warnings are turned on; false otherwiseserverName
- a name for this server, used in warningserrout
- an Appendable used to log warnings; null for the default
-
getCertificates
Get Certificates. This will return null for an HTTP server and an array of certificates for HTTPS. The certificates returned will be those with private keys and any such key is assumed to be possibly used as a server certificate.- Parameters:
aliases
- the names of the aliases; no arguments for all certificates- Returns:
- an array containing certificates; null if not applicable
-
modifyServerSetup
Modify the setup configuration for an HTTPS server. This should be called before the service is stopped, after which it should be restarted. The argument is ignored for HTTP servers.One use of this method is to handle the case in which a server's certificate has to be changed.
- Parameters:
s
- the configuration for an HTTPS server
-
modifyServerSetup
public void modifyServerSetup()Modify the setup configuration for an HTTPS server using a configuredCertManager
. This should be called before the service is stopped, after which it should be restarted. The argument is ignored for HTTP servers.One use of this method is to handle the case in which a server's certificate has to be changed.
-
getAddresses
Get a list of the Internet addresses that this embedded web server uses.The list can have more than one entry when the server is configured using a wildcard address.
- Returns:
- a list of addresses
-
isServerAddressAndPort
Determine if an address and port is one associated with this server.- Parameters:
addr
- the internet addressport
- the port- Returns:
- true if the arguments provide an address and port that this server uses; false otherwise
-
addSessionFilter
Add a session manager for a path. A session implementation is an application-specific object associated with a session, typically used to maintain the state of a session.The method
WebMap.RequestInfo.setSessionState(Object)
, which implementsHttpServerRequest.setSessionState(Object)
, can be used to set the session state. Similarly, the methodWebMap.RequestInfo.getSessionState()
, which implementsHttpServerRequest.getSessionState()
, can be used to fetch the sessions state.EmbeddedWebServer
does not provide any way of deallocating resources once a state is no longer in use. The classCleaner
(the API documentation for this class includes an example) can be used to deallocate resources or to perform some other action when a session is removed.- Parameters:
path
- a path that has been added to this serverwithState
- true if a session has a state; false otherwise- Returns:
- true on success; false otherwise (for example, the path
had not been added to this server or the path does not
have an
HttpContext
)
-
addSessionFilter
Add a session-manager filter for a path, specifying an implementation that maps sessions to states. A session implementation is an application-specific object associated with a session, typically used to maintain the state of a session.The method
WebMap.RequestInfo.setSessionState(Object)
, which implementsHttpServerRequest.setSessionState(Object)
, can be used to set the session state. Similarly, the methodWebMap.RequestInfo.getSessionState()
, which implementsHttpServerRequest.getSessionState()
, can be used to fetch the sessions state.EjwsStateTable
provides the default implementation. This implementation is suitable for most purposes. Subclassing it might be useful for debugging (e.g., to insert print statements).EmbeddedWebServer
does not provide any way of deallocating resources once a state is no longer in use. The classCleaner
(the API documentation for this class includes an example) can be used to deallocate resources or to perform some other action when a session is removed.- Parameters:
path
- a path that has been added to this serversessionOps
- the object that maps a session ID to session implementations; null if no mapping is desired- Returns:
- true on success; false otherwise (for example, the path
had not been added to this server or the path does not
have an
HttpContext
) - See Also:
-
addFilter
Add a filter to the HTTP context associated with a path.- Parameters:
path
- the pathfilter
- to the filter- Returns:
- true if the context exists; false otherwise
-
add
public void add(String p, String className, Object arg, Authenticator authenticator, boolean nowebxml, boolean displayDir, boolean hideWebInf) throws IllegalArgumentException, IllegalStateException, IOException, SAXException Add a context to the server given the name of a WebMap subclass. An instance of the subclass of WebMap will be passed to a new instance of FileHandler and will be created using the argumentarg
as the sole argument for the WebMap's constructor. This WebMap instance will determine how paths are mapped into the resource that is to be returned, and will determine properties such as the resource's MIME type. The context a server uses while handling a request is that starting with the longest matching path, and determines the handler to use. If HTTP authentication is required, a non-null authenticator must be provided.The use of Web-Inf/web.xml files is described in the documentation for
WebMap
.- Parameters:
p
- the path for the context; a null path will be treated as "/"className
- the name of a subclass of WebMap, an instance of which will be used to create a new FileHandlerarg
- the argument used in creating the WebMap instanceauthenticator
- the authenticator for the context; null if there is nonenowebxml
- true if a web.xml file should be ignored; false otherwisedisplayDir
- true if the caller wants directories displayed when possible; false otherwisehideWebInf
- true if the WEB-INF directory should be hidden; false if it should be visible- Throws:
IllegalArgumentException
- the path is invalid or the path was already added.IllegalStateException
- the server has been shut downIOException
- an IO exception occurred (e.g., while printing a warning messages)SAXException
- an error occurred while parsing a web.xml file- See Also:
-
add
public void add(String p, Class<? extends WebMap> clazz, Object arg, Authenticator authenticator, boolean nowebxml, boolean displayDir, boolean hideWebInf) throws IllegalArgumentException, IllegalStateException, IOException, SAXException Add a context to the server given a subclass of WebMap. An instance of the subclass of WebMap will be passed to a new instance of FileHandler and will be created using the argumentarg
as the sole argument for the WebMap's constructor. This WebMap instance will determine how paths are mapped into the resource that is to be returned, and will determine properties such as the resource's MIME type. The context a server uses while handling a request is that starting with the longest matching path, and determines the handler to use. If HTTP authentication is required, a non-null authenticator must be provided.The use of Web-Inf/web.xml files is described in the documentation for
WebMap
.- Parameters:
p
- the path for the contextclazz
- a subclass of WebMap, an instance of which will be used to create a new FileHandlerarg
- the argument used in creating the WebMap instanceauthenticator
- the authenticator for the context; null if there is nonenowebxml
- true if a web.xml file should be ignored; false otherwisedisplayDir
- true if the caller wants directories displayed when possible; false otherwisehideWebInf
- true if the WEB-INF directory should be hidden; false if it should be visible- Throws:
IllegalArgumentException
- the path is invalid or the path was already added.IllegalStateException
- the server has been shut downIOException
- an IO exception occurred (e.g., while printing a warning messages)SAXException
- an error occurred while parsing a web.xml file- See Also:
-
add
public void add(String p, HttpHandler handler, Authenticator authenticator) throws IllegalStateException, IllegalArgumentException, IOException Add a context to the server. The context a server uses while handling a request is that starting with the longest matching path, and determines the handler to use. If HTTP authentication is required, a non-null authenticator must be provided. If p does not start with "/", the character "/" will be prepended to it. A "/" will not be appended to the end of the path.- Parameters:
p
- the path for the contexthandler
- the handler for the contextauthenticator
- the authenticator for the context; null if there is none- Throws:
IllegalStateException
- the server has been shut downIllegalArgumentException
- the path was not valid or already addedIOException
- an IO exception occurred (e.g., while printing a warning messages)
-
remove
Remove a context.- Parameters:
p
- the path used when a context was added.- Returns:
- true if a context exists for path p; false otherwise
-
containsPrefix
Determine if this web server has added a prefix. A leading and trailing '/' will be added to the prefix if missing.- Parameters:
p
- the prefix (null implies the root prefix)- Returns:
- true if the prefix was added; false otherwise
-
getFileHandler
Get an HtppHandler if it is an instance ofFileHandler
. A leading and/or trailing '/' will be added to the prefix if missing.This method is provided for convenience.
- Parameters:
p
- the prefix (null implies the root prefix)- Returns:
- the handler; null if the handler is not an instance of FileHandler
-
getHttpHandler
Get the HttpHandler associated with a prefix. A leading and/or trailing '/' will be added to the prefix if missing.- Parameters:
p
- the prefix (null implies the root prefix)- Returns:
- the handler
-
getAuthenticator
Get the authenticator associated with a prefix. A leading and/or trailing '/' will be added to the prefix if missing.- Parameters:
p
- the prefix (null implies the root prefix)- Returns:
- the authenticator; null if there is none.
-
getWebMap
Get the WebMap associated with a prefix. A leading and/or trailing '/' will be added to the prefix if missing.- Parameters:
p
- the prefix (null implies the root prefix)- Returns:
- the web map (null if there is none).
-
setTracer
Set an Appendable for tracing. This method should be used only for debugging. Currently, the only handler that supports tracing isFileHandler
.- Parameters:
p
- the prefix whose handler should be tracedtracer
- the Appendable for tracing requests and responses- Returns:
- true if the handler for the prefix supports tracing; false otherwise
-
setTracer
Set an Appendable for tracing, optionally with a stack trace for exceptions. This method should be used only for debugging. Currently, the only handler that supports tracing isFileHandler
.- Parameters:
p
- the prefix whose handler should be tracedtracer
- the Appendable for tracing requests and responsesstacktrace
- true for a stack trace; false otherwise- Returns:
- true if the handler for the prefix supports tracing; false otherwise
-
getPrefixes
Determine which prefixes have been configured for this web server.- Returns:
- a set of prefixes
-
setErrorOutput
Set the error output for errors that terminate an executor thread. The default is System.err.- Parameters:
err
- the error output; null to suppress these messages
-
setExecutorServiceFactory
Set up an ExecutorService factory. This method is provided so that the user of this class can install a specificExecutorService
. The argument uses a functional interface, so the factory can be provided as a lambda expression. The argument is anInteger
whose value is the number of threads passed to a constructor of theExecutorService
.- Parameters:
callable
- an object whose 'call' method (with an Integer argument) creates a new ExecutorService; null for the default
-
setRootColors
Set the colors used by a RootHandler. This will also set the colors used inWebMap
generated error pages unless the methodsWebMap.getErrorForegroundColor()
andWebMap.getErrorBackgroundColor()
were overridden.- Parameters:
color
- the CSS color for textbgcolor
- the CSS color for the backgroundlinkColor
- the CSS color for links; null to ignorevisitedColor
- the CSS color for visited links; null to ignore- Throws:
IllegalArgumentException
- if color or bgcolor are missing or if only one of linkColor or visitedColor is null.
-
serverRunning
public boolean serverRunning()Determine if the server is running.- Returns:
- true if the server is running; false otherwise
-
start
public void start()Start the web server. Starting a server that is already running has no effect.- Throws:
IllegalStateException
- the server is stopping or has been shut down
-
stop
Stop the web server. A call to this method will block until the server stops. As soon as this method is called, the server will stop accepting new requests. Processing of existing requests will continue for the time interval specified by the argument. Once the server stops, The server's thread pool will be shut down in case the server fails to do that.- Parameters:
delay
- the delay in seconds before the server is stopped.- Throws:
Exception
- an error occurred
-
shutdown
public void shutdown(int delay) Shutdown the web server. A call to this method will block until the server stops and shuts down. This differs from the methodstop
in that the server cannot be restarted.Warning: if a server was created but not started, some JDK/JRE implementations will keep the port bound after this method returns.
- Parameters:
delay
- the delay in seconds before the server is stopped.
-
newHttpHandler
public static HttpHandler newHttpHandler(String className, Object arg) throws IOException, IllegalArgumentException Create a new HttpHandler. This method is provided so that new HttpHandler instances can be created from a GUI or a command-line interface.- Parameters:
className
- the name of the class of the instance to createarg
- an argument passed to the new instance's constructor (one argument, of type Object).- Returns:
- the new HttpHandler
- Throws:
IOException
- an IO exception occurred during initializationIllegalArgumentException
- one of the arguments was illegal.
-
newWebMap
public static WebMap newWebMap(String className, Object arg) throws IOException, IllegalArgumentException Create a new WebMap. This method is provided so that new WebMap instances can be created from a GUI or a command-line interface.- Parameters:
className
- the name of the class of the instance to createarg
- an argument passed to the new instance's constructor (one argument, of type Object).- Returns:
- the new web map
- Throws:
IOException
- an IO exception occurred during initializationIllegalArgumentException
- one of the arguments was illegal.
-