10.4.1 Common precautions for implementing servlets and JSPs

(1) J2EE application version requirements for Web application operations

For each Web application version, the following table lists the J2EE version to which the J2EE application conforms and that forms the prerequisite for Web application operations:

To Page Top

(2) Supported range of Web applications

The Web application version is identified by the version information of the Servlet specifications described in web.xml. A Web application of a higher version can use the functionality of a lower version. A Web application of a lower version cannot use the functionality of a higher version.

The following table describes the range of functionality available for each Web application version:

Note that if the functionality of a later version is used from a Web application of an earlier version, an error might occur. The following table describes the errors in each version:

For details on operation and precautions when upgrading the Web application version from the Servlet 2.2 specifications, Servlet 2.3 specifications, Servlet 2.4 specifications, or Servlet 2.5 specifications to the Servlet 3.0 specifications, see the manual uCosminexus Application Server Web Container Functionality Guide.

For details on operation and precautions when upgrading the Web application version from the Servlet 2.2 specifications, Servlet 2.3 specifications, or Servlet 2.4 specifications to the Servlet 2.5 specifications, see the manual uCosminexus Application Server Web Container Functionality Guide.

For details on operation and precautions when upgrading the Web application version from the Servlet 2.2 specifications or Servlet 2.3 specifications to the Servlet 2.4 specifications, see the manual uCosminexus Application Server Web Container Functionality Guide.

Note that even if you use the Servlet 2.3 functionality from the Web applications corresponding to the Servlet 2.2 specifications, when imported, the application is rewritten by the Web application conforming to the Servlet 2.3 specifications, and therefore, the application is processed normally and error is not reported.

To Page Top

(3) Notes on using the transaction and JDBC connection

To use a transaction in the servlets and JSPs, acquire the JDBC connection with the applicable service method and release the connection before the applicable service method ends. In the servlets and JSPs where the transaction is running, the use of the following JDBC connections is not supported:

• Use of the JDBC connection on the thread generated by the service methods of the servlets and JSPs.

• Use of the JDBC connection in the service methods of the other servlets and JSPs invoked from the service methods of the servlets and JSPs.

• Use of the JDBC connection acquired with the init method of the service methods of the servlets and JSPs.

• Use of the JDBC connection stored in the instance variable.^#

  #

  When the servlets and JSPs of SingleThreadModel are used, the JDBC connection can be stored in the instance variable.

To Page Top

(4) Notes related to package name specification

If a class with an invalid package name is used in the servlets and JSPs, an error with status code 500 occurs when the class is accessed from the browser. For example, even if a created class file is deployed correctly and accessed from the browser, if the package name declaration is invalid, the applicable class is not found. In this case, an error with status code 500 is returned.

To Page Top

(5) Notes for using cookies

• Do not use cookies containing double-byte codes such as Japanese characters. If such cookies are used, the HTTP session used in the servlets and JSPs might be lost.

• When managing a session with a cookie, the session generated using the servlets or JSPs accessed in the URL by the host name is not inherited in the servlets or JSPs accessed in the URL with the IP address specified instead of the host name (and vice versa).

To Page Top

(6) Notes related to display of input values with special meanings

When the input values of characters with special meanings such as "<" and ">" in forms are displayed as it is, malicious users might use the tags such as <SCRIPT>, <OBJECT>, <APPLET>, <EMBED> that can execute scripts and cause important security-related problems. A processing must be added for the application developer to inspect the data entered by a user and the characters with special meanings must be excluded.

To Page Top

(7) Notes related to error page display after response commit

After the response is committed in the servlets or JSPs, even if an error such as an exception occurs, the following error pages are not displayed in the browser:

• Error pages specified in web.xml

• Error pages specified in the errorPage attribute of the JSP page directive

The Web container commits the response automatically when the response buffer becomes full apart from the case in which the user commits the response by invoking the flushBuffer method of the ServletResponse class explicitly.

To check whether the response is committed in the servlets or JSPs, use the isCommitted method of the ServletResponse class. Also, you can change the buffer size using the setBufferSize method of the ServletResponse class in the case of servlets and by specifying the buffer attribute of the page directive for JSPs.

To Page Top

(8) Improving the performance when using the PrintWriter and JSPWriter class

By reducing the frequency of invoking the print method and the println method of the PrintWriter class and the JSPWriter class, you can reduce the access frequency and improve the performance. For example, use the StringBuffer class and invoke the println method finally to reduce the frequency of invoking the print and println methods.

