Chapter 8. Lower-level APIs

Chapter 8. Lower-level APIs
Prev		Next

Even though SISCweb applies an abstraction layer over characteristics of the HTTP protocol, it is still at times convenient to access the details of requests, responses, sessions and the servlet context in which they live.

For this reason SISCweb provides wrappers around all the methods of the Request, Response, Session and ServletContextobjects. All the procedures operate on the instances current at the time of invocation.

Request Procedures

Requires: (import siscweb/request)
Located in: siscweb.jar

This module provides wrappers around the Request object current at the time of invocation.

Note

Because of the large number of methods, they are here sorted in alphabetical order. The descriptions are adapted from the J2EE 1.3 javadoc.

procedure: (current-request) => javax.servlet.http.HttpServletRequest
Returns the current Request object. Since complete wrappers are provided by this module, this is normally useful to either create Request adapters, or to use the the procedure returned by request/get-dispatcher.

procedure: (request/get-auth-type) => string
Returns the name of the authentication scheme used to protect the URL of the published procedure, or #f if the URL does not require authentication.

procedure: (request/get-character-encoding) => string
Returns the name of the character encoding used in the body of this request, or #f if the request does not specify a character encoding.

procedure: (request/get-content-length) => number
Returns the length, in bytes, of the request body and made available by the input stream, or -1 if the length is not known.

procedure: (request/get-content-type) => string
Returns the MIME type of the body of the request, or #f if the type is not known.

procedure: (request/get-cookies) => list
Returns a list containing all of the javax.servlet.http.Cookie objects the client sent with this request. This method returns the empty list if no cookies were sent.

procedure: (request/get-date-header name) => time
Returns the value of the specified request header as a SRFI-19 time structure. Use this method with headers that contain dates, such as If-Modified-Since.
If the request did not have a header of the specified name, this method returns #f. If the header can't be converted to a date, the method throws a Java IllegalArgumentException.

procedure: (request/get-dispatcher c-url) => proc
Returns a procedure proc that, when invoked with the parameters request and response, will forward the request to the resource located at the given c-url. The resource can be dynamic or static.
The specified c-url may be relative to the path of the published procedure, although it cannot extend outside the current servlet context. If the path begins with a "/" it is interpreted as relative to the current context root. This method returns #f if the servlet container cannot return a RequestDispatcher.

procedure: (request/get-header name) => string
Returns the value of the specified request header as a string. If the request did not include a header of the specified name, this procedure returns #f. The header name is case insensitive. You can use this procedure with any request header.

procedure: (request/get-header-alist) => alist
Returns a (name . value) association list of all the header names. All the header values are returned as strings.

procedure: (request/get-header-hashtable) => hashtable
Returns all the request headers as a hashtable of name-value associations. All the header values are returned as strings.

procedure: (request/get-header-names) => list
Returns list of all the header names this request contains. If the request has no headers, this method returns an empty list.
Some servlet containers do not allow do not allow servlets to access headers using this method, in which case this procedure returns #f.

procedure: (request/get-int-header name) => integer
Returns the value of the specified request header as an integer. If the request does not have a header of the specified name, this procedure returns #f. If the header cannot be converted to an integer, this method throws a Java NumberFormatException.
The header name is case insensitive.

procedure: (request/get-java-attribute name) => jobject
Returns the value of the named attribute as a Java object, or null if no attribute of the given name exists.

procedure: (request/get-java-attribute-names) => list
Returns a list of names of the attributes available to this request. This method returns an empty list if the request has no attributes available to it.

procedure: (request/get-locale) => java.util.Locale
Returns a Java java.util.Locale object representing the preferred locale that the client will accept content in, based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns the default locale for the server.

procedure: (request/get-locales) => list
Returns a list of java.util.Locale objects indicating, in decreasing order starting with the preferred locale, the locales that are acceptable to the client based on the Accept-Language header. If the client request doesn't provide an Accept-Language header, this method returns an Enumeration containing one java.util.Locale, the default locale for the server.

procedure: (request/get-method) => string
Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.

