bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Assembling and Configuring Web Applications

Writing Web Application Deployment Descriptors

The following sections describe how to write Web Application deployment descriptors:

- Overview of Web Application Deployment Descriptors

- Tools for Editing Deployment Descriptors

- Writing the web.xml Deployment Descriptor

- Sample web.xml

- Writing the WebLogic-Specific Deployment Descriptor (weblogic.xml)

Overview of Web Application Deployment Descriptors

WebLogic Server uses the standard J2EE web.xml deployment descriptor for defining a Web Application. Some applications also require the WebLogic-specific deployment descriptor, weblogic.xml. You use these deployment descriptors to define components and operating parameters for a Web Application. Deployment descriptors are standard text files, formatted using XML notation. You package them in the Web Application. For more information on Web Applications, see Web Applications Basics.

The deployment descriptor web.xml is defined by the Servlet 2.3 specification from Sun Microsystems. This deployment descriptor can be used to deploy a Web Application on any J2EE-compliant application server.

The deployment descriptor weblogic.xml defines deployment properties that are specific to a Web Application running on WebLogic Server. weblogic.xml is not required for all Web Applications.

Tools for Editing Deployment Descriptors

To edit a deployment descriptor, you can use one of several tools:

- Use the deployment descriptor editor that is integrated into the WebLogic Server Administration Console. For more information, see Web Application Deployment Descriptor Editor Help.

- Use any plain text editor, for example Windows Notepad, emacs, vi, or your favorite IDE.

- Use WebLogic Builder, a graphic tool for generating and editing deployment descriptors for applications to be deployed on WebLogic Server. See WebLogic Builder Online Help.

- The WebLogic XML editor can be used on Windows or Solaris machines and is downloadable from BEA's Dev2Dev Online.

- You can use the Ant utilities to create skeleton deployment descriptors. The Ant task looks at a directory containing a Web Application and creates deployment descriptors based on the files it finds in the Web Application. Since the Ant tasks do not know all of the desired configurations, mappings, and other information, the skeleton deployment descriptors it creates are incomplete. You can then use a text editor, an XML editor, or the Administration Console to complete configuration of your Web Application using the deployment descriptors.

  For more information, see Packaging Web Applications.

Writing the web.xml Deployment Descriptor

This section describes the steps to create the web.xml deployment descriptor. Depending on the components in your Web application, you may not need to include all of the elements listed here to configure and deploy your Web application.

The elements in the web.xml file must be entered in the order they are presented in this document.

Main Steps to Create the web.xml File

- Step 1: Create a deployment descriptor file

- Step 2: Create the DOCTYPE Statement

- Step 3: Create the main body of the web.xml file

- Step 4: Define deployment-time attributes

- Step 5: Define context parameters

- Step 6: Configure Filters (Servlet 2.3 specification only)

- Step 7: Define Filter Mappings (Servlet 2.3 specification only)

- Step 8: Configure Application Listeners (Servlet 2.3 specification only)

- Step 9: Deploy Servlets

- Step 10: Map a servlet to a URL

- Step 11: Define the session timeout value

- Step 12: Define MIME mapping

- Step 13: Define welcome pages

- Step 14: Define error pages

- Step 15: Define a JSP tag library descriptor

- Step 16: Reference external resources

- Step 17: Set up security constraints

- Step 18: Set up login authentication

- Step 19: Define security roles

- Step 20: Set environment entries

- Step 21: Reference Enterprise JavaBean (EJB) resources

If you have installed the WebLogic Server samples and examples, you can look at the web.xml and weblogic.xml files in the Pet Store sample to see a working example of Web application deployment descriptors. These files are located in the /samples/PetStore/source/dd/war/WEB-INF directory of your WebLogic Server distribution.

Detailed Steps to Create the web.xml File

Step 1: Create a deployment descriptor file

Name the file web.xml and place it under the WEB-INF directory of the Web application. Use any text editor.

Step 2: Create the DOCTYPE Statement

The DOCTYPE statement refers to the location and version of the Document Type Definition (DTD) file for the deployment descriptor. Although this header references an external URL at java.sun.com, WebLogic Server contains its own copy of the DTD file, so your host server need not have access to the Internet. However, you must still include this <!DOCTYPE...> element in your web.xml file, and have it reference the external URL because the version of the DTD contained in this element is used to identify the version of this deployment descriptor.

