2 Stateful Servlets
| (require web-server/servlet) |
A stateful servlet should provide the following exports:
value
interface-version : (one-of/c 'v2)
This indicates that the servlet is a version two servlet.
The manager for the continuations of this servlet. See Continuation Managers for options.
This function is called when an instance of this servlet is started.
The argument is the HTTP request that initiated the instance.
An example version 2 module:
#lang racket (require web-server/http web-server/managers/none) (provide interface-version manager start) (define interface-version 'v2) (define manager (create-none-manager (lambda (req) (response/xexpr `(html (head (title "No Continuations Here!")) (body (h1 "No Continuations Here!"))))))) (define (start req) (response/xexpr `(html (head (title "Hello World!")) (body (h1 "Hi Mom!")))))
These servlets have an extensive API available to them: net/url, web-server/http, web-server/http/bindings, web-server/servlet/servlet-structs, web-server/servlet/web, web-server/servlet/web-cells, and web-server/dispatch. Some of these are documented in the subsections that follow.
2.2 Responses
Servlets communicate to the Web Server by returning HTTP responses. In order to
accommodate lightweight programs (and backwards compatibility), the Web Server
provides an indirection from application-specific response formats and the internal
HTTP response format, response.
procedure
(can-be-response? x) → boolean?
x : any/c
procedure
(any->response x) → (or/c false/c response?)
x : any/c
procedure
(set-any->response! new-any->response) → void
new-any->response : (-> any/c (or/c false/c response?))
any->response coerces any value into a response or returns #f if coercion is not possible.
any->response guarantees that any response? input must always be returned exactly (i.e. eq?.)
The default always returns #f, signifying that no coercion is possible.
can-be-response? returns #t if x is a response or can be turned into a response by calling
any->response.
Users of any->response should protect themselves by using can-be-response? as a contract.
If they do so, they can safely ignore the #f return case of any->response.
set-any->response! replaces the global any->response with the supplied argument. This
function should return the same value for eq? inputs to ensure that can-be-response? is
any accurate predicate. Similarly, this function should be cheap to call multiple times on the same input,
since it will be used in contract checking as well as coercion before transmission. You may want to use a
weak eq?-based hash-table to cache the results for this purpose. (See make-weak-hasheq.)
2.3 Web Interaction
The
web-server/servlet/web library provides the primary
functions of interest for the servlet developer.
procedure
response : can-be-response?
Sends response to the client. No continuation is captured, so the servlet is done.
Example:
(send/back (response/xexpr `(html (body (h1 "The sum is: " ,(+ first-number second-number))))))
procedure
(send/suspend make-response) → request?
make-response : (string? . -> . can-be-response?)
Captures the current continuation, stores it with exp as the expiration
handler, and binds it to a URL. make-response is called with this URL and
is expected to generate a can-be-response?, which is sent to the client. If the
continuation URL is invoked, the captured continuation is invoked and the request is
returned from this call to send/suspend.
Example:
(send/suspend (lambda (k-url) (response/xexpr `(html (head (title "Enter a number")) (body (form ([action ,k-url]) "Enter a number: " (input ([name "number"])) (input ([type "submit"]))))))))
When this form is submitted by the browser, the request will be sent to the URL generated by send/suspend.
Thus, the request will be “returned” from send/suspend to the continuation of this call.
procedure
(send/suspend/url make-response) → request?
make-response : (url? . -> . can-be-response?)
Like send/suspend but with a URL struct.
procedure
(send/suspend/dispatch make-response) → any
make-response : (((request? . -> . any) . -> . string?) . -> . can-be-response?)
Calls make-response with a function (often named embed/url) that, when called with a procedure from
request? to any/c will generate a URL, that when invoked will call
the function with the request? object and return the result to the caller of
send/suspend/dispatch. Therefore, if you pass embed/url the identity function,
send/suspend/dispatch devolves into send/suspend:
(define (send/suspend response-generator) (send/suspend/dispatch (lambda (embed/url) (response-generator (embed/url (lambda (x) x))))))
Use send/suspend/dispatch when there are multiple ‘logical’ continuations of a page.
For example, we could either add to a number or subtract from it:
(define (count-dot-com i) (count-dot-com (send/suspend/dispatch (lambda (embed/url) (response/xexpr `(html (head (title "Count!")) (body (h2 (a ([href ,(embed/url (lambda (req) (sub1 i)))]) "-")) (h1 ,(number->string i)) (h2 (a ([href ,(embed/url (lambda (req) (add1 i)))]) "+")))))))))
Notice that in this example the result of the handlers are returned to the continuation of send/suspend/dispatch.
However, it is very common that the return value of send/suspend/dispatch is irrelevant in
your application and you may think of it as “embedding” value-less callbacks. Here is the same example in this style:
(define (count-dot-com i) (send/suspend/dispatch (lambda (embed/url) (response/xexpr `(html (head (title "Count!")) (body (h2 (a ([href ,(embed/url (lambda (req) (count-dot-com (sub1 i))))]) "-")) (h1 ,(number->string i)) (h2 (a ([href ,(embed/url (lambda (req) (count-dot-com (add1 i))))]) "+"))))))))
procedure
(send/suspend/url/dispatch make-response) → any
make-response : (((request? . -> . any) . -> . url?) . -> . can-be-response?)
Like send/suspend/dispatch, but with a URL struct.
procedure
(send/forward make-response) → request?
make-response : (string? . -> . can-be-response?)
Calls clear-continuation-table!, then send/suspend.
Use this if the user can logically go ‘forward’ in your application, but cannot go backward.
procedure
(send/finish response) → void?
response : can-be-response?
Calls clear-continuation-table!, then send/back.
Use this if the user is truly ‘done’ with your application. For example, it may be used to display the post-logout page:
(send/finish (response/xexpr `(html (head (title "Logged out")) (body (p "Thank you for using the services " "of the Add Two Numbers, Inc.")))))
procedure
(redirect/get [#:headers hs]) → request?
hs : (listof header?) = empty
This implements the Post-Redirect-Get pattern.
Use this to prevent the Refresh button from duplicating effects, such as adding items to a database.
procedure
(redirect/get/forget [#:headers hs]) → request?
hs : (listof header?) = empty
value
current-servlet-continuation-expiration-handler :
(parameter/c (or/c false/c (request? . -> . can-be-response?)))
Holds the expiration handler to be used when a continuation
captured in this context is expired, then looked up.
Example:
(parameterize ([current-servlet-continuation-expiration-handler (lambda (req) (response/xexpr `(html (head (title "Custom Expiration!")))))]) (send/suspend ....))
procedure
Calls the servlet’s manager’s clear-continuation-table! function. Normally, this deletes all the previously
captured continuations.
procedure
(with-errors-to-browser send/finish-or-back thunk) → any send/finish-or-back : (can-be-response? . -> . request?) thunk : (-> any)
Calls thunk with an exception handler that generates an HTML error page
and calls send/finish-or-back.
Example:
(with-errors-to-browser send/back (lambda () (/ 1 (get-number (request-number)))))
procedure
(adjust-timeout! t) → void?
t : number?
Calls the servlet’s manager’s adjust-timeout! function.
Warning: This is deprecated and will be removed in a future release.
Checks if u is a URL that refers to a continuation, if so
returns the instance id, continuation id, and nonce.
The tag used for Web interaction continuation capture.
2.4 Web Cells
The
web-server/servlet/web-cells library provides the
interface to Web cells.
A Web cell is a kind of state defined relative to the frame tree.
The frame-tree is a mirror of the user’s browsing session. Every time a
continuation is invoked, a new frame (called the current frame) is
created as a child of the current frame when the continuation was captured.
You should use Web cells if you want an effect to be encapsulated in all
interactions linked from (in a transitive sense) the HTTP response being
generated. For more information on their semantics, consult the paper
"Interaction-Safe State for the Web".
procedure
(make-web-cell v) → web-cell?
v : any/c
Creates a web-cell with a default value of v.
procedure
(web-cell-ref wc) → any/c
wc : web-cell?
Looks up the value of wc found in the nearest
frame.
procedure
(web-cell-shadow wc v) → void
wc : web-cell? v : any/c
Binds wc to v in the current frame, shadowing any
other bindings to wc in the current frame.
Below is an extended example that demonstrates how Web cells allow
the creation of reusable Web abstractions without requiring global
transformations of the program into continuation or store passing style.
#lang web-server/insta (define (start initial-request) (define counter1 (make-counter)) (define counter2 (make-counter)) (define include1 (include-counter counter1)) (define include2 (include-counter counter2)) (send/suspend/dispatch (lambda (embed/url) (response/xexpr `(html (body (h2 "Double Counters") (div (h3 "First") ,(include1 embed/url)) (div (h3 "Second") ,(include2 embed/url)))))))) (define (make-counter) (make-web-cell 0)) (define (include-counter a-counter) (call-with-current-continuation (λ (k) (let loop () (k (lambda (embed/url) `(div (h3 ,(number->string (web-cell-ref a-counter))) (a ([href ,(embed/url (lambda _ (define last (web-cell-ref a-counter)) (web-cell-shadow a-counter (add1 last)) (loop)))]) "+")))))) servlet-prompt))
2.5 Continuation Managers
Since Racket servlets store their continuations on the server, they take up memory on the server. Furthermore, garbage collection can not be used to free this memory, because there are roots outside the system: users’ browsers, bookmarks, brains, and notebooks. Therefore, some other strategy must be used if memory usage is to be controlled. This functionality is pluggable through the manager interface.
2.5.1 General
This module defines the manager interface. It is required by
the users and implementors of managers.
struct
(struct manager ( create-instance adjust-timeout! clear-continuations! continuation-store! continuation-lookup continuation-peek) #:extra-constructor-name make-manager) create-instance : ((-> void) . -> . number?) adjust-timeout! : (number? number? . -> . void) clear-continuations! : (number? . -> . void)
continuation-store! :
(number? any/c (or/c false/c (request? . -> . can-be-response?)) . -> . (list/c number? number?)) continuation-lookup : (number? number? number? . -> . any/c) continuation-peek : (number? number? number? . -> . any/c)
create-instance is called to initialize a instance, to hold the
continuations of one servlet session. It is passed
a function to call when the instance is expired. It runs the id of the
instance.
adjust-timeout! is a to-be-deprecated function that takes an
instance-id and a number. It is specific to the timeout-based manager
and will be removed.
clear-continuations! expires all the continuations of an instance.
continuation-store! is given an instance-id, a continuation value,
and a function to include in the exception thrown if the continuation is
looked up and has been expired. The two numbers returned are a
continuation-id and a nonce.
continuation-lookup finds the continuation value associated with
the instance-id, continuation-id, and nonce triple it is given.
continuation-peek is identical to continuation-lookup except that
its use must not affect the resource management policy decisions on the instance or
continuation accessed. It is intended to be used by debuggers and benchmarks.
struct
(struct exn:fail:servlet-manager:no-instance exn:fail ( expiration-handler) #:extra-constructor-name make-exn:fail:servlet-manager:no-instance)
expiration-handler :
(or/c false/c (request? . -> . can-be-response?))
This exception should be thrown by a manager when an instance is looked
up that does not exist.
struct
(struct exn:fail:servlet-manager:no-continuation exn:fail ( expiration-handler) #:extra-constructor-name make-exn:fail:servlet-manager:no-continuation)
expiration-handler :
(or/c false/c (request? . -> . can-be-response?))
This exception should be thrown by a manager when a continuation is
looked up that does not exist.
2.5.2 No Continuations
This module defines a manager constructor:
procedure
(create-none-manager instance-expiration-handler) → manager?
instance-expiration-handler :
(or/c false/c (request? . -> . can-be-response?))
This manager does not actually store any continuation or instance data.
You could use it if you know your servlet does not use the continuation
capturing functions and want the server to not allocate meta-data
structures for each instance.
If you do use a continuation capturing function, the continuation is
simply not stored. If the URL is visited, the instance-expiration-handler
is called with the request.
If you are considering using this manager, also consider using the
Web Language. (See Stateless Servlets.)
2.5.3 Timeouts
This module defines a manager constructor:
procedure
(create-timeout-manager instance-exp-handler instance-timeout continuation-timeout) → manager?
instance-exp-handler :
(or/c false/c (request? . -> . can-be-response?)) instance-timeout : number? continuation-timeout : number?
Instances managed by this manager will be expired instance-timeout
seconds after the last time it is accessed. If an expired instance is
looked up, the exn:fail:servlet-manager:no-instance exception
is thrown with instance-exp-handler as the expiration handler.
Continuations managed by this manager will be expired continuation-timeout
seconds after the last time it is accessed. If an expired continuation is looked
up, the exn:fail:servlet-manager:no-continuation exception
is thrown with instance-exp-handler as the expiration handler, if
no expiration-handler was passed to continuation-store!.
adjust-timeout! corresponds to reset-timer! on the timer
responsible for the servlet instance.
This manager has been found to be... problematic... in large-scale
deployments of the Web Server .
2.5.4 LRU
This module defines a manager constructor:
procedure
(create-LRU-manager instance-expiration-handler check-interval collect-interval collect? [ #:initial-count initial-count #:inform-p inform-p]) → manager?
instance-expiration-handler :
(or/c false/c (request? . -> . can-be-response?)) check-interval : integer? collect-interval : integer? collect? : (-> boolean?) initial-count : integer? = 1 inform-p : (integer? . -> . void) = (lambda _ (void))
Instances managed by this manager will be expired if there are no
continuations associated with them, after the instance is unlocked.
If an expired instance is looked up, the
exn:fail:servlet-manager:no-instance exception
is thrown with instance-exp-handler as the expiration handler.
Continuations managed by this manager are given a "Life Count" of
initial-count initially. If an expired continuation is looked
up, the exn:fail:servlet-manager:no-continuation exception
is thrown with instance-exp-handler as the expiration handler, if
no expiration-handler was passed to continuation-store!.
Every check-interval seconds collect? is called to determine
if the collection routine should be run. Every collect-interval seconds
the collection routine is run.
Every time the collection routine runs, the "Life Count" of every
continuation is decremented by 1. If a continuation’s count
reaches 0, it is expired. The inform-p function
is called if any continuations are expired, with the number of
continuations expired.
The recommended usage of this manager is codified as the following function:
procedure
(make-threshold-LRU-manager instance-expiration-handler memory-threshold) → manager?
instance-expiration-handler :
(or/c false/c (request? . -> . can-be-response?)) memory-threshold : number?
This creates an LRU manager with the following behavior:
The memory limit is set to memory-threshold bytes. Continuations start with 24
life points. Life points are deducted at the rate of one every 10 minutes, or one
every 5 seconds when the memory limit is exceeded. Hence the maximum life time for
a continuation is 4 hours, and the minimum is 2 minutes.
If the load on the server spikes—