Java Servlet Specification
|
   
|
| C H A P T E R 9 |
|
Web Applications |
A web application is a collection of servlets, HTML pages, classes, and other resources that make up a complete application on a web server. The web application can be bundled and run on multiple containers from multiple vendors.
A web application is rooted at a specific path within a web server. For example, a catalog application could be located at http://<servername>/catalog. All requests that start with this prefix will be routed to the ServletContext that represents the catalog application.
The servlet container must enforce a one-to-one correspondence between a web application and a ServletContext object. A ServletContext object provides a servlet with its view of the application.
A web application may consist of the following items:
This specification defines a hierarchical structure used for deployment and packaging purposes that can exist in an open file system, in an archive file, or in some other form. It is recommended, but not required, that servlet containers support this structure as a runtime representation.
A web application exists as a structured hierarchy of directories. The root of this hierarchy serves as the document root for files that are part of the application. For example, for a web application with the context path /catalog in a web container, the index.html file at the base of the web application hierarchy can be served to satisfy a request from /catalog/index.html. The rules for matching URLs to context path are laid out in Chapter 11. Since the context path of an application determines the URL namespace of the contents of the web application, web containers must reject web applications defining a context path that could cause potential conflicts in this URL namespace. This may occur, for example, by attempting to deploy a second web application with the same context path. Since requests are matched to resources in a case-sensitive manner, this determination of potential conflict must be performed in a case-sensitive manner as well.
A special directory exists within the application hierarchy named “WEB-INF”. This directory contains all things related to the application that are not in the document root of the application. The WEB-INF node is not part of the public document tree of the application. No file contained in the WEB-INF directory may be served directly to a client by the container. However, the contents of the WEB-INF directory with the exception of the contents of WEB-INF/classes, WEB-INF/lib and the deployment descriptor WEB-INF/web.xml are visible to servlet code using the getResourceAsStream method calls on the ServletContext, and may be exposed using the RequestDispatcher calls. Therefore, if the application developer needs access from servlet code to application-specific configuration information that s/he does not wish to be exposed directly to the web client, s/he may place it under this directory. Since requests are matched to resource mappings in a case-sensitive manner, client requests for “/WEB-INF/foo”, “/WEb-iNf/foo”, for example, should not result in the contents of the web application located under /WEB-INF being returned, nor any form of directory listing thereof.
The contents of the WEB-INF directory are:
Any requests from the client to access the resources in the WEB-INF/ directory must be returned with a SC_NOT_FOUND(404) response.
The following is a listing of all the files in a sample web application:
Web applications can be packaged and signed into a Web ARchive format (WAR) file using the standard Java archive tools. For example, an application for issue tracking might be distributed in an archive file named issuetrack.war.
When packaged into such a form, a META-INF directory will be present which contains information useful to Java Archive tools. This directory must not be directly served as content by the container in response to a web client’s request, and its contents must not be visible to servlet code via the getResourceAsStream calls on the ServletContext. Also, any requests to access the resources in META-INF directory must be returned with a SC_NOT_FOUND(404) response.
See the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Connected Edition for more information on the Java Card Platform-specific mechanism for deploying onto the Java Card Platform a web application’s WAR file.
The web application deployment descriptor (see Chapter 13) includes the following types of configuration and deployment information:
When an application depends on code or resources external to the WAR file, such as when several applications may make use of the same code or resources, they will typically be installed as library files. These files are often common or standard APIs that can be used without sacrificing portability.
The mechanism used for deploying web applications and the libraries they depend on is described in the Runtime Environment Specification, Java Card Platform, Version 3.0.1, Connected Edition.
Servlet containers should not allow applications to override system classes, such as those in the java.*, javax.*, javacard.* and javacardx.* namespaces, that the Java Card Platform does not allow to be modified. The container should not allow applications to override or access the container’s implementation classes.
A web application must be able to specify that when errors occur, other resources in the application are used to provide the content body of the error response. The specification of these resources is done in the deployment descriptor.
If the location of the error handler is a servlet, the following actions must occur:
These attributes allow the servlet to generate specialized content depending on the error code, the exception object propagated, and the URI of the request processed by the servlet in which the error occurred (as determined by the getRequestURI call), and the logical name of the servlet in which the error occurred.
To allow developers to customize the appearance of content returned to a web client when a servlet generates an error, the deployment descriptor defines a list of error page descriptions. The syntax allows the configuration of resources to be returned by the container either when a servlet or filter calls sendError on the response for specific error codes, or if the servlet generates an exception or error that propagates to the container.
If the sendError method is called on the response, the container consults the list of error page declarations for the web application that uses the error-code syntax and attempts a match. If there is a match, the container returns the resource as indicated by the location entry.
A servlet or filter may throw the following exceptions during processing of a request:
The web application may have declared error pages using the exception-type element. In this case the container matches the exception type by comparing the exception thrown with the list of error-page definitions that use the exception-type element. A match results in the container returning the resource indicated in the location entry. The closest match in the class hierarchy wins.
If no error-page declaration containing an exception-type fits using the class-hierarchy match, and the exception thrown is a ServletException or subclass thereof, the container extracts the wrapped exception, as defined by the ServletException.getRootCause method. A second pass is made over the error page declarations, again attempting the match against the error page declarations, but using the wrapped exception instead.
Error-page declarations using the exception-type element in the deployment descriptor must be unique up to the class name of the exception-type. Similarly, error-page declarations using the error-code element must be unique in the deployment descriptor up to the error code.
The error page mechanism described does not intervene when errors occur when invoked using the RequestDispatcher or filter.doFilter method. In this way, a filter or servlet using the RequestDispatcher has the opportunity to handle errors generated.
If a servlet generates an error that is not handled by the error page mechanism as described above, the container must ensure to send a response with status 500, by default - that is if no error code has already been set for the response.
The default servlet and container will use the sendError method to send 4xx and 5xx status responses, so that the error mechanism may be invoked. The default servlet and container will use the setStatus method for 2xx and 3xx responses and will not invoke the error page mechanism.
Web application developers can define an ordered list of partial URIs called “welcome files” in the web application deployment descriptor. The deployment descriptor syntax for the list is described in the 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 appending to URIs when there is a request for a URI that corresponds to a directory entry in the WAR not mapped to a web component. This kind of request is known as a valid partial request.
The use for this facility is made clear by the following common example: A welcome file of index.html can be defined so that a request to a URL such as host:port/webapp/directory/, where directory is an entry in the WAR that is not mapped to a servlet, is returned to the client as “host:port/webapp/directory/index.html”.
If a web container receives a valid partial request, the web container must examine the welcome file list 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 append each welcome file in the order specified in the deployment descriptor to the partial request and check whether a static resource or servlet in the WAR is mapped to that request URI. The web container must send the request to the first resource in the WAR that matches. The container may send the request to the welcome resource with a forward, a redirect, or a container specific mechanism that is indistinguishable from a direct request.
If no matching welcome file is found in the manner described, the container may handle the request in a manner it finds suitable. For some configurations this may mean returning a 404 response.
Consider a web application where:
<welcome-file-list> <welcome-file>index.html</welcome-file> <welcome-file>default.html</welcome-file> </welcome-file-list> |
When a web application is deployed into a container, the following steps must be performed, in this order, before the web application begins processing client requests.
1. Instantiate an instance of each event listener identified by a <listener> element in the deployment descriptor.
2. For instantiated listener instances that implement ServletContextListener, call the contextInitialized() method.
3. Instantiate an instance of each filter identified by a <filter> element in the deployment descriptor and call each filter instance’s init() method.
4. Instantiate an instance of each servlet identified by a <servlet> element that includes a <load-on-startup> element in the order defined by the load-on-startup element values, and call each servlet instance’s init() method.
| Java Servlet Specification
|
5-30-09 |
|
Copyright © 2009 Sun Microsystems, Inc. All rights reserved.