Use one of the following DOCTYPE statements:

- If you are using any of the features of the Servlet 2.3 Specification, such as Filters or Application Events, use the following DOCTYPE statement:

  >     <!DOCTYPE web-app PUBLIC
  >      "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
  >      "http://java.sun.com/dtd/web-app_2_3.dtd">

  Note: The implementation of version 2.3 of the Servlet Specification is based on the Proposed Final Draft 1 of the servlet specification and is subject to change. If you are planning to use features introduced in version 2.3, note that the specification has not been finalized and could change in the future. Features added with Proposed Final Draft 2 are not supported.

- If you do not need to use features of the Servlet 2.3 specification, use the following DOCTYPE statement:

  >     <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//
  >     DTD WebApplication 2.2//EN"
  >     "http://java.sun.com/j2ee/dtds/web-app_2.2.dtd">

Step 3: Create the main body of the web.xml file

Wrap all of your entries within a pair of opening and closing <web-app> tags.

####

<web-app> All elements describing this Web application go within the <web-app> element. </web-app> |

In XML, properties are defined by surrounding a property name or value with opening and closing tags as shown above. The opening tag, the body (the property name or value), and the closing tag are collectively called an element. Some elements do not use the surrounding tags, but instead use a single tag that contains attributes called an empty-tag. Elements contained within other elements are indented in this text for clarity. Indenting is not necessary in an XML file.

The body of the <web-app> element itself contains additional elements that determine how the Web application will run on WebLogic Server. The order of the tag elements within the file must follow the order reflected in this document. This ordering is defined in the Document Type Definition (DTD) file.

Step 4: Define deployment-time attributes

These tags provide information for the deployment tools or the application server resource management tools. These values are not used by WebLogic Server in this release.

####

<icon> | (Optional)
<small-icon> iconfile.gif(jpg) </small-icon> | (Optional)
<large-icon> iconfile.gif(jpg) </large-icon> | (Optional)
</icon> |
<display-name> application-name </display-name> | (Optional)
<description> descriptive-text </description> | (Optional)
<distributable/> | (Optional)

Step 5: Define context parameters

The context-param element declares servlet context initialization parameters for a Web Application. These are parameters that you define to be available throughout your Web application. You set each context-param within a single context-param element, using <param-name> and <param-value> elements. You can access these parameters in your code using the javax.servlet.ServletContext.getInitParameter() and javax.servlet.ServletContext.getInitParameterNames() methods.

####

<context-param> | For more information, see context-param.
<param-name> user-defined param name </param-name> | (Required)
<param-value> user-defined value </param-value> | (Required)
<description text description </description> | (Optional)
</context-param> |

Step 6: Configure Filters (Servlet 2.3 specification only)

Each filter has a name and a filter class. (For more information on filters, see Configuring Filters). A filter can also use initialization parameters. The following elements define a filter:

####

<filter> | For more information, see filter
<icon> <small-icon> iconfile </small-icon> <large-icon> iconfile </large-icon> </icon> | (Optional)
<filter-name> Filter name </filter-name> | (Required)
<display-name> Filter Display Name </display-name> | (Optional)
<description> ...text... </description> | (Optional)
<filter-class> package.name.MyFilterClass </filter-class> | (Required)
<init-param> | (Optional)
<param-name> name </param-name> | (Required)
<param-value> value </param-value> | (Required)
</init-param> | (Optional)
</filter> |

Step 7: Define Filter Mappings (Servlet 2.3 specification only)

After you have declared a filter, map each filter to a URL pattern:

####

<filter-mapping> | For more information, see filter-mapping.
<filter-name> name </filter-name> | (Required)
<url-pattern> pattern </url-pattern> | (Required)
</filter-mapping> |

Step 8: Configure Application Listeners (Servlet 2.3 specification only)

Configure Web Application event listeners using a separate <listener> element for each listener class:

For more information, see

####

<listener> | For more information, see listener.
<listener-class> my.foo.listener </listener-class> | (Required)
</listener> |

