Chapter 7   API Clarifications


This appendix clarifies ways in which the Servlet 2.2 API specification is implemented in iPlanet Web Server 6.0 in the following sections:

• Clarification of HttpSession Scope

• Clarifications for Using Methods

• Other Useful Information

Clarification of HttpSession Scope

---

The Servlet 2.2 API Specification is open to interpretation in regard to the scope of HttpSession objects.

By default, iPlanet Web Server marks the session tracking cookie's path to that of the context or application's contextPath. This results in the browser not replaying a session cookie to an application for which it is not intended. Hence, the HttpSession objects are scoped appropriately.

However, if servlet A in one context dispatches a request to servlet B in a different context, the specification is open to interpretation. By default iPlanet Web Server permits this, and you must make sure that the attributes placed in the HttpSession object are loaded by a class loader that is common to the applications involved. You can use a virtual-server-level class loader or the system class loader, although this is not generally recommended.

To allow different applications to share sessions and session attributes:

• Use a common session manager at the virtual server level.

  <vs>
     <session-manager class="..." />
  </vs>

• Make sure that the session attributes are loaded by the virtual-server-level class loader. Add any common beans and so on that are going to be used as session attributes to the classpath there.

  <vs>
     <class-loader classpath="/myapps/sessionattrs.jar" />
  </vs>

This configuration lets you share sessions across all applications within a virtual server or none at all. For iPlanet Web Server 6.0, there is no way that only a set of applications can share the same session data.

Clarifications for Using Methods

---

This section provides clarifications for using the following Servlet 2.2 API methods with iPlanet Web Server 6.0:

• HttpServlet.service

• ServletContext.getAttribute

• ServletRequest.setAttribute

• ServletRequest.getParameter

• ServletResponse.getOutputStream and getWriter

• RequestDispatcher.forward and include

For the official documentation for the methods discussed here (and for all servlet API methods) see the Servlets API Javadoc published by Sun Microsystems at:

http://java.sun.com/products/servlet/2.2/javadoc/index.html

HttpServlet.service

public void service(ServletRequest req, ServletResponse res) throws ServletException, java.io.IOException

This method dispatches client requests to the protected service method.

Clarification

Servlets may create additional threads to handle their service logic. However, the API functions exposed by these objects must be accessed by either the request handling thread or one of the threads the servlet created, but not by both simultaneously.

ServletContext.getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Returns the servlet container attribute with the given name, or null if there is no attribute by that name.

Clarification

To obtain the context class loader (a java.lang.ClassLoader object), use the com.iplanet.server.http.servlet.classloader attribute. To obtain the context class loader's classpath (a java.lang.String object), use the com.iplanet.server.http.servlet.classpath attribute.To obtain the context class loader's reload interval (a java.lang.Integer object), use the com.iplanet.server.http.servlet.reload-interval attribute.

ServletRequest.setAttribute

public void setAttribute(java.lang.String name, java.lang.Object o)

Stores an attribute in this request. Attributes are reset between requests. This method is most often used in conjunction with RequestDispatcher.

Clarification

You can set the com.iplanet.server.http.servlet.parameterEncoding attribute in the request object to allow the getParameter method to know the encoding of the parameters it extracts.

ServletRequest.getParameter

public java.lang.String getParameter(java.lang.String name)

Retrieves the value associated with a parameter name.

Clarification

When your form fields contain non-UTF-8 characters, you must do one of the following, or the values extracted by the getParameter method are zeros or are undefined:

• Set the enc attribute of the parameter-encoding element to auto (the default) in the web-apps.xml file. For more information, see "parameter-encoding."

• Set the parameterEncoding property to auto (the default) or responseCT in the contexts.properties file, as in iPlanet Web Server 4.x. For more information, see "parameterEncoding."

Because the original encoding used to enter data into form fields is lost when the data is URL-encoded, you must do the following:

• Always set the response content type when sending a form to a client. This ensures that the entire form gets safely to the client.

