![[Contents]](FIGURE/CONTENT.GIF)
uCosminexus Application Server, Web Container Functionality Guide
![[Glossary]](FIGURE/GLOSS.GIF)
![[Index]](FIGURE/INDEX.GIF)
![[Back]](FIGURE/FRONT.GIF)
![[Next]](FIGURE/AFTER.GIF)
This subsection describes the common precautions for implementing servlets and JSPs as the application programs running on the Application Server.
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:
Table 6-3 J2EE version to which the J2EE application conforms
| Version of J2EE specifications to which the J2EE application conforms | Servlet specifications corresponding to the Web applications | ||||
|---|---|---|---|---|---|
| 3.0 | 2.5 | 2.4 | 2.3 | 2.2 | |
| Java EE 6 | Y | Y | Y | Y | Y |
| Java EE 5 | N | Y | Y | Y | Y |
| J2EE1.4 | N | N | Y | Y | Y |
| J2EE1.3 | N | N | L | Y | Y |
| J2EE1.2 | N | N | L | L | Y |
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:
Table 6-4 Supported range of Web applications
| Version of the Web application | Servlet | JSP | Tag library#1 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 3.0 | 2.5 | 2.4 | 2.3 | 2.2 | 2.2 | 2.1 | 2.0 | 1.2 | 1.1 | 2.1 | 2.0 | 1.2 | 1.1 | |
| 3.0 | Y | Y | Y | Y | Y | N#2 | Y | Y | Y | Y | Y | Y | Y | Y |
| 2.5 | N | Y | Y | Y | Y | N | Y | Y | Y | Y | Y | Y | Y | Y |
| 2.4 | N | N | Y | Y | Y | N | N | Y | Y | Y | N | Y | Y | Y |
| 2.3 | N | N | N | Y | Y | N | N | N | Y | Y | N | N | Y | Y |
| 2.2 | N | N | N | N | Y | N | N | N | N | Y | N | N | N | Y |
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:
Table 6-5 Errors that occur if functionalities of Servlet 3.0 are used from a Web application that is compatible with Servlet 2.2, 2.3, 2.4, or 2.5 specifications
| Specifications | Functionality used | Operation in the event of an error |
|---|---|---|
| Servlet 3.0 | Invoking new API | The program does not check whether an API of the Servlet 3.0 specification is being used. To avoid any abnormal operation, do not call the API. |
| Using new annotations | For handling errors occurring due to annotations, see 12. Using Annotations in the uCosminexus Application Server Common Container Functionality Guide. | |
| JSP 2.2 | New EL API | The program does not check whether an API of EL2.2 specification is being used. To avoid any abnormal operation, do not call the API. |
For details on operations and precautions when upgrading a Web application from Servlet 2.2, Servlet 2.3, Servlet 2.4, or Servlet 2.5 specifications to Servlet 3.0 specifications, see 6.2.11 Points to remember when upgrading the version of an existing Web application to the Servlet 3.0 specifications.
Table 6-6 Errors when Servlet 2.5 functionality is used from a Web application corresponding to Servlet 2.2, 2.3, or 2.4 specifications
| Specifications | Functionality used | Error processing |
|---|---|---|
| Servlet 2.5 | Invoking new API | The check whether the API added in the Servlet 2.5 specifications is used, is not performed. The operations when the API is invoked do not function properly, so do not invoke the API. |
| Using new annotations | For the processing when an annotation is used and an error occurs, see 12. Using annotations in the uCosminexus Application Server Common Container Functionality Guide. | |
| JSP 2.1 | Attributes of the new directive#1 | KDJE39145-E message is output in the servlets log and KDJE39186-E message is output in the message log#2 and a translation error occurs. |
| TLD 2.1 | If the following TLD file exists when the Web application starts, the KDJE39293-W message is output in the message log and the processing is not performed:
If JSP compilation occurs when the application is accessed the first time, the KDJE39145-E message is output in the servlets log and the KDJE39186-E message is output in the message log#2 and a translation error occurs. |
|
| EL addition functionality |
|
For details on the operations and precautions when upgrading the Web application version from Servlet 2.2 specifications, Servlet 2.3 specifications, and Servlet 2.4 specifications to Servlet 2.5 specifications, see 6.2.12 Points to remember when upgrading the version of an existing Web application to the Servlet 2.5 specifications.
Table 6-7 Errors when using the functionality of Servlet 2.4 specifications from a Web application corresponding to Servlet 2.2 or 2.3 specifications
| Specifications | Functionality used | Error processing |
|---|---|---|
| Servlet 2.4 | Invoking new API | The check for whether the API added in the Servlet 2.4 specifications is used, is not performed. The operations when the API is invoked do not function properly, so do not invoke the API. |
| Registering new listener | The KDJE39297-W message is output in the message log when the Web application starts and the listener definition is ignored. | |
| JSP 2.0 | New directive and new standard action#1 | The KDJE39145-E message is output in the servlets log and the KDJE39186-E message is output in the message log#2, and a translation error occurs. |
| Tag files |
|
|
| TLD 2.0 | The following TLD files are checked when the Web application starts. When applicable, the KDJE39293-W message is output in the message log and the file is ignored:
|
|
| Simple Tag Handler | The KDJE39145-E message is output in the servlets log and the KDJE39186-E message is output in the message log#2, and a translation error occurs. |
For details on the operations and precautions when upgrading the Web application version from Servlet 2.2 specifications and Servlet 2.3 specifications to Servlet 2.4 specifications, see 6.2.14 Points to remember when upgrading the version of an existing Web application to the Servlet 2.4 specifications.
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 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:
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.
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.
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:
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.
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.
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 access a file, make sure you specify the absolute path. If you specify the relative path, the J2EE server tries to search the target path according to the relative path from the execution directory of the Web container server. 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.
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 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:
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.
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.
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 14. Container Extension Library in the uCosminexus Application Server Common Container Functionality Guide.
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):
Table 6-8 Preconditions for the user threads (server mode)
| Server modes | Availability | |
|---|---|---|
| J2EE server mode | 1.4 mode | Y |
| Basic mode | N | |
| Servlet engine mode | N | |
The following points describe the lifecycle when using the user threads:
In this model, the processing of the user thread is completed with the service method and the init method. The following figure shows the flow of processing in this model:
Figure 6-1 Processing when the thread operates within the scope of the service method and the init method
![[Figure]](FIGURE/ZU050100.GIF)
The user thread will be generated within the invocation scope of the service method and the init method. The service method and the init method wait for the processing of the user thread by the join method to complete, and then the methods are returned.
In this model, the user thread is generated with the service method and the init method, and then the user thread is operated in the background. The following figure shows the flow of processing in this model:
Figure 6-2 Processing when the threads operate in the background of the service method and the init method
![[Figure]](FIGURE/ZU050200.GIF)
The service method and the init method that generated the user thread will be returned without waiting for the processing to complete after the user thread is generated. However, after the application is stopped, the J2EE service cannot be used from the user thread. Therefore, no problem occurs if a user thread is stopped by a contextDestroyed method of javax.servlet.ServletContextListener or a JSP or servlet destroy method invoked by the stopping of an application.
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.
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:
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.
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:
Note the following items to the Web applications containing binary data:
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.
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:
Table 6-9 Return values of the getServerName method and getServerPort method (In Servlet 2.4 or later specifications)
| Presence of Host header | Return value of the getServerName method | Return value of the getServerPort method |
|---|---|---|
| Yes | Part before the colon (:) of the Host header | Part after the colon (:) of the Host header |
| No | Resolved server name or IP address | Port number of the server that receives the connection with the client |
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 6-9.
Table 6-10 Return values of the getServerName method and getServerPort method (In the application server)
| HTTP request | Functionality used | Return value of the getServerName method | Return value of the getServerPort method | |
|---|---|---|---|---|
| Presence of the Host header | URI type of the request line | |||
| Yes | Absolute URI | Web server integration | Host name of request line | Port number of request line |
| In-process HTTP server | Host name of request line | Port number of request line | ||
| Relative URI | Web server integration | Host name of Host header | Port number of Host header | |
| In-process HTTP server | Host name of Host header | Port number of Host header | ||
| No | Absolute URI | Web server integration | Host name of request line | Port number of request line |
| In-process HTTP server | Host name of request line | Port number of request line | ||
| Relative URI | Web server integration | Host name or IP address of the Web server#2 | Port number of the Web server | |
| In-process HTTP server | Host name or IP address of the J2EE server#1 | Port number of the in-process HTTP server | ||
The following table lists the return values of the getServerName method and the getServerPort method when you use the gateway specification functionality:
Table 6-11 Return values of the getServerName method and getServerPort method when you use the gateway specification functionality (in the Application Server)
| HTTP request | Functionality used | Return value of the getServerName method | Return value of the getServerPort method | |
|---|---|---|---|---|
| Presence of the Host header | URI type of the request line | |||
| Yes | Absolute URI | Web server integration | Host name of request line | Port number of request line |
| In-process HTTP server | Host name of request line | Port number of request line | ||
| Relative URI | Web server integration | Host name of Host header | Port number of Host header | |
| In-process HTTP server | Host name of Host header | Port number of Host header | ||
| No | Absolute URI | Web server integration | Host name specified in the gateway specification functionality | Port number specified in the gateway specification functionality |
| In-process HTTP server | Host name of request line | Port number of request line | ||
| Relative URI | Web server integration | Host name specified in the gateway specification functionality | Port number specified in the gateway specification functionality | |
| In-process HTTP server | Host name specified in the gateway specification functionality | Port number specified in the gateway specification functionality | ||
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.
Table 6-12 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 |
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.
With Application Server, the character strings included in request URIs are used in the following matching processes after normalizing the request URIs:
The normalized URL is considered as a return value in the getRequestURI and getRequestURL methods of the javax.servlet.http.HttpServletRequest interface.
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:
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 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.
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.
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 (/).
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: 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:
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.
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.
When only the part after equal (=) sign is specified in the query character string of a request (for example, in the case of ), 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:
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.
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.
All Rights Reserved. Copyright (C) 2013, Hitachi, Ltd.