procedure: (request/get-parameter name) => string
Returns the value of a request parameter as a string, or #f if the parameter does not exist.
You should only use this method when you are sure the parameter has only one value. If the parameter might have more than one value, use request/get-parameter-values. If you use this method with a multivalued parameter, the value returned is equal to the first value in the list returned by request/get-parameter-values.
If the parameter data was sent in the request body, such as occurs with an HTTP POST request, then reading the body directly via request/open-binary-input-port or request/open-input-port can interfere with the execution of this procedure.

procedure: (request/get-parameter-alist) => alist
Returns a (name . (value1 ...)) association list of all parameters and their values.

procedure: (request/get-parameter-hashtable) => hashtable
Returns a hashtable containing the association between parameter names and lists of the parameter values.

procedure: (request/get-parameter-names) => list
Returns a list of names of the parameters contained in this request. If the request has no parameters, the procedure returns an empty list.

procedure: (request/get-parameter-values name) => list
Returns a list of values of the given request parameter, or the empty list if the parameter does not exist.
If the parameter has a single value, the list has a length of 1.

procedure: (request/get-path-info) => string
Returns any extra path information associated with the URL the client sent when it made this request. The extra path information follows the path of the SISCAdapterServlet but precedes the query string. This procedure returns #f if there was no extra path information.

procedure: (request/get-path-translated) => string
Returns any extra path information after the servlet name but before the query string, and translates it to a real path.
If the URL does not have any extra path information, this method returns #f. The web container does not decode thins string.

procedure: (request/get-protocol) => string
Returns the name and version of the protocol the request uses in the form protocol/majorVersion.minorVersion, for example, HTTP/1.1.

procedure: (request/get-query-string) => string
Returns the query string that is contained in the request URL after the path. This procedure returns #f if the URL does not have a query string.

procedure: (request/get-remote-addr) => string
Returns the Internet Protocol (IP) address of the client that sent the request.

procedure: (request/get-remote-host) => string
Returns the fully qualified name of the client that sent the request. If the engine cannot or chooses not to resolve the hostname (to improve performance), this procedure returns the dotted-string form of the IP address.

procedure: (request/get-remote-user) => string
Returns the login of the user making this request, if the user has been authenticated, or #f if the user has not been authenticated. Whether the user name is sent with each subsequent request depends on the browser and type of authentication.

procedure: (request/get-requested-session-id) => string
Returns the session ID specified by the client. This may not be the same as the ID of the actual session in use. For example, if the request specified an old (expired) session ID and the server has started a new session, this method gets a new session with a new ID. If the request did not specify a session ID, this method returns #f.

procedure: (request/get-scheme) => string
Returns the name of the scheme used to make this request.

procedure: (request/get-server-name) => string
Returns the host name of the server that received the request.

procedure: (request/get-server-port) => integer
Returns the port number on which this request was received.

procedure: (request/get-servlet-path) => string
Returns the part of this request's URL that calls the SISCAdapterServlet. This includes either the servlet name or a path to the servlet, but does not include any extra path information or a query string.

procedure: (request/get-session [create?]) => javax.servlet.http.HttpSession
Returns the current HttpSession associated with this request or, if if there is no current session and the create? is #t or absent, returns a new session.
If create is #f and the request has no valid HttpSession, this method returns null.
To make sure the session is properly maintained, you must call this method before the response is committed. If the container is using cookies to maintain session integrity and is asked to create a new session when the response is committed, a Java IllegalStateException is thrown.

procedure: (request/get-uri) => string
Returns the part of this request's URL from the protocol name up to the query string in the first line of the HTTP request. The web container does not decode this String.

procedure: (request/get-url) => string
Reconstructs the URL the client used to make the request. The returned URL contains a protocol, server name, port number, and server path, but it does not include query string parameters.

procedure: (request/get-user-principal) => java.security.Principal
Returns a java.security.Principal object containing the name of the current authenticated user. If the user has not been authenticated, the method returns null.

procedure: (request/open-binary-input-port) => binary-input-port
Retrieves the body of the request as binary data using a binary input port. Either this procedure or request/open-input-port may be called to read the body, not both.

procedure: (request/open-input-port) => character-input-port
Retrieves the body of the request as character data using a character input port. The port translates the character data according to the character encoding used on the body. Either this procedure or request/open-binary-input-port may be called to read the body, not both.

