1 Running Web Servlets
There are a number of ways to run Web servlets.
1.1 Instant Servlets
The fastest way to get a servlet running in the Web server is to use the
"Insta" language in DrRacket. Enter the following into DrRacket:
And press Run. A Web browser will open up showing your new servlet.
This servlet will only be accessible from your local machine.
Behind the scenes, DrRacket has used serve/servlet to start a new server
that uses your start function as the servlet.
You are given the entire web-server/servlet API.
The following API is provided to customize the server instance:
Calling this will instruct DrRacket to not start a Web browser when you press
This instructs the Web server to serve static files, such as stylesheet and images, from path.
If you want more control over specific parameters, keep reading about web-server/servlet-env.
1.2 Simple Single Servlet Servers
The Web Server provides a way to quickly configure and start a servlet with more customizability than web-server/insta
provides. This is provided by the web-server/servlet-env
module. Here is a simple example of its use:
Unlike the web-server/insta
is not a special identifier, so we could just as well have written the example as:
Suppose you’d like to change the port to something else, change the last line to:
Suppose you want to accept connections from external machines:
By default the URL for your servlet is "http://localhost:8000/servlets/standalone.rkt",
suppose you wanted it to be "http://localhost:8000/hello.rkt":
Suppose you wanted it to capture top-level requests:
Or, perhaps just some nice top-level name:
Suppose you wanted to use a style-sheet ("style.css") found on your Desktop ("/Users/jay/Desktop/"):
These files are served in addition to those from the #:server-root-path "htdocs" directory.
You may pass any number of extra paths.
If you want to use serve/servlet
in a start up script for a Web application,
and don’t want a browser opened or the DrRacket banner printed, then you can write:
Suppose you would like to start a server for a stateless Web servlet "servlet.rkt" that provides start:
If you put the call to serve/servlet
in a web-server
module directly it will not work correctly.
Consider the following module:
First, if this module is not saved in a file (e.g., "servlet.rkt"
), then the serialization layer cannot locate the definitions of the
serialized continuations. Second, due to an unfortunately subtle bug that we have not yet corrected,
every time the continuation link is clicked, serve/servlet
run and attempt to start a Web server instance and open a browser window. These problems do not occur if your servlet is saved in a file
and if serve/servlet
is run in another module.
| || ||start|| |
| || [||#:command-line? command-line?|| |
| || ||#:launch-browser? launch-browser?|| |
| || ||#:quit? quit?|| |
| || ||#:banner? banner?|| |
| || ||#:listen-ip listen-ip|| |
| || ||#:port port|| |
| || ||#:servlet-path servlet-path|| |
| || ||#:servlet-regexp servlet-regexp|| |
| || ||#:stateless? stateless?|| |
| || ||#:stuffer stuffer|| |
| || ||#:manager manager|| |
| || ||#:servlet-namespace servlet-namespace|| |
| || ||#:server-root-path server-root-path|| |
| || ||#:extra-files-paths extra-files-paths|| |
| || ||#:servlets-root servlets-root|| |
| || ||#:servlet-current-directory servlet-current-directory|| |
| || ||#:file-not-found-responder file-not-found-responder|| |
| || ||#:mime-types-path mime-types-path|| |
| || ||#:ssl? ssl?|| |
| || ||#:ssl-cert ssl-cert|| |
| || ||#:ssl-key ssl-key|| |
| || ||#:log-file log-file|| |
| || ||#:log-format log-format])|| |
| → void|
| start : (request? . -> . response/c)|
| command-line? : boolean? = #f|
| launch-browser? : boolean? = (not command-line?)|
| quit? : boolean? = (not command-line?)|
| banner? : boolean? = (not command-line?)|
| listen-ip : (or/c false/c string?) = "127.0.0.1"|
| port : number? = 8000|
| servlet-path : string? = "/servlets/standalone.rkt"|
| stateless? : boolean? = #f|
| stuffer : (stuffer/c serializable? bytes?) = default-stuffer|
| servlet-namespace : (listof module-path?) = empty|
| server-root-path : path-string? = default-server-root-path|
| servlet-current-directory : path-string? = servlets-root|
| mime-types-path : path-string? = ....|
| ssl? : boolean? = #f|
| log-file : (or/c false/c path-string?) = #f|
| log-format : log-format/c = 'apache-default|
This sets up and starts a fairly default server instance.
start is loaded as a servlet and responds to requests that match servlet-regexp. The current directory
of servlet execution is servlet-current-directory.
If launch-browser? is true, then a web browser is opened to "http://localhost:<port><servlet-path>".
If quit? is true, then the URL "/quit" ends the server.
If stateless? is true, then the servlet is run as a stateless
module and stuffer
as the stuffer
Advanced users may need the following options:
The server listens on listen-ip and port port. If listen-ip is #f, then the server accepts
connections to all of the listening machine’s addresses. Otherwise, the server accepts connections only at the interface(s) associated with the given string.
For example, providing "127.0.0.1" (the default) as listen-ip creates a server that accepts only connections to "127.0.0.1" (the loopback interface) from the local machine.
If ssl-cert and ssl-key are not false, then the server runs in HTTPS mode with ssl-cert
and ssl-key as the certificates and private keys.
The servlet is loaded with manager
as its continuation manager. (The default manager limits the amount of memory to 64 MB and
deals with memory pressure as discussed in the make-threshold-LRU-manager
The modules specified by servlet-namespace are shared with other servlets.
The server files are rooted at server-root-path (which is defaultly the distribution root.)
File paths, in addition to the "htdocs" directory under server-root-path may be
provided with extra-files-paths. These paths are checked first, in the order they appear in the list.
Other servlets are served from servlets-root.
If a file cannot be found, file-not-found-responder is used to generate an error response.
If banner? is true, then an informative banner is printed. You may want to use this when
running from the command line, in which case the command-line? option controls similar options.
MIME types are looked up at mime-types-path. By default the "mime.types" file in the
server-root-path is used, but if that file does not exist, then the file that ships with the
Web Server is used instead. Of course, if a path is given, then it overrides this behavior.
is given, then it used to log requests using log-format
as the format. Allowable formats
are those allowed by log-format->format
1.3 Command-line Tools
One command-line utility is provided with the Web Server:
plt-web-server [-f <file-name> -p <port> -a <ip-address> --ssl]
The optional file-name argument specifies the path to a
configuration-table S-expression (see configuration-table->sexpr for the syntax documentation.)
If this is not provided, the
default configuration shipped with the server is used. The optional
port and ip-address arguments override the corresponding portions of
the configuration-table. If the SSL option is provided, then
the server uses HTTPS with "server-cert.pem" and "private-key.pem"
in the current directory, with 443 as the default port. (See the openssl
module for details on the SSL implementation.)
The configuration-table is given to
configuration-table->web-config@ and used to construct a
web-config^ unit, and is linked with the
web-server@ unit. The resulting unit is invoked, and the
server runs until the process is killed.