Application Events and Listeners.

Step 9: Deploy Servlets

To deploy a servlet, give the servlet a name, specify the class file or JSP used to implement its behavior, and set other servlet-specific properties. List each servlet in your Web application within separate <servlet>...</servlet> elements. After you create entries for all your servlets, you must include elements that map the servlet to a URL pattern. These mapping elements are described in Step 10: Map a servlet to a URL.

For more information, see Configuring Servlets

Use the following elements to declare a servlet:

####

<servlet> | For more information, see servlet
<servlet-name> name </servlet-name> | (Required)
<servlet-class> package.name.MyClass </servlet-class> -or- <jsp-file> /foo/bar/myFile.jsp </jsp-file> | (Required)
<init-param> | (Optional) For more information, see init-param
<param-name> name </param-name> | (Required)
<param-value> value </param-value> | (Required)
<description> ...text... </description> </init-param> | (Optional)
<load-on-startup> loadOrder </load-on-startup> | (Optional)
<security-role-ref> | (Optional). For more information, see security-role-ref
<description> ...text... </description> | (Optional)
<role-name> rolename </role-name> | (Required)
<role-link> rolelink </role-link> | (Required)
</security-role-ref> |
<small-icon> iconfile </small-icon> | (Optional)
<large-icon> iconfile </large-icon> | (Optional)
<display-name> Servlet Name </display-name> | (Optional)
<description> ...text... </description> | (Optional)
</servlet> |

Here is an example of a servlet element that includes an initialization parameter.

>     <servlet>
>        ...
>        <init-param>
>            <param-name>feedbackEmail</param-name>
>            <param-value>feedback123@beasys.com</param-value>
>            <description>
>              The email for web-site feedback.
>            </description>
>        </init-param>
>        ...
>        </servlet>

Step 10: Map a servlet to a URL

Once you declare your servlet or JSP using a <servlet> element, map it to one or more URL patterns to make it a public HTTP resource. The use of URL patterns is defined in the Servlet 2.3 specification from Sun Microsystems. For each mapping, use a <servlet-mapping> element.

####

<servlet-mapping> | For more information, see servlet-mapping
<servlet-name> name </servlet-name> | (Required)
<servlet-name> pattern </url-pattern> | (Required)
</servlet-mapping> |

Here is an example of a <servlet-mapping> for the <servlet> declaration example used earlier:

>     <servlet-mapping>
>       <servlet-name>LoginServlet</servlet-name>
>       <url-pattern>/login</url-pattern>
>     </servlet-mapping>

Step 11: Define the session timeout value

####

<session-config> | (Optional)
<session-timeout> minutes </session-timeout> | For more information, see session-config
</session-config> |

Step 12: Define MIME mapping

To create a MIME mapping, you map a file extension to a MIME type.

####

<mime-mapping> | (Optional) Define MIME types. For more information, see mime-mapping
<extension> ext </extension> |
<mime-type> mime type </mime-type> |
</mime-mapping> |

Step 13: Define welcome pages

For more information, see Configuring Welcome Pages

####

<welcome-file-list> | (Welcome pages are Optional.) For more information, see welcome-file-list
<welcome-file> myWelcomeFile.jsp </welcome-file> <welcome-file> myWelcomeFile.html </welcome-file> | See also Configuring Welcome Pagesand How WebLogic Server Resolves HTTP Requests.
</welcome-file-list> |

.

Step 14: Define error pages

For more information, see Customizing HTTP Error Responses

####

<error-page> | (Optional) Define a customized page to respond to errors. For more information, see error-pageand How WebLogic Server Resolves HTTP Requests.
<error-code> HTTP error code </error-code> -or- |
<exception-type> Java exception class </exception-type> |
<location> URL </location> |
</error-page> |

.

Step 15: Define a JSP tag library descriptor

For more information, see Configuring JSP Tag Libraries

####

<taglib> | (Optional) Identify JSP tag libraries. For more information, see taglib.
<taglib-uri> string_pattern </taglib-uri> | (Required)
<taglib-location> filename </taglib-location> | (Required)
</taglib> |

The following is an example of a taglib directive used in a JSP:

>     <%@ taglib uri="string_pattern" prefix="taglib" %>

For more details, see Programming WebLogic JSP Tag Extensions.

Step 16: Reference external resources

For more information, see Configuring Resources in a Web Application.

####

<resource-ref> | (Optional) For more information, see resource-ref.
<res-ref-name> name </res-ref-name> | (Required)
<res-type> Java class </res-type> | (Required)
<res-auth> CONTAINER | SERVLET </res-auth> | (Required)
<res-sharing-scope> Sharable | Unsharable </res-sharing-scope> | (Optional)
</resource-ref> | (Required)

Step 17: Set up security constraints

A Web application that uses security requires the user to log in in order to access its resources. The user's credentials are verified against a security realm, and once authorized, the user will have access only to specified resources within the Web application.

Security in a Web application is configured using three elements:

- The <login-config> element specifies how the user is prompted to log in and the location of the security realm. If this element is present, the user must be authenticated in order to access any resource that is constrained by a <security-constraint> defined in the Web application.

- A <security-constraint> is used to define the access privileges to a collection of resources via their URL mapping.

- A <security-role> element represents a group or principal in the realm. This security role name is used in the <security-constraint> element and can be linked to an alternative role name used in servlet code via the <security-role-ref> element.

For more information, see Restricting Access to Resources in a Web Application.

####

<security-constraint> | (Optional) For more information, see security-constraint.
<web-resource-collection> | (Required) For more information, see web-resource-collection.
<web-resource-name> name </web-resource-name> | (Required)
<description> ...text... </description> | (Optional)
<url-pattern> pattern </url-pattern> | (Optional)
<http-method> GET | POST </http-method> | (Optional)
</web-resource-collection> |
<auth-constraint> | (Optional) For more information, see auth-constraint.
<role-name> group | principal </role-name> | (Optional)
</auth-constraint> |
<user-data-constraint> | (Optional) For more information, see user-data-constraint
<description> ...text... </description> | (Optional)
<transport-guarantee> NONE|INTEGRAL|CONFIDENTIAL </transport-guarantee> | (Required)
</user-data-constraint> |
</security-constraint> |

Step 18: Set up login authentication

For more information, see Setting Up Authentication for Web Applications.

####

<login-config> | (Optional) For more information, see login-config.
<auth-method> BASIC|FORM|CLIENT-CERT </auth-method> | (Optional) Specifies the method used to authenticate the user.
<realm-name> realmname </realm-name> | (Optional) For more information, see Managing WebLogic Sercurity.
<form-login-config> | (Optional) For more information, see form-login-config. Use this element if you configure the <auth-method> to FORM.
<form-login-page> URI </form-login-page> | (Required)
<form-error-page> URI </form-error-page> </form-login-config> | (Required)
</login-config> |

Step 19: Define security roles

For more information, see Configuring Security in Web Applications

####

<security-role> | (Optional) For more information, see security-role
<description> ...text... </description> | (Optional)
<role-name> rolename </role-name> | (Required)
</security-role> |

Step 20: Set environment entries

For more information, see Configuring Resources in a Web Application.

####

<env-entry> | (Optional) For more information, see env-entry.
<description> ...text... </description> | (Optional)
<env-entry-name> name </env-entry-name> | (Required)
<env-entry-value> value </env-entry-value> | (Required)
<env-entry-type> type </env-entry-type> | (Required)
</env-entry> |

Step 21: Reference Enterprise JavaBean (EJB) resources

For more information, see Referencing EJBs in a Web Application.

####

<ejb-ref> | Optional) For more information, see ejb-ref.
<description> ...text... </description> | (Optional)
<ejb-ref-name> name </ejb-ref-name> | (Required)
<ejb-ref-type> Java type </ejb-ref-type> | (Required)
<home> mycom.ejb.AccountHome </home> | (Required)
<remote> mycom.ejb.Account </remote> | (Required)
<ejb-link> ejb.name </ejb-link> | (Optional)
<run-as> security role </run-as> | (Optional)
</ejb-ref> | (Required)

Sample web.xml

Listing 8-1 Sample web.xml with Servlet Mapping, Welcome file, and Error Page