To Page Top

(9) Notes on referencing the error information by javax.servlet.error.XXXXX

The javax.servlet.error.XXXXX attributes defined in the Servlet 2.3 specifications are used for referencing the error information that causes the execution of the error page in the servlets or JSPs specified in the <error-page> tag of web.xml. Do not reference these attributes from servlets or JSPs other than those specified in the <error-page> tag of web.xml.

To Page Top

(10) Notes on accessing files

To access a file, make sure you specify the absolute path. If you specify a relative path, the J2EE server tries to use the relative path to find the target path from the execution directory. If you specify the relative path in the getRealPath method of the ServletContext class, the relative path in the directory that deploys the WAR file is acquired.

Furthermore, when you access a file, make sure that you close the file. If you access a file in the WAR file deployment directory and do not close the file, you cannot perform the normal un-deployment on the J2EE server. If the file not closed even when the path under the WAR file deployment directory is not specified, events such as the files cannot be deleted when the J2EE server is running occur.

To Page Top

(11) Error page settings when an exception occurs

If an exception occurs while accessing the JSPs and servlets, the exception status code is returned to the browser by the default processing in the Web Container. To change this default processing, specify the JSP errorPage or set the error page in web.xml.

To Page Top

(12) Notes related to acquisition of the class loader

To use the following methods by acquiring the class loader of the Cosminexus Component Container from the code in the J2EE application, use the java.net.JarURLConnection class:

• getResource(String).openConnection().getInputStream()

• getResource(String).openStream()

In the process in which these methods are invoked, the openConnection method of the java.net.JarURLConnection class is invoked and the JAR file specified in the applicable URL is opened. This JAR file remains open unless the close method is explicitly invoked and cannot be deleted. Do not use these methods in the J2EE application. Also, when the operations for the JAR file are required and when using the openConnection method of the java.net.JarURLConnection class, make sure that you invoke the close method of the JarFile instance that the getJarFile method of the java.net.JarURLConnection returns.

To Page Top

(13) Notes on using the URLConnection class

When the java.net.URLConnection class uses the setUseCaches(boolean) method to acquire the connection for the specified URL, you can specify whether or not to use the cache information. When the setUseCaches(false) method is specified for the URLConnection class, the target object is generated for each connection. When the URLConnection class is used from the code in the J2EE application, memory might be insufficient for the J2EE server JavaVM.

To Page Top

(14) Notes related to the loading of the native library

Do not use the System.loadLibrary method to load the native library from the servlets and JSPs. If the native library is loaded with the servlets and JSPs, the error java.lang.UnsatisfiedLinkError might occur depending on the constraints of the JNI specifications. If you must load the native library, create the container extension library that invokes the System.loadLibrary method and implement settings so that the container extension library is referenced from the servlets and JSPs. For creating the container extension library, see 16. Container Extension Library in the uCosminexus Application Server Common Container Functionality Guide.

To Page Top

(15) Using user thread

You can generate and use threads from the servlets and JSPs that form the application. The thread that a user explicitly generates in a program is called a user thread.

The user threads are classified as follows depending on the operation method after generating the threads (lifecycle):

• Threads operating within the scope of the service method and the init method.

• Threads operating in the background of the service method and the init method.

Usage conditions of the user thread

• The user thread cannot be used in the Enterprise Bean (since the generation of threads from the Enterprise Bean is prohibited in the EJB specifications).

The following points describe the lifecycle when using the user threads:

To Page Top

(16) Persistence of session information

The Web container does not support the persistence of the session information. Irrespective of whether the session information in the Web container is normal or abnormal, the information is lost once the Web container exits. If you want to maintain the session information, use the session failover functionality.

Furthermore, when the <distributable> tag is specified in web.xml or when the not Serializable object is registered as the session information, IllegalArgumentException does not occur.

To Page Top

(17) Messages output when the init method and destroy method are not overridden

If you initialize or terminate the servlets that do not override the init method and the destroy method, the log of the following format is output in the servlets log:

• Message ID: KDJE39037-I

