From d6813fc8939cb5468bba9dea621ebfe8f3ce92a0 Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Sat, 2 Jun 2007 03:11:41 +0000 Subject: [PATCH] Documentation stubs and configuration documentation svn: r6460 --- .../docs/reference/configuration.scrbl | 173 +++++++++++++++++- .../docs/reference/dispatchers.scrbl | 13 ++ collects/web-server/docs/reference/lang.scrbl | 13 ++ .../web-server/docs/reference/managers.scrbl | 13 ++ .../web-server/docs/reference/private.scrbl | 13 ++ .../web-server/docs/reference/reference.scrbl | 12 ++ .../docs/reference/servlet-env.scrbl | 13 ++ .../web-server/docs/reference/servlet.scrbl | 13 ++ .../docs/reference/web-config-unit.scrbl | 13 ++ .../docs/reference/web-server-unit.scrbl | 13 ++ .../docs/reference/web-server.scrbl | 13 ++ 11 files changed, 299 insertions(+), 3 deletions(-) create mode 100644 collects/web-server/docs/reference/dispatchers.scrbl create mode 100644 collects/web-server/docs/reference/lang.scrbl create mode 100644 collects/web-server/docs/reference/managers.scrbl create mode 100644 collects/web-server/docs/reference/private.scrbl create mode 100644 collects/web-server/docs/reference/servlet-env.scrbl create mode 100644 collects/web-server/docs/reference/servlet.scrbl create mode 100644 collects/web-server/docs/reference/web-config-unit.scrbl create mode 100644 collects/web-server/docs/reference/web-server-unit.scrbl create mode 100644 collects/web-server/docs/reference/web-server.scrbl diff --git a/collects/web-server/docs/reference/configuration.scrbl b/collects/web-server/docs/reference/configuration.scrbl index fd909159cd..e21bf918df 100644 --- a/collects/web-server/docs/reference/configuration.scrbl +++ b/collects/web-server/docs/reference/configuration.scrbl @@ -1,13 +1,180 @@ #reader(lib "docreader.ss" "scribble") @require["../web-server.ss"] +@; XXX require mzscheme, url.ss, and contract.ss @title[#:style 'toc]{Configuration} -XXX - @local-table-of-contents[] @; ------------------------------------------------------------ -@section[#:tag "example"]{Example} +@section[#:tag "configuration-table-structs"]{Configuration Table Structure} + +@file{configuration/configuration-table-structs.ss} provides the following structures that +represent a standard configuration (see @secref["XXX"]) of the @file{web-server}. +The contracts on this structure influence the valid types of values in +the configuration table S-expression file format described in +@secref["configuration-table"]. + +@defstruct[configuration-table + ([port (between/c 1 65535)] + [max-waiting natural-number/c] + [initial-connection-timeout natural-number/c] + [default-host host-table?] + [virtual-hosts (listof (cons/c string? host-table?))])] + +@defstruct[host-table + ([indices (listof string?)] + [log-format symbol?] + [messages messages?] + [timeouts timeouts?] + [paths paths?])] + +@defstruct[host + ([indices (listof string?)] + [log-format symbol?] + [log-path (or/c false/c path-string?)] + [passwords (or/c false/c path-string?)] + [responders responders?] + [timeouts timeouts?] + [paths paths?])] + +@defstruct[responders + ([servlet (url? any/c . -> . response?)] + [servlet-loading (url? any/c . -> . response?)] + [authentication (url? (cons/c symbol? string?) . -> . response?)] + [servlets-refreshed (-> response?)] + [passwords-refreshed (-> response?)] + [file-not-found (request? . -> . response?)] + [protocol (url? . -> . response?)] + [collect-garbage (-> response?)])] + +@defstruct[messages + ([servlet string?] + [authentication string?] + [servlets-refreshed string?] + [passwords-refreshed string?] + [file-not-found string?] + [protocol string?] + [collect-garbage string?])] + +@defstruct[timeouts + ([default-servlet number?] + [password number?] + [servlet-connection number?] + [file-per-byte number?] + [file-base number?])] + +@defstruct[paths + ([conf (or/c false/c path-string?)] + [host-base (or/c false/c path-string?)] + [log (or/c false/c path-string?)] + [htdocs (or/c false/c path-string?)] + [servlet (or/c false/c path-string?)] + [mime-types (or/c false/c path-string?)] + [passwords (or/c false/c path-string?)])] + +@; ------------------------------------------------------------ +@section[#:tag "configuration-table"]{Configuration Table} + +@file{configuration/configuration-table.ss} provides functions for +reading, writing, parsing, and printing @scheme[configuration-table] +structures. + +@defproc[(sexpr->configuration-table (sexpr list?)) + configuration-table?] + +@defproc[(configuration-table->sexpr (ctable configuration-table?)) + list?] + +These functions do the expected and convert a @scheme[configuration-table] +from (to) an S-expression. The format of this S-expresssion is: + +@schemeblock[ +`((port ,integer?) + (max-waiting ,integer?) + (initial-connection-timeout ,integer?) + (default-host-table + ,host-table-sexpr?) + (virtual-host-table + (list ,symbol? ,host-table-sexpr?) + ...))] + +where a @scheme[host-table-sexpr] is: + +@; XXX Allowable log-formats? +@; XXX Where the paths are resolved relative to +@schemeblock[ +`(host-table + (default-indices ,string? ...) + (log-format ,symbol?) + (messages + (servlet-message ,path-string?) + (authentication-message ,path-string?) + (servlets-refreshed ,path-string?) + (passwords-refreshed ,path-string?) + (file-not-found-message ,path-string?) + (protocol-message ,path-string?) + (collect-garbage ,path-string?)) + (timeouts + (default-servlet-timeout ,integer?) + (password-connection-timeout ,integer?) + (servlet-connection-timeout ,integer?) + (file-per-byte-connection-timeout ,integer?) + (file-base-connection-timeout ,integer)) + (paths + (configuration-root ,path-string?) + (host-root ,path-string?) + (log-file-path ,path-string?) + (file-root ,path-string?) + (servlet-root ,path-string?) + (mime-types ,path-string?) + (password-authentication ,path-string?)))] + +@defproc[(read-configuration-table (path path-string?)) + configuration-table?] +@defproc[(write-configuration-table (ctable configuration-table?) (path path-string?)) + void] + +These functions do the expected and read (write) a @scheme[configuration-table] +from (to) the given @scheme[path]. + +@; ------------------------------------------------------------ +@section[#:tag "namespace"]{Servlet Namespaces} + +@; XXX Require dispatch-servlets and dispatch-lang + +@file{configuration/namespace.ss} provides a function to help create the +@scheme[make-servlet-namespace] procedure needed by the @scheme[make] functions +of @file{dispatchers/dispatch-servlets.ss} and @file{dispatchers/dispatch-lang.ss}. + +@; XXX Use actual keyword argument syntax +@; XXX Require for current-namespace + +@defproc[(make-make-servlet-namespace (keyword to-be-copied-module-specs (listof module-spec?))) + (key-> ([additional-specs (listof module-spec?)]) + namespace?)] + +This function creates a function that when called will construct a new @scheme[namespace] that +has all the modules from @scheme[to-be-copied-module-specs] and @scheme[additional-specs], as well +as @scheme[mzscheme] and @scheme[(lib "mred.ss" "mred")], provided they are already attached +to the @scheme[(current-namespace)] of the call-site. + +@subsection{Why this is useful} + +A different namespace is needed for each servlet, so that if servlet A and servlet B both use +a stateful module C, they will be isolated from one another. We see the @file{web-server} as +an operating system for servlets, so we inherit the isolation requirement on operating systems. + +However, there are some modules which must be shared. If they were not, then structures cannot +be passed from the @file{web-server} to the servlets, due to a subtlety in the way MzScheme +implements structures. + +Since, on occasion, a user will actually wanted servlets A and B to interact through module C. +A custom @scheme[make-servlet-namespace] can be created, through this procedure, that attaches +module C to all servlet namespaces. Through other means (see @secref["pipelines"]) different sets +of servlets can share different sets of modules. + +@; ------------------------------------------------------------ +@section[#:tag "responders"]{Standard Responders} XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/dispatchers.scrbl b/collects/web-server/docs/reference/dispatchers.scrbl new file mode 100644 index 0000000000..1e0f720356 --- /dev/null +++ b/collects/web-server/docs/reference/dispatchers.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Dispatchers} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/lang.scrbl b/collects/web-server/docs/reference/lang.scrbl new file mode 100644 index 0000000000..11a2dc069d --- /dev/null +++ b/collects/web-server/docs/reference/lang.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Web Language} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/managers.scrbl b/collects/web-server/docs/reference/managers.scrbl new file mode 100644 index 0000000000..60bd7f5b67 --- /dev/null +++ b/collects/web-server/docs/reference/managers.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Continuation Managers} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/private.scrbl b/collects/web-server/docs/reference/private.scrbl new file mode 100644 index 0000000000..6f634ab14d --- /dev/null +++ b/collects/web-server/docs/reference/private.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Internal} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/reference.scrbl b/collects/web-server/docs/reference/reference.scrbl index ca97588aa4..7900de810f 100644 --- a/collects/web-server/docs/reference/reference.scrbl +++ b/collects/web-server/docs/reference/reference.scrbl @@ -3,8 +3,20 @@ @title{Web Server Reference Manual} +The @file{web-server} collection provides libraries that can be used to +develop Web applications in Scheme. + @table-of-contents[] @include-section["configuration.scrbl"] +@include-section["dispatchers.scrbl"] +@include-section["lang.scrbl"] +@include-section["managers.scrbl"] +@include-section["private.scrbl"] +@include-section["servlet-env.scrbl"] +@include-section["servlet.scrbl"] +@include-section["web-config-unit.scrbl"] +@include-section["web-server-unit.scrbl"] +@include-section["web-server.scrbl"] @index-section["web-server-ref-index"] \ No newline at end of file diff --git a/collects/web-server/docs/reference/servlet-env.scrbl b/collects/web-server/docs/reference/servlet-env.scrbl new file mode 100644 index 0000000000..327bcf12a0 --- /dev/null +++ b/collects/web-server/docs/reference/servlet-env.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Servlet Environment} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/servlet.scrbl b/collects/web-server/docs/reference/servlet.scrbl new file mode 100644 index 0000000000..412120aa65 --- /dev/null +++ b/collects/web-server/docs/reference/servlet.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Servlets} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/web-config-unit.scrbl b/collects/web-server/docs/reference/web-config-unit.scrbl new file mode 100644 index 0000000000..4afbb7202a --- /dev/null +++ b/collects/web-server/docs/reference/web-config-unit.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Web Config Unit} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/web-server-unit.scrbl b/collects/web-server/docs/reference/web-server-unit.scrbl new file mode 100644 index 0000000000..2a0e39e5f8 --- /dev/null +++ b/collects/web-server/docs/reference/web-server-unit.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Web Server Unit} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file diff --git a/collects/web-server/docs/reference/web-server.scrbl b/collects/web-server/docs/reference/web-server.scrbl new file mode 100644 index 0000000000..69e9c77b4c --- /dev/null +++ b/collects/web-server/docs/reference/web-server.scrbl @@ -0,0 +1,13 @@ +#reader(lib "docreader.ss" "scribble") +@require["../web-server.ss"] + +@title[#:style 'toc]{Web Server} + +XXX + +@local-table-of-contents[] + +@; ------------------------------------------------------------ +@section[#:tag "example"]{Example} + +XXX \ No newline at end of file