Previous Section  < Day Day Up >  Next Section

F.2 Web Application Deployment Descriptor

The WEB-INF/web.xml file is the Java web application deployment descriptor that contains all general configuration information for the application, in addition to the JSF-specific information in the WEB-INF/faces-config.xml file described in Appendix E. Some elements are especially important for a JSF application, namely the <context-param>, <servlet>, and <servlet-mapping> elements. See the subsections for these elements for what configurations you must and can set for a JSF-application in the WEB-INF/web.xml file.

The deployment descriptor is an XML file. Starting with Servlet 2.4 and JSP 2.0, the elements it can contain and how they must be arranged are controlled by a number of XML Schema documents. The main XML Schema document, which includes the others, is available online at http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd. This XML Schema document must be referenced in the root element of the deployment description, as shown in Example F-1.

Example F-1. Web Application Descriptor root element for Servlet 2.4/JSP 2.0
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"

  xmlns:xsi="http://www.w3c.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>

If you're not familiar with the intricate details of XML Schema and namespace declarations, just accept the fact that you must enclose all other elements in the deployment descriptor within a <web-app> element exactly as shown in Example F-1.

A JSF application can be deployed in a Servlet 2.3/JSP 1.2 container,[1] and the rules for the deployment descriptor for those specification versions are defined by a Document Type Descriptor (DTD), available online at http://java.sun.com/dtd/web-app_2_3.dtd. Most of the elements are the same between the two deployment descriptor versions, but the Servlet 2.3 DTD requires a fixed ordering of the top-level elements while the Servlet 2.4 XML Schema allows them to be declared in any order (see the DTD for details if you use a Servlet 2.3 container). Other than that, the only visible difference is at the top of the deployment descriptor. Example F-2 shows how it must look like for a Servlet 2.3 deployment descriptor.

[1] Note that the examples described in this book use JSP 2.0 features and will not run in a Servlet 2.3/JSP 1.2 container unless the JSP pages are modified.

Example F-2. Web Application Descriptor root element for Servlet 2.3/JSP 1.2
<!DOCTYPE web-app PUBLIC

  "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

  "http://java.sun.com/dtd/web-app_2_3.dtd">



<web-app>

  ...

</web-app>

Within the <web-app> element body, top-level elements can be included in any order if you're using Servlet 2.4/JSP 2.0 deployment descriptor. Each top-level element is described in a separate section in this appendix. The top-level elements all are optional and can be included more than once, unless otherwise stated. Most top-level elements contain other elements.

I use syntax descriptions similar to those in the other appendixes to show the rules for the elements nested within top-level elements. The nested elements must be included in the order they are listed in the syntax description. Mutually exclusive elements are separated by vertical bars (|). Optional nested elements are embedded in square brackets ([]), followed by an asterisk (*) if more than one element of this type may be used. An element name followed by a plus sign (+) means the element is required, but it can be used more than once. For elements that accept predefined values, all values are listed separated by vertical bars; the default value (if any) is in bold face. Italics are used for element values that don't have a fixed set of accepted values. Element attribute values are described using the same syntax as element values.

<description>, <display-name>, and <icon>

These three elements provide information a web container deployment tool can use to describe the application. As an exception to the rule that top-level elements can be included in any order, these three must be in the order shown here.

Syntax

<description [xml:lang="lang"]>description</description>

<display-name [xml:lang="lang"]>displayName</display-name>

<icon [xml:lang="lang"]>

  [<small-icon>iconPath</small-icon>]

  [<large-icon>iconPath</large-icon>]

</icon>

The <icon> element can contain a <small-icon> and a <large-icon> element, each with a context-relative path to an image file (GIF and JPEG formats are supported). The small icon must be 16x16 pixels, and the large 32x32. The <display-name> element can specify a name for the application, and the <description> element a longer description.

You can use different versions of all these top-level elements for multiple languages, each with a unique xml:lang attribute value ("en", for English, is the default value):

<icon>

  <small-icon>/images/small.gif</small-icon>

  <large-icon>/images/large.gif</large-icon>

</icon>

<display-name>The application name</display-name>

<description>

  A longer description of

  the application.

</description>
<distributable>

The <distributable> element is used to tell the web container that the application is designed to run in a distributed web container.

Syntax

<distributable/>