procedure: (request/remove-java-attribute! name) => #!void
Removes an attribute from this request. This method is not generally needed as attributes only persist as long as the request is being handled.

procedure: (request/session-id-from-cookie?) => #t/#f
Checks whether the requested session ID came in as a cookie.

procedure: (request/session-id-from-url?) => #t/#f
Checks whether the requested session ID came in as part of the request URL.

procedure: (request/requested-session-id-valid?) => #t/#f
Checks whether the requested session ID is still valid.

procedure: (request/secure?) => #t/#f
Checks whether this request was made using a secure channel, such as HTTPS.

procedure: (request/set-character-encoding! encoding) => #!void
Overrides the name of the character encoding used in the body of this request. This method must be called prior to reading request parameters or reading input using request/open-input-port.

procedure: (request/set-java-attribute! name jobject) => #!void
Stores a Java object in the named attribute in this request. Attributes are reset between requests. This method is most often used in conjunction with request/make-dispatcher.

procedure: (request/user-in-role? username) => #t/#f
Checks whether the authenticated user is included in the specified logical "role". Roles and role membership can be defined using deployment descriptors. If the user has not been authenticated, the method returns #f.

Response Procedures

Requires: (import siscweb/response)
Located in: siscweb.jar

This module provides wrappers around the Response object current at the time of invocation.

Note

Because of the large number of methods, they are here sorted in alphabetical order. The descriptions are adapted from the J2EE 1.3 javadoc.

procedure: (current-response) => javax.servlet.http.HttpServletResponse
Returns the current Response object. Since complete wrappers are provided by this module, this is normally useful to either create Request adapters, or to use the the procedure returned by request/get-dispatcher.

procedure: (response/add-cookie! javax.servlet.http.Cookie) => #!void
Adds the specified cookie to the response. This method can be called multiple times to set more than one cookie.

procedure: (response/add-header! name value) => #!void
Adds a response header with the given name and value. This method allows response headers to have multiple values.
The value parameter can either be a string, an integer number or an SRFI-19 date or time structure.

procedure: (response/add-headers! alist) => #!void
Adds multiple headers, one for each (name . value) element of the alist, with value being either a string, an integer number or an SRFI-19 time structure.

procedure: (response/commit!) => #!void
Commits the response, forcing any content in the buffer to be written to the client, including the status code and headers.

procedure: (response/committed?) => #t/#f
Checks if the response has been committed. A commited response has already had its status code and headers written.

procedure: (response/contains-header? name) => #t/#f
Checks whether the named response header has already been set.

procedure: (response/encode-redirect-url url) => string
Encodes the specified url for use in the response/send-redirect procedure or, if encoding is not needed, returns the url unchanged. The implementation of this method includes the logic to determine whether the session ID needs to be encoded in the URL. Because the rules for making this determination can differ from those used to decide whether to encode a normal link, this procedure is separate from response/encode-url.
All URLs sent to the response/send-redirect procedure should be run through this method. Otherwise, URL rewriting cannot be used with browsers which do not support cookies.

procedure: (response/encode-url url) => string
Encodes the specified url by including the session ID in it, or, if encoding is not needed, returns the url unchanged. The implementation of this method includes the logic to determine whether the session ID needs to be encoded in the URL. For example, if the browser supports cookies, or if session tracking is turned off, URL encoding is unnecessary.
For robust session tracking, all URLs emitted by a servlet should be run through this method. Otherwise, URL rewriting cannot be used with browsers which do not support cookies.

procedure: (response/get-buffer-size) => integer
Returns the actual buffer size used for the response. If no buffering is used, this procedure returns 0.

procedure: (response/get-character-encoding) => encoding
Returns the name of the charset used for the MIME body sent in this response. If no charset has been assigned, it is implicitly set to ISO-8859-1 (Latin-1).

procedure: (response/get-locale) => java.util.Locale
Returns the locale assigned to the response.

procedure: (response/open-binary-output-port) => binary-output-port
Returns a binary output port suitable for writing binary data in the response. The servlet container does not encode the binary data.
Flushing the port commits the response. Either this method or response/open-output-port may be called to write the body, not both.

