Java Servlet Specification

This chapter specifies the Java Servlet Specification for the Java Card Platform requirements for web container support of deployment descriptors. The deployment descriptor conveys the elements and configuration information of a web application between application developers, application assemblers, and deployers.

The deployment descriptor is defined in an XML schema document.

---

13.1 Deployment Descriptor Elements

The following types of configuration and deployment information are required to be supported in the web application deployment descriptor for all servlet containers:

• ServletContext Init Parameters
• Session Configuration
• Servlet Declaration
• Servlet Mappings
• Application Life Cycle Listener classes
• Filter Definitions and Filter Mappings
• MIME Type Mappings
• Welcome File list
• Error Pages
• Locale and Encoding Mappings
• Security

---

13.2 Rules for Processing the Deployment Descriptor

This section lists some general rules that web containers and developers must note concerning the processing of the deployment descriptor for a web application.

• Web containers must remove all leading and trailing white space, which is defined as “S(white space)” in XML 1.0 (http://www.w3.org/TR/2000/WD-xml-2e-20000814), for the element content of the text nodes of a deployment descriptor.
• The deployment descriptor must be valid against the schema. Web containers and tools that manipulate web applications have a wide range of options for checking the validity of a WAR. This includes checking the validity of the deployment descriptor document held within. Tools are required to validate deployment descriptor against the XML schema for structural correctness. The validation is recommended, but not required for the web containers.

Additionally, it is recommended that web containers and tools that manipulate web applications provide a level of semantic checking. For example, it should be checked that a role referenced in a security constraint has the same name as one of the security roles defined in the deployment descriptor.

In cases of non-conformant web applications, tools and containers should inform the developer with descriptive error messages. Vendors are encouraged to supply this kind of validity checking in the form of a tool separate from the container.

• The subelements under web-app can be in an arbitrary order in this version of the specification. Because of the restriction of XML Schema, the multiplicity of the elements session-config, welcome-file-list, login-config, and locale-encoding-mapping-list is set to “0 or more”. The containers or tools must inform the developer with a descriptive error message when the deployment descriptor contains more than one element of session-config, and login-config. The container must concatenate the items in welcome-file-list and locale-encoding-mapping-list when there are multiple occurrences.
• URI paths specified in the deployment descriptor are assumed to be in URL-decoded form. The containers or tools must inform the developer with a descriptive error message when URL contains CR(#xD) or LF(#xA). The containers must preserve all other characters including white space in a URL.
• Containers or tools must attempt to canonicalize paths in the deployment descriptor. For example, paths of the form /a/../b must be interpreted as /b. Paths beginning or resolving to paths that begin with ../ are not valid paths in the deployment descriptor.
• URI paths referring to a resource relative to the root of the WAR, or a path mapping relative to the root of the WAR, unless otherwise specified, should begin with a leading /.
• In elements whose value is an enumerated type, the value is case sensitive.

---

13.3 Deployment Descriptor

The XML Schema for the deployment descriptor of web applications intended to be deployed on the Java Card Platform is defined as a subset of the schema defined in the Servlet Specification, version 2.4.

Deployment descriptors conforming to the XML Schema defined for the Java Card Platform are also conforming to the schema defined for the Servlet Specification, version 2.4.

---

13.4 Deployment Descriptor Element Structure

This section illustrates the elements in a deployment descriptor. All diagrams follow the convention displayed in FIGURE 13-1. Attributes are not shown in the diagrams. See Deployment Descriptor Schema for the detailed information.

FIGURE 13-1 Conventions Used in Diagrams of Elements

13.4.1 web-app Element

The web-app element is the root deployment descriptor for a web application. This element has a required attribute version to specify to which version of the schema the deployment descriptor conforms. All sub-elements under this element can be in an arbitrary order. FIGURE 13-2 shows the structure of the web-app element.

Caution - While the multiplicity of the elements session-config, welcome-file-list, login-config, and locale-encoding-mapping-list is set to “0 or more” in the XML Schema, they should actually occur only once at the most. See Section 13.2, Rules for Processing the Deployment Descriptor for more details.

FIGURE 13-2 web-app Element Structure

13.4.2 description Element

The description element is to provide a text describing the parent element. This element occurs not only under the web-app element but also under other multiple elements. It has an optional attribute xml:lang to indicate which language is used in the description. The default value of this attribute is English (“en”).

13.4.3 display-name Element

The display-name contains a short name that is intended to be displayed by tools. The display name need not be unique. This element occurs not only under the web-app element but also under other multiple elements. This element has an optional attribute xml:lang to specify the language.

13.4.4 icon Element

The icon contains small-icon and large-icon elements that specify the file names for small and large GIF or JPEG icon images used to represent the parent element in a GUI tool. This element occurs not only under the web-app element but also under other multiple elements.FIGURE 13-3 shows structure of the icon element.

FIGURE 13-3 icon Element Structure

13.4.5 context-param Element

The context-param contains the declaration of a web application’s servlet context initialization parameters.

FIGURE 13-4 context-param Element Structure

13.4.6 filter Element

The filter declares a filter in the web application. The filter is mapped to either a servlet or a URL pattern in the filter-mapping element, using the filter-name value to reference. Filters can access the initialization parameters declared in the deployment descriptor at runtime via the FilterConfig interface. The filter-name element is the logical name of the filter. It must be unique within the web application. The element content of the filter-name element must not be empty. The filter-class is the fully qualified class name of the filter. The init-param element contains name-value pair as an initialization parameter of this filter. FIGURE 13-5 shows structure of the filter element.

FIGURE 13-5 filter Element Structure

13.4.7 filter-mapping Element

The filter-mapping element is used by the container to decide which filters to apply to a request in what order. The value of the filter-name must be one of the filter declarations in the deployment descriptor. The matching request can be specified either url-pattern or servlet-name. FIGURE 13-6 shows the structure of the filter-mapping element.

FIGURE 13-6 filter-mapping Element Structure

13.4.8 listener Element

The listener element indicates the deployment properties for an application listener bean. The sub-element listener-class declares that a class in the application must be registered as a web application listener bean. The value is the fully qualified class name of the listener class. FIGURE 13-7 shows the structure of the listener element.

FIGURE 13-7 listener Element Structure

13.4.9 servlet Element

The servlet element is used to declare a servlet. It contains the declarative data of a servlet. The servlet-name element contains the canonical name of the servlet. Each servlet name is unique within the web application. The element content of servlet-name must not be empty. The servlet-class contains the fully qualified class name of the servlet. The element load-on-startup indicates that this servlet should be loaded (instantiated and have its init() called) on the startup of the web application. The element content of this element must be an integer indicating the order in which the servlet should be loaded. If the value is a negative integer, or the element is not present, the container is free to load the servlet whenever it chooses. If the value is a positive integer or 0, the container must load and initialize the servlet as the application is deployed. The container must guarantee that servlets marked with lower integers are loaded before servlets marked with higher integers. The container may choose the order of loading of servlets with the same load-on-startup value. The security-role-ref element declares the security role reference in a component’s, or in a deployment component’s, code. It consists of an optional description, the security role name used in the code (role-name), and an optional link to a security role (role-link). If the security role is not specified, the deployer must choose an appropriate security role. FIGURE 13-8 shows the structure of the servlet element.

FIGURE 13-8 servlet Element Structure

13.4.10 servlet-mapping Element

The servlet-mapping element defines a mapping between a servlet and a URL pattern. FIGURE 13-9 shows the structure of the servlet-mapping element.

FIGURE 13-9 servlet-mapping Element Structure

13.4.11 session-config Element

The session-config element defines the session parameters for this web application. The sub-element session-timeout defines the default session timeout interval for all sessions created in this web application. The specified timeout must be expressed in a whole number of minutes. If the timeout is 0 or less, the container ensures the default behavior of sessions is never to time out. If this element is not specified, the container must set its default timeout period. FIGURE 13-10 shows the structure of the session-config element.

FIGURE 13-10 session-config Element Structure

13.4.12 mime-mapping Element

The mime-mapping element defines a mapping between an extension and a mime type. The extension element contains a string describing an extension, such as “txt”. FIGURE 13-11 shows the structure of the mime-mapping element.

FIGURE 13-11 mime-mapping Element Structure

13.4.13 welcome-file-list Element

The welcome-file-list element contains an ordered list of welcome files. The sub-element welcome-file contains a file name to use as a default welcome file, such as index.html. FIGURE 13-12 shows the structure of the welcome-file-list element.

FIGURE 13-12 welcome-file-list Element Structure

13.4.14 error-page Element

The error-page element contains a mapping between an error code or an exception type to the path of a resource in the web application. The sub-element exception-type contains a fully qualified class name of a Java programming language exception type. The sub-element location element contains the location of the resource in the web application relative to the root of the web application. The value of the location must have a leading /. FIGURE 13-13 shows the structure of the error-page element.

FIGURE 13-13 error-page Element Structure

13.4.15 security-constraint Element

The security-constraint element is used to associate security constraints with one or more web resource collections. The sub-element web-resource-collection identifies a subset of the resources and HTTP methods on those resources within a web application to which a security constraint applies. The auth-constraint indicates the user roles that should be permitted access to this resource collection. The role-name used here must either correspond to the role-name of one of the security-role elements defined for this web application, or be the specially reserved role name “*”, which is a compact syntax for indicating all roles in the web application. If both “*” and role names appear, the container interprets this as all roles. If no roles are defined, no user is allowed access to the portion of the web application described by the containing security-constraint. The container matches role names case sensitively when determining access. The user-data-constraint indicates how data communicated between the client and container should be protected by the sub-element transport-guarantee. The legal values of the transport-guarantee is either NONE, INTEGRAL or CONFIDENTIAL. FIGURE 13-14 shows the structure of the security-constraint element.

FIGURE 13-14 security-constraint Element Structure

13.4.16 login-config Element

The login-config element is used to configure the authentication method that should be used, the realm name that should be used for this application, and the attributes that are needed by the form login mechanism. The sub-element auth-method configures the authentication mechanism for the web application. The element content must be either BASIC, DIGEST, FORM or a vendor-specific authentication scheme.

The Runtime Environment Specification, Java Card Platform, Version 3.0.1, Connected Edition defines a Java Card Platform-specific extensible authentication scheme as a required extension to the default supported schemes listed above.

The realm-name indicates the realm name to use for the web application. The form-login-config specifies the login and error pages that should be used in FORM-Based login. If FORM-Based login is not used, these elements are ignored (unless the scheme is the Java Card Platform-specific extensible authentication scheme, which is similar to the FORM-Based login and therefore reuses these elements).

FIGURE 13-15 shows the structure of the login-config element.

FIGURE 13-15 login-config Element Structure

13.4.17 security-role Element

The security-role element defines a security role. The sub-element role-name designates the name of the security role. The name must conform to the lexical rules for NMTOKEN. FIGURE 13-16 shows the structure of the security-role element.

FIGURE 13-16 security-role Element Structure

13.4.18 locale-encoding-mapping-list Element

The locale-encoding-mapping-list contains the mapping between the locale and the encoding, specified by the sub-element locale-encoding-mapping as shown in CODE EXAMPLE 13-1 and FIGURE 13-7.

<locale-encoding-mapping-list>
	<locale-encoding-mapping>
		<locale>ja</locale>
		<encoding>Shift_JIS</encoding>
	</locale-encoding-mapping>
</locale-encoding-mapping-list>

FIGURE 13-17 locale-encoding-mapping-list Element Structure

---

13.5 Examples of Deployment Descriptor Usage

The following examples illustrate the usage of the definitions listed in the deployment descriptor schema.

13.5.1 A Basic Example

CODE EXAMPLE 13-2 is a deployment descriptor conforming to the XML schema defined for this Java Card Platform version of the Java Servlet Specification. This deployment descriptor can be validated against the XML schema defined for this specification, as well as against the XML schema defined for Java Servlet Specification, version 2.4.

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
		http://java.sun.com/xml/ns/javacard/jcweb-app_3_0.xsd"
		version="2.4">
		<display-name>A Simple Application</display-name>
		<context-param>
			<param-name>Webmaster</param-name>
			<param-value>webmaster@mycorp.com</param-value>
		</context-param>
		<servlet>
			<servlet-name>catalog</servlet-name>
			<servlet-class>com.mycorp.CatalogServlet
			 	</servlet-class>
			<init-param>
				<param-name>catalog</param-name>
				<param-value>Spring</param-value>
			</init-param>
		</servlet>
		<servlet-mapping>
			<servlet-name>catalog</servlet-name>
			<url-pattern>/catalog/*</url-pattern>
		</servlet-mapping>
		<session-config>
			<session-timeout>30</session-timeout>
		</session-config>
		<mime-mapping>
			<extension>pdf</extension>
			<mime-type>application/pdf</mime-type>
		</mime-mapping>
		<welcome-file-list>
			<welcome-file>index.shtm</welcome-file>
			<welcome-file>index.html</welcome-file>
			<welcome-file>index.htm</welcome-file>
		</welcome-file-list>
		<error-page>
			<error-code>404</error-code>
			<location>/404.html</location>
		</error-page>
	</web-app>

The same example may be generated by a Java Servlet 2.4-compliant tool. This deployment descriptor can be validated against the XML Schema defined for Servlet Specification, version 2.4, as well as against the schema defined for Java Card Platform version of this specification.

<?xml version="1.0" encoding="UTF-8"?>
	<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
		http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd”
		version=”2.4”>
	...
	</web-app>

13.5.2 An Example of Security

See CODE EXAMPLE 13-3

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
	http://java.sun.com/xml/ns/javacard/jcweb-app_3_0.xsd" 
	version=”2.4”>
	<display-name>A Secure Application</display-name>
	<servlet>
		<servlet-name>catalog</servlet-name>
			<servlet-class>com.mycorp.CatalogServlet
			</servlet-class>
		<init-param>
			<param-name>catalog</param-name>
			<param-value>Spring</param-value>
		</init-param>
		<security-role-ref>
			<role-name>MGR</role-name>
			<!-- role name used in code -->
			<role-link>manager</role-link>
		</security-role-ref>
	</servlet>
	<security-role>
		<role-name>manager</role-name>
	</security-role>
	<servlet-mapping>
		<servlet-name>catalog</servlet-name>
		<url-pattern>/catalog/*</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>catalog</servlet-name>
		<url-pattern>/salesinfo/*</url-pattern>
	</servlet-mapping>
	<security-constraint>
		<web-resource-collection>
			<web-resource-name>SalesInfo
			</web-resource-name>
			<url-pattern>/salesinfo/*</url-pattern>
			<http-method>GET</http-method>
			<http-method>POST</http-method>
		</web-resource-collection>
		<auth-constraint>
			<role-name>manager</role-name>
		</auth-constraint>
		<user-data-constraint>
			<transport-guarantee>CONFIDENTIAL
			</transport-guarantee>
		</user-data-constraint>
	</security-constraint>
	<login-config>
		<auth-method>BASIC</auth-method>
		<realm-name>mgmt</realm-name>
	</login-config>
</web-app>

Java Servlet Specification

5-30-09

Copyright © 2009 Sun Microsystems, Inc. All rights reserved.