2.5 Web Interaction

(require web-server/servlet/web)

The web-server/servlet/web library provides the primary functions of interest for the servlet developer.

(send/back response) → void?

response : response?

Sends response to the client. No continuation is captured, so the servlet is done.

Example:

(send/back

`(html

(body

(h1 "The sum is: "

,(+ first-number

second-number)))))

(send/suspend make-response [exp]) → request?

make-response : response-generator/c

exp   :   expiration-handler/c       =   (current-servlet-continuation-expiration-handler)

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 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)

`(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.

(send/suspend/dispatch make-response) → any/c

make-response : (embed/url/c . -> . response?)

Calls make-response with a function 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.

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)

`(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)))])

"+"))))))))

It is very common that the return value of send/suspend/dispatch is irrevelant in your application and you may think of it as “embedding” value-less callbacks.

(send/forward make-response [exp]) → request?

make-response : response-generator/c

exp   :   expiration-handler/c       =   (current-servlet-continuation-expiration-handler)

Calls clear-continuation-table!, then send/suspend.

Use this if the user can logically go `forward’ in your application, but cannot go backward.

(send/finish response) → void?

response : 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

`(html (head (title "Logged out"))

(body (p "Thank you for using the services "

"of the Add Two Numbers, Inc."))))

(redirect/get) → request?

Calls send/suspend with redirect-to.

This implements the Post-Redirect-Get pattern. Use this to prevent the Refresh button from duplicating effects, such as adding items to a database.

(redirect/get/forget) → request?

Calls send/forward with redirect-to.

current-servlet-continuation-expiration-handler : (parameter/c expiration-handler/c)

Holds the expiration-handler/c to be used when a continuation captured in this context is expired, then looked up.

Example:

(parameterize

([current-servlet-continuation-expiration-handler

(lambda (req)

`(html (head (title "Custom Expiration!"))))])

(send/suspend

...))

(clear-continuation-table!) → void?

Calls the servlet’s manager’s clear-continuation-table! function. Normally, this deletes all the previously captured continuations.

(with-errors-to-browser   send/finish-or-back             thunk)   →   any

send/finish-or-back : (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)))))

(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.

(continuation-url? u)

→ (or/c false/c (list/c number? number? number?))

u : url?

Checks if u is a URL that refers to a continuation, if so returns the instance id, continuation id, and nonce.