Next: Generating HTTP responses, Previous: Installing Kawa programs as CGI scripts, Up: Working with XML and HTML [Contents][Index]
The following functions are useful for accessing properties of a HTTP request, in a Kawa program that is run either as a servlet or a CGI script. These functions can be used from plain Scheme, from KRL (whether in BRL-compatible mode or not), and from XQuery.
The examples below assume the request http://example.com:8080/myapp/foo/bar?val1=xyz&val2=abc, where myapp is the application context.
We also assume that this is handled by a script foo/+default+.
The file testsuite/webtest/info/+default+ in the Kawa source distribution
calls most of these functions.
You can try it as described in Self-configuring web page scripts.
Returns the URI of the request, as a value of type URI.
This excludes the server specification,
but includes the query string.
(It is the combination of CGI variables SCRIPT_NAME,
PATH_INFO, and QUERY_STRING.
Using servlets terminology, it is the combination of
Context Path, Servlet Path, PathInfo, and Query String.)
(request-URI) ⇒ "/myapp/foo/bar?val1=xyz&val2=abc"
Returns the URI of the request, as a value of type URI.
This excludes the server specification and the query string.
Equivalent to (path-file (request-URI)).
(It is the combination of CGI variables SCRIPT_NAME, and
PATH_INFO.
Same as the concatenation of (request-context-path),
(request-script-path), and (request-local-path).
Using servlets terminology, it is the combination of
Context Path, Servlet Path, and PathInfo.)
(request-path) ⇒ "/myapp/foo/bar"
This function is deprecated, because of possible confusion
with request-URI. Use request-path instead.
Returns the complete URL of the request, except the query string.
The result is a java.lang.StringBuffer.
(request-url) ⇒ "http://example.com:8080/myapp/foo/bar"
Returns the context path, relative to the server root.
This is an initial substring of the (request-path).
Similar to the Context Path of a servlet request,
except that it ends with a "/".
(request-context-path) ⇒ "/myapp/"
Returns the path of the script, relative to the context.
This is either an empty string, or a string that ends with "/",
but does not start with one. (The reason for this is to produce URIs
that work better with operations like resolve-uri.)
This is conceptually similar to request-servlet-path,
though not always the same, and the "/" conventions differ.
(request-script-path) ⇒ "foo/"
Returns the remainder of the request-path,
relative to the request-script-path.
(request-local-path) ⇒ "bar"
Returns the query string from an HTTP request. The query string is
the part of the request URL after a question mark.
Returns false if there was no query string.
Corresponds to the CGI variable QUERY_STRING.
(request-query-string) ⇒ "val1=xyz&val2=abc"
Request parameters are used for data returned from forms, and for other uses. They may be encoded in the query string or in the request body.
If there is a parameter with the given name (a string),
return the (first) corresponding value, as a string.
Otherwise, return the default value,
or #!null if there is no default.
(request-parameter "val1") ⇒ "xyz" (request-parameter "val9" "(missing)") ⇒ "(missing)"
If there is are one or more parameter with the given name (a string),
return them all (as multiple values).
Otherwise, return no values (i.e. (values)).
(request-parameters "val1") ⇒ "xyz" (request-parameters "val9") ⇒ #!void
Request a map of all the parameters.
This is a map from strings to a sequence of strings.
(Specifically, a java.util.Map<String,java.util.List<String>>.)
The request headers are a set of (keyword, string)-pairs transmitted as part of the HTTP request, before the request body.
If there is a header with the given name (a string),
return the corresponding value string.
Otherwise, return #!null.
(request-header "accept-language") ⇒ "en-us,en;q=0.5"
Request a map of all the headers.
This is a map from strings to a sequence of strings.
(Specifically, a java.util.Map<String,java.util.List<String>>.)
Return a textual input port for reading the request body, as a sequence of characters.
Return a binary input stream for reading the request body, as a sequence of bytes.
Return the entire request body as a string
Information about the interface and port on which the request was received.
The local address on which the request was received.
This is the combination of (request-local-host)
and (request-local-port), as an instance of
java.net.InetSocketAddress.
Get the IP address of the interface on which request was received,
as an java.net.InetAddress.
Get the IP address of the interface on which request was received, a string in numeric form:
(request-local-host) ⇒ "127.0.0.1"
Get the port this request was received on.
(request-local-port) ⇒ 8080
Information about the interface and port of the remote client that invoked the request.
The address of the remote client (usually a web browser)
which invoked the request.
This is the combination of (request-remove-host)
and (request-remote-port), as an instance of
java.net.InetSocketAddress.
Get the IP address of the remote client which invoked the request,
as an java.net.InetAddress.
Get the IP address of the remote client which invoked the request, as a string in numeric form.
(request-remote-host) ⇒ "123.45.6.7"
The port used by the remote client.
Map the request-path to a file name (a string)
in the server application directory.
Corresponds to the CGI variable PATH_TRANSLATED.
Returns the method of the HTTP request, usually "GET"
or "POST". Corresponds to the CGI variable REQUEST_METHOD.
Returns the scheme (protocol) of the request.
Usually "http", or "https".
Next: Generating HTTP responses, Previous: Installing Kawa programs as CGI scripts, Up: Working with XML and HTML [Contents][Index]