This element does not contain a body. A distributable application does not rely on servlet instance variables, static classes or variables, servlet context attributes, or any other mechanism for shared information that is restricted to one Java Virtual Machine (JVM). It also means that all objects placed in the session scope are serializable, so that the container can move the session data from one JVM to another. For more information about distributed applications, see the servlet specification or my book JavaServer Pages (O'Reilly).

<context-param>

Using the <context-param> element, you can define context parameters that are available to all components of the application (both servlets and JSP pages).

Syntax

<context-param>

  [<description [xml:lang="lang"]>description</description>]*

  <param-name>paramName</param-name>

  <param-value>paramValue</param-value>

<context-param>

The <param-name> subelement specifies the name and the <param-value> element the value. Optionally, the <description> element can be used for a description that can be displayed by a deployment tool:

<context-param>

  <param-name>jdbcURL</param-name>

  <param-value>jdbc:idb:/usr/local/db/mydb.prp</param-value>

</context-param>

The JSF specification defines the following context parameters:


javax.faces.CONFIG_FILES

Optionally defines a comma-separated list of context-relative paths for JSF configuration files. See Chapter 13 for details.


javax.faces.DEFAULT_SUFFIX

Optionally defines a suffix (file extension) for the JSP pages that contains JSF component action elements, to use a different one than the default (.jsp). If you define a nondefault suffix, you must also define that this suffix represents a JSP page, using the <jsp-config> element in a Servlet 2.4/JSP 2.0 container or an implementation-dependent mapping in a Servlet 2.3/JSP 1.2 container.


javax.faces.LIFECYCLE_ID

Optionally defines a lifecycle identifier other than the default set by the javax.faces.lifecycle.LifecycleFactory.DEFAULT_LIFECYCLE constant.


javax.faces.STATE_SAVING_METHOD

Optionally defines a state saving method other than the default (server). Valid values are client and server. See Chapter 6 for details.

<filter>

The <filter> element registers a filter component.

Syntax

<filter>

  [<description [xml:lang="lang"]>description</description>]*

  [<display-name [xml:lang="lang"]>displayName</display-name>]*

  [<icon [xml:lang="lang"]>

     [<small-icon>iconPath</small-icon>]

     [<large-icon>iconPath</large-icon>]

   </icon>]*

  <filter-name>filterName</filter-name>

  <filter-class>className</filter-class>

  [<init-param>

     [<description [xml:lang="lang"]>description</description>]*

     <param-name>paramName</param-name>

     <param-value>paramValue</param-value>

   </init-param>]*

</filter>

Nested <icon>, <display-name>, and <description> elements can optionally define icons and descriptions that can be used by a tool. The nested <filter-name> element defines a unique logical name for the filter, and the <filter-class> element the class name. A set of initialization parameters can optionally be defined by <init-param> elements.

<filter>

  <filter-name>accessControl</filter-name>

  <filter-class>com.mycomp.AccessControlFilter</filter-class>

  <init-param>

    <param-name>loginPage</param-name>

    <param-value>/login.jsp</param-value>

  </init-param>

</filter>
<filter-mapping>

A filter is mapped to either to a URI pattern or a servlet using the <filter-mapping> element.

Syntax

<filter-mapping>

  <filter-name>filterName </filter-name>

  <url-pattern>urlPattern </url-pattern> |

    <servlet-name>servletName</servlet-name>

  [<dispatcher>FORWARD|INCLUDE|REQUEST |ERROR</dispatcher>]*

</filter-mapping>

The <filter-name> subelement identifies the filter using a name defined by a <filter> element. A <url-pattern> or a <servlet-name> defines when the filter shall be invoked. If a URL mapping is used, the same values as for a <servlet-mapping> element can be used. More than one filter may match a specific request. If so, the container chains them in the order the matching <filter-mapping> elements appear in the deployment descriptor.

Up to four <dispatcher> elements may be used to define for what circumstances the filter should be applied: FORWARD and INCLUDE mean it's applied for internal request made through the javax.servlet.RequestDispatcher forward( ) and include() methods, respectively; ERROR means it's applied when dispatching to an error page as part of the error mechanism; REQUEST means it's applied for regular, external client requests. If no <dispatcher> element is used, the default behavior is as if an element with the REQUEST value had been specified:

<filter-mapping>

  <filter-name>accessControl</filter-name>

  <url-pattern>/protected</url-pattern>

</filter-mapping>
<listener>

All the listener types defined by the servlet specification (as opposed to the JSF listener types) must be registered with a <listener> element.

Syntax

<listener>

  [<description [xml:lang="lang"]>description</description>]*

  [<display-name [xml:lang="lang"]>displayName</display-name>]*

  [<icon [xml:lang="lang"]>

     [<small-icon>iconPath</small-icon>]

     [<large-icon>iconPath</large-icon>]

   </icon>]*

  <listener-class>className</listener-class>

</listener>

The <description>, <display-name>, and <icon>, elements can optionally be used, the same as for many other top-level elements. The nested <listener-class> element contains the listener class name:

<listener>

  <listener-class>com.mycomp.AppInitListener</listener-class>

</listener>
<servlet>

The <servlet> element defines servlet class or JSP page details.

Syntax

<servlet>

  [<description [xml:lang="lang"]>description</description>]*

  [<display-name [xml:lang="lang"]>displayName</display-name>]*

  [<icon [xml:lang="lang"]>

     [<small-icon>iconPath</small-icon>]

     [<large-icon>iconPath</large-icon>]

   </icon>]*

  <servlet-name>servletName</servlet-name>

  <servlet-class>className</servlet-class> |

    <jsp-file>jspPath</jsp-file>

  [<init-param>

     [<description [xml:lang="lang"]>description</description>]*

     <param-name>paramName</param-name>

     <param-value>paramValue</param-value>

   </init-param>]*

  [<load-on-startup>startupValue</load-on-startup>]

  [<run-as>roleName</run-as>]

  [<security-role-ref>

    [<description [xml:lang="lang">description</description>]*

    <role-name>internalRoleName</role-name>

    [<role-link>roleName</role-link>]

   </security-role-ref>]*

</servlet>

Most commonly, this element just associates a servlet or JSP page with a short name and specifies initialization parameters:

<servlet>

  <servlet-name>

    purchase

  </servlet-name>

  <servlet-class>

    com.mycorp.servlets.PurchaseServlet

  </servlet-class>

  <init-param>

    <param-name>maxAmount</param-name>

    <param-value>500.00</param-value>

  </init-param>

</servlet>

<servlet>

  <servlet-name>

    order-form

  </servlet-name>

  <jsp-file>

    /po/orderform.jsp

  </jsp-file>

  <init-param>

    <param-name>bgColor</param-name>

    <param-value>blue</param-value>

  </init-param>

</servlet>

The same servlet class (or JSP page) can be defined with multiple names, typically with different initialization parameters. The container creates an instance of the class for each name.

The <load-on-startup> subelement can tell the container to load the servlet when the application is started. The value is a positive integer, indicating when the servlet is to be loaded relative to other servlets. A servlet with a low value is loaded before a servlet with a higher value:

<servlet>

  <servlet-name>

    controller

  </servlet-name>

  <servlet-class>

    com.mycorp.servlets.ControllerServlet

  </servlet-class>

  <load-on-startup>1</load-on-startup>

</servlet>

The <icon>, <display-name>, and <description> elements describe the servlet or JSP page, the same way as for other top-level elements.

<security-role-ref> elements, combined with <security-role> elements, can link a security role name used in a servlet as the argument to the HttpServletRequest.isUserInRole() method to a role name known by the web container:

<servlet>

  <servlet-name>

    controller

  </servlet-name>

  <servlet-class>

    com.mycorp.servlets.ControllerServlet

  </servlet-class>

  <security-role-ref>

    <role-name>administrator</role-name>

    <role-link>admin</role-link>

  </security-role-ref>

</servlet>

...

<security-role>

  <role-name>admin</role-name>

</security-role>

All role names defined by <security-role> elements must be mapped to users and/or groups known by the web container. How this is done is container-dependent. The <security-role-ref> element allows you to use a servlet that uses a role name in the isUserInRole( ) method that is not defined by a <security-role> element. A typical scenario where this can be useful is when you combine servlets from different sources into one application, and the servlets use different role names for the same logical role.

Finally, the <run-as> element can define the security role that the servlet should be presented as if it makes calls into an EJB container. The nested <role-name> value must be defined by a <security-role> element:

<servlet>

  <servlet-name>

    controller

  </servlet-name>

  <servlet-class>

    com.mycorp.servlets.ControllerServlet

  </servlet-class>

  <run-as>

    <role-name>admin</role-name>

  </run-as>

</servlet>

...

<security-role>

  <role-name>admin</role-name>

</security-role>

See the J2EE documentation for details about how to use this element.

JSF relies on a servlet that must be declared and mapped to a URL pattern. The servlet class name is javax.faces.webapp.FacesServlet, but you can use any symbolic name you want:

<servlet>

  <servlet-name>facesServlet</servlet-name>

  <servlet-class>

    javax.faces.webapp.FacesServlet

  </servlet-class>

</servlet>
<servlet-mapping>

The <servlet-mapping> element maps a servlet or JSP page to a URL pattern.

Syntax

<servlet-mapping>

  <servlet-name>servletName</servlet-name>

  <url-pattern>urlPattern</url-pattern>

</servlet-mapping>

Most containers support a special URI prefix (/servlet) that can invoke any servlet class that the container has access to, for instance the URI /servlet/com.mycompany.MyServlet can invoke the servlet class com.mycomapany.MyServlet. This isn't mandated by the specification, however, so to make sure the application is portable, it's better to map a unique path to a servlet instead. Explicit mapping also simplifies references between servlets and JSP pages. The <servlet-mapping> element is used for this purpose. The <servlet-name> subelement contains a name defined by a <servlet> element, and the <url-pattern> contains the pattern that should be mapped to the servlet (or JSP page):

<servlet-mapping>

  <servlet-name>purchase</servlet-name>

  <url-pattern>/po/*</url-pattern>

</servlet-mapping>

<servlet-mapping>

  <servlet-name>sales-report</servlet-name>

  <url-pattern>/report</url-pattern>

</servlet-mapping>

<servlet-mapping>

  <servlet-name>XMLProcessor</servlet-name>

  <url-pattern>*.xml</url-pattern>

</servlet-mapping>

A pattern can take one of four forms:

  • A path prefix pattern starts with a slash (/) and ends with /*, for instance /po/*.

  • An extension mapping pattern starts with *., for instance *.xml.

  • A default servlet pattern consists of just the / character.

  • All other patterns are exact match patterns.

When the container receives a request, it strips off the context path and then tries to find a pattern that matches a servlet mapping. Exact match patterns are analyzed first, then the path prefix patterns starting with the longest one, and then the extension mapping patterns. If none of these patterns match, the default servlet pattern is used, if specified. As a last resort, the containers default request processor handles the request.

With the mappings defined here, a URI like /po/supplies invokes the purchase servlet, /report invokes the sales-report servlet (but note that /report/spring doesn't, because an exact match pattern is used), and /eastcoast/forecast.xml invokes the XMLProcessor servlet.

The JSF servlet must be mapped to a URL pattern. The *.faces extension mapping pattern is recommended, but you can also use path prefix pattern, for instance /faces/*:

<servlet-mapping>

  <servlet-name>facesServlet</servlet-name>

  <url-pattern>*.faces</url-pattern>

</servlet-mapping>
<session-config>

The <session-config> element can customize session handling attributes. You must use only one element of this type in a deployment descriptor.

Syntax

<session-config>

  [<session-timeout>minutes</session-timeout>]

</session-config>

It contains just one subelement: the <session-timeout> element used to specify the default session timeout value in minutes. A value of 0 or less means that sessions never time out. Omitting the nested element means the container uses its own default:

<session-config>

  <session-timeout>30</session-timeout>

</session-config>
<mime-mapping>

The <mime-mapping> element can define the mappings an application requires.

Syntax

<mime-mapping>

  <extension>fileExtension</extension>

  <mime-type>mimeType</mime-type>

</mime-mapping>

A servlet may need to know which MIME type a file extension corresponds to, and such a mapping can be defined with this element:

<mime-mapping>

  <extension>wml</extension>

  <mime-type>text/vnd.wap.wml</mime-type>

</mime-mapping>

Most containers provide default mappings for the most commonly used extensions, such as .html, .htm, .gif, .jpg, and so on, but if you need to be absolutely sure that a mapping is defined for your application, put it in the web.xml file.

<welcome-file-list>

The <welcome-file-list> element can define an ordered list of files to look for in the directory and serve if present. If you use more than one element of this type, the container merges them.

Syntax

<welcome-file-list>

  <welcome-file>fileName</welcome-file>+

</welcome-file-list>

A welcome file is a file (or a URL mapped to a servlet) that the container serves when it receives a request URI that identifies a directory as opposed to a web page or a servlet:

<welcome-file-list>

  <welcome-file>index.html</welcome-file>

  <welcome-file>index.htm</welcome-file>

  <welcome-file>default.html</welcome-file>

  <welcome-file>default.htm</welcome-file>

</welcome-file-list>

When a directory entry request (a request for a URI ending with a slash) is received that does not match a servlet mapping, the container appends each welcome file name in the order specified in the deployment descriptor to the request URI and checks whether a resource in the WAR is mapped to the new URI. If it is, the request is sent to the resource. If no matching resource is found, the behavior is container dependent. The container may, for instance, return a directory listing an HTTP 404 status code (Not Found).

<error-page>

The <error-page> element can define pages that inform the user about various errors.

Syntax

<error-page>

  <error-code>errorCode</error-code> |

    <exception-type>className</exception-type>

  <location>pagePath</location>

</error-page>

A page can be specified for an HTTP error status code, such as 404 (Not Found), using the <error-code> subelement. As an alternative, the <exception-type> subelement can be used to specify a Java exception class name, to use a special page to handle exceptions thrown by servlets and JSP pages. The <location> subelement contains the context-relative path for the error page:

<error-page>

  <error-code>404</error-code>

  <location>/errors/404.html</location>

</error-page>

<error-page>

  <exception-type>javax.servlet.ServletException</exception-type>

  <location>/errors/exception.jsp</location>

</error-page>
<jsp-config>

The <jsp-config> element embeds most elements dealing with JSP configuration. You must use only one element of this type in a deployment descriptor.

Syntax

<jsp-config>

  [<taglib>

    <taglib-uri>taglibURI </taglib-uri>

    <taglib-location>filePath </taglib-location>

   </taglib>]*

  [<jsp-property-group>

     [<description [xml:lang="lang "]>description </description>]*

     [<display-name [xml:lang="lang "]>displayName </display-name>]*

     [<icon [xml:lang="lang "]>

        [<small-icon>iconPath </small-icon>]

        [<large-icon>iconPath </large-icon>]

      </icon>]*

     <url-pattern>urlPattern </url-pattern>+

     [<el-ignored>true|false</el-ignored>]

     [<page-encoding>encoding </page-encoding>]

     [<scripting-invalid>true|false </scripting-invalid>]

     [<is-xml>true|false </is-xml>]

     [<include-prelude>filePath </include-prelude>]*

     [<include-coda>filePath </include-coda]*

   </jsp-property-group>]*

</jsp-config>

Nested <taglib> elements map the symbolic name for a tag library specified by the taglib directive in a JSP page to the location of the TLD file or JAR file that contains the TLD file. The <taglib-uri> element value must match the uri attribute value used in the JSP page and the <taglib-location> subelement contains the context-relative path to the library file:

<jsp-config>

  <taglib>

    <taglib-uri>orataglib</taglib-uri>

    <taglib-location>/WEB-INF/lib/orataglib_1_0.jar</taglib-location>

  </taglib>

</jsp-config>

With the introduction of the auto-discovery feature in JSP 1.2, this element is rarely needed. For more details, see Chapter 4.

Nested <jsp-property-group> elements define a number of attributes for a set of JSP pages. The set of pages is defined by one or more <url-pattern> elements, with the same pattern types as are valid for the <servlet-mapping> element. The other elements define the attributes shared by these pages.

<jsp-config>

  <jsp-property-group>

    <url-pattern>*.xml</url-pattern>

    <el-ignored>true</el-ignored>

    <page-encoding>Shift_JIS</page-encoding>

    <scripting-invalid>true</scripting-invalid>

    <is-xml>true</is-xml>

    <include-prelude>/copyright.txt</include-prelude>

  </jsp-property-grop>

</jsp-config>

An <el-ignored> value of true means that character sequences that look like EL expressions, i.e., starts with ${, are treated as template text instead of EL expressions. This can be useful when pre-JSP 2.0 pages must be used in a JSP 2.0 application. The default is true for an application deployed with a pre-JSP 2.0 deployment descriptor, and it's false for an application with a JSP 2.0 deployment descriptor.

The <page-encoding> element defines the file encoding for all matching JSP files.

The <scripting-invalid> element can be used to define an application-wide policy for use of the JSP scripting elements (i.e., Java code). With a value of true, a page that contains scripting elements is rejected at translation time.

A <is-xml> element with a value of true tells the container that matching pages are written as JSP Documents, i.e., as XML documents instead of regular JSP pages.

The <include-prelude> and <include-coda> elements provide for automatic inclusion of files during the translation phase. Files defined by <include-prelude> elements are included at the top of each matching page; files defined by <include-coda> are included at the end. The file location is specified as a context-relative path.

For more on all the <jsp-property-group> elements, see the JSP specification or my book JavaServer Pages (O'Reilly).

<resource-env-ref>

The <resource-env-ref> element declares an application resource accessible through JNDI.

Syntax

<resource-env-ref>

  [<description [xml:lang="lang"]>description</description>]*

  <resource-env-ref-name>envRefName</resource-env-ref-name>

  <resource-env-ref-type>envRefType</resource-env-ref-type>

</resource-env-ref>

In a complete J2EE-compiant container (i.e., one that supports other J2EE technologies besides servlets and JSP), the container can provide access to so-called administered objects through JNDI. Examples of this type of object are the ones used by the Java Messaging System (JMS) API. The <resource-env-ref> elements declares the JNDI path used to access the object in the application and its type, using nested <resource-env-ref-name> and <resource-end-ref-type> elements:

<resource-env-ref>

  <resource-env-ref-name>/jms/StockQueue</resource-env-ref-name>

  <resource-env-ref-type>/javax.jms.Queue</resource-env-ref-type>

</resource-env-ref>

Optionally, descriptions can be provided by the <description> element.

<resource-ref>

The <resource-ref> element defines JNDI accessible object factories for application objects.

Syntax

<resource-ref>

  [<description [xml:lang="lang "]>description </description>]*

  <res-ref-name>refName </res-ref-name>

  <res-ref-type>refType </res-ref-type>

  <res-auth>Application|Container</res-auth>

  [<res-sharing-scope>Shareable |Unshareable</res-sharing-scope>]

</resource-ref>

A J2EE-compliant container (and some web containers that support JNDI in addition to servlets and JSP) can also provide access to resource factories that produce the objects used in an application, such as a DataSource that produces Connection objects for database access. The <resource-ref> element defines these factories using the <res-ref-name> to specify the JNDI path used in the application, the <res-type> for the factory type, and <res-auth> to define whether the authentication is performed by the application (with the Application value) or the container (with the Container value). An optional <res-sharing-scope> element can be used to define if the objects produced by the factory may be shared or not (with Shareable and Unshareable, respectively, the prior being the default):

<resource-ref>

  <res-ref-name>/jms/Production</res-ref-name>

  <res-ref-type>/javax.sql.DataSource</res-ref-type>

  <res-auth>Container</res-auth>

</resource-ref>

As for most elements, <description> elements can provide descriptions in multiple languages to help the deployer.

<security-constraint>

The <security-constraint> element defines how and by whom resources can be accessed.

Syntax

<security-constraint>

  [<display-name [xml:lang="lang "]>displayName </display-name>]*

  <web-resource-collection>

    <web-resource-name>resName </web-resource-name>

    [<description [xml:lang="lang "]>description </description>]*

    <url-pattern>urlPattern </url-pattern>+

    [<http-method>GET|POST|PUT|DELETE|HEAD|OPTIONS|TRACE</http-method>]

  </web-resource-collection>+

  [<auth-constraint>

     [<description [xml:lang="lang "]>description </description>]*

     [<role-name>roleName </role-name>]*

   </auth-constraint>]

  [<user-data-constraint>

     <transport-guarantee>

       NONE |INTEGRAL|CONFIDENTIAL

     </ transport-guarantee>

   </user-data-constraint>]

</security-constraint>

The <security-constraint> element contains a <web-resource-collection> subelement that defines the resources to be protected and an <auth-constraint> subelement that defines who has access to the protected resources. It can also contain a <user-data-constraint> subelement that describes security requirements for the connection used to access the resource:

<security-constraint>

  <web-resource-collection>

    <web-resource-name>admin</web-resource-name>

    <url-pattern>/admin/*</url-pattern>

    <http-method>GET</http-method>

  </web-resource-collection>

  <auth-constraint>

    <role-name>admin</role-name>

  </auth-constraint>

  <user-data-constraint>

    <transport-guarantee>CONFIDENTIAL</ transport-guarantee>

  </user-data-constraint>

</security-constraint>

Within the <web-resource-collection> element, the resource is given a name with the <web-resource-name> subelement and the URI patterns for the protected resources are specified with <url-pattern> elements. <http-method> subelements can also be used to restrict the types of accepted requests. This example protects all resources accessed with URIs that starts with /admin and says that only the GET method can access these resources.

The <role-name> subelements within the <auth-constraint> element specify the roles that the current user must have to get access to the resource. The value must be a role name defined by a <security-role> element. In this example, the user must belong to the admin role in order to access resources under /admin. How the role names are mapped to user and/or group names in the container's security system is container dependent.

A <transport-guarantee> element can contain one of three values:


NONE

No special requirements. This is the default.


INTEGRAL

Data must be sent between the client and server in such a way that it can't be changed in transit. Typically this means that an SSL connection is required.


CONFIDENTIAL

Data must be sent in such a way that it can't be observed by others. This is also typically satisfied by an SSL connection.

<login-config>

The <login-config> element declares which authentication method to use for protected resources. You must use only one element of this type in a deployment descriptor.

Syntax

<login-config>

  [<auth-method>BASIC|DIGEST|FORM|CLIENT-CERT</auth-method>]

  [<realm-name>realmName</realm-name>]

  [<form-login-config>

     <form-login-page>loginPagePath</form-login-page>

     <form-error-page>errorPagePath</form-error-page>

   </form-login-config>]

</login-config>

For an application that uses the <security-constraint> element to protect resources, you must also define how to authenticate users with a <login-config> element. It can contain three subelements: <auth-method>, <realm-name>, and <form-login-config>:

<login-config>

  <auth-method>BASIC</auth-method>

  <realm-name>Protected pages</realm-name>

</login-config>

The <auth-method> element can have one of the values BASIC, DIGEST, FORM, and CLIENT-CERT, corresponding to the four container-provided authentication methods described in Chapter 5. The <realm-name> element can specify the name shown by the browser when it prompts for a password when the BASIC authentication is used.

If FORM authentication is used, the <form-login-config> element defines the login page and an error pages (used for invalid login attempts):

<login-config>

  <auth-method>FORM</auth-method>

  <form-login-config>

    <form-login-page>/login/login.html</form-login-page>

    <form-error-page>/login/error.html</form-error-page>

  </form-login-config>

</login-config>

For more about the FORM authentication method, see Chapter 5.

<security-role>

<security-role> elements are used to define the role names that the application uses.

Syntax

<security-role>

  [<description [xml:lang="lang"]>description</description>]*

  <role-name>roleName</role-name>

</security-role>

All names used in isUserInRole() calls, in <security-role-ref> elements and <auth-constraint> elements must be declared by a separate <security-role> element:

<security-role>

  <role-name>admin</role-name>

</security-role>

<security-role>

  <role-name>user</role-name>

</security-role>

Each role must be mapped to a user and/or group in the container's security domain in a container dependent way.

<locale-encoding-mapping-list>

The <locale-encoding-mapping-list> element defines mappings between locales and response encodings. If you use more than one element of this type, the container merges them.

Syntax

<locale-encoding-mapping-list>

  <locale-encoding-mapping>

    <locale>locale</locale>

    <encoding>encoding</encoding>

  </locale-encoding-mapping>+

</locale-encoding-mapping-list>

Unless a specific response encoding is been specified explicitly, setting the locale for a response also sets its encoding. The <locale-encoding-mapping-list> element allows you to define how locales map to response encodings, overriding the container's default mappings. The <locale> element contains the locale value as an ISO-639 language code, optionally combined with an ISO-3166 country code, separated by an underscore or a dash. The <encoding> element contains an encoding (charset) value recognized by Java.

<locale-encoding-mapping-list>

  <locale-encoding-mapping>

    <locale>en-US</locale>

    <encoding>UTF-8</encoding>

  </locale-encoding-mapping>

  <locale-encoding-mapping>

    <locale>ja</locale>

    <encoding>Shift_JIS</encoding>

  </locale-encoding-mapping>

</locale-encoding-mapping-list>
<env-entry>

The <env-entry> element is used to define simple objects, such as a String or Boolean, accessed by the application through JNDI.

Syntax

<env-entry>

  [<description [xml:lang="lang"]>description</description>]*

  <env-entry-name>entryName</env-entry-name>

  <env-entry-type>entryType</env-entry-type>

  [<env-entry-value>entryValue</env-entry-value>]

</env-entry>

The <env-entry-name> defines the JNDI name relative to the java:comp/env context and <env-entry-type> the type, which must be one of java.lang.Boolean, java.lang.Byte, java.lang.Character, java.lang.String, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float or java.lang.Double. The value can optionally be defined statically, using the <env-entry-value> element or be provided at deployment. An optional <description> element is also supported:

<env-entry>

  <env-entry-name>maxConnections</env-entry-name>

  <env-entry-type>java.lang.Integer</env-entry-type>

  <env-entry-value>100</env-entry-value>

</env-entry>
<ejb-ref>

The <ejb-ref> element is used to declare a remote EJB reference used by the application.

Syntax

<ejb-ref>

  [<description [xml:lang="lang"]>description</description>]*

  <ejb-ref-name>ejbRefName</ejb-ref-name>

  <ejb-ref-type>Entity|Session</ejb-ref-type>

  <home>homeInterfaceName</home>

  <remote>remoteInterfaceName</remote>

  [<ejb-link>linkedEJBName</ejb-link>]

</ejb-ref>

In a J2EE-compliant container, the <ejb-ref> element is used to declare EJB objects. The name (JNDI path), type (Entity or Session), home, and remote interface class names must be specified with the <ejb-ref-name>, <ejb-ref-type>, <home>, and <remote> elements:

<ejb-ref>

  <ejb-ref-name>ejb/Payroll</ejb-ref-name>

  <ejb-ref-type>Session</ejb-ref-type>

  <home>com.mycomp.PayrollHome</home>

  <remote>com.mycomp.Payroll</remote>

</ejb-ref>

An optional <ejb-link> element can be used to uniquely identify a specific bean if more than one EJB has the same name. In addition, an optional <description> element can be used to add a description of the EJB.

<ejb-local-ref>

The <ejb-ref> element is used to declare a local EJB reference used by the application.

Syntax

<ejb-local-ref>

  [<description [xml:lang="lang"]>description</description>]*

  <ejb-ref-name>ejbRefName</ejb-ref-name>

  <ejb-ref-type>Entity|Session</ejb-ref-type>

  <local-home>homeInterfaceName</local-home>

  <local>localInterfaceName</local>

  [<ejb-link>linkedEJBName</ejb-link>]

</ejb-local-ref>

The <ejb-local-ref> element serves the same purpose as the <ejb-ref> element but for local beans. It supports all the same nested elements, except that <home> is replaced by <local-home> and <remote> is replaced by <local>:

<ejb-local-ref>

  <ejb-ref-name>ejb/Payroll</ejb-ref-name>

  <ejb-ref-type>Session</ejb-ref-type>

  <local-home>com.mycomp.PayrollHome</local-home>

  <local>com.mycomp.Payroll</local>

</ejb-local-ref>
<service-ref>

The <service-ref> element declares a reference to a web service used by the application.

Syntax

<service-ref>

  [<description [xml:lang="lang"]>description</description>]*

  [<display-name [xml:lang="lang"]>displayName</display-name>]*

  [<icon [xml:lang="lang"]>

    [<small-icon>iconPath</small-icon>]

    [<large-icon>iconPath</large-icon>]

   </icon>]*

  <service-ref-name>serviceRefName</service-ref-name>

  <service-interface>jaxrpcInterfaceName</service-interface>

  [<wsdl-file>wsdlFilePath</wsdl-file>]

  [<jaxrpc-mapping-file>mappingFilePath</jaxrpc-mapping-file>]

  [<service-qname>wdslQName</service-qname>]

  [<port-component-ref>portComponentRef</port-component-ref>]*

  [<handler>portComponentHandler</handler>]*

</service-ref>

See the Servlet 2.4 and J2EE 1.4 web services specifications for details on how to use this element.

<message-destination-ref>

The <message-destination-ref> element declares a JMS message destination reference used by the application.

Syntax

<message-destination-ref>

  [<description [xml:lang="lang"]>description</description>]*

  <message-destination-ref-name>refName</message-destination-ref-name>

  <message-destination-type>typeName</message-destination-type>

  <message-destination-usage>

    Consumes|Produces|ConsumesProduces

  </message-destination-usage>

  [<message-destination-link>linkedDestName</message-destination-link>]

</message-destination-ref>

See the Servlet 2.4 and J2EE 1.4 messaging specifications for details on how to use this element.

<message-destination>

The <message-destination> element declares a logical name for a JMS message destination used by the application.

Syntax

<message-destination>

  [<description [xml:lang="lang"]>description</description>]*

  [<display-name [xml:lang="lang"]>displayName</display-name>]*

  [<icon [xml:lang="lang"]>

    [<small-icon>iconPath</small-icon>]

    [<large-icon>iconPath</large-icon>]

   </icon>]*

  <message-destination-name>destName</message-destination-name>

</message-destination>

See the Servlet 2.4 and J2EE 1.4 messaging specifications for details on how to use this element.

F.2.1 Example Application Deployment Descriptor

Example F-3 shows an example of a deployment descriptor (web.xml) file with the most common declarations needed for a JSF- application.

Example F-3. Example deployment descriptor file
<?xml version="1.0" encoding="ISO-8859-1"?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"

  xmlns:xsi="http://www.w3c.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>



  <context-param>

    <param-name>javax.faces.STATE_SAVING_METHOD</param-name>

    <param-value>client</param-value>

  </context-param>



  <servlet>

    <servlet-name>facesServlet</servlet-name>

    <servlet-class>

      javax.faces.webapp.FacesServlet

    </servlet-class>

  </servlet>



  <servlet-mapping>

    <servlet-name>facesServlet</servlet-name>

    <url-pattern>*.faces</url-pattern>

  </servlet-mapping>

</web-app>

At the top of the file, you find a standard XML declaration and the <web-app> element, with the reference to the deployment descriptor schema. Next comes a <context-param> element that tells JSF to save state in the client. The <servlet> element maps the JSF servlet class to a name, and the <servlet-mapping> element maps the servlet to the recommended *.faces extension pattern.

    Previous Section  < Day Day Up >  Next Section