Functions for accessing HTTP requests
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 page scripts.
Procedure: request-URI
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"
Procedure: request-path
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"
Procedure: request-uri
This function is deprecated, because of possible confusion
with request-URI. Use request-path instead.
Procedure: request-url
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"
Procedure: request-context-path
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/"
Procedure: request-script-path
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/"
Procedure: request-local-path
Returns the remainder of the request-path,
relative to the request-script-path.
(request-local-path) ⇒ "bar"
Procedure: request-query-string
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.
Procedure: request-parameter name [default]
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)"
Procedure: request-parameters name
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
Procedure: request-parameter-map
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.
Procedure: request-header name
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"
Procedure: request-header-map
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>>.)
Procedure: request-input-port
Return a textual input port for reading the request body,
as a sequence of characters.
Procedure: request-input-stream
Return a binary input stream for reading the request body,
as a sequence of bytes.
Procedure: request-body-string
Return the entire request body as a string
Request IP addresses and ports
Information about the interface and port on which the request was received.
Procedure: request-local-socket-address
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.
Procedure: request-local-host
Get the IP address of the interface on which request was received,
as an java.net.InetAddress.
Procedure: request-local-IP-address
Get the IP address of the interface on which request was received,
a string in numeric form:
(request-local-host) ⇒ "127.0.0.1"
Procedure: request-local-port
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.
Procedure: request-remote-socket-address
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.
Procedure: request-remote-host
Get the IP address of the remote client which invoked the request,
as an java.net.InetAddress.
Procedure: request-remote-IP-address
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"
Procedure: request-remote-port
The port used by the remote client.
Miscellaneous request properties
Procedure: request-path-translated
Map the request-path to a file name (a string)
in the server application directory.
Corresponds to the CGI variable PATH_TRANSLATED.
Procedure: request-method
Returns the method of the HTTP request, usually "GET"
or "POST". Corresponds to the CGI variable REQUEST_METHOD.
Procedure: request-scheme
Returns the scheme (protocol) of the request.
Usually "http", or "https".
