|
|
|
|
|
|
| | | |
Writing Web Application Deployment Descriptors
The following sections describe how to write Web Application deployment descriptors:
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 and 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:
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
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:
<!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.
<!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 </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.
Step 5: Define context parameters
The context-param element declares servlet context initialization parameters for a Web Application. These are parameters that you define that and are 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.
The weblogic.http.clientCertProxy context parameter specifies to trust client certificates in the WL-Proxy-Client-Cert header. In previous releases of WebLogic Server, the client certificates in the WL-Proxy-Client-Cert header were trusted by default.
|
<context-param> |
For more information, see context-param Element. |
|
<param-name> |
(Required) |
|
<param-value> |
(Required) |
|
<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 Element. |
|
<icon> <small-icon> <large-icon> </icon> |
(Optional) |
|
<filter-name> |
(Required) |
|
<display-name> |
(Optional) |
|
<description> |
(Optional) |
|
<filter-class> |
(Required) |
|
<init-param> |
(Optional) |
|
<param-name> |
(Required) |
|
<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 Element. |
|
<filter-name> |
(Required) |
|
<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 Element. |
|
<listener-class> |
(Required) |
|
</listener> |
|
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 Element. |
|
<servlet-name> |
(Required) |
|
<servlet-class> |
(Required) |
|
<init-param> |
(Optional) For more information, see init-param Element. |
|
<param-name> |
(Required) |
|
<param-value> |
(Required) |
|
<description> </init-param> |
(Optional) |
|
<load-on-startup> |
(Optional) |
|
<security-role-ref> |
(Optional). For more information, see security-role-ref Element. |
|
<description> |
(Optional) |
|
<role-name> |
(Required) |
|
<role-link> |
(Required) |
|
</security-role-ref> |
|
|
<small-icon> |
(Optional) |
|
<large-icon> |
(Optional) |
|
<display-name> |
(Optional) |
|
<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 Element. |
|
<servlet-name> |
(Required) |
|
<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> |
For more information, see session-config Element. |
|
</session-config> |
|
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 Element. |
|
<extension> |
|
|
<mime-type> |
|
|
</mime-mapping> |
|
For more information, see Configuring Welcome Pages
|
<welcome-file-list> |
(Welcome pages are Optional.) |
|
<welcome-file> <welcome-file> |
See also Configuring Welcome Pagesand How WebLogic Server Resolves HTTP Requests. |
|
</welcome-file-list> |
|
For more information, see Customizing HTTP Error Responses
|
<error-page> |
(Optional) Define a customized page to respond to errors.
|
|
<error-code>
|
|
|
<exception-type> |
|
|
<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 Element. |
|
<taglib-uri> |
(Required) |
|
<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 External Resources in a Web Application.
|
<resource-ref> |
(Optional) |
|
<res-ref-name> |
(Required) |
|
<res-type> |
(Required) |
|
<res-auth> |
(Required) |
|
<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:
For more information, see Restricting Access to Resources in a Web Application.
|
<security-constraint> |
(Optional) For more information, see security-constraint Element. |
|
<web-resource-collection> |
(Required) For more information, see web-resource-collection Element. |
|
<web-resource-name> |
(Required) |
|
<description> |
(Optional) |
|
<url-pattern> |
(Optional) |
|
<http-method> |
(Optional) |
|
</web-resource-collection> |
|
|
<auth-constraint> |
(Optional) For more information, see auth-constraint Element. |
|
<role-name> |
(Optional) |
|
</auth-constraint> |
|
|
<user-data-constraint> |
(Optional) For more information, see user-data-constraint Element. |
|
<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 Element. |
|
<auth-method> |
(Optional) Specifies the method used to authenticate the user. |
|
<realm-name> |
(Optional) For more information, see Specifying a Security Realm. |
|
<form-login-config> |
(Optional) For more information, see form-login-config Element. Use this element if you configure the <auth-method> to FORM. |
|
<form-login-page> |
(Required) |
|
<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 Element. |
|
<description> |
(Optional) |
|
<role-name> |
(Required) |
|
</security-role> |
|
Step 20: Set environment entries
For more information, see Configuring External Resources in a Web Application.
|
<env-entry> |
(Optional) For more information, see env-entry Element. |
|
<description> |
(Optional) |
|
<env-entry-name> |
(Required) |
|
<env-entry-value> |
(Required) |
|
<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 Element. |
|
<description> |
(Optional) |
|
<ejb-ref-name> |
(Required) |
|
<ejb-ref-type> |
(Required) |
|
<home> |
(Required) |
|
<remote> |
(Required) |
|
<ejb-link> |
(Optional) |
|
<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
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.
Step 2: Map security role names to a security realm
|
<security-role-assignment> |
|
|
<role-name> |
(Required) For more information, see security-role-assignment Element. |
|
<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 Element. |
|
<resource-description> |
For more information, see resource-description Element. |
|
<res-ref-name> |
(Required) |
|
<jndi-name> |
(Required) |
|
</resource-description> |
|
|
<ejb-reference- |
|
|
<ejb-ref-name> |
(Required) For more information, see ejb-reference-description Element. |
|
<jndi-name> |
(Required) |
|
</ejb-reference- |
|
|
</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 session-descriptor Element
|
<session-descriptor> |
For more information, see session-descriptor Element. |
|
<session-param> |
|
|
<param-name> |
|
|
<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 Element
|
<jsp-descriptor> |
For more information, see jsp-descriptor Element. |
|
<jsp-param> |
|
|
<param-name> |
|
|
<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 container-descriptor Element. |
|
<check-auth-on-forward/> |
|
|
<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 charset-params Element. |
|
<input-charset> |
|
|
<resource-path> |
|
|
<java-charset-name> |
|
|
</input-charset> |
|
|
<charset-mapping> |
|
|
<iana-charset-name> |
|
|
<java-charset-name> |
|
|
</charset-mapping> |
|
|
</charset-params> |
|
Step 8: Complete the descriptor file.
Close the desciptor file with the following tag:
|
</weblogic-web-app> |
|
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|