https://github.com/javahongxi
This article is reproduced from kaitao.toutiao.im
web application
A Web application is a collection of many servlets, HTML pages, classes, and other resources that make up a complete application running on a Web server. Web applications can be bundled and run on different containers from different providers.
10.1 Web Applications in a Web Server
The root directory of a web application in a web server is a specific path. For example, a catalog application can be located at http://www.mycorp.com/catalog. All requests starting with this prefix will be routed to the ServletContext representing the catalog application.
The servlet container can make rules that are automatically generated by the web application. For example, a ~user/ mapping can be used to map to a web application based on /home/user/public_html/.
By default, an instance of a web application must be running in a virtual machine (VM) at all times. This behavior can be overridden if the application is marked as "distributed" through its deployment descriptor. Applications marked as distributed must obey stricter rules than normal web applications. These rules are stated in this specification.
10.2 Relationship with ServletContext
The servlet container must enforce one-to-one communication between the web application and the ServletContext. The ServletContext object provides a servlet and its application view.
10.3 Elements of a Web Application
A web application may include the following items:
■ Servlets
■ JSP™ pages
■ Utility classes
■ Static files (HTML, images, sounds, etc.)
■ Client-side Java applets, beans, and classes
■ Descriptive meta-information combining all of the above
10.4 Deployment Hierarchy
This specification defines a hierarchy that can exist in an open file system, archive, or some other form for deployment and packaging purposes. It is recommended, but not required, that the servlet container support this construct as a runtime representation.
10.5 Directory Structure
A web application exists in a structured directory hierarchy. The root of the hierarchy serves as the archive directory for files that are part of the application. For example, for the context path /catalog of a web application in a web container, in the index.html file in the web application hierarchy, or in the META-INF/resources directory in a JAR file in the WEB-INF/lib directory The included index.html file can satisfy requests served from /catalog/index.html. If an index.html file exists both in the root context and in the META-INF/resources directory of the JAR file in the application's WEB-INF/lib directory, then the index.html in the root context must be used. The rules for matching URLs to context paths are arranged in Chapter 12: "Request Mapping to servlets". Since the application's context path determines the URL namespace of the web application's content, the web container MUST reject the web application-defined context path because of potential conflicts in this URL namespace. This can happen, for example, when trying to deploy two web applications with the same context path. Since matching requests to resources is case-sensitive, it must also be case-sensitive when determining potential conflicts.
A special directory called "WEB-INF" exists in the application hierarchy. This directory contains everything related to the application that is not in the application's archive directory. Most WEB-INF nodes are not part of the application's common document tree. Except for static resources and JSP files packaged in the META-INF/resources directory in the JAR file in the WEB-INF/lib directory, any other files contained in the WEB-INF directory cannot be directly provided by the container to the client for access. However, the content in the WEB-INF directory can be accessed by servlet code calling the ServletContext's getResource and getResourceAsStream methods, and can be exposed using RequestDispatcher calls. Therefore, if the application developer wants to access this content through servlet code without exposing the application-specific configuration information directly to the client, it can be placed in this directory. Since the mapping of matching requests to resources is case-sensitive, for example, a client requesting '/WEB-INF/foo', '/WEb-iNf/foo' should not return the content of a web application located under /WEB-INF , nor should it return a directory listing of any kind.
The contents of the WEB-INF directory are:
■ /WEB-INF/web.xml deployment description file.
■ servlet and utility classes directory /WEB-INF/classes/. The classes in this directory must be visible to the application class loader.
■ The java archive area /WEB-INF/lib/*.jar. These files include servlets, beans, static resources, and JSP files packaged in JAR files, as well as other useful utility classes for Web applications. The web application's class loader must be able to load classes from these archives.
Web application class loaders must first load classes from the WEB-INF/classes directory, and then load from the JAR library in the WEB-INF/lib directory. In addition, except in the case of static resources packaged in JAR files, any request from a client to access resources in the WEB-INF/ directory must return a SC_NOT_FOUND (404) response.
10.5.1 Example application directory structure
Here is the file listing for a sample web application:
/index.html
/howto.jsp
/feedback.jsp
/images/banner.gif
/images/jumping.gif
/WEB-INF/web.xml
/WEB-INF/lib/ jspbean.jar
/WEB-INF/lib/catalog.jar!/META-INF/resources/catalog/moreOffers/books.html
/WEB-INF/classes/com/mycorp/servlets/MyServlet.class
/WEB-INF/classes /com/mycorp/util/MyUtils.class
10.6 Web Application Archives
Web applications can be packaged and signed into a Web Archive Format (WAR) file using standard Java archive tools. For example, an application about "issue tracking" could be distributed in an archive called issuetrack.war.
When packaged in this form, a META-INF directory is generated that contains information useful to the java archiver. Although the contents of this directory can be accessed by servlet code calling the ServletContext's getResource and getResourceAsStream methods, the container cannot use this directory as content to respond to client requests. Additionally, any request to access resources in the META-INF directory must return a SC_NOT_FOUND (404) response.
10.7 Web Application Deployment Descriptors
Configuration and deployment information for Web application deployment descriptors (see Chapter 14, "Deployment descriptors") includes the following types:
■ ServletContext initialization parameters
■ Session configuration
■ Servlet/JSP definitions
■ Servlet JSP mappings
■ MIME Typemaps
■ Welcome File List
■ Error Pages
■ Security
10.7.1 Extended dependencies
When many applications use the same code or resources, they are usually installed in the container's library file. These files tend to be generic or standard APIs that can be used without sacrificing portability. Files that are only used by one or a few applications will be accessed as part of a web application. The container must provide a directory for these libraries. Files placed in this directory must be visible to all web applications. The location of this directory is specified by the container. The class loader used by the servlet container to load these library files must be the same as the class loader for all web applications in the same JVM. An instance of this classloader must be in the parent classloader chain of the web application classloader.
To maintain portability, the application developer needs to know which extensions are installed in the web container, and the container needs to know which libraries the servlets in the WAR depend on.
Application developers relying on such extensions must provide a META-INF/MANIFEST.MF file in the WAR file that lists all required extensions for the WAR file. The format of the manifest file should follow the standard JAR manifest format. When deploying a web application, the web container must make the correct extension version pair follow the Optional Package Versioning mechanism (http://java.sun.com/j2se/1.4/docs/guide/extensions/ ) is visible to the application of the rules defined.
The web container must also be able to recognize the dependencies declared in the manifest file in any JAR package in the WEB-INF/lib directory of the WAR file.
If the web container cannot satisfy dependencies declared in this way, it should reject the application with a meaningful error message.
10.7.2 Web Application Class Loaders
The class loader that the container uses to load servlets in the WAR file must allow developers to use getResource to load any resource contained in the JAR package of the WAR file that follows normal JavaSE semantics. As described in the Java EE License Agreement, servlet containers that are not part of a Java EE product should not allow applications to override classes in the Java SE platform, such as classes in the java.* and javax.* namespaces, which Java SE does not allow to modify. The container should not allow applications to override or access the container's implementation class. It is also recommended that the application class loader be implemented so that classes and resources in the WAR file take precedence over classes and resources in the container-scoped JAR package. A classloader implementation must ensure that for each web application deployed to a container, calling Thread.currentThread.getContextClassLoader() returns a ClassLoader instance that implements the conventions specified in this section. Additionally, the ClassLoader instance must be a separate instance for each web application deployed. The container must set the thread context ClassLoader described above before any callbacks (including listener callbacks) to the web application, and once the callback returns, it needs to be set to the original ClassLoader.
10.8 Updating the Web Application
The server should be able to update a new version of the application without restarting the container. When an application is updated, the container should provide a reliable way to save the application's session data.
10.9 Error Handling
10.9.1 Request attributes
When an error occurs, the web application must be able to specify that other resources in the application are used to provide the content body of the error response. Provisions for these resources are configured in deployment descriptors.
If the error handling is in a servlet or JSP page:
■ Originally opened request and response objects created by the container are passed to the servlet or JSP page. .
■ The request path and properties are set as if RequestDispatcher.forward jumps to a completed error resource.
■ The request attributes in Table 10-1 must be set.
Table 10-1 Request attributes and their types
| request attribute |
Types of |
| javax.servlet.error.status_code |
java.lang.Integer |
| javax.servlet.error.exception_type |
java.lang.Class |
| javax.servlet.error.message |
java.lang.Class |
| javax.servlet.error.exception |
java.lang.Throwable |
| javax.servlet.error.request_uri |
java.lang.String |
| javax.servlet.error.servlet_name |
java.lang.String |
These attributes allow the servlet to generate a special-purpose servlet based on the status code, exception type, error message, the exception object being propagated, the request URI handled by the servlet when the error occurred (as determined by calling the getRequestURI method), and the logical name of the servlet in which the error occurred. Content.
Since version 2.3 of this specification introduced the exception object property list, the exception type and error message properties are redundant. They retain backward compatibility with earlier API versions.
10.9.2 Error pages
To enable developers to customize the appearance of content returned to the Web client when the servlet generates an error, a set of error page descriptions are defined in the deployment descriptor. This syntax allows the resource configuration to be returned by the container when the servlet or filter calls the response's sendError method to specify a status code, or if the servlet generates an exception or an error propagates to the container.
If the response's sendError method is called, the container consults the list of error pages declared for the web application, uses the status code syntax and attempts to match an error page. If a matching error page is found, the container returns the resource indicated by this location entry.
The following exceptions may be thrown by a servlet or filter while processing a request:
■ Runtime exceptions or errors
■ ServletException or its subclasses
■ IOException or its subclasses
Web applications can declare error pages using the exception-type element . In this case, the container matches the exception type by comparing the thrown exception to the list of error-pages defined using the exception-type element. A match in the container returns the resource indicated by this location entry. The closest match in the class hierarchy will be returned.
If the declared error-page does not contain a match for the class hierarchy for which the exception-type is appropriate, then a ServletException or its subclasses is thrown, and the container retrieves the wrapped exception via the ServletException.getRootCause method. The second pass attempts to match the declared error page again with the wrapped exception by modifying the error page declaration.
The error-page declared with the exception-type element must be unique in the deployment description file, and its uniqueness is determined by the class name of the exception-type. Likewise, the error-page declared with the status-code element must be unique within the deployment descriptor, and its uniqueness is determined by the status code.
When an error occurs, the error page mechanism does not interfere with calling the RequestDispatcher or filter.doFilter methods. In this way, the filter or servlet has the opportunity to use the RequestDispatcher to handle the resulting error.
If the error page mechanism described above does not handle errors generated by the servlet, the container MUST ensure that a status 500 response is sent.
The default servlet and container will use the sendError method to send responses with 4xx and 5xx status so that the error mechanism may be invoked. The default servlet and container will use the setStatus method, setting 2xx and 3xx responses, and will not invoke the error page mechanism.
If an application uses asynchronous operations as described in Section 2.3.3.3, “Asynchronous Processing” on page 2-10, it is the application's responsibility to handle all errors for threads created by the application. The container should be aware of errors issued by threads via the AsyncContext.start method. For errors in handling AsyncContext.dispatch, see the sections on page 2-16, "Errors or exceptions that may occur while executing the dispatch method must be caught and handled by the container as follows".
10.9.3 Error filter
The error page mechanism operates on the original unwrapped or unfiltered request or response object created by the container. The mechanism described in Section 6.2.5, “Filters and Request Forwarding” can be used to specify filters to apply before generating an error response.
10.10 Welcome Document
Web application developers can define an ordered list of partial URIs called welcome files in the Web application deployment description file. The syntax of the welcome file list in a deployment descriptor is described in Web Application Deployment Descriptor Schema.
The purpose of this mechanism is to allow the deployer to specify an ordered list of partial URIs for the container to use for adding URIs when a request URI corresponding to a directory entry in a WAR file does not map to a web component. Such requests are considered valid partial requests.
The convenience of this usage is made clear by the following common example: the 'index.html' welcome file can be defined so that a request URL like host:port/webapp/directory/ where 'directory' is one in the WAR file cannot be mapped to a servlet Or an entry for a JSP page, returned to the client in the form: 'host:port/webapp/directory/index.html'.
If the web container receives a valid partial request, the web container MUST check the list of welcome files defined in the deployment descriptor. The welcome file list is an ordered list of partial URLs with no trailing or leading /. The web server must add each welcome file in the deployment descriptor in the specified order to the partial request and check that the static resources in the WAR file map to the request URI. The web server must then add each welcome file in the deployment descriptor in the specified order to the partial request and check that the servlet maps to the request URI. The web container must send the request to the first matching resource in the WAR file. Containers can use forwarding, redirection, or container-specified mechanisms to send requests to welcome resources, no different from direct requests.
If no matching welcome file is found as described above, the container may process the request as it sees fit. For some configurations this might mean returning a directory listing, for others it might return a 404 response.
Consider a web application:
■ The deployment descriptor lists the following welcome files.
index.htmldefault.jsp
■ The static content in the WAR file is as follows
/foo/index.html
/foo/default.jsp
/foo/orderform.html
/foo/home.gif
/catalog/default.jsp
/catalog/products/shop.jsp
/catalog/products /register.jsp
■ Requests for URI /foo will be redirected to URI /foo/.
■ Requesting the URI /foo/ will return /foo/index.html.
■ The request URI /catalog will be redirected to the URI /catalog/.
■ Requesting the URI /catalog/ will return /catalog/default.jsp.
■ Requesting the URI /catalog/index.html will result in a 404 Not Found error.
■ The request URI /catalog/products will be redirected to the URI /catalog/products/.
■ The request URI /catalog/products/ will be passed to the "default" servlet (if there is one). If not mapped to the "default" servlet, the request may result in a 404 Not Found error, may result in a directory listing including shop.jsp and register.jsp, or may result in other container-defined behavior. See Section 12.2, The "default" servlet defined by the "Mapping Specification".
■ All of the above static content can be packaged into the META-INF/resources directory of the JAR file. This JAR file can be placed in the WEB-INF/lib directory of the web application.
10.11 Web Application Environment
The servlet container does not belong to the implementation of the JavaEE technical standard. The implementation of this container is encouraged but not required. Please refer to the "Web Application Environment" and the JavaEE specification described in Section 15.2.2 to implement the function of the application environment. Containers should provide a warning if they do not implement the conditions required to support such an environment, depending on the deployment of applications that depend on them.
10.12 Web Application Deployment
When a web application is deployed into a container, the following sequence of steps must be followed before the web application starts processing client requests.
■ Instantiate one instance of each event listener identified by the element in the deployment description file.
■ For an instantiated listener instance that implements the ServletContextListener interface, call the contextInitialized() method.
■ Instantiate one instance of each filter identified by the element in the deployment description file, and call the init() method of each filter instance.
■ Elements containing elements that instantiate an instance for each servlet in the order defined by the value of the load-on-startup element, and call the init() method of each servlet instance.
10.13 Including the web.xml deployment descriptor file
If the web application does not contain any servlet, filter, or listener components or declares the same using annotations, then the web.xml file may not be required. In other words, applications that contain only static files or JSP pages do not need a web.xml to exist.