procedure: (response/open-output-port) => character-output-port
Returns a character output port that can send character text to the client. The character encoding used is the one specified in the charset= property of the response/set-content-type! procedure, which must be called before calling this procedure for the charset to take effect.
If necessary, the MIME type of the response is modified to reflect the character encoding used.
Flushing the port commits the response. Either this method or response/open-binary-output-port may be called to write the body, not both.

procedure: (response/reset!) => #!void
Clears any data that exists in the buffer as well as the status code and headers. If the response has been committed, this method throws a Java IllegalStateException.

procedure: (response/reset-buffer!) => #!void
Clears the content of the underlying buffer in the response without clearing headers or status code. If the response has been committed, this method throws a Java IllegalStateException.

procedure: (request/send-error status-code [message]) => #!void
Sends an error response to the client using the specified status clearing the buffer. The server defaults to creating the response to look like an HTML-formatted server error page containing the specified message, setting the content type to "text/html", leaving cookies and other headers unmodified. If an error-page declaration has been made for the web application corresponding to the status code passed in, it will be served back in preference to the suggested msg parameter.
If the response has already been committed, this method throws a Java IllegalStateException. After using this method, the response should be considered to be committed and should not be written to.

procedure: (request/send-redirect url) => #!void
Sends a temporary redirect response to the client using the specified redirect url. This method can accept relative URLs; the servlet container must convert the relative URL to an absolute URL before sending the response to the client. If the location is relative without a leading '/' the container interprets it as relative to the current request URI. If the location is relative with a leading '/' the container interprets it as relative to the servlet container root.
If the response has already been committed, this method throws a Java IllegalStateException. After using this method, the response should be considered to be committed and should not be written to.

procedure: (request/set-buffer-size! bufsize) => #!void
Sets the preferred buffer size for the body of the response. The servlet container will use a buffer at least as large as the size requested. The actual buffer size used can be found using response/get-buffer-size.
This method must be called before any response body content is written; if content has been written, this method throws a Java IllegalStateException.

procedure: (request/set-content-length! length) => #!void
Sets the length of the content body in the response In HTTP servlets, this method sets the HTTP Content-Length header.

procedure: (request/set-content-type! type) => #!void
Sets the content type of the response being sent to the client. The content type may include the type of character encoding used, for example, text/html; charset=ISO-8859-4.
If obtaining a character output port, this method should be called first.

procedure: (response/set-header! name value) => #!void
Sets a response header with the given name and value. If the header had already been set, the new value overwrites the previous one. The response/contains-header? procedure can be used to test for the presence of a header before setting its value.
The value parameter can either be a string, an integer number or an SRFI-19 date or time structure.