• Message text: path="aa....aa" :bb....bb: init^#

  aa....aa

  Indicates the context path starting with a forward slash (/).

  bb....bb

  Indicates the servlets name specified in the <servlet-name> tag of web.xml. In the case of servlets with default mapping, the name is org.apache.catalina.INVOKER.class-name.

  #

  In the case of the init method, the name is init and in the case of destroy method, the name is destroy. The output messages are the log output in the init method and destroy method of the javax.servlet.GenericServlet class respectively. Therefore, these messages are not output in the servlets that override the init method or the destroy method.

Also, in the case of JSP, if the init method and the destroy method are not overridden in the base class of JSP specified in the extends attribute of the page directive, a similar message is output. In this case, servlets name is com.hitachi.software.web.servlet-name.jsp. If the extends attribute of the page directive is not specified in JSP, only the init method log is output and the destroy method log is not output.

However, for both servlet and JSP, when the init method and the destroy method of the superclass are invoked by overriding the init method and the destroy method, this message is output.

To Page Top

(18) javax.servlet.error.exception attribute of the javax.servlet.ServletRequest object

The javax.servlet.error.exception attribute of the javax.servlet.ServletRequest object is separately described as follows for the case in which exception is thrown in the Servlet and when exception is thrown in the JSP file:

To Page Top

(19) Operating Web applications containing binary data

Note the following items to the Web applications containing binary data:

• When executing the requests to the binary data sent from the client

  Do not acquire PrintWriter from the response object in the filter applied in the request to the binary data.

• When the servlets or JSPs that process the requests sent from the client are to be dispatched

  Do not acquire PrintWriter from the response object in the following locations:

  • In the filter applied in the request to the binary data

  • In the servlets or JSPs to be dispatched to the binary data

    Reference note

    Binary data means static contents in which the MIME type mapped to the extension does not begin with "text/" or static contents for which mapping does not exist.

To Page Top

(20) Notes related to response character encoding

If the character encoding of the response body in the JSPs or servlets is UTF-16 (16 bit UCS conversion format), the character encoding might not be displayed correctly by the browser. In this case, use UTF-16BE (big-endian byte order of the 16 bit UCS conversion format) or UTF-16LE (little-endian byte order of the 16 bit UCS conversion format) for the character encoding of the JSPs or servlets.

To Page Top

(21) Return values of the getServerName method and getServerPort method of the javax.servlet.ServletRequest interface

This point describes the return values of the getServerName method and the getServerPort method.

In Servlet 2.4 and later specifications, the return values of the getServerName method and the getServerPort method differ depending on the availability of the Host header. The following table lists the return values of the getServerName method and the getServerPort method in the Servlet 2.4 and later specifications:

In Application Server, the return values of the getServerName method and the getServerPort method are acquired depending on the combination of the HTTP requests and the functionality used. Note that when the Host header is not included in the HTTP 1.1 request, 400 error occurs according to the HTTP 1.1 specifications. Furthermore, the HTTP 1.1 specifications define that if the request URI of the request line is an absolute URI, use the host of the request URI for the host and ignore the contents of the Host header. Though not explicitly mentioned in the Servlet specifications, the host name included in the request line URI is given priority based on the HTTP specifications.

The following table lists the return values of the getServerName method and the getServerPort method obtained depending on the combination of the HTTP requests and the functionality used. For details on the return values of the getServerName method and getServerPort method when the gateway specification functionality is used, see Table 10-13.

The following table lists the return values of the getServerName method and the getServerPort method when you use the gateway specification functionality:

To Page Top

(22) Acquiring the root cause exception specified in the constructor of the javax.servlet.ServletException class

With the Application Server, you can acquire the root cause exception specified in the constructor ServletException(String, Throwable) or ServletException(Throwable) using the getCause method. Note that you can also acquire the exception using the getRootCause method. However, with versions prior to 07-60 version, the getCause method returns null.

This point describes the compatibility parameters and notes related to the acquisition of the root cause exception specified in the constructor of the javax.servlet.ServletException class.

• Compatibility parameters

  To perform the same operations as are operated with the versions prior to 07-60 version, specify true in the compatibility parameter webserver.servlet_api.exception.getCause.backcompat in the <configuration> tag of the logical J2EE server (j2ee-server) in the Easy Setup definition file. For details on the parameters, see the uCosminexus Application Server Definition Reference Guide.

  The following table lists the differences in the return values of the getCause method and the getRootCause method depending on the value specified in the compatibility parameter webserver.servlet_api.exception.getCause.backcompat.

  Table 10‒16: Differences in the return values of the getCause method and getRootCause method depending on the value specified in webserver.servlet_api.exception.getCause.backcompat

  Method	Value specified in webserver.servlet_api.exception.getCause.backcompat
  	true	false
  getCause()	N	Y
  GetRemoteUser()	Y	Y

  Legend:

  Y: Returns the root cause exception

  N: Returns null

  Note that the contents specified in the compatibility parameter are also applied to the operations of the getCause method and the getRootCause method of the javax.servlet.jsp.JspException class.

