PLT Web Server: Servlet Interface
Instead of serving files from a special directory verbatim, the Web server executes the contained Scheme code and serves the output. By default, the special directory is named "servlets" within the "default-web-root" of the "web-server" collection directory. Each file in that directory must evaluate to a servlet.
A servlet is a |
unit/sig that imports the
signature and exports nothing. (Search in
help-desk for more information on
unit/sig and on signatures.) To construct a
unit/sig with the appropriate imports, the servlet must require the two modules providing
unit/sigs and the
(require (lib "unitsig.ss")
(lib "servlet-sig.ss" "web-server"))
...insert servlet code here...
The last value in the
unit/sig must be a response to an HTTP request.
Response is one of the following:
X-expression representing HTML
(Search for XML in
(listof string) where
- The first string is the mime type (often "text/html", but see RFC 2822 for other options).The rest of the strings provide the document's content.
(make-response/full code message seconds mime extras body
- code is a natural number indicating the HTTP response code
- message is a string describing the code to a human
- seconds is a natural number indicating the time the resource was
created. Use (current-seconds) for dynamically created responses.
- mime is a string indicating the response type.
- extras is a
(listof (cons symbol string)) containing extra headers for redirects, authentication, or cookies.
- body is a
(require (lib "servlet-sig.ss" "web-server")) loads
servlet^ signature consisting of the following imports:
- initial-request :
request, where a request is
(make-request method uri headers bindings host-ip client-ip), where
- method :
(Union 'get 'post)
- uri :
net collection in
help-desk for details
- headers :
(listof (cons symbol string))
optional HTTP headers for this request
- bindings :
(listof (cons symbol string))
name value pairs from the form submitted or the query part of the URL.
path part of the URL suplies the file path to the servlet relative to the "servlets" directory. However, paths may also contain extra path components that servlets may use as additional input. For example all of the following URLs refer to the same servlet:
The above imports support handling a single input from a Web form. To ease the development of more interactive servlets, the
servlet^ signature also provides the following functions:
The argument, a function that consumes a string, is given a
send/suspend : (str -> Response) -> request
URL that can be used in the document. The argument function must produce a
response corresponding to the document's body. Requests to the
URL resume the computation at the point
send/suspend was invoked. Thus, the argument function normally
produces an HTML form with the "action" attribute set to the provided
URL. The result of
send/suspend represents the
send/finish : Response -> doesn't return
This provides a convenient way to report an error or otherwise produce a final response. Once called, all URLs generated by send/suspend become invalid. Calling send/finish allows the system to reclaim resources consumed by the servlet.
adjust-timeout! : Nat -> Void
The server will shutdown each instance of a servlet after an unspecified default amount of time since the last time that servlet instance handled a request. Calling adjust-timeout! allows programmers to choose this number of seconds. Larger numbers consume more resources
while smaller numbers force servlet users to restart computations more often.