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.
Requires:
(import siscweb/request)
Located in:
siscweb.jar
This module provides wrappers around the Request object current at the time of invocation.
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.HttpServletRequestReturns 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) => stringReturns 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) => stringReturns 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) => numberReturns 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) => stringReturns the MIME type of the body of the request, or #f if the type is not known.
procedure:
(request/get-cookies) => listReturns a list containing all of the
javax.servlet.http.Cookieobjects the client sent with this request. This method returns the empty list if no cookies were sent.
procedure:
(request/get-date-header name) => timeReturns 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) => procReturns a procedure
procthat, when invoked with the parametersrequestandresponse, will forward the request to the resource located at the givenc-url. The resource can be dynamic or static.The specified
c-urlmay 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) => stringReturns 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 headernameis case insensitive. You can use this procedure with any request header.
procedure:
(request/get-header-alist) => alistReturns a
(name . value)association list of all the header names. All the headervalues are returned as strings.
procedure:
(request/get-header-hashtable) => hashtableReturns all the request headers as a hashtable of
name-valueassociations. All the headervalues are returned as strings.
procedure:
(request/get-header-names) => listReturns 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-header-names) => listReturns 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) => integerReturns 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) => jobjectReturns the value of the
named attribute as a Java object, ornullif no attribute of the givennameexists.
procedure:
(request/get-java-attribute-names) => listReturns 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.LocaleReturns a Java
java.util.Localeobject 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) => listReturns a list of
java.util.Localeobjects 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 onejava.util.Locale, the default locale for the server.
procedure:
(request/get-method) => stringReturns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.
procedure:
(request/get-parameter name) => stringReturns 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 byrequest/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-portorrequest/open-input-portcan interfere with the execution of this procedure.
procedure:
(request/get-parameter-alist) => alistReturns a
(name . (value1 ...))association list of all parameters and their values.
procedure:
(request/get-parameter-hashtable) => hashtableReturns a hashtable containing the association between parameter names and lists of the parameter values.
procedure:
(request/get-parameter-names) => listReturns 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) => listReturns 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) => stringReturns 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
SISCAdapterServletbut precedes the query string. This procedure returns #f if there was no extra path information.
procedure:
(request/get-path-translated) => stringReturns 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) => stringReturns 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) => stringReturns 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) => stringReturns the Internet Protocol (IP) address of the client that sent the request.
procedure:
(request/get-remote-host) => stringReturns 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) => stringReturns 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) => stringReturns 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-server-name) => stringReturns the host name of the server that received the request.
procedure:
(request/get-server-port) => integerReturns the port number on which this request was received.
procedure:
(request/get-servlet-path) => stringReturns 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.HttpSessionReturns 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
createis #f and the request has no validHttpSession, this method returnsnull.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
IllegalStateExceptionis thrown.
procedure:
(request/get-uri) => stringReturns 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) => stringReconstructs 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.PrincipalReturns a
java.security.Principalobject containing the name of the current authenticated user. If the user has not been authenticated, the method returnsnull.
procedure:
(request/open-binary-input-port) => binary-input-portRetrieves the body of the request as binary data using a binary input port. Either this procedure or
request/open-input-portmay be called to read the body, not both.
procedure:
(request/open-input-port) => character-input-portRetrieves 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-portmay be called to read the body, not both.
procedure:
(request/remove-java-attribute! name) => #!voidRemoves 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/#fChecks whether the requested session ID came in as a cookie.
procedure:
(request/session-id-from-url?) => #t/#fChecks whether the requested session ID came in as part of the request URL.
procedure:
(request/requested-session-id-valid?) => #t/#fChecks whether the requested session ID is still valid.
procedure:
(request/secure?) => #t/#fChecks whether this request was made using a secure channel, such as HTTPS.
procedure:
(request/set-character-encoding! encoding) => #!voidOverrides 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.
Requires:
(import siscweb/response)
Located in:
siscweb.jar
This module provides wrappers around the Response object current at the time of invocation.
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.HttpServletResponseReturns 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) => #!voidAdds 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) => #!voidAdds a response header with the given name and value. This method allows response headers to have multiple values.
The
valueparameter can either be a string, an integer number or an SRFI-19 date or time structure.
procedure:
(response/add-headers! alist) => #!voidAdds multiple headers, one for each (
name.value) element of thealist, withvaluebeing either a string, an integer number or an SRFI-19 time structure.
procedure:
(response/commit!) => #!voidCommits the response, forcing any content in the buffer to be written to the client, including the status code and headers.
procedure:
(response/committed?) => #t/#fChecks if the response has been committed. A commited response has already had its status code and headers written.
procedure:
(response/contains-header? name) => #t/#fChecks whether the
named response header has already been set.
procedure:
(response/encode-redirect-url url) => stringEncodes the specified
urlfor use in theresponse/send-redirectprocedure or, if encoding is not needed, returns theurlunchanged. 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 fromresponse/encode-url.All URLs sent to the
response/send-redirectprocedure should be run through this method. Otherwise, URL rewriting cannot be used with browsers which do not support cookies.
procedure:
(response/encode-url url) => stringEncodes the specified
urlby including the session ID in it, or, if encoding is not needed, returns theurlunchanged. 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) => integerReturns the actual buffer size used for the response. If no buffering is used, this procedure returns 0.
procedure:
(response/get-character-encoding) => encodingReturns 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/open-binary-output-port) => binary-output-portReturns 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-portmay be called to write the body, not both.
procedure:
(response/open-output-port) => character-output-portReturns 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-portmay be called to write the body, not both.
procedure:
(response/reset!) => #!voidClears 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!) => #!voidClears 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]) => #!voidSends 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) => #!voidSends 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) => #!voidSets 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) => #!voidSets 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) => #!voidSets 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) => #!voidSets a response header with the given
nameandvalue. If the header had already been set, the new value overwrites the previous one. Theresponse/contains-header?procedure can be used to test for the presence of a header before setting its value.The
valueparameter can either be a string, an integer number or an SRFI-19 date or time structure.
procedure:
(response/set-locale! java.util.Locale) => #!voidSets 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) => #!voidSets 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-errorprocedure should be used instead.The container clears the buffer and sets the Location header, preserving cookies and other headers.
Requires:
(import siscweb/session)
Located in:
siscweb.jar
This module provides wrappers around the Response object current at the time of invocation.
The procedures are sorted in alphabetical order. The descriptions are adapted from the J2EE 1.3 javadoc.
procedure:
(current-session) => javax.servlet.HttpSessionReturns 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) => timeReturns the time when this session was created as an SRFI-19 time structure.
procedure:
(session/get-id) => stringReturns 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) => jobjectReturns the Java object bound with the specified name in this session, or
nullif no object is bound under the name.
procedure:
(session/get-java-attribute-names) => listReturns an list of names of all the objects bound to this session.
procedure:
(session/get-last-accessed-time) => timeReturns 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) => secondsReturns 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.ServletContextReturns the
javax.servlet.ServletContextobject to which this session belongs.
procedure:
(session/invalidate!) => #!voidInvalidates this session then unbinds any objects bound to it.
procedure:
(session/make-parameter name) => procReturns a procedure
procthat, when invoked, sets or retrieves a Scheme value to/from the a Session attribute namedname, depending on whether a value is passed or not to. Ifprocis passed the #f value, the attribute is removed from the Session object altogether.
procedure:
(session/new?) => #t/#fReturns #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) => #!voidRemoves the object bound with the specified
namefrom 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) => #!voidBinds a Java object
jobjectto this session, using the specifiedname. 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 callingsession/remove-java-attribute!.
Requires:
(import siscweb/context)
Located in:
siscweb.jar
This module provides wrappers around the ServletContext object.
The procedures are sorted in alphabetical order. The descriptions are adapted from the J2EE 1.3 javadoc.
procedure:
(current-context) => javax.servlet.ServletContextReturns the current ServletContext. Also see the procedure
context/get.
procedure:
(context/get uripath) => javax.servlet.ServletContextReturns 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) => procReturns a procedure
procthat, when invoked with the parametersrequestandresponse, will forward the request to the resource located at the givenc-url. The resource can be dynamic or static.In the first form, the specified
c-urlmay 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-nameindicates 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) => stringReturns 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) => alistReturns a
(name . value)association list of all the context's initialization parameter names and their values.
procedure:
(context/get-init-parameter-hashtable) => hashtableReturns a hashtable containing the association between all the context's initialization parameter names and their values.
procedure:
(request/get-init-parameter-names) => listReturns 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) => jobjectReturns 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) => listReturns a list containing the attribute names available within this servlet context. Use the
context/get-java-attributeprocedure with an attribute name to get the value of an attribute.
procedure:
(context/get-major-version) => integer
procedure:(context/get-minor-version) => integerThese 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) => stringReturns 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) => stringReturns the name of this web application correponding to this servlet context as specified in the deployment descriptor for this web application by the
display-nameelement.
procedure:
(context/get-real-path c-url) => pathReturns 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-real-path c-url) => pathReturns 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) => urlReturns 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) => listReturns 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) => stringReturns 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) => procReturns a procedure
procthat, when invoked, sets or retrieves a Scheme value to/from the a servlet context attribute namedname, depending on whether a value is passed or not to. Ifprocis passed the #f value, the attribute is removed from the servlet context altogether.
procedure:
(context/open-resource-binary-input-port file-path) => binary-input-portReturns a binary input port that reads from the resource located at the named
file-pathas an InputStream object.The data in file can be of any type or length. The
file-pathmust be specified according to the rules given incontext/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-resourcemethod is lost when using this method.
procedure:
(context/remove-java-attribute! name) => #!voidRemoves the attribute with the given name from the servlet context. After removal, subsequent calls to
context/get-java-attributeto 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) => #!voidBinds an object to a given attribute
namein 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
jnullvalue is passed, the effect is the same as callingcontext/remove-java-attribute!.
procedure:
(context/get-dispatcher c-url) => proc
procedure:(context/get-named-dispatcher servlet-name) => procReturns a procedure
procthat, when invoked with the parametersrequestandresponse, will forward the request to the resource located at the givenc-url. The resource can be dynamic or static.In the first form, the specified
c-urlmay 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-nameindicates 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.