• Notes

  When the root cause exception can be acquired by implementing the getCause method, you cannot invoke initCause(Throwable) for the ServletException object generated by the constructor ServletException(String, Throwable) or ServletException(Throwable). If initCause(Throwable) is invoked, the java.lang.IllegalStateException exception is thrown.

To Page Top

(23) Notes related to the execution of the flush method for the javax.servlet.ServletOutputStream object

With the Application Server, even if the flush method is executed after executing the close method for the javax.servlet.ServletOutputStream object obtained from the javax.servlet.ServletResponse object, the java.io.IOException exception is not thrown.

To Page Top

(24) Normalizing request URIs

With Application Server, the character strings included in request URIs are used in the following matching processes after normalizing the request URIs:

• Matching context path and context root

• Matching URL pattern of servlets and JSPs

• Matching default mapping

• Matching static contents

• Matching URL pattern of filter

• Matching with the <error-page> tag of web.xml or with the errPage attribute of the page directive of JSPs

• Matching URL pattern for restricting access

• Determining URL for login authentication

• Forwarding and including requests

• Matching URL pattern for HTTP response compression filter

• Matching URL pattern to control the number of concurrently executing threads in the URL group

• Error page customization of the in-process HTTP server

• Request distribution by redirecting the in-process HTTP server

To Page Top

(25) Return value of the getRequestURI and getRequestURL methods of the javax.servlet.http.HttpServletRequest interface

The normalized URL is considered as a return value in the getRequestURI and getRequestURL methods of the javax.servlet.http.HttpServletRequest interface.

To Page Top

(26) Specifying a Servlet or JSP mapped to a URL in the welcome file

When a request URL must be forwarded to the welcome file without matching it with a Servlet or JSP mapped to the URL, the forwarding-destination welcome file is selected as follows in the Web container:

First of all, from the specified welcome file name, the static contents and JSP file candidate are selected on priority. If no corresponding item exists, the candidate of the Servlet or JSP for which URL mapping is performed is selected.

The notes on the welcome file are as follows:

• Limitations based on the welcome file forwarding method

  The welcome file is forwarded based on HTTP redirect (the browser redirects to HTTP status code 302). This forwarding method has some limitations that must be noted when designing the URL.

  • When a POST request is received, the information of the request body sent from the browser cannot be inherited in the welcome file at the forwarding destination. Only when the posted information is in the form input format (Content-Type is application/x-www-form-urlencoded), the information can be inherited by assigning to the query string of the forwarding-destination URL of the welcome file created by the Web container. However, even in this case, consideration must be given to the fact that when the information of the request body is large in size, the forwarding-destination URL becomes too long, and the information is visible as is in the address bar of the browser in the form of the query string.

  • When the doGet method is not implemented in the Servlet of the forwarding-destination welcome file, 400 Bad Request (for other than HTTP/1.1) or 405 Method Not Allowed (for HTTP/1.1) is displayed on the browser.

  • When you invoke the include method of the javax.servlet.RequestDispatcher interface from the Web application, then in spite of specifying the directory in which the welcome file exists as the URL to be included, the contents of the welcome file of the forwarding destination are not inserted.

• Adding the welcome file in an environment for which JSP pre-compilation is complete

  When adding the JSP file specified in the welcome file to a Web application for which JSP pre-compilation is complete, you must again perform JSP pre-compilation after adding the JSP file. When you do not perform JSP pre-compilation again, the welcome file is not forwarded properly.

• Specifying a servlet whose servlet class cannot be referenced in the welcome file

  Do not specify a servlet whose servlet class cannot be referenced in the welcome file. When you specify a servlet whose servlet class cannot be referenced, the welcome file is not forwarded properly.

• Requesting the welcome file to a path in which no directory exists

  When a request is sent to the path of a directory that does not exist as a resource within the Web application, the welcome file is not forwarded even when the request URL ends with a forward slash (/).

