This subsection describes specifications where functionalities added in Servlet 3.0 and functionalities of Application Server are combined.

(a) Functionality for setting the Web application version

You cannot set the version to 3.0 in the Web application version setting functionality.

(b) JSP pre-compile under META-INF/resources

Although it is now possible with Servlet 3.0 specifications to include JSP files in the hierarchy of the META-INF/resources inside a JAR file, you cannot execute JSP pre-compile for Web applications that have a JSP in the META-INF/resources hierarchy. If you execute the JSP pre-compile, the JSP in the META-INF/resources hierarchy is not pre-compiled, and an error occurs on executing the request.

(c) Reloading an application that uses Servlet 3.0

Reloading of an application that uses Servlet 3.0 functionalities has the following constraints:

• If an application contains a JAR file that has static contents (also includes the JSP) in META-INF/resources, even if you update and reload the JAR file, the pre-update static contents in META-INF/resources of the JAR file can only be accessed. If you reload an application that contains a JAR file that has static contents in META-INF/resources, the KDJE39556-W message is output.
  

  Note

  With version 09-00-02 or earlier, if you reload the following applications, the operation is not guaranteed.

  • When you reload an application that contains an implementation class of the ServletContainerInitializer interface, the KDJE39557-W message is output.
  • When you reload an application that contains servlets added by the dynamic servlet definitions, filters, or listeners, the KDJE39558-W message is output.

(d) Using the run-as functionality in servlets defined by using API

You cannot use the run-as functionality in a servlet defined by using an API. Settings are ignored if you:

• use the @RunAs annotation in a servlet class.
• call the setRunAsRole method of the ServletRegistration.Dynamic interface.

(e) Monitoring the execution time of servlets or filters defined by using APIs

You cannot use the execution time monitoring functionality of the J2EE application for the servlets or filters defined by using APIs. Even if you define the method-observation-timeout tag in the cosminexus.xml file, the tag is ignored.

(f) Continuation of the HTTP session when the Web application is invoked

The operation regarding the continuation of an HTTP session when the Web application is invoked is the same as in the case of Servlet 2.5 specifications. For details, see 6.2.4(6) Continuation of the HTTP session when the Web application is invoked.

(g) Request redirecting when the cookie name of the session is changed

When the Web container is deployed in a cluster configuration, you can distribute requests by using the Redirector. The Redirector references the session ID added to each request and distributes the requests in such a way that the requests from the same Web client are redirected to the same Web container. However, if you change the session cookie name from the default name JSESSIONID to some other name, requests from the same Web client might not be redirected to the same Web container.

When you want to combine Servlet 3.0 and CDI to use them together, use a web.xml that is compatible with Servlet 3.0. A web.xml of any other version cannot be used in combination with CDI.

You cannot use the @PostConstruct or @PreDestroy annotations in filters or listeners defined with APIs. Such annotations are ignored if used.

In Servlet 3.0, default servlets (servlets provided by the container to provide static content) are included. If there is no content to be included, the system throws the FileNotFoundException exception. If the exception is not handled in the user program, the response is not committed and the status code 500 is returned.

Application Server does not support this specification. The same status code 404 as in versions prior to 08-70 is returned.

