Appendix G   API Clarifications


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

• Clarifications for Using Methods

• Other Useful Information

Clarifications for Using Methods

---

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

• HttpUtils.getRequestURL

• HttpServletRequest.getContextPath

• HttpServletRequest.getUserPrincipal

• HttpServletRequest.isUserInRole

• HttpSession.setMaxInactiveInterval

• GenericServlet.getInitParameter and getInitParameterNames

• ServletContext.getAttributeNames

• ServletContext.getContext

• ServletContext.getRealPath

• ServletContext.getResourceAsStream

• ServletRequest.getAttribute

• ServletRequest.getParameter

• RequestDispatcher.forward and include

• Request.getInputStream and getReader

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

HttpUtils.getRequestURL

public static StringBuffer getRequestURL(HttpServletRequest request);

This method reconstructs the URL used by the client to make the given request on the server. This method accounts for difference in scheme (such as http, https) and ports, but does not attempt to include query parameters.

This method returns a StringBuffer instead of a String so that the URL can be modified efficiently by the servlet.

Clarification

To determine the server name part of the requested URL, iPlanet Web Server first tries to use the "Host" header and then looks at the value of ServerName in magnus.conf. By default, the server name is the machine name, but this value is editable during iPlanet Web Server 4.1 installation. If the server name has been changed, HttpUtils.getRequestURL might not return the host name that is needed to reconstruct the request.

For example, suppose the request is http://abc/index.html. However, the server name has been changed to xyz. In this case, HttpUtils.getRequestURL might return http://xyz/index.html, which is not the original URL that was requested.

HttpServletRequest.getContextPath

public java.lang.String getContextPath(java.lang.String path)

Returns the portion of the request URI that indicates the context of the request.

Clarification

This method always returns an empty string.

HttpServletRequest.getUserPrincipal

public java.security.Principal getUserPrincipal()

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.

Clarification

For this method to work, you must set up access control in iPlanet Web Server in the usual manner.

HttpServletRequest.isUserInRole

public boolean isUserInRole(java.lang.String role)

Returns a boolean indicating whether the authenticated user is included in the specified logical "role." If the user has not been authenticated, the method returns false.

Clarification

This method maps roles to the group names in the underlying user or group database.

HttpSession.setMaxInactiveInterval

public void setMaxInactiveInterval(int interval);

Sets the amount of time that a session can be inactive before the servlet engine is allowed to expire it.

Clarification

It is not possible to set the maximum inactive interval so that the session never times out. The session always has a timeout value.

If you pass a negative or zero value, the session expires immediately.

GenericServlet.getInitParameter and getInitParameterNames

public String getInitParameter(String name);

This method returns a String containing the value of the servlet's named initialization parameter, or null if this parameter does not exist.

public Enumeration getInitParameterNames();

This method returns an enumeration of String objects containing the names of the initialization parameters for the calling servlet. If the calling servlet has no initialization parameters, getInitParameterNames returns an empty enumeration.

Clarification

For servlets running on iPlanet Web Server 4.1, the methods getInitParameter and getInitParameterNames for the class ServletConfig only work for servlets that are invoked through virtual path translations. The same restriction applies to the convenience methods of the same names in the class GenericServlet, which invoke the corresponding methods on ServletConfig.

For information about setting virtual path translations, see the section "Specifying Servlet Virtual Paths."

These methods do not work if the servlet is invoked by a client request that specifies a servlet in a registered servlet directory rather than using a virtual path translation to access the servlet.

ServletContext.getAttributeNames

public java.util.Enumeration getAttributeNames()

This method returns an enumeration containing the attribute names available within the servlet's context.

Clarification

If you are using MMapSessions, iPlanet Web Server truncates names retrieved by ServletContext.getAttributeNames to 128 characters.

ServletContext.getContext

public ServletContext getContext(String uripath);

Returns the servlet context object that contains servlets and resources for a particular URI path, or null if a context cannot be provided for the path.

Clarification

This method only works if both the following conditions are true:

• The servlet whose context is being obtained (that is, the servlet pointed to by uripath) has been configured either through the Servlets>Configure Servlet attributes property of the Server Manager interface or by editing servlets.properties.

• The servlet whose context is being obtained has been loaded.

  iPlanet Web Server 4.1 does not load a servlet specified by a URI when getContext is called from another servlet to get the context of an unloaded servlet.

ServletContext.getRealPath

public java.lang.String getRealPath(java.lang.String path)

Converts the URI path to the servlet into the real path to the servlet.

Clarification

This method does not work if the path is mapped. In this case, use ServletRequest.getRealPath instead.

ServletContext.getResourceAsStream

public java.io.InputStream getResourceAsStream(java.lang.String path)

Returns the resource located at the named path as an InputStream object.

Clarification

This method does not work if the path is mapped.

ServletRequest.getAttribute

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

Returns the value of the named attribute as an object, or returns null if no attribute of the given name exists.

Clarification

ServletRequest.getAttribute returns a CGI variable if it exists. However, the getAttributeNames method does not show these variables within its enumeration.

---

Note	The HttpServletRequest.getCgiVariable method is not supported.

---

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, the parameterEncoding property must be set to auto (the default) in the contexts.properties file. Otherwise, the values extracted by the getParameter method are zeros or are undefined. 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 same servlet or JSP generates and processes the form, 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"%>

  • 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, for example:

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

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), the method is not guaranteed to 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 4.1, 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.

Request.getInputStream and getReader

There are two ways for a servlet to read the raw data posted by a client:

• by obtaining the InputStream through the request.InputStream method, an older method.

• by obtaining a BufferedRead through the request.getReader method, a method in use since 2.0.

Clarification

A servlet hangs if it attempts to use an InputStream to read more data than is physically available. (To find how much data is available, use request.getContentLength.) However, if the servlet reads data using a BufferedReader returned from a call to getReader, the allowed content length is automatically taken into account.

You can also set the inputStreamLengthCheck parameter to true in the contexts.properties file to prevent this problem.

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 cert;    cert = req.getAttribute("javax.servlet.request.x509Certificate");    if (cert != null) {       // Get the Distinguished Name for the user       java.security.Principal userDn = cert.getSubjectDN();    } }

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