To Page Top

(27) Starting and stopping order of the servlet, filter and listener

If you start a Web application, perform the initialization process in the order below before starting the receipt of requests, according to the Servlet 2.4 specifications. In Cosminexus Application Server, the initialization process is performed in the same order even in Web applications of Servlet2.3 or earlier versions. The order of starting the servlets, filters, and listeners at the time of starting the Web application is as follows:

1. Starting the listener (generating an instance^#1, invoking methods of the @PostConstruct annotation and the contextInitialized method of ServletContextListener^#2)

2. Starting the filter (generating an instance^#1, invoking the methods of @PostConstruct annotation and the init method)

3. Starting Servlet/JSP specified in the load-on-startup tag (generating an instance^#1, invoking method of the @PostConstruct annotation and the init method)

#1: In Servlet 3.0 or later, you can dynamically add the servlets, filters, and listeners by API calling. However, for the servlets, filters, and listeners for which the definition is added by the API calling that specifies the instances, the instance has already been generated and hence the Web container does not generate an instance.

#2: Even if an exception occurs while invoking the contextInitialized() method of the listener, the system outputs the message of KDJE39103-E and continues the process of starting the Web application.

Note that for servlets for which the execution of the initialization process at the time of Web application startup is not specified with the load-on-startup element in web.xml, the system generates the instances of the servlet and invokes the init() method at the time of the initial request execution.

At this time, the instance generation and the init() method invocation of the servlet is performed before the filter.

The order of stopping the servlets, filters, and listeners at the time of stopping the Web application is as follows:

1. Stopping the already started Servlet/JSP (invoking the destroy method or the methods of the @PreDestroy annotation)

2. Stopping the filter (invoking the destroy method or the methods of the @PreDestroy annotation)

3. Stopping the listener (invoking the methods of the @PreDestroy annotation)

To Page Top

(28) Accessing the static contents within a Web application

You can use any one of the methods such as GET, HEAD, POST, TRACE, and OPTIONS, to access the static contents within a Web application.

When you use the POST method, same details of the static contents are sent as a response, as when you use the GET method.

To Page Top

(29) Precautions related to character encoding

In the same Web application, use the same character encoding in the error page specified in web.xml as the character encoding used for the servlets and JSPs that use character encoding in the HTTP response.

To Page Top

(30) Return value when only the part after equal (=) sign is used in the query character string

When only the part after equal sign ("=") is specified in the query character string of a request (for example, in the case of http://localhost/application/getparam.jsp?=param), the return value of the Servlet API that obtains the request parameter of javax.servlet.ServletRequest differs depending on the type of Web server in use.

The following are the respective return values of Servlet APIs for each type of the Web server:

• When using the Web server integration functionality of a simple Web server

  • getParameter method

    When you specify a blank character (""), the parameter specified after the equal sign ("=") is returned.

  • getParameterMap method

    The java.util.Map object that includes the parameter for which a blank character ("") acts as a key, is returned.

  • getParameterNames method

    The java.util.Enumeration object that includes a blank character (""), is returned.

  • getParameterValues method

    When you specify a blank character (""), the parameter specified after the equal sign ("=") is returned.

• When using the in-process HTTP server

  • getParameter method

    Even if you specify a blank character (""), null is returned.

  • getParameterMap method

    A blank java.util.Map object is returned.

  • getParameterNames method

    A blank java.util.Enumeration object is returned.

  • getParameterValues method

    Even if you specify a blank character (""), null is returned.

To Page Top

(31) containsHeader method of javax.servlet.http.HttpServletResponse instance

The following response headers are sometimes automatically set to responses, by the Web container. You cannot use the containsHeader method of the javax.servlet.http.HttpServletResponse interface to check whether such response headers are set for responses.

• For Web server integration

  • Content-Length

  • Content-Type

  • Set-Cookie

• For the in-process HTTP server

  • Connection

  • Content-Language

  • Content-Length

  • Content-Type

  • Date

  • Server

  • Set-Cookie

  • Transfer-Encoding

To Page Top

(32) Precautions related to the libraries of Application Server

If you include the libraries of Application Server in J2EE applications, it may lead to incorrect operations during the start and execution of the application import, due to reasons like a conflict in the library version. Therefore, do not include the libraries of Application Server in a J2EE application, except for cases where inclusion of the libraries is specified as a method of using the product.

To Page Top