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.

Request URL components

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

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

Request headers

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

Request body

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