>     <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//
>     DTD Web Application 1.2//EN"
>     "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

>     <web-app>

>     <!-- The following servlet element defines a servlet called servletA.
>      The Java class of this servlet is servlets.servletA -->
>       <servlet>
>         <servlet-name>servletA</servlet-name>
>         <servlet-class>servlets.servletA</servlet-class>
>       </servlet>

>     <!-- The following servlet element defines another servlet called
>      servletB. The Java class of this servlet is servlets.servletB -->
>       <servlet>
>         <servlet-name>servletB</servlet-name>
>         <servlet-class>servlets.servletB</servlet-class>
>       </servlet>

>     <!-- The following servlet-mapping maps the servlet called servletA
>      (see the servlet element) to a url-pattern of "blue".
>      The url-pattern is used when requesting this servlet, for example:
>      http://host:port/myWebApp/blue. -->
>       <servlet-mapping>
>         <servlet-name>servletA</servlet-name>
>         <url-pattern>blue</url-pattern>
>       </servlet-mapping>

>     <!-- The following servlet-mapping maps the servlet called servletB
>      (see the servlet element) to a url-pattern of "yellow".
>      The url-pattern is used when requesting this servlet, for example:
>      http://host:port/myWebApp/yellow. -->
>       <servlet-mapping>
>         <servlet-name>servletB</servlet-name>
>         <url-pattern>yellow</url-pattern>
>       </servlet-mapping>

>     <!--The following welcome-file-list specifies a welcome-file.
>      Welcome files are discussed elsewhere in this document-->
>       <welcome-file-list>
>         <welcome-file>hello.html</welcome-file>
>       </welcome-file-list>

>     <!--The following error-page element specifies a page that is served
>      in place of the standard HTTP error response pages, in this case
>      HTTP error 404.-->
>       <error-page>
>         <error-code>404</error-code>
>         <location>/error.jsp</location>
>       </error-page>

>     </web-app>

Writing the WebLogic-Specific Deployment Descriptor (weblogic.xml)

The weblogic.xml file contains WebLogic-specific attributes for a Web application. You define the following attributes in this file: HTTP session parameters, HTTP cookie parameters, JSP parameters, resource references, security role assignments, character set mappings, and container attributes.

If you define external resources such as DataSources, EJBs, or a Security realm in the web.xml deployment descriptor, you can use any descriptive name to define the resource. To access the resource, you then map this resource name to the actual name of the resource in the JNDI tree using a file called weblogic.xml. Place this file in the WEB-INF directory of your Web application.

If you have installed the WebLogic Server samples and examples, you can look at the web.xml and weblogic.xml files in the Pet Store sample to see a working example of Web application deployment descriptors. These files are located in the /samples/PetStore/source/dd/war/WEB-INF directory of your WebLogic Server distribution.

The ordering of the tag elements within the weblogic.xml file must follow the ordering specified in this document.

Main Steps to Create the weblogic.xml File

- Step 1: Begin the weblogic.xml file with a DOCTYPE header

- Step 2: Map security role names to a security realm

- Step 3 Map resources to JNDI

- Step 4: Define session parameters

- Step 5: Define JSP parameters

- Step 6: Define container parameters

- Step 7: Define character set parameters

- Step 8: Complete the descriptor file

Detailed Steps to Create the weblogic.xml File

Step 1: Begin the weblogic.xml file with a DOCTYPE header

This header refers to the location and version of the DTD file for the deployment descriptor. Although this header references an external URL at www.beasys.com, WebLogic Server has its own copy of the DTD file, so your host server need not have access to the Internet. However, you must still include this DOCTYPE element in your weblogic.xml file, and have it reference the external URL since the version of the DTD is used to identify the version of this deployment descriptor.

####

<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 7.0//EN" "http://www.bea.com/servers/wls700/dtd/weblogic700-web-jar.dtd"> |
<weblogic-web-app> |
<description> Text description of the Web App </description> |
<weblogic-version> </weblogic-version> | This element is not used by WebLogic Server.

Step 2: Map security role names to a security realm

####

<security-role-assignment> |
<role-name> name </role-name> | (Required) For more information, see security-role-assignment.
<principal-name> name </principal-name> | (Required)
</security-role-assignment> |

