Академический Документы
Профессиональный Документы
Культура Документы
Server
Copyright
Copyright 2003-2005 BEA Systems, Inc. All Rights Reserved.
Contents
Ant Tasks to Create Skeleton Deployment Descriptors. . . . . . . . . . . . . . . . . . . . . . . 1-9 XML Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 appc Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 appc Syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 appc Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 wlappc Ant Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Web Application Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
vi
Configuring Java Server Pages (JSPs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Registering a JSP as a Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6 Configuring JSP Tag Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Configuring Welcome Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Setting Up a Default Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Customizing HTTP Error Responses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Using CGI with WebLogic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Configuring WebLogic Server to Use CGI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Requesting a CGI Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 CGI Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Serving Resources from the CLASSPATH with the ClasspathServlet . . . . . . . . . . . . . . 3-12 Configuring Resources in a Web Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12 Configuring External Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13 Referencing External EJBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 More about the ejb-ref* Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 Referencing Application-Scoped EJBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 Loading Servlets, Context Listeners, and Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18 Determining the Encoding of an HTTP Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 Mapping IANA Character Sets to Java Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
vii
Configuring Session Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 Attributes Shared by Different Types of Session Persistence . . . . . . . . . . . . . . . . . . 4-4 Using Memory-based, Single-server, Non-replicated Persistent Storage . . . . . . . . . 4-5 Using File-based Persistent Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5 Using a Database for Persistent Storage (JDBC persistence) . . . . . . . . . . . . . . . . . . 4-6 Using Cookie-Based Session Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 Using URL Rewriting Instead of Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 Coding Guidelines for URL Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10 URL Rewriting and Wireless Access Protocol (WAP) . . . . . . . . . . . . . . . . . . . . . . 4-11
6. Filters
Overview of Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1 How Filters Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Uses for Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Writing a Filter Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2 Configuring Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 Configuring a Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
viii
Configuring a Chain of Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Filtering the Servlet Response Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5 Additional Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
ix
user-data-constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-18 login-config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19 form-login-config. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-19 security-role. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20 env-entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-20 ejb-ref . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ejb-local-refA-22
single-threaded-servlet-pool-size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-17 session-monitoring-enabled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-17 save-sessions-enabled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-17 prefer-web-inf-classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-17 default-mime-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-17 retain-original-url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18 charset-params . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18 input-charset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-18 charset-mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19 virtual-directory-mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-19 url-match-map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-20 preprocessor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21 preprocessor-mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-21 security-permission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-22 context-root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-22 wl-dispatch-policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-23 servlet-descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-23 init-as . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-24 destroy-as. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-24
xi
xii
This document describes how to assemble and configure J2EE Web applications. The document is organized as follows: Chapter 1, Web Applications Basics, is an overview of using Web applications in WebLogic Server. Chapter 2, Deploying Web Applications,discusses Web application deployment. Chapter 3, Configuring Web Application Components,describes how to configure Web application components. Chapter 4, Using Sessions and Session Persistence in Web Applications, describes how to use HTTP sessions and session persistence in a Web application. Chapter 5, Application Events and Event Listener Classes, describes how to use J2EE event listeners in a Web application. Chapter 6, Filters,describes how to use filters in a Web application. Appendix A, web.xml Deployment Descriptor Elements, provides a reference of deployment descriptor elements for the web.xml deployment descriptor. Appendix B, weblogic.xml Deployment Descriptor Elements, provides a reference of deployment descriptor elements for the weblogic.xml deployment descriptor.
xiii
Audience
This document is written for application developers who want to build e-commerce applications using the Java 2 Platform, Enterprise Edition (J2EE) from Sun Microsystems. It is assumed that readers know Web technologies, object-oriented programming techniques, and the Java programming language.
Related Information
The BEA corporate Web site provides all documentation for WebLogic Server. The following WebLogic Server documents contain information that is relevant to creating WebLogic Server application components: Programming WebLogic HTTP Servlets Programming WebLogic Java Server Pages (JSPs) Programming WebLogic Web Services Developing WebLogic Server Applications Deploying WebLogic Server Applications
xiv
For more information in general about Java application development, refer to the Sun Microsystems, Inc. Java 2, Enterprise Edition Web Site at http://java.sun.com/products/j2ee/.
Contact Us!
Your feedback on BEA documentation is important to us. Send us e-mail at docsupport@bea.com if you have questions or comments. Your comments will be reviewed directly by the BEA professionals who create and update the documentation. In your e-mail message, please indicate the software name and version you are using, as well as the title and document date of your documentation. If you have any questions about this version of BEA WebLogic Server, or if you have problems installing and running BEA WebLogic Server, contact BEA Customer Support through BEA WebSupport at http://www.bea.com. You can also contact Customer Support by using the contact information provided on the Customer Support Card, which is included in the product package. When contacting Customer Support, be prepared to provide the following information: Your name, e-mail address, phone number, and fax number Your company name and company address Your machine type and authorization codes The name and version of the product you are using A description of the problem and the content of pertinent error messages
Documentation Conventions
The following documentation conventions are used throughout this document. Convention
Ctrl+Tab italics
Usage
Keys you press simultaneously. Emphasis and book titles.
xv
Convention
monospace text
Usage
Code samples, commands and their options, Java classes, data types, directories, and file names and their extensions. Monospace text also indicates text that you enter from the keyboard. Examples:
import java.util.Enumeration; chmod u+w * samples/domains/examples/applications .java config.xml float
UPPERCASE TEXT
Device names, environment variables, and logical operators. Examples: LPT1 BEA_HOME OR
{ } [ ]
xvi
Convention
...
Usage
Indicates one of the following in a command line: An argument can be repeated several times in the command line. The statement omits additional optional arguments. You can enter additional attributes, values, or other information
. . .
Indicates the omission of items from a code example or from a syntax line.
xvii
xviii
C H A P T E R 1ti
The following sections provide an overview of WebLogic Server Web applications: How to Use This Book on page 1-1 Overview of Web Applications on page 1-1 Main Steps to Create a Web Application on page 1-5 URLs and Web Applications on page 1-8 Web Application Developer Tools on page 1-8 Web Application Security on page 1-10
1-1
application can also define links to outside resources such as Enterprise JavaBeans (EJBs). Web applications deployed on WebLogic Server use a standard J2EE deployment descriptor file and a WebLogic-specific deployment descriptor file to define their resources and operating attributes. JSPs and HTTP servlets can access all services and APIs available in WebLogic Server. These services include EJBs, database connections via Java Database Connectivity (JDBC), JavaMessaging Service (JMS), XML, and more. A Web archive (WAR file) contains the files that make up a Web application (WAR file). A WAR file is deployed as a unit on one or more WebLogic Server instances. A Web archive on WebLogic Server always includes the following files: One servlet or Java Server Page (JSP), along with any helper classes. A web.xml deployment descriptor, which is a J2EE standard XML document that describes the contents of a WAR file. A weblogic.xml deployment descriptor, which is an XML document containing WebLogic Server-specific elements for Web applications. A Web archive may also include HTML or XML pages and supporting files such as image and multimedia files. The WAR file can be deployed alone or packaged in an Enterprise application archive (EAR file) with other application components. If deployed alone, the archive must end with a .war extension. If deployed in an EAR file, the archive must end with an .ear extension. BEA recommends that you package and deploy your stand-alone Web applications as part of an Enterprise application. This is a BEA best practice, which allows for easier application migration, additions, and changes. Also, packaging your applications as part of an Enterprise application allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure. See Creating WebLogic Server Applications in Developing WebLogic Server Applications. Note: If you are deploying a directory in exploded format (not archived), do not name the directory .ear, .jar, and so on. For more information on archived format, see Web Application Directory Structure on page 1-3.
Servlets
Servlets are Java classes that execute in WebLogic Server, accept a request from a client, process it, and optionally return a response to the client. A GenericServlet is protocol independent and can be used in J2EE applications to implement services accessed from other Java classes. An
1-2 Developing Web Applications for WebLogic Server
HttpServlet extends GenericServlet with support for the HTTP protocol. An HttpServlet is most often used to generate dynamic Web pages in response to Web browser requests.
1-3
DefaultWebApp/
Place your static files, such as HTML files and JSP files in the directory that is the document root of your Web application. In the default installation of WebLogic Server, this directory is called DefaultWebApp, under user_domains/mydomain/applications. (To make your Web application the default Web application, you must set
context-root to "/" in the weblogic.xml deployment descriptor file.)
DefaultWebApp/WEB-INF/web.xml
The Web application deployment descriptor that configures the Web application.
DefaultWebApp/WEB-INF/weblogic.xml
The WebLogic-specific deployment descriptor file that defines how named resources in the web.xml file are mapped to resources residing elsewhere in WebLogic Server. This file is also used to define JSP and HTTP session attributes.
DefaultWebApp/WEB-INF/classes
Contains JAR files used by the Web application, including JSP tag libraries. The entire directory, once staged, is bundled into a WAR file using the jar command. The WAR file can be deployed alone or as part of an Enterprise application (recommended) with other application components, including other Web applications, EJB components, and WebLogic Server components. JSP pages and HTTP servlets can access all services and APIs available in WebLogic Server. These services include EJBs, database connections through Java Database Connectivity (JDBC), JavaMessaging Service (JMS), XML, and more.
1-4
The following is an example of a Web application directory structure, in which myWebApp/ is the staging directory:
On Windows NT, execute the setWLSEnv.cmd command, located in the directory server\bin\, where server is the top-level directory in which WebLogic Server is installed. On UNIX, execute the setWLSEnv.sh command, located in the directory server/bin/, where server is the top-level directory in which WebLogic Server is installed and domain refers to the name of your domain. 3. Package your Enterprise application in the \src\myEAR\ directory as follows: a. Place the Enterprise applications descriptors (application.xml and weblogic-application.xml) in the META-INF\ directory. See Enterprise Application Deployment Descriptors in Developing WebLogic Server Applications. You can automatically generate the Enterprise application descriptors using the DDInit Java utility by executing the following command:
java weblogic.marathon.ddinit.EarInit \myEAR
For more information on DDInit, see Using the WebLogic Server Java Utilities. b. Edit the deployment descriptors as needed to fine-tune the behavior of your Enterprise application. See Deployment Descriptors on page 2-2. c. Place the Enterprise application .jar files in:
\src\myEAR\APP-INF\lib\
2. Package your Web application in the \src\myEAR\myWebApp\ directory as follows: a. Place the Web application descriptors (web.xml and weblogic.xml) in the \src\myEAR\myWebApp\WEB-INF\ directory. See Appendix A, web.xml Deployment Descriptor Elements, and Appendix B, weblogic.xml Deployment Descriptor Elements. You can automatically generate the Web application descriptors using the DDInit utility by executing the following command:
java weblogic.marathon.ddinit.WebInit \myEAR\myWebApp
For more information on DDInit, see Using the WebLogic Server Java Utilities.
1-6
b. Edit the deployment descriptors as needed to fine-tune the behavior of your Enterprise application. See Deployment Descriptors on page 2-2. c. Place all HTML files, JSPs, images and any other files referenced by the Web application pages in the root of the Web application:
\src\myEAR\myWebApp\images\myimage.jpg \src\myEAR\myWebApp\login.jsp \src\myEAR\myWebApp\index.html
d. Place your Web application Java source files (servlets, tag libs, other classes referenced by servlets or tag libs) in:
\src\myEAR\myWebApp\WEB-INF\src\
Step Four: Execute the Split Development Directory Structure Ant Tasks
1. Execute the wlcompile Ant task to invoke the javac compiler. This compiles your Web application Java components into an output directory: /build/myEAR/WEB-INF/classes. See Creating WebLogic Server Applications in Developing WebLogic Server Applications. 2. Execute wlappc Ant task to invoke the appc compiler. This compiles any JSPs and container-specific EJB classes for deployment. See Creating WebLogic Server Applications in Developing WebLogic Server Applications. Also see appc Compiler on page 1-9. 3. Execute the wldeploy Ant task to deploy your Web application as part of an archived or exploded EAR to WebLogic Server. See Deployment Tools Reference in Deploying WebLogic Server Applications. 4. If this is a production environment (rather than development), execute the wlpackage Ant task to package your Web application as part of an archived or exploded EAR. See Creating WebLogic Server Applications in Developing WebLogic Server Applications. Note: The wlpackage Ant task places compiled versions of your Java source files in the build directory. For example: /build/myEAR/myWebApp/classes.
1-7
Where
hoststring
is the remaining portion of the URL, typically a file name. If you are using virtual hosting, you can substitute the virtual host name for the hoststring portion of the URL.
WebLogic Builder
WebLogic Builder is a graphical tool for assembling a J2EE application module; creating and editing its deployment descriptors; and deploying it to WebLogic Server. WebLogic Builder is a graphical environment in which you edit an applications deployment descriptor XML files. You can view these XML files as you edit them graphically in WebLogic Builder, but you wont need to make textual edits to the XML files. Use WebLogic Builder to do the following development tasks: Generate deployment descriptor files for a J2EE module Edit a modules deployment descriptor files Compile and validate deployment descriptor files Deploy a J2EE application to a server For more information on WebLogic Builder, see WebLogic Builder Online Help.
1-8
Web A pp l i c a t i o n D e v e l o p e r T o o l s
XML Editors
To create and edit XML files, you can use an XML Editor with DTD validation, such as BEA XML Editor on dev2dev or XMLSpy. (An evaluation copy of XMLSpy is bundled with this version of WebLogic Server.) See BEA dev2dev Online at http://dev2dev.bea.com/index.jsp.
appc Compiler
The appc compiler compiles and generates J2EE EAR files, EJB JAR files, and Web application WAR files for deployment. It also validates the descriptors for compliance with the current specifications at both the individual module level and the application level. The application level checks include checks between the application-level deployment descriptors and the individual modules as well as validation checks across the modules. The appc compiler reports any warnings or errors encountered in the descriptors. Finally, the appc compiler compiles all of the relevant modules into an EAR file, which can be deployed to WebLogic Server.
appc Syntax
Use the following syntax to run appc:
prompt>java weblogic.appc [options] <ear, jar, or war file or directory>
For example, to validate the descriptors in myWebApp.war, as well as compile the jsp files and update the WAR file with the resulting class files, you would execute the following command:
java weblogic.appc -keepgenerated myWebApp.war
1-9
appc Options
For a complete list of appc options, see "Compiling Java Code" in Developing WebLogic Server Applications.
For a complete list of wlappc options, see "Compiling Java Code" in Developing WebLogic Server Applications.
1-10
CHAPTER
This chapter discusses the deployment of Web applications: Deployment Overview on page 2-2 Deployment Descriptors on page 2-2 Deployment Options on page 2-5 Deployment Guidelines for Web Applications on page 2-6 WebLogic Server application deployment is covered in more detail in Deploying WebLogic Server Applications. This topics covered in this section explain only deployment procedures that are specific to Web applications.
2-1
Deployment Overview
Deployment of a Web application is similar to deployment of Connectors, EJBs, and Enterprise Applications. Like these deployment units, you can deploy a Web application in an exploded directory format or as an archive file. Note: For development and production purposes, BEA recommends that you deploy applications in exploded (unarchived) directory format. This applies also to stand-alone Web applications, EJBs, and connectors packaged as part of an Enterprise application. Using this format allows you to update files directly in the exploded directory rather than having to unarchive, edit, and rearchive the whole application. Using exploded archive directories also has other benefits, as described in Exploded Archive Directories in Deploying WebLogic Server Applications. Deploying a Web application enables WebLogic Server to serve the components of a Web application to clients. You can deploy a Web application using one of several procedures, depending on your environment and whether or not your Web application is in production. You can use the WebLogic Server Administration Console, the weblogic.Deployer utility, or you can use auto-deployment. In the procedures for deploying a Web application, it is assumed that you have created a functional Web application that uses the correct directory structure and contains the web.xml deployment descriptor and, if needed, the weblogic.xml deployment descriptor. For an overview of the steps required to package and create a Web application, see Main Steps to Create a Web Application on page 1-5.
Deployment Descriptors
Web applications use two deployment descriptors to define their operational attributes. A web.xml deployment descriptor is a J2EE standard XML document that describes the contents of a WAR file. The weblogic.xml deployment descriptor is an XML document containing WebLogic Server-specific elements for Web applications. For more information about the elements in these deployment descriptor, refer to Appendix A, web.xml Deployment Descriptor Elements, and Appendix B, weblogic.xml Deployment Descriptor Elements. You can modify deployment descriptors using the following tools: WebLogic Builder. WebLogic Builder is the BEA preferred WebLogic Server tool for generating and editing deployment descriptors for WebLogic Server applications. It can also deploy WebLogic Server applications to single servers. For more information, see
2-2
Deployment Tools Reference in Deploying WebLogic Server Applications. For more information, see Using WebLogic Builder to Edit Deployment Descriptors on page 2-3. XML Editor with DTD validation, such as BEA XML Editor on dev2dev or XMLSpy. (An evaluation copy of XMLSpy is bundled with this version of WebLogic Server.) See BEA dev2dev Online at http://dev2dev.bea.com/index.jsp. Using the Administration Console Descriptor tab. The Descriptor tab has replaced the deprecated Deployment Descriptor Editor in the Administration Console. For more information on the Descriptor tab, see the WebLogic Server online help. Also refer to Dynamic Descriptor Updates on page 2-4.
2-4
D e p l o y m e n t O pt i o n s
Session Invalidation Interval SecsThe time, in seconds, that WebLogic Server waits between doing house-cleaning checks for timed-out and invalid sessions, and deleting the old sessions and freeing up memory. Session Timeout SecsThe amount of time (in seconds) that a session can remain inactive before it is invalidated. Servlet Reload Check SecsThe amount of time (in seconds) that WebLogic Server waits to check if a servlet was modified and needs to be reloaded. Single Threaded Servlet Pool SizeThe size of the pool used for single-threaded mode servlets. Index Directory EnabledSpecifies whether the target should automatically generate an HTML directory listing if no suitable index file is found. Session Monitoring EnabledSpecifies whether runtime MBeans will be created for session monitoring. JSPPage Check SecsThe interval, in seconds, at which WebLogic Server checks to see if JSP files have changed and need recompiling. JSPKeep GeneratedSpecifies whether to save the Java files that are generated as an intermediary step in the JSP compilation process. JSPVerboseSpecifies whether to print debugging info to the browser during compilation. Enable JSP Line NumbersSpecifies whether to add JSP line numbers to generated class files to aid in debugging.
Deployment Options
You can deploy a Web application by using: WebLogic Server Administration Console weblogic.Deployer Utility Auto-deployment. This is useful for testing purposes. For Web-application specific information on this topic, see Auto-Deployment of Web Applications on page 2-6 For more information on these tools, see Deployment Tools Reference in Deploying WebLogic Server Applications.
2-5
2-6
D e p l o y m e n t G ui d e l i ne s f o r We b A pp l i c at i o n s
so that the application uses the latest version of the class. (This is one reason why objects stored in a session should be serializable.) You can control the timing of automatic class updates by setting the servlet-reload-check-secs element, as described in Appendix B, weblogic.xml Deployment Descriptor Elements. To re-deploy an entire auto-deployed Web application in exploded directory format, modify the REDEPLOY file: 1. Create an empty file called REDEPLOY and place it in the WEB-INF directory of your Web application. (You may have to create this directory.) 2. Open the REDEPLOY file, modify the contents (this modification can be as simple as adding a space character in the file contentsany modification works), and then save the file. Note: The point in modifying the contents of REDEPLOY is to change the timestamp of the file. You can achieve this by making a simple edit and saving it. 3. Alternatively, on UNIX machines, use the touch command on the REDEPLOY file. For example:
touch user_domains/mydomain/applications/DefaultWebApp/WEB-INF/REDEPLOY
As soon as the REDEPLOY file is modified, the Web application is redeployed. The servlet container detects changes to servlet and filter classes and resets its classloader when a change is detected. Note that all servlets and filters are reloaded together, so changing one servlet or filter causes all to be reloaded. For more information, refer to Using Command Line Deployment on page 2-7. Similarly, changes to JSP files cause a recompilation of the JSP. JSP class files are reloaded individually, so reloading a JSP only affects the one JSP class. Because static content is served directly from the disk, no redeployment is necessary for HTML pages, image files, and so on. However, if you are using caching tags or filters, you must ensure that the cache is flushed when modifying content. You can redeploy a Web application deployed in exploded directory format when using auto-deployment by modifying a special file called REDEPLOY. You can also cause a partial redeploy by copying a new version of a class file over an old in the WEB-INF/classes directory.
2-7
addition, auto-deployment is disabled when the server is running in production mode. Therefore, command line deployment is necessary for all applications when production mode is enabled. You enable production mode by starting the domain's Administration Server using the following flag: -Dweblogic.ProductionModeEnabled=true. This sets the production mode for all server instances in the domain. When you modify a component (for instance, a servlet, JSP, or HTML page) of a Web application, you must take additional steps to refresh the modified component so that it is also deployed on any targeted Managed Servers. One way to refresh a component is to redeploy the entire Web application. Redeploying the Web application means that the entire Web application (not just the modified component) is re-sent over the network to all of the Managed Servers targeted by that Web application. Note the following regarding re-deployment of Web applications: Depending on your environment, there may be performance implications due to increased network traffic when a Web application is re-sent to the Managed Servers. If the Web application is currently in production and in use, redeploying the Web application causes WebLogic Server to lose all active HTTP sessions for current users of the Web application. Note: Sessions will be restored if you have set the save-sessions-enabled element to true in the weblogic.xml deployment descriptors. If you have updated any Java class files, you must redeploy the entire Web application to refresh the class. If you change the deployment descriptors, you must redeploy the entire Web application.
CHAPTER
The following sections describe how to configure Web application components: Configuring Servlets on page 3-1 Configuring Java Server Pages (JSPs) on page 3-5 Configuring JSP Tag Libraries on page 3-7 Configuring Welcome Pages on page 3-7 Setting Up a Default Servlet on page 3-8 Customizing HTTP Error Responses on page 3-9 Using CGI with WebLogic Server on page 3-9 Serving Resources from the CLASSPATH with the ClasspathServlet on page 3-12 Configuring Resources in a Web Application on page 3-12 Loading Servlets, Context Listeners, and Filters on page 3-18 Mapping IANA Character Sets to Java Character Sets on page 3-20
Configuring Servlets
You define servlets as a part of a Web application in several entries in the Web Application deployment descriptor. The first entry, under the <servlet> element, defines a name for the servlet and specifies the compiled class that executes the servlet. (Or, instead of specifying a
3-1
servlet class, you can specify a JSP.) This element also contains definitions for initialization attributes and security roles for the servlet. The second entry, under the <servlet-mapping> element, defines the URL pattern that calls this servlet.
Servlet Mapping
Servlet mapping controls how you access a servlet. The following examples demonstrate how you can use servlet mapping in your Web application. In the examples, a set of servlet configurations and mappings (from the web.xml deployment descriptor) is followed by a table (see url-patterns and Servlet Invocation on page 3-3) showing the URLs used to invoke these servlets. For more information on servlet mappings, such as general servlet mapping rules and conventions, refer to Section 11 of the Servlet 2.3 specification at: http://www.jcp.org/aboutJava/communityprocess/final/jsr053/ Listing 3-1 Servlet Mapping Example
<servlet> <servlet-name>watermelon</servlet-name> <servlet-class>myservlets.watermelon</servlet-class> </servlet> <servlet> <servlet-name>garden</servlet-name> <servlet-class>myservlets.garden</servlet-class> </servlet> <servlet> <servlet-name>list</servlet-name> <servlet-class>myservlets.list</servlet-class> </servlet> <servlet> <servlet-name>kiwi</servlet-name> <servlet-class>myservlets.kiwi</servlet-class> </servlet> <servlet-mapping> <servlet-name>watermelon</servlet-name>
3-2
C o n fi gu ri ng Se rv l e t s
<url-pattern>/fruit/summer/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>garden</servlet-name> <url-pattern>/seeds/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>list</servlet-name> <url-pattern>/seedlist</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>kiwi</servlet-name> <url-pattern>*.abc</url-pattern> </servlet-mapping>
Servlet Invoked
watermelon watermelon list
3-3
Servlet Invoked
The default servlet, if configured, or an HTTP 404 File Not Found error message. If the mapping for the list servlet had been /seedlist*, the list servlet would be invoked.
http://host:port/mywebapp/seedlist/pear.abc
kiwi
If the mapping for the list servlet had been /seedlist*, the list servlet would be invoked.
http://host:port/mywebapp/seeds http://host:port/mywebapp/seeds/index.html http://host:port/mywebapp/index.abc garden garden kiwi
ServletServlet can be used to create a default mappings for servlets. For example, to create
a default mapping to map all servlets to /myservlet/*, so the servlets can be called using
http://host:port/web-app-name/myservlet/com/foo/FooServlet, add the following to
3-4
For more information on editing the Web Application deployment descriptor, see Deploying Web Applications on page 2-1.
3-5
<jsp-descriptor> element of the WebLogic-specific deployment descriptor, weblogic.xml. These attributes define the following functionality:
Options for the JSP compiler Debugging How often WebLogic Server checks for updated JSPs that need to be recompiled Character encoding For a complete description of these attributes, see JSP Attribute Names and Values on page B-13.
Registering a JSP as a servlet allows you to specify the load order, initialization attributes, and security roles for a JSP, just as you would for a servlet.
3-6 Developing Web Applications for WebLogic Server
C o n f i gu ri ng J SP T a g L i br a ri e s
and the TLD is located in the WEB-INF directory of your Web application, you would create the following entry in the Web Application deployment descriptor:
<taglib> <taglib-uri>myTaglib</taglib-uri> <tablig-location>WEB-INF/myTLD.tld</taglib-location> </taglib>
You can also deploy a tag library as a .jar file. For more information on creating custom JSP tag libraries, see Programming JSP Tag Extensions. WebLogic Server also includes several custom JSP tags that you can use in your applications. These tags perform caching, facilitate query attribute-based flow control, and facilitate iterations over sets of objects. For more information, see: Using Custom WebLogic JSP Tags in Programming WebLogic JSP. Using WebLogic JSP Form Validation Tags in Programming WebLogic JSP.
To define Welcome pages, you edit the Web application deployment descriptor, web.xml. If you do not define Welcome Pages, WebLogic Server looks for the following files in the following order and serves the first one it finds:
1. index.html 2. index.htm 3. index.jsp
The following is an example Welcome page configuration: Listing 3-3 Welcome Page Example
<servlet> <servlet-name>WelcomeServlet</servlet-name> <servlet-class>foo.bar.WelcomeServlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>WelcomeServlet</servlet-name> <url-pattern>*.foo</url-pattern> </servlet-mapping> <welcome-file-list> <welcome-file>/welcome.foo</welcome-file> </welcome-file-list>
3-8
Customizing HT TP Er ro r Re spo ns es
you expect your default servlet to serve such files, you will need to write that functionality into your default servlet. To set up a user-defined default servlet: 1. Define your servlet as described in Configuring Servlets on page 3-1. 2. If you still want the FileServlet to serve files with other extensions: a. Define a servlet and give it a <servlet-name>, for example myFileServlet. b. Define the <servlet-class> as weblogic.servlet.FileServlet. a. Using the <servlet-mapping> element, map file extensions to the myFileServlet (in addition to the mappings for your default servlet). For example, if you want the myFileServlet to serve.gif files, map *.gif to the myFileServlet. Note: The FileServlet includes the SERVLET_PATH when determining the source filename if docHome is not specified. As a result, it is possible to explicitly serve only files from specific directories by mapping the FileServlet to /dir/*, etc.
3-9
1. Declare the CGIServlet in your Web application by using the <servlet> and <servlet-mapping> elements. The class name for the CGIServlet is weblogic.servlet.CGIServlet. You do not need to package this class in your Web application. 2. Register the following initialization attributes for the CGIServlet by defining the following <init-param> elements:
cgiDir
The path to the directory containing your CGI scripts. You can specify multiple directories, separated by a semicolon (;). This separator applies to both Windows and UNIX. If you do not specify cgiDir, the directory defaults to a directory named cgi-bin under the Web application root.
useByteStream
The alternate to using the default Char streams for data transfer, this parameter, which is case sensitive, will allow the use of images in the CGI servlet without distortion.
extension mapping
Maps a file extension to the interpreter or executable that runs the script. If the script does not require an executable, this initialization attribute may be omitted. The <param-name> for extension mappings must begin with an asterisk followed by a dot, followed by the file extension, for example, *.pl. The <param-value> contains the path to the interpreter or executable that runs the script. You can create multiple mappings by creating a separate <init-param> element for each mapping.
Listing 3-4 Example Web Application Deployment Descriptor Entries for Registering the CGIServlet
<servlet> <servlet-name>CGIServlet</servlet-name> <servlet-class>weblogic.servlet.CGIServlet</servlet-class> <init-param> <param-name>cgiDir</param-name> <param-value> /bea/wlserver6.0/config/mydomain/applications/myWebApp/cgi-bin </param-value> </init-param>
3-10
<init-param> <param-name>*.pl</param-name> <param-value>/bin/perl.exe</param-value> </init-param> </servlet> ... <servlet-mapping> <servlet-name>CGIServlet</servlet-name> <url-pattern>/cgi-bin/*</url-pattern> </servlet-mapping>
Where
host:port
is the name of the Perl script that is located in the directory specified by the cgiDir initialization attribute.
3-11
In this case, the resource is located in the following directory, relative to the root of the Web application:
WEB-INF/classes/my/resource/myClass.class
Warning: Because the ClasspathServlet serves any resource located in the system CLASSPATH, do not place resources that should not be publicly available in the system CLASSPATH.
3-12
weblogic.xml deployment descriptors. See Configuring External Resources on page 3-13 for more information.
WebLogic Server versions 7.x and later enable you to deploy JDBC DataSources as part of the Web application EAR file by configuring those resources in the weblogic-application.xml deployment descriptor. Resources deployed as part of the EAR file are referred to as application-scoped resources. These resources remain private to the Web application, and application components can access the resource names directly from the local JNDI tree at java:app/env.
3-13
<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> </resource-description>
3-14
3-15
To allow the code in the Web application to use an EJB in ejb1.jar, the Web application deployment descriptor (web.xml) must include an <ejb-ref> stanza that contains an <ejb-link> referencing the JAR file and the name of the EJB that is being called. The format of the <ejb-link> entry must be as follows:
filename#ejbname
where filename is the name of the JAR file, relative to the Web application, and ejbname is the EJB within that JAR file. The <ejb-link> element should look like the following:
<ejb-link>../ejb1.jar#myejb</ejb-link>
Note that since the JAR path is relative to the WAR file, it begins with "../". Also, if the ejbname is unique across the application, the JAR path may be dropped. As a result, your entry may look like the following:
<ejb-link>myejb</ejb-link>
The <ejb-link> element is a sub-element of an <ejb-ref> element contained in the Web application's web.xml descriptor. The <ejb-ref> element should look like the following:
3-16 Developing Web Applications for WebLogic Server
Referring to the syntax for the <ejb-link> element in the above example,
<ejb-link>../ejb1.jar#ejb1</ejb-link>,
the portion of the syntax to the left of the # is a relative path to the EJB module being referenced. The syntax to the right of # is the particular EJB being referenced in that module. In the above example, the EJB JAR and WAR files are at the same level. The name referenced in the <ejb-link> (in this example, myejb) corresponds to the <ejb-name> element of the referenced EJB's descriptor. As a result, the deployment descriptor (ejb-jar.xml) of the EJB module that this <ejb-ref> is referencing should have an entry an entry similar to the following: Listing 3-8 <ejb-jar> Element
<ejb-jar> ... <enterprise-beans>
3-17
<session> <ejb-name>myejb</ejb-name> <home>mypackage.ejb1.MyHome</home> <remote>mypackage.ejb1.MyRemote</remote> <ejb-class>mypackage.ejb1.MyBean</ejb-class> <session-type>Stateless</session-type> <transaction-type>Container</transaction-type> </session> </enterprise-beans> ... </ejb-jar>
Notice the <ejb-name> element is set to myejb. At runtime, the Web application code looks up the EJB's JNDI name relative to
java:/comp/env. The following is an example of the servlet code:
MyHome home = (MyHome)ctx.lookup("java:/comp/env/ejb1");
The name used in this example (ejb1) is the <ejb-ref-name> defined in the <ejb-ref> element of the web.xml segment above.
3-18
2. Filters 3. Context Listeners Servlets and filters are loaded in the same order they are defined in the web.xml file and unloaded in reverse order. Context listeners are loaded in the following order: 1. All context listeners in the web.xml file in the order as specified in the file 2. Packaged JAR files containing tag library descriptors 3. Tag library descriptors in the WEB-INF directory
When the form is read by WebLogic Server, it processes the data using the SJIS character set. Because all Web clients do not transmit the information after the semicolon in the above example, you can set the code set to be used for requests by using the <input-charset> element in the WebLogic-specific deployment descriptor, weblogic.xml. The <java-charset-name> element defines the encoding used to convert data when the URL of the request contains the path specified with the <resource-path> element. For example:
<input-charset> <resource-path>/foo/*</resource-path> <java-charset-name>SJIS</java-charset-name> </input-charset>
3-19
3-20
CHAPTER
The following sections describe how to set up sessions and session persistence: Overview of HTTP Sessions on page 4-1 Setting Up Session Management on page 4-1 Configuring Session Persistence on page 4-4 Using URL Rewriting Instead of Cookies on page 4-10
4-1
Using Ses sions and Sessi on Pe rsi stenc e in Web Appl icatio ns
How long each session lasts How much data you expect to store for each user Heap size allocated to the WebLogic Server instance You can also store data permanently from an HTTP session. See Configuring Session Persistence on page 4-4. For information on editing deployment descriptors, see Deployment Descriptors on page 2-2 in Chapter 2, Deploying Web Applications.
Session Timeout
You can specify an interval of time after which HTTP sessions expire. When a session expires, all data stored in the session is discarded. You can set the interval in either web.xml or weblogic.xml: Set the TimeoutSecs attribute in the session-descriptor element of the WebLogic-specific deployment descriptor, weblogic.xml. This value is set in seconds. For more information, see session-descriptor on page B-5. Set the session-timeout element in the Web Application deployment descriptor, web.xml. For more information, see session-config on page A-11.
The cookies that WebLogic Server uses to track sessions are set as transient by default and do not outlive the session. When a user quits the browser, the cookies are lost and the session ends. This behavior is in the spirit of session usage and it is recommended that you use sessions in this way. You can configure session-tracking attributes of cookies in the WebLogic-specific deployment descriptor, weblogic.xml. A complete list of session and cookie-related attributes is available in session-descriptor on page B-5.
4-3
Using Ses sions and Sessi on Pe rsi stenc e in Web Appl icatio ns
Limits the number of cached sessions that can be active in memory at any one time. If you expect high volumes of simultaneous active sessions, you do not want these sessions to soak up the RAM of your server because this may cause performance problems swapping to and from virtual memory. When the cache is full, the least recently used sessions are stored in the persistent store and recalled automatically when required. If you do not use persistence, this property is ignored, and there is no soft limit to the number of sessions allowed in main memory. By default, the number of cached sessions is 256. To turn off caching, set this to 0.
4-4
Note: CacheSize is used by JDBC and file-based sessions only for maintaining the in-memory bubbling cache. It is not applicable for other persistence types.
InvalidationIntervalSecs
Sets the time, in seconds, that WebLogic Server waits between doing house-cleaning checks for timed-out and invalid sessions, and deleting the old sessions and freeing up memory. Set this attribute to a value less than the value set for the <session-timeout> element. Use this attribute to tune WebLogic Server for best performance on high traffic sites. The minimum value is every second (1). The maximum value is once a week (604,800 seconds). If not set, the attribute defaults to 60 seconds. To set <session-timeout>, see session-config on page A-11.
4-5
Using Ses sions and Sessi on Pe rsi stenc e in Web Appl icatio ns
Data Type
Variable-width alphanumeric column, up to 100 characters; for example, Oracle VARCHAR2(100). The primary key must be set as follows:
wl_id + wl_context_path.
wl_context_path
Variable-width alphanumeric column, up to 100 characters; for example, Oracle VARCHAR2(100). This column is used as part of the primary key. (See the wl_id column description.) Single char column; for example, Oracle CHAR(1)
wl_is_new
4-6
Column Name
wl_create_time
Data Type
Numeric column, 20 digits; for example, Oracle NUMBER(20) Single char column; for example, Oracle CHAR(1) Large binary column; for example, Oracle LONG RAW Numeric column, 20 digits; for example, NUMBER(20) Integer column; for example, Oracle Integer. Number of seconds between client requests before the session is invalidated. A negative time value indicates that the session should never time out.
If you are using an Oracle DBMS, use the following SQL statement to create the wl_servlet_sessions table. Modify the SQL statement for use with your DBMS. Listing 4-1 Creating wl_servlet_sessions table with Oracle DBMS
create table wl_servlet_sessions ( wl_id VARCHAR2(100) NOT NULL, wl_context_path VARCHAR2(100) NOT NULL, wl_is_new CHAR(1), wl_create_time NUMBER(20), wl_is_valid CHAR(1), wl_session_values LONG RAW, wl_access_time NUMBER(20), wl_max_inactive_interval INTEGER, PRIMARY KEY (wl_id, wl_context_path) );
Note: You can use the JDBCConnectionTimeoutSecs attribute to configure a maximum duration that JDBC session persistence should wait for a JDBC connection from the connection pool before failing to load the session data. For more information, see JDBCConnectionTimeoutSecs on page B-9.
4-7
Using Ses sions and Sessi on Pe rsi stenc e in Web Appl icatio ns
If you are using SqlServer2000, use the following SQL statement to create the wl_servlet_sessions table. Modify the SQL statement for use with your DBMS.
If you are using Pointbase, Pointbase translates the SQL. For example, Pointbase would translate the SQL provided in Listing 4-1 as follows. Listing 4-3 Creating wl_servlet_sessions table with Pointbase SQL Translation
SQL> describe wl_servlet_sessions; WL_SERVLET_SESSIONS WL_ID VARCHAR(100) NULLABLE: NO WL_CONTEXT_PATH VARCHAR(100) NULLABLE: NO WL_IS_NEW CHARACTER(1) NULLABLE: YES WL_CREATE_TIME DECIMAL(20) NULLABLE: YES WL_IS_VALID CHARACTER(1) NULLABLE: YES WL_SESSION_VALUES BLOB(65535) NULLABLE: YES
4-8
WL_ACCESS_TIME DECIMAL(20) NULLABLE: YES WL_MAX_INACTIVE_INTERVAL INTEGER(10) NULLABLE: YES Primary Key: WL_CONTEXT_PATH Primary Key: WL_ID
4-9
Using Ses sions and Sessi on Pe rsi stenc e in Web Appl icatio ns
2. Optionally, set a name for the cookie using the PersistentStoreCookieName attribute. The default is WLCOOKIE.
Calling the encodeURL() method determines whether the URL needs to be rewritten. If it does need to be rewritten, WebLogic Server rewrites the URL by appending the session ID to the URL, with the session ID preceded by a semicolon. In addition to URLs that are returned as a response to WebLogic Server, also encode URLs that send redirects. For example:
if (session.isNew()) response.sendRedirect (response.encodeRedirectUrl(welcomeURL));
WebLogic Server uses URL rewriting when a session is new, even if the browser does accept cookies, because the server cannot tell whether a browser accepts cookies in the first visit of a session.
4-10 Developing Web Applications for WebLogic Server
Your servlet can determine whether a given session ID was received from a cookie by checking the Boolean returned from the HttpServletRequest.isRequestedSessionIdFromCookie() method. Your application may respond appropriately, or simply rely on URL rewriting by WebLogic Server.
4-11
Using Ses sions and Sessi on Pe rsi stenc e in Web Appl icatio ns
4-12
CHAPTER
The following sections discuss application events and event listener classes: Overview of Application Event Listener Classes on page 5-2 Servlet Context Events on page 5-2 HTTP Session Events on page 5-3 Configuring an Event Listener Class on page 5-4 Writing an Event Listener Class on page 5-5 Templates for Event Listener Classes on page 5-5 Additional Resources on page 5-7
5-1
5-2
Interface
javax.servlet.ServletContextListener
Method
contextInitialized()
javax.servlet.ServletContextListener
contextDestroyed()
attributeAdded()
attributeRemoved()
attributeReplaced()
Interface
javax.servlet.http. HttpSessionListener javax.servlet.http. HttpSessionListener javax.servlet.http. HttpSessionAttributeListener
Method
sessionCreated()
sessionDestroyed()
attributeAdded()
5-3
Type of Event
An attribute is removed. An attribute is replaced.
Interface
javax.servlet.http. HttpSessionAttributeListener javax.servlet.http. HttpSessionAttributeListener
Method
attributeRemoved()
attributeReplaced()
interfaces are implemented by objects that are stored as session attributes and do not require registration of an event listener in web.xml. For more information, see the Javadocs for these interfaces.
3. Write and deploy the event listener class. For details, see the section, Writing an Event Listener Class on page 5-5.
5-4
3. Implement the required methods of the interface. See the J2EE API Reference (Javadocs) at http://java.sun.com/j2ee/tutorial/api/index.html for more information. 4. Copy the compiled event listener classes into the WEB-INF/classes directory of the Web application, or package them into a JAR file and copy the JAR file into the WEB-INF/lib directory of the Web application. The following useful classes are passed into the methods in an event listener class:
javax.servlet.http.HttpSessionEvent
5-5
public final class MyContextListenerClass implements ServletContextListener { public void contextInitialized(ServletContextEvent event) { /* This method is called when the servlet context is initialized(when the Web application is deployed). You can initialize servlet context related data here. */ } public void contextDestroyed(ServletContextEvent event) { /* This method is invoked when the Servlet Context (the Web application) is undeployed or WebLogic Server shuts down. */ } }
5-6
*/ } public void attributeReplaced(HttpSessionBindingEvent sbe) { /* This method is invoked when an attibute is replaced in a session. */ } }
Additional Resources
Servlet 2.3 Specification from Sun Microsystems at
http://java.sun.com/aboutJava/communityprocess/first/jsr053/index.html
5-7
5-8
CHAPTER
Filters
The following sections provide information about using filters in a Web application: Overview of Filters on page 6-1 Writing a Filter Class on page 6-2 Configuring Filters on page 6-3 Filtering the Servlet Response Object on page 6-5 Additional Resources on page 6-6
Overview of Filters
A filter is a Java class that is invoked in response to a request for a resource in a Web application. Resources include Java Servlets, JavaServer pages (JSP), and static resources such as HTML pages or images. A filter intercepts the request and can examine and modify the response and request objects or execute other tasks. Filters are an advanced J2EE feature primarily intended for situations where the developer cannot change the coding of an existing resource and needs to modify the behavior of that resource. Generally, it is more efficient to modify the code to change the behavior of the resource itself rather than using filters to modify the resource. In some situations, using filters can add unnecessary complexity to an application and degrade performance.
6-1
Fil ters
response, and a javax.servlet.FilterChain object. The FilterChain object contains a list of filters that can be invoked sequentially. When a filter has completed its work, the filter can either call the next filter in the chain, block the request, throw an exception, or invoke the originally requested resource. After the original resource is invoked, control is passed back to the filter at the bottom of the list in the chain. This filter can then examine and modify the response headers and data, block the request, throw an exception, or invoke the next filter up from the bottom of the chain. This process continues in reverse order up through the chain of filters. Note: The filter can modify the headers only if the response has not already been committed.
Configuring F ilters
You use the doFilter() method to examine and modify the request and response objects, perform other tasks such as logging, invoke the next filter in the chain, or block further processing. Several other methods are available on the FilterConfig object for accessing the name of the filter, the ServletContext and the filters initialization attributes. For more information see the J2EE Javadocs from Sun Microsystems for javax.servlet.FilterConfig. Javadocs are available at http://java.sun.com/j2ee/tutorial/api/index.html. To access the next item in the chain (either another filter or the original resource, if that is the next item in the chain), call the FilterChain.doFilter() method.
Configuring Filters
You configure filters as part of a Web application, using the applications web.xml deployment descriptor. In the deployment descriptor, you specify the filter and then map the filter to a URL pattern or to a specific servlet in the Web application. You can specify any number of filters.
Configuring a Filter
To configure a filter: 1. Open the web.xml deployment descriptor in a text editor or use the Administration Console. For more information, see Web Application Developer Tools on page 1-8. The web.xml file is located in the WEB-INF directory of your Web application. 2. Add a filter declaration. The <filter> element declares a filter, defines a name for the filter, and specifies the Java class that executes the filter. The <filter> element must directly follow the <context-param> element and directly precede the <listener> and <servlet> elements. For example:
<context-param>Param</context-param> <filter> <icon> <small-icon>MySmallIcon.gif</small-icon> <large-icon>MyLargeIcon.gif</large-icon> </icon> <filter-name>myFilter</filter-name>
6-3
Fil ters
The icon, description, and display-name elements are optional. 3. Specify one or more initialization attributes inside a <filter> element. For example:
<filter> <icon> <small-icon>MySmallIcon.gif</small-icon> <large-icon>MyLargeIcon.gif</large-icon> </icon> <filter-name>myFilter</filter-name> <display-name>My Filter</display-name> <description>This is my filter</description> <filter-class>examples.myFilterClass</filter-class> <init-param> <param-name>myInitParam</param-name> <param-value>myInitParamValue</param-value> </init-param> </filter>
Your Filter class can read the initialization attributes using the FilterConfig.getInitParameter() or FilterConfig.getInitParameters() methods. 4. Add filter mappings. The <filter-mapping> element specifies which filter to execute based on a URL pattern or servlet name. The <filter-mapping> element must immediately follow the <filter> element(s). To create a filter mapping using a URL pattern, specify the name of the filter and a URL pattern. URL pattern matching is performed according to the rules specified in the Servlet 2.3 Specification from Sun Microsystems at
http://java.sun.com/aboutJava/communityprocess/first/jsr053/index.ht ml, in section 11.1. For example, the following filter-mapping maps myFilter to requests that contain /myPattern/. <filter-mapping> <filter-name>myFilter</filter-name> <url-pattern>/myPattern/*</url-pattern> </filter-mapping>
6-4
To create a filter mapping for a specific servlet, map the filter to the name of a servlet that is registered in the Web application. For example, the following code maps the myFilter filter to a servlet called myServlet:
<filter-mapping> <filter-name>myFilter</filter-name> <servlet-hame>myServlet</servlet-name> </filter-mapping>
5. To create a chain of filters, specify multiple filter mappings. For more information, see Configuring a Chain of Filters on page 6-5.
6-5
Fil ters
Additional Resources
Servlet 2.3 Specification from Sun Microsystems at
http://java.sun.com/aboutJava/communityprocess/first/jsr053/index.html
6-6
APPENDIX
The following sections describe the deployment descriptor elements defined in the web.xml file under the root element <web-app>: context-param on page A-4 description on page A-3 display-name on page A-2 distributable on page A-3 ejb-ref on page A-21 ejb-local-ref on page A-22 env-entry on page A-20 error-page on page A-13 filter on page A-5 filter-mapping on page A-7 icon on page A-2 listener on page A-7 login-config on page A-19 mime-mapping on page A-12
A-1
resource-env-ref on page A-14 resource-ref on page A-15 security-constraint on page A-16 security-role on page A-20 servlet on page A-8 servlet-mapping on page A-10 session-config on page A-11 taglib on page A-13 welcome-file-list on page A-12
icon
The icon element specifies the location within the Web application for a small and large image used to represent the Web application in a GUI tool. (The servlet element also has an element called the icon element, used to supply an icon to represent a servlet in a GUI tool.) The following table describes the elements you can define within an icon element. Element
<small-icon>
Required/ Optional
Optional
Description
Location for a small (16x16 pixel) .gif or .jpg image used to represent the Web application in a GUI tool. Currently, this is not used by WebLogic Server. Location for a large (32x32 pixel) .gif or .jpg image used to represent the Web application in a GUI tool. Currently, this element is not used by WebLogic Server.
<large-icon>
Optional
display-name
The optional display-name element specifies the Web application display name, a short name that can be displayed by GUI tools.
A-2
des cr ipt io n
Element
<display-name>
Required/ Optional
Optional
Description
Currently, this element is not used by WebLogic Server.
description
The optional description element provides descriptive text about the Web application.
Element
<description>
Required/ Optional
Optional
Description
Currently, this element is not used by WebLogic Server.
distributable
The distributable element is not used by WebLogic Server. Element
<distributable>
Required/ Optional
Optional
Description
Currently, this element is not used by WebLogic Server.
A-3
context-param
The optional context-param element contains the declaration of a Web applications servlet context initialization parameters. The following table describes the reserved context parameters used by the Web application container, which have been deprecated and have replacements in weblogic.xml.. Deprecated Parameter
weblogic.httpd.inputCh arset
Description
Defines code set behavior for non-unicode operations.
weblogic.httpd.servlet .reloadCheckSecs
Define how often WebLogic Server checks whether a servlet has been modified, and if so, reloads it. A value of -1 is never reload, 0 is always reload. The default is set to 1 second.
in weblogic.xml.See
container-descriptor on page B-16. No replacement. Use other means such as manifest classpath or WEB-INF/lib or WEB-INF/classes or virtual directories. No replacement. Instead use the servlet and servlet-mapping elements in web.xml to define a default servlet. The URL pattern for default-servlet should be /. See servlet-mapping on page A-10. For additional examples of servlet mapping, see Servlet Mapping on page 3-2.
weblogic.httpd.servlet .classpath
When this values has been set, the container appends this path to the Web application classpath. This is not a recommended method and is supported only for backward compatibility. Sets the default servlet for the Web application. This is not a recommended method and is supported only for backward compatibility.
weblogic.httpd.default Servlet
f i l te r
Element
weblogic.httpd. clientCertProxy
Required/ Optional
optional
Description
This attribute specifies that certifications from clients of the Web application are provided in the special WL-Proxy-Client-Cert header sent by a proxy plug-in or HttpClusterServlet. This setting is useful if user authentication is performed on a proxy serversetting clientCertProxy causes the proxy server to pass on the certs to the cluster in a special header, WL-Proxy-Client-Cert. A WL-Proxy-Client-Cert header could be provided by any client with access to WebLogic Server. WebLogic Server takes the certificate information from that header, trusting that is came from a secure source (the plug-in) and uses that information to authenticate the user. For this reason, if you set clientCertProxy, use a connection filter to ensure that WebLogic Server accepts connections only from the machine on which the plug-in is running. See "Using Network Connection Filters" in Programming WebLogic Security. In addition to setting this attribute for an individual Web application, you can define this attribute: For all web applications hosted by a server instance, on the Server-->Configuration-->General page in the Administration Console For all web applications hosted by server instances in a cluster, on the Cluster-->Configuration-->General page.
filter
The filter element defines a filter class and its initialization attributes. For more information on filters, see Configuring Filters on page 6-3.
A-5
The following table describes the elements you can define within a filter element. Element
<icon>
Required/ Optional
Optional
Description
Specifies the location within the Web application for a small and large image used to represent the filter in a GUI tool. Contains a small-icon and large-icon element. Currently, this element is not used by WebLogic Server.
<filter-name>
Defines the name of the filter, used to reference the filter definition elsewhere in the deployment descriptor. A short name intended to be displayed by GUI tools. A text description of the filter. The fully-qualified class name of the filter. Contains a name/value pair as an initialization attribute of the filter. Use a separate set of <init-param> tags for each attribute.
A-6
fi l t e r- m a pp i n g
filter-mapping
The following table describes the elements you can define within a filter-mapping element. Element
<filter-name>
Required/ Optional
Required
Description
The name of the filter to which you are mapping a URL pattern or servlet. This name corresponds to the name assigned in the <filter> element with the <filter-name> element. Describes a pattern used to resolve URLs. The portion of the URL after the http://host:port + ContextPath is compared to the <url-pattern> by WebLogic Server. If the patterns match, the filter mapped in this element is called. Example patterns:
/soda/grape/* /foo/* /contents *.foo
<url-pattern>
The URL must follow the rules specified in the Servlet 2.3 Specification. <servlet-name> Required - or map by <url-pattern> The name of a servlet which, if called, causes this filter to execute.
listener
Define an application listener using the listener element. Element
<listener-class>
Required/ Optional
Optional
Description
Name of the class that responds to a Web application event.
For more information, see Configuring an Event Listener Class on page 5-4.
A-7
servlet
The servlet element contains the declarative data of a servlet. If a jsp-file is specified and the <load-on-startup> element is present, then the JSP is precompiled and loaded when WebLogic Server starts. The following table describes the elements you can define within a servlet element. Element
<icon>
Required/ Optional
Optional
Description
Location within the Web application for a small and large image used to represent the servlet in a GUI tool. Contains a small-icon and large-icon element. Currently, this element is not used by WebLogic Server.
<servlet-name>
Required Optional Optional Required (or use <jspfile>) Required (or use <servletclass>) Optional
Defines the canonical name of the servlet, used to reference the servlet definition elsewhere in the deployment descriptor. A short name intended to be displayed by GUI tools. A text description of the servlet. The fully-qualified class name of the servlet. Use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body. The full path to a JSP file within the Web application, relative to the Web application root directory. Use only one of either the <servlet-class> tags or <jsp-file> tags in your servlet body. Contains a name/value pair as an initialization attribute of the servlet. Use a separate set of <init-param> tags for each attribute.
<jsp-file>
<init-param>
<load-on-startup>
Optional
WebLogic Server initializes this servlet when WebLogic Server starts up. The optional content of this element must be a positive integer indicating the order in which the servlet should be loaded. Lower integers are loaded before higher integers. If no value is specified, or if the value specified is not a positive integer, WebLogic Server can load the servlet in any order during application startup.
A-8
s er vlet
Element
<run-as>
Required/ Optional
Optional
Description
Specifies the run-as identity to be used for the execution of the Web application. It contains an optional description and the name of a security role. Used to link a security role name defined by <security-role> to an alternative role name that is hard coded in the servlet logic. This extra layer of abstraction allows the servlet to be configured at deployment without changing servlet code.
<security-roleref>
Optional
icon
This is an element within the servlet on page A-8. The icon element specifies the location within the Web application for small and large images used to represent the servlet in a GUI tool. The following table describes the elements you can define within an icon element. Element
<small-icon>
Required/ Optional
Optional
Description
Specifies the location within the Web application for a small (16x16 pixel) .gif or .jpg image used to represent the servlet in a GUI tool. Currently, this element is not used by WebLogic Server.
<large-icon>
Optional
Specifies the location within the Web application for a small (32x32 pixel) .gif or.jpg image used to represent the servlet in a GUI tool. Currently, this element is not used by WebLogic Server.
init-param
This is an element within the servlet on page A-8. The optional init-param element contains a name/value pair as an initialization attribute of the servlet. Use a separate set of init-param tags for each attribute. You can access these attributes with the
javax.servlet.ServletConfig.getInitParameter() method.
A-9
The following table describes the elements you can define within a init-param element. Element
<param-name> <param-value> <description>
Required/ Optional
Required Required Optional
Description
Defines the name of this attribute. Defines a String value for this attribute. Text description of the initialization attribute.
security-role-ref
This is an element within the servlet on page A-8.
The security-role-ref element links a security role name defined by <security-role> to an alternative role name that is hard-coded in the servlet logic. This extra layer of abstraction allows the servlet to be configured at deployment without changing servlet code.
The following table describes the elements you can define within a security-role-ref element. Element
<description> <role-name>
Required/ Optional
Optional Required Required
Description
Text description of the role. Defines the name of the security role or principal that is used in the servlet code. Defines the name of the security role that is defined in a <security-role> element later in the deployment descriptor.
<role-link>
servlet-mapping
The servlet-mapping element defines a mapping between a servlet and a URL pattern.
A-10
sess ion-confi g
The following table describes the elements you can define within a servlet-mapping element. Element
<servlet-name>
Required/ Optional
Required
Description
The name of the servlet to which you are mapping a URL pattern. This name corresponds to the name you assigned a servlet in a <servlet> declaration tag. Describes a pattern used to resolve URLs. The portion of the URL after the http://host:port + WebAppName is compared to the <url-pattern> by WebLogic Server. If the patterns match, the servlet mapped in this element will be called. Example patterns:
/soda/grape/* /foo/* /contents *.foo
<url-pattern>
Required
The URL must follow the rules specified in the Servlet 2.3 Specification. For additional examples of servlet mapping, see Servlet Mapping on page 3-2.
session-config
The session-config element defines the session attributes for this Web application.
A-11
The following table describes the element you can define within a session-config element. Element
<session-timeout>
Required/ Optional
Optional
Description
The number of minutes after which sessions in this Web application expire. The value set in this element overrides the value set in the TimeoutSecs attribute of the <session-descriptor> element in the WebLogic-specific deployment descriptor weblogic.xml, unless one of the special values listed here is entered. Default value: -2 Maximum value: Integer.MAX_VALUE 60 Special values: -2 = Use the value set by TimeoutSecs in <session-descriptor> element of weblogic.xml -1 = Sessions do not timeout. The value set in <session-descriptor> element of weblogic.xml is ignored.
mime-mapping
The mime-mapping element defines a mapping between an extension and a mime type. The following table describes the elements you can define within a mime-mapping element. Element
<extension> <mime-type>
Required/ Optional
Required Required
Description
A string describing an extension, for example: txt. A string describing the defined mime type, for example: text/plain.
welcome-file-list
The optional welcome-file-list element contains an ordered list of welcome-file elements. When the URL request is a directory name, WebLogic Server serves the first file specified in this element. If that file is not found, the server then tries the next file in the list.
A-12 Developing Web Applications for WebLogic Server
er ro r-p ag e
For more information, see Configuring Welcome Pages on page 3-7 and "How WebLogic Server Resolves HTTP Requests." The following table describes the element you can define within a welcome-file-list element. Element
<welcome-file>
Required/ Optional
Optional
Description
File name to use as a default welcome file, such as index.html
error-page
The optional error-page element specifies a mapping between an error code or exception type to the path of a resource in the Web application. When an error occurswhile WebLogic Server is responding to an HTTP request, or as a result of a Java exceptionWebLogic Server returns an HTML page that displays either the HTTP error code or a page containing the Java error message. You can define your own HTML page to be displayed in place of these default error pages or in response to a Java exception. For more information, see Customizing HTTP Error Responses on page 3-9 and "How WebLogic Server Resolves HTTP Requests." The following table describes the elements you can define within an error-page element. Note: Define either an <error-code> or an <exception-type> but not both. Element
<error-code> <exception-type>
Required/ Optional
Optional Optional Required
Description
A valid HTTP error code, for example, 404. A fully-qualified class name of a Java exception type, for example, java.lang.string The location of the resource to display in response to the error. For example, /myErrorPg.html.
<location>
taglib
The optional taglib element describes a JSP tag library.
Developing Web Applications for WebLogic Server A-13
This element associates the location of a JSP Tag Library Descriptor (TLD) with a URI pattern. Although you can specify a TLD in your JSP that is relative to the WEB-INF directory, you can also use the <taglib> tag to configure the TLD when deploying your Web application. Use a separate element for each TLD. The following table describes the elements you can define within a taglib element. Element
<taglib-location>
Required/ Optional
Required
Description
Gives the file name of the tag library descriptor relative to the root of the Web application. It is a good idea to store the tag library descriptor file under the WEB-INF directory so it is not publicly available over an HTTP request. Describes a URI, relative to the location of the web.xml document, identifying a Tag Library used in the Web application. If the URI matches the URI string used in the taglib directive on the JSP page, this taglib is used.
<taglib-uri>
Required
resource-env-ref
The resource-env-ref element contains a declaration of a Web application's reference to an administered object associated with a resource in the Web application's environment. It consists of an optional description, the resource environment reference name, and an indication of the resource environment reference type expected by the Web application code. For example:
<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>
A-14
The following table describes the elements you can define within a resource-env-ref element. Element
<description> <resource-env-ref -name>
Required/ Optional
Optional Required
Description
Provides a description of the resource environment reference. Specifies the name of a resource environment reference; its value is the environment entry name used in the Web application code. The name is a JNDI name relative to the java:comp/env context and must be unique within a Web application. Specifies the type of a resource environment reference. It is the fully qualified name of a Java language class or interface.
<resource-env-ref-type>
Required
resource-ref
The optional resource-ref element defines a reference lookup name to an external resource. This allows the servlet code to look up a resource by a virtual name that is mapped to the actual location at deployment time. Use a separate <resource-ref> element to define each external resource name. The external resource name is mapped to the actual location name of the resource at deployment time in the WebLogic-specific deployment descriptor weblogic.xml. The following table describes the elements you can define within a resource-ref element. Element
<description> <res-ref-name>
Required/ Optional
Optional Required Required
Description
A text description. The name of the resource used in the JNDI tree. Servlets in the Web application use this name to look up a reference to the resource. The Java type of the resource that corresponds to the reference name. Use the full package name of the Java type.
<res-type>
A-15
Element
<res-auth>
Required/ Optional
Required
Description
Used to control the resource sign on for security. If set to APPLICATION, indicates that the application component code performs resource sign on programmatically. If set to CONTAINER, WebLogic Server uses the security context established with the login-config element. See login-config on page A-19.
<res-sharing-scop e>
Optional
Specifies whether connections obtained through the given resource manager connection factory reference can be shared. Valid values: Shareable Unshareable
security-constraint
The security-constraint element defines the access privileges to a collection of resources defined by the <web-resource-collection> element. For detailed instructions and an example on configuring security in Web applications, see Securing WebLogic Resources. Also, for more information on WebLogic Security, refer to Programming WebLogic Security. The following table describes the elements you can define within a security-constraint element. Element
<web-resourcecollection> <auth-constraint>
Required/ Optional
Required Optional
Description
Defines the components of the Web application to which this security constraint is applied. Defines which groups or principals have access to the collection of web resources defined in this security constraint. See also auth-constraint on page A-17. Defines how the client should communicate with the server. See also user-data-constraint on page A-18.
<user-dataconstraint>
Optional
A-16
sec urity-constraint
web-resource-collection
Each <security-constraint> element must have one or more <web-resource-collection> elements. These define the area of the Web application to which this security constraint is applied. This is an element within the security-constraint on page A-16. The following table describes the elements you can define within a web-resource-collection element. Element
<web-resourcename> <description> <url-pattern>
Required/ Optional
Required Optional Optional
Description
The name of this Web resource collection. A text description of this security constraint. Use one or more of the <url-pattern> elements to declare to which URL patterns this security constraint applies. If you do not use at least one of these elements, this <web-resource-collection> is ignored by WebLogic Server. Use one or more of the <http-method> elements to declare which HTTP methods (usually, GET or POST) are subject to the authorization constraint. If you omit the <http-method> element, the default behavior is to apply the security constraint to all HTTP methods.
<http-method>
Optional
auth-constraint
This is an element within the security-constraint on page A-16. The optional auth-constraint element defines which groups or principals have access to the collection of Web resources defined in this security constraint.
A-17
The following table describes the elements you can define within an auth-constraint element. Element
<description> <role-name>
Required/ Optional
Optional Optional
Description
A text description of this security constraint. Defines which security roles can access resources defined in this security-constraint. Security role names are mapped to principals using the security-role-ref. See security-role-ref on page A-10.
user-data-constraint
This is an element within the security-constraint on page A-16. The user-data-constraint element defines how the client should communicate with the server. The following table describes the elements you may define within a user-data-constraint element. Element
<description> <transportguarantee>
Required/ Optional
Optional Required
Description
A text description. Specifies that the communication between client and server. WebLogic Server establishes a Secure Sockets Layer (SSL) connection when the user is authenticated using the INTEGRAL or CONFIDENTIAL transport guarantee. Range of values:
NONEThe application does not require any transport guarantees. INTEGRALThe application requires that the data be sent between the client and server in such a way that it cannot be changed in transit. CONFIDENTIALThe application requires that data be transmitted so as to prevent other entities from observing the contents of the transmission.
A-18
login-confi g
login-config
Use the optional login-config element to configure how the user is authenticated; the realm name that should be used for this application; and the attributes that are needed by the form login mechanism. 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. Once authenticated, the user can be authorized to access other resources with access privileges. The following table describes the elements you can define within a login-config element. Element
<auth-method>
Required/ Optional
Optional
Description
Specifies the method used to authenticate the user. Possible values:
BASICuses browser authentication. (This is the default value.) FORMuses a user-written HTML form. CLIENT-CERT
<realm-name>
Optional
The name of the realm that is referenced to authenticate the user credentials. If omitted, the realm defined with the Auth Realm Name field on the Web applicationConfiguration Other tab of the Administration Console is used by default. For more information, see "Managing WebLogic Security". Note: The <realm-name> element does not refer to system security realms within WebLogic Server. This element defines the realm name to use in HTTP Basic authorization. The system security realm is a collection of security information that is checked when certain operations are performed in the server. The servlet security realm is a different collection of security information that is checked when a page is accessed and basic authentication is used.
<form-loginconfig>
Optional
Use this element if you configure the <auth-method> to FORM. See form-login-config on page A-19.
form-login-config
This is an element within the login-config on page A-19. Use the <form-login-config> element if you configure the <auth-method> to FORM.
A-19
. Element
<form-login-page>
Required/ Optional
Required
Description
The URI of a Web resource relative to the document root, used to authenticate the user. This can be an HTML page, JSP, or HTTP servlet, and must return an HTML page containing a FORM-based authentication that conforms to a specific naming convention. The URI of a Web resource relative to the document root, sent to the user in response to a failed authentication login.
<form-error-page>
Required
security-role
The following table describes the elements you can define within a security-role element. Element
<description> <role-name>
Required/ Optional
Optional Required
Description
A text description of this security role. The role name. The name you use here must have a corresponding entry in the WebLogic-specific deployment descriptor, weblogic.xml, which maps roles to principals in the security realm. For more information, see security-role-assignment on page B-2.
env-entry
The optional env-entry element declares an environment entry for an application. Use a separate element for each environment entry. The following table describes the elements you can define within an env-entry element. Element
<description> <env-entry-name>
Required/ Optional
Optional Required
Description
A textual description. The name of the environment entry.
A-20
ejb-ref
Element
<env-entry-value> <env-entry-type>
Required/ Optional
Required Required
Description
The value of the environment entry. The type of the environment entry. Can be set to one of the following Java types:
java.lang.Boolean java.lang.String java.lang.Integer java.lang.Double java.lang.Float
ejb-ref
The optional ejb-ref element defines a reference to an EJB resource. This reference is mapped to the actual location of the EJB at deployment time by defining the mapping in the WebLogic-specific deployment descriptor file, weblogic.xml. Use a separate <ejb-ref> element to define each reference EJB name. The following table describes the elements you can define within an ejb-ref element. Element
<description> <ejb-ref-name>
Required/ Optional
Optional Required
Description
A text description of the reference. The name of the EJB used in the Web application. This name is mapped to the JNDI tree in the WebLogic-specific deployment descriptor weblogic.xml. For more information, see ejb-reference-description on page B-5. The expected Java class type of the referenced EJB. The fully qualified class name of the EJB home interface. The fully qualified class name of the EJB remote interface.
A-21
Element
<ejb-link>
Required/ Optional
Optional Optional
Description
The <ejb-name> of an EJB in an encompassing J2EE application package. A security role whose security context is applied to the referenced EJB. Must be a security role defined with the <security-role> element.
<run-as>
ejb-local-ref
The ejb-local-ref element is used for the declaration of a reference to an enterprise bean's local home. The declaration consists of: An optional description The EJB reference name used in the code of the Web application that references the enterprise bean. The expected type of the referenced enterprise bean The expected local home and local interfaces of the referenced enterprise bean Optional ejb-link information, used to specify the referenced enterprise bean The following table describes the elements you can define within an ejb-local-ref element. Element
<description> <ejb-ref-name>
Required/ Optional
Optional Required
Description
A text description of the reference. Contains the name of an EJB reference. The EJB reference is an entry in the Web application's environment and is relative to the java:comp/env context. The name must be unique within the Web application. It is recommended that name is prefixed with ejb/. For example: <ejb-ref-name>ejb/Payroll</ejb-ref-name>
<ejb-ref-type>
Required
The ejb-ref-type element contains the expected type of the referenced enterprise bean. The ejb-ref-type element must be one of the following:
<ejb-ref-type>Entity</ejb-ref-type> <ejb-ref-type>Session</ejb-ref-type>
A-22
Element
<local-home>
Required/ Optional
Required Required Optional
Description
Contains the fully-qualified name of the enterprise bean's local home interface. Contains the fully-qualified name of the enterprise bean's local interface. The ejb-link element is used in the ejb-ref or ejb-local-ref elements to specify that an EJB reference is linked to an EJB. The name in the ejb-link element is composed of a path name. This path name specifies the ejb-jar containing the referenced EJB with the ejb-name of the target bean appended and separated from the path name by #. The path name is relative to the WAR file containing the Web application that is referencing the EJB. This allows multiple EJBs with the same ejb-name to be uniquely identified. Used in: ejb-local-ref and ejb-ref elements Examples: <ejb-link>EmployeeRecord</ejb-link> <ejb-link>../products/product.jar#ProductEJB</ejb-link>
<local>
<ejb-link>
A-23
A-24
APPENDIX B
The following sections describe the deployment descriptor elements that you define in the weblogic.xml file under the root element <weblogic-web-app>: auth-filter on page B-15 charset-params on page B-18 container-descriptor on page B-16 context-root on page B-22 description on page B-2 destroy-as on page B-24 init-as on page B-24 jsp-descriptor on page B-11 preprocessor on page B-21 preprocessor-mapping on page B-21 reference-descriptor on page B-4 run-as-role-assignment on page B-3 security-permission on page B-22 security-role-assignment on page B-2
B-1
servlet-descriptor on page B-23 session-descriptor on page B-5 url-match-map on page B-20 virtual-directory-mapping on page B-19 weblogic-version on page B-2 wl-dispatch-policy on page B-23 The DOCTYPE header for the weblogic.xml file is as follows:
<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN" "http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd">
You can also access the Document Type Descriptor (DTD) for weblogic.xml at http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd.
description
The description element is a text description of the Web application.
weblogic-version
The weblogic-version element indicates the version of WebLogic Server on which this Web application is intended to be deployed. This element is informational only and is not used by WebLogic Server.
security-role-assignment
The security-role-assignment element declares a mapping between a security role and one or more principals in the realm, as shown in the following example.
<security-role-assignment> <role-name>PayrollAdmin</role-name> <principal-name>Tanya</principal-name> <principal-name>Fred</principal-name> <principal-name>system</principal-name> </security-role-assignment>
B-2
r un -a s - r o l e -a s s i gn m e nt
The following table describes the elements you can define within a security-role-assignment element. Element
<role-name> <principal-name>
Required Optional
Required Required
Description
Specifies the name of a security role. Specifies the name of a principal that is defined in the security realm. You can use multiple <principal-name> elements to map principals to a role. For more information on security realms, see
Optional
Specifies that a particular security role is defined globally in a security realm; WebLogic Server uses this security role as the principal name, rather than looking it up in a global realm. When the security role and its principal-name mapping are defined elsewhere, this is used as an indicative placeholder.
Note: If you do not define a security-role-assignment element and its subelements, the Web application container implicitly maps the role name as a principal name and logs a warning. The EJB container does not deploy the module if mappings are not defined. Consider the following usage scenarios for the role name is role_xyz If you maprole_xyz to user joe in weblogic.xml, role_xyz becomes a local role. If you specify role_xyz as an externally defined role, it becomes global (it refers to the role defined at the realm level). If you do not define a security-role-assignment element, role_xyz becomes a local role, and the Web application container creates an implicit mapping to it and logs a warning.
run-as-role-assignment
The run-as-role-assignment element maps a run-as role name (a subelement of the servlet element) in web.xml to a valid user name in the system. The value can be overridden for a given servlet by the run-as-principal-name element in the servlet-descriptor. If the run-as-role-assignment is absent for a given role name, the Web application container chooses the first principal-name defined in the security-role-assignment.
B-3
The following table describes the elements you can define within a run-as-role-assignment element. Element
<role-name> <run-as-principal -name>
Required Optional
Required Required
Description
Specifies the name of a security role. Specifies the name of a principal.
reference-descriptor
The reference-descriptor element maps a name used in the Web application to the JNDI name of a server resource. The reference-description element contains two elements: The resource-description element maps a resource, for example, a DataSource, to its JNDI name. The ejb-reference element maps an EJB to its JNDI name.
resource-env-description
The resource-env-description element maps a resource-env-ref, declared in the ejb-jar.xml deployment descriptor, to the JNDI name of the server resource it represents. The following table describes the elements you can define within a resource-env-description element. Element
<res-env-ref-name > <jndi-name>
Required/ Optional
Required Required
Description
Specifies the name of a resource environment reference. Specifies a JNDI name for the resource environment reference.
resource-description
The resource-description element is used to map the JNDI name of a server resource to an EJB resource reference in WebLogic Server.
B-4
The following table describes the elements you can define within a resource-description element. Element
<res-ref-name> <jndi-name>
Required/ Optional
Required Required
Description
Specifies the name of a resource reference. Specifies a JNDI name for the resource.
ejb-reference-description
The following table describes the elements you can define within a ejb-reference-description element. Element
<ejb-ref-name> <jndi-name>
Required/ Optional
Required Required
Description
Specifies the name of an EJB reference used in your Web application. Specifies a JNDI name for the reference.
session-descriptor
The session-descriptor element contains the session-param element, which defines attributes for HTTP sessions, as shown in the following example:
<session-descriptor> <session-param> <param-name> CookieDomain </param-name> <param-value> myCookieDomain </param-value> </session-param> </session-descriptor>
B-5
session-param
The following table describes the elements you can define within a session-param element. Element
<param-name> <param-value>
Required/ Optional
Required Required
Description
Specifies the name of the parameter. Specifies the value of the parameter.
The following table describes the valid session attribute names and values you can define within a session-param element:
Attribute Name ConsoleMainAttribute
Default Value
Value
If you enable Session Monitoring in the WebLogic Server Administration Console, set this attribute to the name of the session attribute you will use to identify each session that is monitored.
CookieDomain
Null
Specifies the domain for which the cookie is valid. For example, setting CookieDomain to .mydomain.com returns cookies to any server in the *.mydomain.com domain. The domain name must have at least two components. Setting a name to *.com or *.net is not valid. If not set, this attribute defaults to the server that issued the cookie. For more information, see Cookie.setDomain() in the Servlet specification from Sun Microsystems.
CookieComment
Specifies the comment that identifies the session tracking cookie in the cookie file. If not set, this attribute defaults to WebLogic Session Tracking Cookie. You may provide a more specific name for your application.
B-6
Attribute Name
CookieSecure
Default Value
false
Value
Tells the browser to only send the cookie back over an HTTPS connection. This ensures that the cookie ID is secure and should only be used on Websites that use HTTPS. Session Cookies over HTTP no longer work if this feature is enabled. You should turn off the URLRewritingEnabled attribute if you intend to use this feature.
CookieMaxAgeSecs
-1
Sets the life span of the session cookie, in seconds, after which it expires on the client. If the value is 0, the cookie expires immediately. The maximum value is Integer.MAX_VALUE, where the cookie lasts forever. If set to -1, the cookie expires when the user exits the browser. For more information about cookies, see Using Sessions and Session Persistence in Web Applications on page 4-1.
CookieName
JSESSIONID
Defines the session cookie name. Defaults to JSESSIONID if not set. You may set this to a more specific name for your application. Specifies the path name to which the browser sends cookies. If not set, this attribute defaults to / (slash), where the browser sends cookies to all URLs served by WebLogic Server. You may set the path to a narrower mapping, to limit the request URLs to which the browser sends cookies.
CookiePath
Null
CookiesEnabled
true
Use of session cookies is enabled by default and is recommended, but you can disable them by setting this property to false. You might turn this option off to test.
B-7
Attribute Name
EncodeSessionIdInQueryParams
Default Value
false
Value
By default, when you use the HTTPServletResponse.encodeURL(UR L) method to encode a URL in the HTTP response, the session identifier is added to the URL as a path parameter after the ; character in the URL. This behavior is defined by the Servlet 2.3 J2EE specification, implemented as of Version 6.1 of WebLogic Server. In Versions 6.0 and previous of WebLogic Server, however, the default behavior was to add the session identifier as a query parameter after the ? character in the URL. To enable this old behavior, set this session parameter to true. Note: You typically use this parameter when WebLogic Server interacts with Web Servers that do not completely comply with the Servlet 2.3 specification.
IDLength
52
Sets the size of the session ID. The minimum value is 8 bytes and the maximum value is Integer.MAX_VALUE. If you are writing a WAP application, you must use URL rewriting because the WAP protocol does not support cookies. Also, some WAP devices have a 128-character limit on URL length (including attributes), which limits the amount of data that can be transmitted using URL re-writing. To allow more space for attributes, use this attribute to limit the size of the session ID that is randomly generated by WebLogic Server. You can also limit the length to a fixed 52 characters, and disallow special characters, by setting the WAPEnabled attribute. For more information, see URL Rewriting and Wireless Access Protocol in Developing Web Applications for WebLogic Server.
B-8
Default Value
60
Value
Sets the time, in seconds, that WebLogic Server waits between doing house-cleaning checks for timed-out and invalid sessions, and deleting the old sessions and freeing up memory. Use this attribute to tune WebLogic Server for best performance on high traffic sites. The minimum value is every second (1). The maximum value is once a week (604,800 seconds). If not set, the attribute defaults to 60 seconds.
JDBCConnectionTimeoutSecs
120
Sets the time, in seconds, that WebLogic Server waits before timing out a JDBC connection, where x is the number of seconds between. If you have set PersistentStoreType to file, this attribute sets the directory path where WebLogic Server will store the sessions. The directory path is an absolute path to the temp directory. The temp directory is specified by the context-param javax.servlet.context.tmpdir. Ensure that you have enough disk space to store the number of valid sessions multiplied by the size of each session. You can find the size of a session by looking at the files created in the PersistentStoreDir. Note that the size of each session can vary as the size of serialized session data changes. You can make file-persistent sessions clusterable by making this directory a shared directory among different servers. You must create this directory manually.
PersistentStoreDir
session_db
PersistentStorePool
None
Specifies the name of a JDBC connection pool to be used for persistence storage. Applies only when PersistentStoreType is set to jdbc. This is used when you choose a database table name other than the default.
PersistentStoreTable
wl_servlet_ sessions
B-9
Default Value
memory
Value
Sets the persistent store method to one of the following options:
memoryDisables persistent session storage. fileUses file-based persistence (See also PersistentStoreDir, above). jdbcUses a database to store persistent sessions. (see also PersistentStorePool, above). replicatedSame as memory, but session data is replicated across the clustered servers.
cookieAll session data is stored in a cookie in the users browser. replicated_if_clusteredIf the Web application is deployed on a clustered server, the in-effect PersistentStoreType will be replicated. Otherwise, memory is the default.
PersistentStoreCookieName
WLCOOKIE
Sets the name of the cookie used for cookie-based persistence. The WLCOOKIE cookie carries the session state, which should not be shared between Web applications. For more information, see Using Cookie-Based Session Persistence on page 4-9.
B-10
jsp-de scriptor
Default Value
3600
Value
Sets the time, in seconds, that WebLogic Server waits before timing out a session, where x is the number of seconds between a session's activity. Minimum value is 1, default is 3600, and maximum value is integer MAX_VALUE. On busy sites, you can tune your application by adjusting the timeout of sessions. While you want to give a browser client every opportunity to finish a session, you do not want to tie up the server needlessly if the user has left the site or otherwise abandoned the session. This attribute can be overridden by the session-timeout element (defined in minutes) in web.xml. For more information, see session-config on page A-11.
TrackingEnabled
true
Tells the Web application to keep track of the session between requests, in one of the following ways: SessionCookie URLEncoding If this is set to false, the session is not tracked, cookies coming in with the response are ignored, and the URL is not encoded.
URLRewritingEnabled
true
Enables URL rewriting, which encodes the session ID into the URL and provides session tracking if cookies are disabled in the browser.
jsp-descriptor
The jsp-descriptor element defines attribute names and values for JSPs. You define the attributes as name/value pairs. The following example shows how to configure the compileCommand attribute. Enter all of the JSP configurations using the pattern demonstrated in this example:
<jsp-descriptor> <jsp-param> <param-name>
B-11
The following table describes the element you can define within a jsp-descriptor element. Element
<jsp-param>
Required/ Optional
Required
Description
Specifies parameters for servlet JSPs. Contains the following sub-elements: <param-name> specifies a parameter name. <param-value> specifies a parameter value.
B-12
jsp-de scriptor
Default Value
javac, or the Java compiler defined for a server under the configuration /tuning tab of the WebLogic Server Administration Console
Value
Specifies the full path name of the standard Java compiler used to compile the generated JSP servlets. For example, to use the standard Java compiler, specify its location on your system as shown below:
<param-value> /jdk130/bin/javac.exe </param-value>
For faster performance, specify a different compiler, such as IBM Jikes or Symantec sj. Passes one or more command-line flags to the compiler. Enclose multiple flags in quotes, separated by a space. For example:
<jsp-param> <param-name>compileFlags</param-name> <param-value>"-g -v"</param-value> </jsp-param>
compileFlags
None
compilerclass
None
Name of a Java compiler that is executed in WebLogic Serverss virtual machine. (Used in place of an executable compiler such as javac or sj.) If this attribute is set, the compileCommand attribute is ignored. Note: JSPs can be complied either in memory (in process) or by forking a new process for the compilation.
A new process is forked when the compilerclass is not specified and production mode is the startup mode. The in memory compilerclass option uses the compiler class used by Sun to internally compile Java files. For more information see Precompiling JSPs at the following URL http://e-docs.bea.com/wls/docs81/jsp/reference.ht ml
debug None When set to true this adds JSP line numbers to generated class files to aid debugging.
B-13
Attribute Name
encoding
Default Value
Default encoding of your platform
Value
Specifies the default character set used in the JSP page. Use standard Java character set names (see http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.htm). If not set, this attribute defaults to the encoding for your platform. A JSP page directive (included in the JSP code) overrides this setting. For example:
<%@ page contentType="text/html; charset=custom-encoding%>
compilerSupports Encoding
true
When set to true, the JSP compiler uses the encoding specified with the contentType attribute contained in the page directive on the JSP page, or, if a contentType is not specified, the encoding defined with the encoding attribute in the jsp-descriptor. When set to false, the JSP compiler uses the default encoding for the JVM when creating the intermediate .java file.
exactMapping
true
When true, upon the first request for a JSP the newly created JspStub is mapped to the exact request. If exactMapping is set to false, the Web application container generates non-exact url mapping for JSPs. exactMapping allows path info for JSP pages. Saves the Java files that are generated as an intermediary step in the JSP compilation process. Unless this attribute is set to true, the intermediate Java files are deleted after they are compiled. If a JSP file has numerous or deeply nested custom JSP tags and you receive a java.lang.VerifyError exception when compiling, use this flag to allow the JSPs to compile correctly. Specifies the package into which all JSP pages are compiled.
keepgenerated
false
noTryBlocks
false
packagePrefix
jsp_servlet
B-14
a ut h- f i l ter
Attribute Name
pageCheckSeconds
Default Value
1
Value
Sets the interval, in seconds, at which WebLogic Server checks to see if JSP files have changed and need recompiling. Dependencies are also checked and recursively reloaded if changed. If set to 0, pages are checked on every request. This default is preset for a development environment. If set to -1, page checking and recompiling is disabled. In a production environment where cchanges to a JSP are rare, change the value of pageCheckSeconds to 60 or greater, according to your tuning requirements, or to -1 to disable page checking and recompiling.
precompile
false
When set to true, WebLogic Server automatically precompiles all modified JSPs when the Web application is deployed or re-deployed or when starting WebLogic Server. When set to true, WebLogic Server continues precompiling all modified JSPs even if some of those JSPs fail during compilation. Only takes effect when precompile is set to true. When set to false, this parameter ensures that expressions with null results are printed as . When set to true, debugging information is printed out to the browser, the command prompt, and WebLogic Server log file. The name of a directory where WebLogic Server saves the generated Java and compiled class files for a JSP. Sets the JSP compiler for use with this instance of WebLogic Server. Provides a means to override the default superclass for JSPs. The JSPs are compiled as servlet classes extending from this base class.
precompileContin ue printNulls
verbose workingDir
false
null
true
compiler
superclass
auth-filter
The auth-filter element specifies an authentication filter HttpServlet class.
B-15
container-descriptor
The <container-descriptor> element defines general attributes for Web applications.
check-auth-on-forward
Add the <check-auth-on-forward/> element when you want to require authentication of forwarded requests from a servlet or JSP. Omit the tag if you do not want to require re-authentication. For example:
<container-descriptor> <check-auth-on-forward/> </container-descriptor>
Note that the default behavior has changed with the release of the Servlet 2.3 specification, which states that authentication is not required for forwarded requests.
redirect-with-absolute-url
The <redirect-with-absolute-url> element controls whether the javax.servlet.http.HttpServletResponse.SendRedirect() method redirects using a relative or absolute URL. Set this element to false if you are using a proxy HTTP server and do not want the URL converted to a non-relative link. The default behavior is to convert the URL to a non-relative link. user readable data used in a redirect.
index-directory-enabled
The <index-directory-enabled> element controls whether or not to automatically generate an HTML directory listing if no suitable index file is found. The default value is false (does not generate a directory). Values are true or false.
index-directory-sort-by
The <index-directory-sort-by> element defines the order in which the directory listing generated by weblogic.servlet.FileServlet is sorted. Valid sort-by values are NAME, LAST_MODIFIED, and SIZE. The default sort-by value is NAME.
B-16
servlet-reload-check-secs
The <servlet-reload-check-secs> element defines whether a WebLogic Server will check to see if a servlet has been modified, and if it has been modified, reloads it. The -1 value tells the server never to check the servlets, 0 tells the server to always check the servlets, and the default is to check each 1 second. A value specified in the console will always take precedence over a manually specified value.
single-threaded-servlet-pool-size
The <single-threaded-servlet-pool-size> element defines the size of the pool used for SingleThreadMode instance pools. The default value is 5.
session-monitoring-enabled
The <session-monitoring-enabled> element, if set to true, allows runtime MBeans to be created for sessions. When set to false, the default value, runtime MBeans are not created. A value specified in the console takes precedence over a value set manually.
save-sessions-enabled
The <save-sessions-enabled> element controls whether session data is cleaned up during redeploy or undeploy. It affects memory and replicated sessions. Setting the value to true means session data is saved. Setting to false means session data will be destroyed when the Web application is redeployed or undeployed. The default is false.
prefer-web-inf-classes
The <prefer-web-inf-classes> element, if set to true, will cause classes located in the WEB-INF directory of a Web application to be loaded in preference to classes loaded in the application or system classloader. The default value is false. A value specified in the console will take precedence over a value set manually.
default-mime-type
The <default-mime-type> element default value is null. This element allows the user to specify the default mime type for a content-type for which the extension is not mapped.
B-17
retain-original-url
Set the <retain-original-url> element to true to retain the HTTP in the original URL you are requesting prior to being forwarded to the authentication URL. Once you login successfully using the authentication URL, you are then taken back to the exact URL that you had originally requested.
charset-params
The <charset-params> element is used to define code set behavior for non-unicode operations. For example:
<charset-params> <input-charset> <resource-path>/*</resource-path> <java-charset-name>UTF-8</java-charset-name> </input-charset> </charset-params>
input-charset
Use the <input-charset> element to define which character set is used to read GET and POST data. For example:
<input-charset> <resource-path>/foo</resource-path> <java-charset-name>SJIS</java-charset-name> </input-charset>
For more information, see Loading Servlets, Context Listeners, and Filters on page 3-18.
B-18
The following table describes the elements you can define within a <input-charset> element. Element
<resource-path>
Required/ Optional
Required
Description
A path which, if included in the URL of a request, signals WebLogic Server to use the Java character set specified by <java-charset-name>. Specifies the Java characters set to use.
<java-charset-name>
Required
charset-mapping
Use the <charset-mapping> element to map an IANA character set name to a Java character set name. For example:
<charset-mapping> <iana-charset-name>Shift-JIS</iana-charset-name> <java-charset-name>SJIS</java-charset-name> </charset-mapping>
For more information, see Mapping IANA Character Sets to Java Character Sets on page 3-20. The following table describes the elements you can define within a <charset-mapping> element. Element
<iana-charset-name>
Required/ Optional
Required
Description
Specifies the IANA character set name that is to be mapped to the Java character set specified by the <java-charset-name> element. Specifies the Java characters set to use.
<java-charset-name>
Required
virtual-directory-mapping
Use the virtual-directory-mapping element to specify document roots other than the default document root of the Web application for certain kinds of requests, such as image requests. All images for a set of Web applications can be stored in a single location, and need not be copied to the document root of each Web application that uses them. For an incoming request,
B-19
if a virtual directory has been specified servlet container will search for the requested resource first in the virtual directory and then in the Web applications original document root. This defines the precedence if the same document exists in both places. Example:
<virtual-directory-mapping> <local-path>c:/usr/gifs</local-path> <url-pattern>/images/*</url-pattern> <url-pattern>*.jpg</url-pattern> </virtual-directory-mapping> <virtual-directory-mapping> <local-path>c:/usr/common_jsps.jar</local-path> <url-pattern>*.jsp</url-pattern> </virtual-directory-mapping>
The following table describes the elements you can define within the virtual-directory-mapping element. Element
<local-path>
Required/ Optional
Required Required
Description
Specifies a physical location on the disk. Contains the URL pattern of the mapping. Must follow the rules specified in Section 11.2 of the Servlet API Specification.
<url-pattern>
The WebLogic Server implementation of virtual directory mapping requires that you have a directory that matches the url-pattern of the mapping. The image example requires that you create a directory named images at c:/usr/gifs/images. This allows the servlet container to find images for multiple Web applications in the images directory.
url-match-map
Use this element to specify a class for URL pattern matching. The WebLogic Server default URL match mapping class is weblogic.servlet.utils.URLMatchMap, which is based on J2EE
B-20
standards. Another implementation included in WebLogic Server is SimpleApacheURLMatchMap, which you can plug in using the url-match-map element. Rule for SimpleApacheURLMatchMap: If you map *.jws to JWSServlet then
http://foo.com/bar.jws/baz will be resolved to JWSServlet with pathInfo = baz.
preprocessor
The preprocessor element contains the declarative data of a preprocessor. The following table describes the elements you can define within the preprocessor element.
Element
<preprocessor-name> <preprocessor-class>
Required/ Optional
Required Required
Description
Contains the canonical name of the preprocessor. Contains the fully qualified class name of the preprocessor.
preprocessor-mapping
The preprocessor-mapping element defines a mapping between a preprocessor and a URL pattern. The following table describes the elements you can define within the preprocessor-mapping element.
B-21
Element
<preprocessor-name> <url-pattern>
Required/ Optional
Required Required
Description
security-permission
The security-permission element specifies a single security permission based on the Security policy file syntax. Refer to the following URL for Sun's implementation of the security permission specification: http://java.sun.com/j2se/1.3/docs/guide/security/PolicyFiles.html#FileSyntax Disregard the optional codebase and signedBy clauses. For example:
<security-permission-spec> grant { permission java.net.SocketPermission "*", "resolve" }; </security-permission-spec>
where:
permission java.net.SocketPermission is the permission class name. "*" represents the target name. resolve indicates the action.
context-root
The context-root element defines the context root of this stand-alone Web application. If the Web application is part of an EAR, not stand-alone, specify the context root in the EARs application.xml file. A context-root setting in application.xml takes precedence over context-root setting in weblogic.xml. Note that this weblogic.xml element only acts on deployments using the two-phase deployment model. See "Two-Phase Deployment" in Deploying WebLogic Server Applications. The order of precedence for context root determination for a Web application is as follows:
B-22 Developing Web Applications for WebLogic Server
wl- d i s p at c h - pol i c y
1. Check application.xml for context root; if found, use as Web applications context root. 2. If context root is not set in application.xml, and the Web application is being deployed as part of an EAR, check whether context root is defined in weblogic.xml. If found, use as Web applications context root. If the Web application is deployed standalone, application.xml does not come into play and the determination for context-root starts at weblogic.xml and defaults to URI if it is not defined there. 3. If context root is not defined in weblogic.xml or application.xmll, then infer the context path from the URI, giving it the name of the value defined in the URI minus the WAR suffix. For instance, a URI MyWebApp.war would be named MyWebApp.
wl-dispatch-policy
Use the wl-dispatch-policy element to assign the Web application to a configured execute queue by identifying the execute queue name.
servlet-descriptor
Use the servlet-descriptor element to aggregate the servlet-specific elements. The following table describes the elements you can define within the servlet-descriptor element. Element
<servlet-name>
Required/ Optional
Required Optional
Description
Specifies the servlet name as defined in the servlet element of the web.xml deployment descriptor file. Contains the name of a principal against the run-as-role-name defined in the web.xml deployment descriptor. Equivalent to run-as-principal-name for the init method for servlets. The identity specified here should be a valid user name in the system. If init-as-principal-name is not specified, the container uses the run-as-principal-name element.
<run-as-principal-na me>
<init-as-principal-n ame>
Optional
B-23
Element
<destroy-as-principa l-name>
Required/ Optional
Optional
Description
Equivalent to run-as-principal-name for the destroy method for servlets. The identity specified here should be a valid user name in the system. If destroy-as-principal-name is not specified, the container uses the run-as-principal-name element. This is a deprecated element. Used to assign a given servlet to a configured execute-queue by identifying the execute queue name. This setting overrides the Web application-level dispatch policy defined by wl-dispatch-policy.
<dispatch-policy>
Optional
init-as
This is an equivalent of <run-as> for init method for servlets. For example:
<init-as> <servlet-name>FooServlet</servlet-name> <principal-name>joe</principal-name> </init-as>
destroy-as
This is an equivalent of <run-as> for destroy method for servlets. For example:
<destroy-as> <servlet-name>BarServlet</servlet-name> <principal-name>bob</principal-name> </destroy-as>
B-24
Index
A
application events 5-2 appliction event listeners 5-2 event listeners configuring 5-4 events declaration 5-4 exploded directory format re-deployment 2-6
C
CGI 3-9 chaining filters 6-5 Configuration JSP tag libraries 3-7 servlets 3-1 cookies 4-2 URL rewriting 4-10 customer support contact information xv
F
filter class 6-2 filter mapping 6-4 to a servlet 6-5 URL pattern 6-4 filters and Web Applications 6-2 chaining 6-5 configuring 6-3 declaration 6-3 mappings 6-4 overview 6-1 uses 6-2 writing a filter class 6-2
D
default servlet 3-8 deployment options, for resource adapters 2-5 overview 2-2 deployment descriptor re-deployment 2-8 deployment descriptors basic conventions for manually editing 2-3 DOCTYPE header information 2-4 documentation, where to find it xiv doFilter() 6-3
H
HTTP session events 5-3 HTTP sessions 4-1 and redeployment 2-8
E
error pages 3-9 event listener declaration 5-4
I
init params 3-5 in-memory replication 4-4
Index-1
J
JSP modifying 2-8 refreshing 2-8 tag libraries 3-7
response 6-1
S
servlet configuration 3-1 default servlet 3-8 initialization parameters 3-5 mapping 3-2 url-pattern 3-2 servlet context events 5-2 session persistence file-based 4-5 JDBC (database) 4-6 single server 4-5 Session Timeout 4-2 sessions 4-1 cookies 4-2 persistence 4-4 Session Timeout attribute 4-2 setting up 4-1 URL rewriting 4-10 URL rewriting and WAP 4-11 support technical xv
L
listener writing a listener class 5-5 listener class 5-5 listeners 5-2 configuring 5-4 HTTP session events 5-3 servlet context events 5-2
M
manually editing XML deployment files 2-3 mapping filters 6-4 modifying components 2-8 modifying JSP 2-8
P
persistence for sessions 4-4 printing product documentation xiv
U
URL rewriting 4-10
R
REDEPLOY file 2-7 re-deployment 2-5 and HTTP sessions 2-8 exploded directory format 2-6 of Java classes 2-8 using REDEPLOY file 2-7 when using auto-deployment 2-5 refreshing JSP 2-8 resource adapters deployment options 2-5
Index-2 Developing Web Applications for WebLogic Server
W
WAP 4-11 Web Application configuring external resources 3-13 default servlet 3-8 error page 3-9 URI 1-8 WEB-INF directory 1-4 weblogic-ra.xml file manually editing XML deployment files 2-3 welcome pages 3-7
X
XML deployment files, manually editing 2-3
Index-3