{"size": 3555, "ext": "scrbl", "max_stars_repo_path": "web-server-doc/web-server/scribblings/dispatch-servlets.scrbl", "max_stars_repo_name": "jessealama/web-server", "max_stars_repo_stars_event_min_datetime": "2015-01-21T08:11:58.000Z", "max_stars_repo_stars_event_max_datetime": "2022-03-20T08:28:39.000Z", "max_issues_repo_path": "web-server-doc/web-server/scribblings/dispatch-servlets.scrbl", "max_issues_repo_name": "jessealama/web-server", "max_issues_repo_issues_event_min_datetime": "2015-01-14T08:06:37.000Z", "max_issues_repo_issues_event_max_datetime": "2022-02-12T14:38:40.000Z", "max_forks_repo_path": "web-server-doc/web-server/scribblings/dispatch-servlets.scrbl", "max_forks_repo_name": "jessealama/web-server", "max_forks_repo_forks_event_min_datetime": "2015-03-05T15:07:36.000Z", "max_forks_repo_forks_event_max_datetime": "2021-07-30T18:59:25.000Z"}
{"max_stars_count": 82, "max_issues_count": 105, "max_forks_count": 37, "avg_line_length": 42.8313253012, "max_line_length": 100, "alphanum_fraction": 0.6559774965}
#lang scribble/doc
@(require "web-server.rkt"
          (for-label web-server/http
                     web-server/private/servlet
                     web-server/configuration/responders
                     web-server/dispatchers/filesystem-map
                     web-server/servlet/setup
                     net/url
                     web-server/managers/manager))

@title[#:tag "dispatch-servlets"]{Serving Servlets}
@a-dispatcher[web-server/dispatchers/dispatch-servlets
              @elem{defines a dispatcher constructor
                    that runs servlets.}]{
          
@defthing[url->servlet/c contract?]{Equivalent to @racket[(url? . -> . servlet?)]}

@defproc[(make-cached-url->servlet
          [url->path url->path/c]
          [path->serlvet path->servlet/c])
         (values (->* () ((or/c false/c (listof url?)) (-> servlet? void?)) void?)
                 url->servlet/c)]{
 The first return value is a procedure that flushes the cache. If its first
 optional argument is @racket[#f] (the default), all servlet caches are
 flushed. Otherwise, only those servlet caches to which @racket[url->path]
 maps the given URLs are flushed. The second optional argument is a procedure
 which is invoked on each cached value before it is flushed, which can be used
 to finalize servlet resources. Beware that the default value @racket[void]
 performs no finalization. In particular, it does not shut down the servlet's
 custodian, instead allowing the servlet's custodian-managed resources (such
 as threads) to persist.
 
 The second return value is a procedure that uses
 @racket[url->path] to resolve the URL to a path, then uses
 @racket[path->servlet] to resolve that path to a servlet, caching the
 results in an internal table.

 @history[#:changed "1.3" "Added optional argument to first return value for list of URLs."
	  #:changed "1.3" "Added optional argument to first return value for servlet finalizer procedure."]
}

@defproc[(make [url->servlet url->servlet/c]
               [#:responders-servlet-loading
                responders-servlet-loading
                (url? exn? . -> . can-be-response?)
                servlet-loading-responder]
               [#:responders-servlet
                responders-servlet
                (url? exn? . -> . can-be-response?)
                servlet-error-responder])
         dispatcher/c]{
 This dispatcher runs racket servlets, using @racket[url->servlet] to
 resolve URLs to the underlying servlets.  If servlets have errors
 loading, then @racket[responders-servlet-loading] is used. Other errors
 are handled with @racket[responders-servlet]. If a servlet raises calls
 @racket[next-dispatcher], then the signal is propagated by this
 dispatcher.
}

}

@include-section["servlet-setup.scrbl"]

@include-section["namespace.scrbl"]

@section{Internal Servlet Representation}

@defmodule[web-server/private/servlet]{
  @defstruct[servlet ([custodian custodian?]
                      [namespace namespace?]
                      [manager manager?]
                      [directory path-string?]
                      [handler (request? . -> . can-be-response?)])
                     #:mutable]{
   Instances of this structure hold the necessary parts of a servlet:
   the @racket[custodian] responsible for the servlet's resources,
   the @racket[namespace] the servlet is executed within,
   the @racket[manager] responsible for the servlet's continuations,
   the current @racket[directory] of the servlet,
   and the @racket[handler] for all requests to the servlet.
  }
}