Do not use an escape sequence (\b, \t, \n, \f, \r,\" ,\',\\)for input characters in API or the properties newly added in Servlet 3.0. If you use the escape sequence, new lines might get randomly added in the log thus affecting the layout of the log.

The following points describe how the behavior of dynamic servlets differs from the Servlet 3.0 specifications when the dynamic servlets are defined and used in Application Server:

(a) Defining servlets, filters, or listeners

• When you add a filter by using both API and web.xml, and set the filter mapping method isMatchAfter defined in the API for the other filter mapping to false, the API definition is called first when a request is processed.
• When you define a listener by using both API and web.xml, the listener defined in the web.xml is read first when the application starts and the listener is generated. When you want to delete the listener, the definition in the API is read first.
• When you specify a NULL character ("") for the URL pattern and call the addMapping(String... urlPatterns) method of the javax.servlet.ServletRegistration interface, only the context name is used for accessing the servlet. If the context name is also a NULL character (""), the servlet cannot be accessed.
• Do not call the addServlet() method by specifying a servlet name already defined in web.xml or the same servlet name as that created by the servlet class with the @WebServlet annotation.
• If the setMultipartConfig() method is called and the @MultipartConfig annotation is specified for the same servlet in a user application, the value specified in the setMultipartConfig() method is used.
  Similarly, if the setServletSecurity() method is called and the @ServletSecurity annotation is also specified for the same servlet in a user application, the value specified in the setServletSecurity() method is used.
  
• You cannot acquire or set a role by using the getRunAsRole() or the setRunAsRole(String roleName) method. Furthermore, no warning or error message is output.
• If you register a servlet or a filter with an already registered name, the KDJE39552-W message is output when the application starts and the operation continues.
• If a URL pattern contains a linefeed code, the KDJE39555-W message is output when the application starts and the operation continues.

(b) Defining by using the ServletContainerInitializer interface

When you define using the ServletContainerInitializer interface in Application Server, the following points differ from the Servlet 3.0 specifications:

• You can deploy a JAR file that contains a class with the ServletContainerInitializer interface implemented in the following locations:
  
  1. The WEB-INF/lib directory in the WAR file included in the application
  2. A location other than WEB-INF/lib directory
  If you want to deploy a JAR file that contains a class with the ServletContainerInitializer interface implemented in a location other than the WEB-INF/lib directory, you must specify the absolute path of the JAR file in the following property of usrconf.properties.
  

  webserver.ServletContainerInitializer_jar.include.path

  The following example shows how to set the path:

  webserver.ServletContainerInitializer_jar.include.path=C:/Program Files/HITACHI/Cosminexus/foo/lib/bar.jar

• The search range of the @HandlesTypes annotation class is limited to the WAR file that contains the implementation class of the ServletContainerInitializer interface. Search can be executed in classes within the WEB-INF/classes directory and the JAR files present in the WEB-INF/lib directory of WAR.
• If the JAR file that contains a class with the ServletContainerInitializer interface implemented cannot be read or processed, the KDJE39548-E message is output when you attempt to start the application and the application fails to start.
• When search is performed for a class that extends or implements a class specified with the @HandlesTypes annotation, or for a class to which the annotation of the class specified with the @HandlesTypes annotation is attached, if the class fails to load, the KDJE39549-W message is output and the start processing of the application continues.
• If a JAR file that you specified in webserver.ServletContainerInitializer_jar.include.path and that contains a class with the ServletContainerInitializer interface implemented is not found, or if a JAR file or files cannot be read, the KDJE39553-W message is output when the application starts and the process continues. The KDJE39553-W message is output for each JAR file specified in Web server. ServletContainerInitializer_jar.include.path.
• If the JAR file that you specified in webserver.ServletContainerInitializer_jar.include.path and that contains a class with the ServletContainerInitializer interface implemented is not found in the class path, the KDJE39554-W message is output when the application starts and the process continues. The KDJE39554-W message is output for each JAR file that is specified in webserver.ServletContainerInitializer_jar.include.path.

Also, implementation class information of the ServletContainerInitializer interface, defined in the javax.servlet.ServletContainerInitializer file, is read as described below.

• Only the class coded in the first line is read and the classes coded from second line onwards are ignored.

If you use the file upload functionality with Application Server, the following points differ from the Servlet3.0 specifications:

• If the multipart config element is set in both web.xml and @MultipartConfig annotations, the element defined in the web.xml is given priority.
• If you execute the file upload with a request other than the one with the request type multipart/form-data, the javax.servlet.ServletException exception is thrown. The following table describes the mapping between the type of requests that execute file upload and the corresponding execution result.
  

  Table 6-14 Type of requests that execute file upload and the corresponding execution result

  Request type specified in web.xml or @MultipartConfig annotation	Execution result
  Other than mime-multipart	The javax.servlet.ServletException exception is thrown.
  mime-multipart other than multipart/form-data	The javax.servlet.ServletException exception is thrown.
  multipart/form-data	File upload is executed. No exception is thrown.

• When you define MultipartConfigElement in the program, it functions in the same way as when you define it in web.xml. However, if you specify a NULL character ("") in the location, files are stored in the work directory of the Web application.
• If the size of the uploaded file is greater than the value specified in the file-size-threshold tag in the web.xml or the fileSizeThreshold attribute of the @MultipartConfig annotation, temporary files are generated for a part of the objects included in the request. A temporary file is saved with a unique name that begins with upload and has a .tmp extension.
  Example: upload__5f8d5c62_1316c5ef08b__8000_00000012.tmp.
  Temporary files are deleted when the request is completely processed. However, if a temporary file is open, or if the J2EE server is not shut down properly, or if the system shuts down, the file might not get deleted. Delete the file manually from the path specified in the location.
  If a temporary file is generated with the same name as a file created manually by the user, the file created by the user is overwritten by the temporary file.
  
• You can use the Part objects inside a request. The Part objects are deleted once the request is completely processed. If you save the Part objects in the session for later use, the operation is not guaranteed.

This point describes the deployment of static resources and the points that differ from the Servlet 3.0 specifications when the static resources are used with Application Server.

• When a JAR file that contains static resources cannot be read or processed, the KDJE39548-E message is output when you attempt to start the application and the application fails to start.
• If a specified JAR file has an invalid format, the KDJE39550-E message is output when the application starts, and the process continues.
• If an invalid JAR file or a file that cannot be read is included in WEB-INF/lib, the KDJE39551-W message is output when the application starts, the JAR file is ignored, and the process continues.

The following points differ from the Servlet 3.0 specifications if APIs are used with Application Server.

• Among the APIs that are added in Servlet3.0, the APIs that are not listed in the following table can be used with Application Server 09-00. For details on APIs, see the Servlet3.0 specifications. If you use any of the non-supported APIs listed in the following table, Application Server throws the java.lang.UnsupportedOperationException exception.
  

  Table 6-15 Non-supported APIs (Servlet 3.0)

  No.	Package	Class	Interface/Class	Method	Functionality
  1	javax.servlet	AsyncContext	Interface	All methods	Asynchronous servlet
  2		AsyncListener	Interface	All methods	Asynchronous servlet
  3		ServletContext	Interface	getJspConfigDescriptor	JSP
  4		ServletRequest	Interface	startAsync	Asynchronous servlet
  5				isAsyncStarted	Asynchronous servlet
  6				isAsyncSupported	Asynchronous servlet
  7				getAsyncContext	Asynchronous servlet
  8				getDispatcherType	Asynchronous servlet
  9		AsyncEvent	Class	All methods	Asynchronous servlet
  10		ServletRequestWrapper	Class	startAsync	Asynchronous servlet
  11				isAsyncStarted	Asynchronous servlet
  12				isAsyncSupported	Asynchronous servlet
  13				getAsyncContext	Asynchronous servlet
  14				getDispatcherType	Asynchronous servlet
  15		Registration	Interface	setAsyncSupported	Asynchronous servlet
  16	javax.servlet.descriptor	JspConfigDescriptor	Interface	All methods	JSP
  17		JspPropertyGroupDescriptor	Interface	All methods	JSP
  18		TaglibDescriptor	Interface	All methods	JSP

• You cannot use the APIs added in Servlet 3.0 in Web applications that are compatible with Servlet 2.5. Because the program does not check if the correct APIs are being used, the operation is not guaranteed.
• You cannot use SSL in the SessionTrackingMode. You can use only COOKIE and URL with Application Server.

You can omit web.xml in Servlet 3.0 for the following applications:

• Web applications that contain static contents and JSP only (excluding listeners, servlets, and filters)
• Web applications with listeners, servlets, and filters defined with annotations

When changing the HTTP Cookie name that indicates the session ID, you cannot specify csfcfc in the Cookie name.

Also, the following are the conditions for the characters that you can use. If you violate these conditions, KDJE39559-W is output. This may also lead to incorrect operations of the session, therefore use the characters that conform to the conditions.

• Use ASCII characters, excluding the following characters.
  "#", "(", ")", "<", ">", "@", ",", ";", ":", "\", "/", """, "[", "]", "?", "=", "{", "}"
  
• You cannot use the space or control characters.
• You cannot use $ at the beginning of a character string.

You cannot use the following names for HTTP Cookies you use in a Web application. Note that the Cookie names are not case sensitive.

• An HTTP Cookie name used as the session ID of an HTTP session. The default name is JSESSIONID.
• An HTTP Cookie name that represents a global session. The default name is GSESSIONID.
• The same name as an HTTP Cookie name appended with a server ID by using the append server ID functionality of the J2EE server.
• The HTTP Cookie name csfcf used internally in the J2EE server.

If you want to omit the servlet-class element in the web.xml, you must include the subclass of javax.servlet.http.HttpServlet in which you have specified the @WebServlet annotation in the Web application, and specify the name of the servlet for which you have omitted the servlet-class element in the name attribute. If, the corresponding HttpServlet class is not available, the KDJE39339-E message is output and the servlet class fails to load.

If you want to omit the filter-class element in web.xml, you must include the implementation class of javax.servlet.Filter in which you have specified the @WebServlet annotation in the Web application, and specify the name of the filter for which you have omitted the filter-class element in the filterName attribute. If the corresponding Filter class is not available, the KDJE39340-E message is output and the application fails to start.

When you change the Path attribute of an HTTP Cookie indicating a session ID, and the HTTP Cookie name or the Path attribute indicating a session ID duplicates that of another Web application, the HTTP Cookie value indicating the session ID might be overwritten or deleted, and the HTTP session can no longer be inherited.

Note that the following are the conditions for characters that can be used in the Path attribute and Domain attribute of an HTTP Cookie indicating a session ID. If the following conditions are not satisfied, the KDJE39559-W message is output. If you use invalid characters, it might result in an abnormal behavior of the session. Therefore, use characters that satisfy the following conditions:

• For the Path attribute, you can use only ASCII characters excluding control characters and semicolons (;).
• For the Domain attribute, you can use only alphanumeric characters, hyphens (-), and periods (.).