If you need to define multiple roles, define each additional pair of <role-name> and <principal-name> tags within separate <security-role-assignment> elements.

Step 3 Map resources to JNDI

In this step you map resources used in your Web application to the JNDI tree. When you define an <ejb-ref-name> or a <res-ref-name> in the web.xml deployment descriptor, you also reference those names in weblogic.xml and map them to an actual JNDI name that is available in WebLogic Server. In the following example, a Data Source is referenced in a servlet with the name myDataSource. myDataSource is then referenced in web.xml and its data type defined. Finally, in the weblogic.xml file, myDataSource is mapped to the JNDI name accountDataSource, which is available in the JNDI tree. The JNDI name must match the name of an object bound in the JNDI tree. Objects can be bound to the JNDI tree programatically or by configuring them in the Administration Console. For more information, see Programming WebLogic JNDI.

Servlet code:

javax.sql.DataSource ds = (javax.sql.DataSource) ctx.lookup
("myDataSource");

web.xml entries:

<resource-ref>
. . .
<res-ref-name>myDataSource</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>CONTAINER</res-auth>
. . .
</resource-ref>

weblogic.xml entries:

<resource-description>
<res-ref-name>myDataSource</res-ref-name>
<jndi-name>accountDataSource</jndi-name>
</security-role-ref>

A similar pattern is used to map EJBs to the JNDI tree, but uses the <ejb-ref-name> element of the <ejb-reference-description> element in place of the <res-ref-name> element of the <resource-description> element.

####

<reference-descriptor> | For more information, see reference-descriptor.
<resource-description> | For more information, see resource-description.
<res-ref-name> name </res-ref-name> | (Required)
<jndi-name> JNDI name of resource </jndi-name> | (Required)
</resource-description> |
<ejb-reference- description> |
<ejb-ref-name> name </ejb-ref-name> | (Required) For more information, see ejb-reference-description
<jndi-name> JNDI name of EJB </jndi-name> | (Required)
</ejb-reference- description> |
</reference-descriptor> |

Step 4: Define session parameters

You define HTTP session parameters for this Web application inside of <session-param> tags, which are nested inside <session-descriptor> tags. For each <session-param> you need to supply a <param-name>...</param-name> element that names the parameter being defined and a <param-value>...</param-value> element that provides the value of the parameter. For a list of HTTP session parameters and details on setting them, see jsp-descriptor

####

<session-descriptor> | For more information, see jsp-descriptor.
<session-param> |
<param-name> session param name </param-name> |
<param-value> my value </param-value> |
</session-param> |
</session-descriptor> |

.

Step 5: Define JSP parameters

You define JSP configuration parameters for this Web application inside of <jsp-param> tags, which are nested in side <jsp-descriptor> tags. For each <jsp-param> you need to supply a <param-name>...</param-name> element that names the parameter being defined and a <param-value>...</param-value> element that provides the value of the parameter. For a list of JSP parameters and details on setting them, see jsp-descriptor

####

<jsp-descriptor> | For more information, see jsp-descriptor.
<jsp-param> |
<param-name> jsp param name </param-name> |
<param-value> my value </param-value> |
</jsp-param> |
</jsp-descriptor> |

.

Step 6: Define container parameters

There is one valid, optional element you can enter in the <container-descriptor> element, the <check-auth-on-forward> element.

####

<container-descriptor> | For more information, see resolve indicates the action..
<check-auth-on-forward/> |
<redirect-with-absolute-url> true|false </redirect-with-absolute-url> |
</container-descriptor> |

Step 7: Define character set parameters

The optional <charset-params> element is used to define character set mappings.

####

<charset-params> | For more information, see resolve indicates the action..
<input-charset> |
<resource-path> path to match </resource-path> |
<java-charset-name> name of Java character set </java-charset-name> |
</input-charset> |
<charset-mapping> |
<iana-charset-name> name of IANA character set </iana-charset-name> |
<java-charset-name> name of Java character set </java-charset-name> |
</charset-mapping> |
</charset-params> |

Step 8: Complete the descriptor file

Close the desciptor file with the following tag:

####

</weblogic-web-app> |