• When sending form data to a server that uses a different locale than the form fields, you must tell the server the charset before you call the getParameter method, as follows:
  • If the servlet or JSP that generated the form is different than the one processing the form, use a hidden field in the form (called j_encoding by default), for example:

          <input type="hidden" name="j_encoding" value="US_ASCII">

  • Set the com.iplanet.server.http.servlet.parameterEncoding attribute in the request object (see "ServletRequest.setAttribute"). The getParameter method uses this attribute to decode the parameters.

  • If parameterEncoding=responseCT in contexts.properties and the same servlet or JSP generates and processes the form, you can set the response content type. For servlets, explicitly set it as in this example:

          res.setContentType("text/plain; charset=Shift_JIS");

    For JSPs, set the response content type using a page directive, for example:

          <%@ page contentType="text/html; charset=gb2312"%>

ServletResponse.getOutputStream and getWriter

public ServletOutputStream getOutputStream() throws java.io.IOException

Returns a ServletOutputStream suitable for writing binary data in the response. The servlet container does not encode the binary data. Either this method or getWriter may be called to write the body, not both.

public java.io.PrintWriter getWriter() throws java.io.IOException

Returns a PrintWriter object that can send character text to the client. The character encoding used is the one specified in the charset= property of the setContentType(java.lang.String) method, which must be called before calling this method for the charset to take effect.

Either this method or getOutputStream may be called to write the body, not both.

Clarification

The specification recommends that when a servlet calls the getWriter method on a response for which the getOutputStream method has already been called, or the other way around, the servlet container should throw an IllegalStateException.

iPlanet Web Server 6.0 doesn't throw the exception, while ensuring that the writes to writer and the output stream are ordered. This implementation is more lenient but preserves correctness and permits scenarios like these:

• A servlet calls getOutputStream and throws an exception, and a JSP is used for the exception page. With strict compliance, this fails, because the JSP tries to call getWriter on the response object.

• A JSP that calls getWriter includes a servlet that calls getOutputStream.

RequestDispatcher.forward and include

public void forward(ServletRequest request, ServletResponse response) throws ServletException, IOException;

Used for forwarding a request from this servlet to another resource on the web server. This method is useful when one servlet does preliminary processing of a request and wants to let another object generate the response.

The request object passed to the target object will have its request URL path and other path parameters adjusted to reflect the target URL path of the target object.

You cannot use this method if a ServletOutputStream object or PrintWriter object has been obtained from the response. In that case, the method throws an IllegalStateException.

public void include(ServletRequest request, ServletResponse response) throws ServletException, IOException;

Used for including the content generated by another server resource in the body of a response. In essence, this method enables programmatic server-side includes. The request object passed to the target object reflects the request URL path and path info of the calling request. The response object only has access to the calling servlet's ServletOutputStream object or PrintWriter object.

An included servlet cannot set headers. If the included servlet calls a method that needs to set headers (such as cookies), it will not work. As a servlet developer, you must ensure that any methods that might need direct access to headers are properly resolved. To ensure that a session works correctly, start the session outside the included servlet, even if you use session tracking.

Clarification

In iPlanet Web Server 6.0, the dispatcher.forward method may or may not throw an IllegalStateException when either Writer or OutputStream have been obtained. This behavior follows the 2.2 draft and is needed for JSP error page handling. It throws the exception only if the actual data has been flushed out and sent to the client. Otherwise, the data pending in the buffer is simply discarded.

The forward and include methods may throw a ServletException if the target URI is identified as an unsafe URI (that is, it includes insecure path characters such as //, /./, /../ and/., /.. (and also ./ for NT) at the end of the URI.

You can control the nesting depth of the RequestDispatcher.forward and include methods using the requestDispatcherNestDepth parameter in magnus.conf. For more information, see Appendix A "Servlet Settings in magnus.conf and obj.conf."

Other Useful Information

---

This section contains information about the following topics:

• Database Connection Pooling

• Fetching the Client Certificate

Database Connection Pooling

Database connection pooling enhances the performance of servlet or JSP database interactions. There are several JDBC 2.0 compatible drivers that support connection pooling, for example Oracle 8i update and CloudScape 3.0.

Fetching the Client Certificate

When you enable SSL and require client certificate authorization, your servlets have access to the client certificate as shown in the following example:

if (request.isSecure()) {
   java.security.cert.X509Certificate[] certs;
   certs = request.getAttribute("javax.servlet.request.X509Certificate");
   if (certs != null) {
      clientCert = certs[0];
      if (clientCert != null) {
         // Get the Distinguised Name for the user.
         java.security.Principal userDN = clientCert.getSubjectDN();
         ...
      }
   }
}

The userDn is the fully qualified Distinguished Name for the user.