procedure: (response/set-locale! java.util.Locale) => #!void
Sets the locale of the response, setting the headers (including the Content-Type's charset) as appropriate. This method should be called before a call to reponse/open-output-port. By default, the response locale is the default locale for the server.

procedure: (response/set-status! status-code) => #!void
Sets the status code for this response. This method is used to set the return status code when there is no error (for example, for the status codes SC_OK or SC_MOVED_TEMPORARILY). If there is an error, and the caller wishes to invoke an defined in the web applicaion, the response/send-error procedure should be used instead.
The container clears the buffer and sets the Location header, preserving cookies and other headers.

Session Procedures

Requires: (import siscweb/session)
Located in: siscweb.jar

This module provides wrappers around the Response object current at the time of invocation.

Note

The procedures are sorted in alphabetical order. The descriptions are adapted from the J2EE 1.3 javadoc.

procedure: (current-session) => javax.servlet.HttpSession
Returns the current Session, or creates a new one if one is not defined yet. Also see the procedure request/get-session.

procedure: (session/get-creation-time) => time
Returns the time when this session was created as an SRFI-19 time structure.

procedure: (session/get-id) => string
Returns a string containing the unique identifier assigned to this session. The identifier is assigned by the servlet container and is implementation dependent.

procedure: (session/get-java-attribute name) => jobject
Returns the Java object bound with the specified name in this session, or null if no object is bound under the name.

procedure: (session/get-java-attribute-names) => list
Returns an list of names of all the objects bound to this session.

procedure: (session/get-last-accessed-time) => time
Returns the last time the client sent a request associated with this session, as an SRFI-19 time structure, and marked by the time the container received the request.
Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time.

procedure: (session/get-max-inactive-interval) => seconds
Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses. After this interval, the servlet container will invalidate the session. The maximum time interval can be set with the setMaxInactiveInterval method. A negative time indicates the session should never timeout.

procedure: (session/get-servlet-context) => javax.servlet.ServletContext
Returns the javax.servlet.ServletContext object to which this session belongs.

procedure: (session/invalidate!) => #!void
Invalidates this session then unbinds any objects bound to it.

procedure: (session/make-parameter name) => proc
Returns a procedure proc that, when invoked, sets or retrieves a Scheme value to/from the a Session attribute named name, depending on whether a value is passed or not to
. If proc is passed the #f value, the attribute is removed from the Session object altogether.

procedure: (session/new?) => #t/#f
Returns #t if the client does not yet know about the session or if the client chooses not to join the session. For example, if the server used only cookie-based sessions, and the client had disabled the use of cookies, then a session would be new on each request.

procedure: (session/remove-java-attribute! name) => #!void
Removes the object bound with the specified name from this session. If the session does not have an object bound with the specified name, this method does nothing.

procedure: (session/set-java-attribute! name jobject) => #!void
Binds a Java object jobject to this session, using the specified name. If an object of the same name is already bound to the session, that object is replaced.
If the value passed in is jnull, this has the same effect as calling session/remove-java-attribute!.

procedure: (session/set-max-inactive-interval! seconds) => #!void
Specifies the time, in seconds, between client requests before the servlet container will invalidate this session. A negative time indicates the session should never timeout.

ServletContext Procedures

Requires: (import siscweb/context)
Located in: siscweb.jar

This module provides wrappers around the ServletContext object.

Note

The procedures are sorted in alphabetical order. The descriptions are adapted from the J2EE 1.3 javadoc.

procedure: (current-context) => javax.servlet.ServletContext
Returns the current ServletContext. Also see the procedure context/get.

procedure: (context/get uripath) => javax.servlet.ServletContext
Returns a ServletContext object that corresponds to a specified URL on the server.
This method allows servlets to gain access to the context for various parts of the server, and as needed obtain RequestDispatcher objects from the context. The given path must be begin with "/", is interpreted relative to the server's document root and is matched against the context roots of other web applications hosted on this container.
In a security conscious environment, the servlet container may return
for a given URL.

procedure: (context/get-dispatcher c-url) => proc
procedure: (context/get-named-dispatcher servlet-name) => proc
Returns a procedure proc that, when invoked with the parameters request and response, will forward the request to the resource located at the given c-url. The resource can be dynamic or static.
In the first form, the specified c-url may be relative to the path of the published procedure, although it cannot extend outside the current servlet context. If the path begins with a "/" it is interpreted as relative to the current context root. This method returns #f if the servlet container cannot return a RequestDispatcher.
In the second form, the specified servlet-name indicates a Servlet or JSP page named either via server administration or via a web application deployment descriptor.
This method returns #f if the ServletContext cannot return a dispatcher for any reason.

procedure: (context/get-init-parameter name) => string
Returns the value of the namedd context-wide initialization parameter as a string, or #f if the parameter does not exist.
This method can make available configuration information useful to an entire "web application". For example, it can provide a webmaster's email address or the name of a system that holds critical data.

procedure: (context/get-init-parameter-alist) => alist
Returns a (name . value) association list of all the context's initialization parameter names and their values.

procedure: (context/get-init-parameter-hashtable) => hashtable
Returns a hashtable containing the association between all the context's initialization parameter names and their values.

procedure: (request/get-init-parameter-names) => list
Returns a list of names of the context' s initialization parameters. If the has no initialization parameters, the procedure returns an empty list.

procedure: (context/get-java-attribute name) => jobject
Returns the servlet container attribute with the given name, or null if there is no attribute by that name. An attribute allows a servlet container to give the servlet additional information not already provided by this interface. See your server documentation for information about its attributes. A list of supported attributes can be retrieved using context/get-java-attribute-names.

procedure: (context/get-java-attribute-names) => list
Returns a list containing the attribute names available within this servlet context. Use the context/get-java-attribute procedure with an attribute name to get the value of an attribute.

procedure: (context/get-major-version) => integer
procedure: (context/get-minor-version) => integer
These procedures return the major and minor versions of the Java Servlet API that this servlet container supports. All implementations that comply with Version 2.3 must have this methods respectively return the integers 2 and 3.

procedure: (context/get-mime-type file-path) => string
Returns the MIME type of the specified file, or #f if the MIME type is not known. The MIME type is determined by the configuration of the servlet container, and may be specified in a web application deployment descriptor. Common MIME types are "text/html" and "image/gif".

procedure: (context/get-name) => string
Returns the name of this web application correponding to this servlet context as specified in the deployment descriptor for this web application by the display-name element.

procedure: (context/get-real-path c-url) => path
Returns a string containing the real path for a given virtual path. For example, the path "/index.html" returns the absolute file path on the server's filesystem would be served by a request for "http://host/contextPath/index.html", where contextPath is the context path of this servlet context.
The real path returned will be in a form appropriate to the computer and operating system on which the servlet container is running, including the proper path separators. This method returns null if the servlet container cannot translate the virtual path to a real path for any reason (such as when the content is being made available from a .war archive).

procedure: (context/get-resource file-path) => url
Returns a string representing a URL to the resource that is mapped to a specified path. The path must begin with a "/" and is interpreted as relative to the current context root.
This procedure allows the servlet container to make a resource available to servlets from any source. Resources can be located on a local or remote file system, in a database, or in a .war file.
This procedure returns #f if no resource is mapped to the pathname.

procedure: (context/get-resource-paths file-path) => list
Returns a directory-like list of all the paths to resources within the web application whose longest sub-path matches the supplied path argument. Paths indicating subdirectory paths end with a "/". The returned paths are all relative to the root of the web application and have a leading "/".

procedure: (context/get-resource-paths) => string
Returns the name and version of the servlet container on which the servlet is running.
The form of the returned string is servername/versionnumber. For example, the JavaServer Web Development Kit may return the string JavaServer Web Dev Kit/1.0.
The servlet container may return other optional information after the primary string in parentheses, for example, JavaServer Web Dev Kit/1.0 (JDK 1.1.6; Windows NT 4.0 x86).

procedure: (context/make-parameter name) => proc
Returns a procedure proc that, when invoked, sets or retrieves a Scheme value to/from the a servlet context attribute named name, depending on whether a value is passed or not to
. If proc is passed the #f value, the attribute is removed from the servlet context altogether.

procedure: (context/open-resource-binary-input-port file-path) => binary-input-port
Returns a binary input port that reads from the resource located at the named file-path as an InputStream object.
The data in file can be of any type or length. The file-path must be specified according to the rules given in context/get-resource. This procedure returns #f if no resource exists at the specified path.
Meta-information such as content length and content type that is available via context/get-resource method is lost when using this method.

procedure: (context/remove-java-attribute! name) => #!void
Removes the attribute with the given name from the servlet context. After removal, subsequent calls to context/get-java-attribute to retrieve the attribute's value will return #f.
If listeners are configured on the ServletContext the container notifies them accordingly.

procedure: (context/set-java-attribute! name jobject) => #!void
Binds an object to a given attribute name in this servlet context. If the name specified is already used for an attribute, this method will replace the attribute with the new to the new attribute.
If listeners are configured on the ServletContext the container notifies them accordingly.
If a jnull value is passed, the effect is the same as calling context/remove-java-attribute!.

procedure: (context/get-dispatcher c-url) => proc
procedure: (context/get-named-dispatcher servlet-name) => proc
Returns a procedure proc that, when invoked with the parameters request and response, will forward the request to the resource located at the given c-url. The resource can be dynamic or static.
In the first form, the specified c-url may be relative to the path of the published procedure, although it cannot extend outside the current servlet context. If the path begins with a "/" it is interpreted as relative to the current context root. This method returns #f if the servlet container cannot return a RequestDispatcher.
In the second form, the specified servlet-name indicates a Servlet or JSP page named either via server administration or via a web application deployment descriptor.
This method returns #f if the ServletContext cannot return a dispatcher for any reason.

Prev		Next
Chapter 7. Interaction with SQL Databases	Home	Appendix A. GNU General Public License