Developing Web Applications for WebLogic Server

Deploying Web Applications

This chapter discusses the deployment of Web applications:

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.

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.

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 web.xml Deployment Descriptor Elements, and 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 Deployment Tools Reference in Deploying WebLogic Server Applications. For more information, see Using WebLogic Builder to Edit Deployment Descriptors.
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 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.

Using WebLogic Builder to Edit Deployment Descriptors

WebLogic Builder provides a visual environment for editing an application's deployment descriptor XML files. You can view these XML files as you visually edit them in WebLogic Builder, but you do not need to make textual edits to the XML files.

Use WebLogic Builder for the following development tasks:

Generate deployment descriptor files for a J2EE module
Edit a module's deployment descriptor files
View deployment descriptor files
Compile and validate deployment descriptor files
Deploy a module to a server

For instructions on using WebLogic Builder, refer to the WebLogic Builder documentation.

Manually Editing XML Deployment Files

To manually edit XML elements:

Make sure that you use an ASCII text editor that does not reformat the XML or insert additional characters that could invalidate the file.
Use the correct case for file and directory names, even if your operating system ignores the case.
To use the default value for an optional element, you can either omit the entire element definition or specify a blank value. For example:

<max-config-property></max-config-property>

DOCTYPE Header Information

When editing or creating XML deployment files, it is critical to include the correct DOCTYPE header for each deployment file. In particular, using an incorrect PUBLIC element within the DOCTYPE header can result in parser errors that may be difficult to diagnose.

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

XML files with incorrect header information may yield error messages similar to the following, when used with a utility that parses the XML (such as appc):

SAXException: This document may not have the identifier `identifier_name'

identifier_name generally includes the invalid text from the PUBLIC element.

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">

Dynamic Descriptor Updates

This release of WebLogic Server has deprecated the Administration Console Deployment Descriptor Editor. A new Descriptor tab in the Administration Console has replaced it. The Descriptor tab is intended for administrative purposes.

Using the Descriptor tab, you can view, modify, and persist deployment descriptor elements to the descriptor file within the Web application. You can also the apply descriptor file changes to the deployed application on all its targets.

However, these changes take effect dynamically at runtime without requiring the Web application to be redeployed. The descriptor element attributes contained in the Descriptor tab are limited to only those that may be dynamically changed at runtime. These include the following:

Session Cookie Max Age Secs—The life span of the session cookie, in seconds, after which it expires on the client.
Session Invalidation Interval Secs—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.
Session Timeout Secs—The amount of time (in seconds) that a session can remain inactive before it is invalidated.
Servlet Reload Check Secs—The 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 Size—The size of the pool used for single-threaded mode servlets.
Index Directory Enabled—Specifies whether the target should automatically generate an HTML directory listing if no suitable index file is found.
Session Monitoring Enabled—Specifies whether runtime MBeans will be created for session monitoring.
JSPPage Check Secs—The interval, in seconds, at which WebLogic Server checks to see if JSP files have changed and need recompiling.
JSPKeep Generated—Specifies whether to save the Java files that are generated as an intermediary step in the JSP compilation process.
JSPVerbose—Specifies whether to print debugging info to the browser during compilation.
Enable JSP Line Numbers—Specifies 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

For more information on these tools, see Deployment Tools Reference in Deploying WebLogic Server Applications.

Deployment Guidelines for Web Applications

The following sections provide some guidelines that are specific to deploying Web applications.

Deploying Web Applications as Part of an Enterprise Application

For both production and development purposes, BEA recommends that you package and deploy your stand-alone Web applications, EJBs, and resource adapters as part of an Enterprise application. This practice allows for easier application migration, additions, and changes. For example, to add more than one Web application, EJB, or resource adapter module to an application, you must package the modules in an Enterprise application. Packaging and deploying stand-alone applications in an Enterprise application from the start saves you a lot of time. It also allows you to take advantage of the split development directory structure, which provides a number of benefits over the traditional single directory structure.

For more information, see Creating WebLogic Server Applications in Developing WebLogic Server Applications.

Auto-Deployment of Web Applications

When WebLogic Server is running in development mode, Web applications that are copied into the applications/ directory are automatically deployed. In addition, modifications to files within these applications can trigger either partial or full redeployment.

Auto-deployment of the applications/ directory is intended for iterative development (not for production) and only for single server (specifically, the Administration Server). That is, applications deployed using the applications/ directory should not be targeted to servers other than the Administration Server.

Redeploying a Web Application in Exploded Directory Format

When a Web application is deployed in exploded directory format, redeployment is affected by changing specific files within the directory structure. If the Web application is deployed using auto-deployment, you must modify a special file named REDEPLOY, which is located in the WEB-INF/ directory of your Web application, to redeploy the entire application.

Modifying individual files of an exploded Web application can cause partial redeployment of the Web application, depending on the files you changed. For example, modifying servlets or other classes in the WEB-INF/classes directory can cause the associated classloader to be replaced, 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 weblogic.xml Deployment Descriptor Elements.

To re-deploy an entire auto-deployed Web application in exploded directory format, modify the REDEPLOY file:

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.)

Open the REDEPLOY file, modify the contents (this modification can be as simple as adding a space character in the file contents—any 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.

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.

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.

Using Command Line Deployment

You use command line deployment for applications that are not auto-deployed. This includes any applications that are deployed from locations other than the applications/ directory. In 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.

Refreshing Static Components

BEA recommends that you use the weblogic.Deployer utility to refresh static components (such as JSP files, HTML files, image files, and so on). For information about the weblogic.Deployer utility, see Deployment Tools Reference in Deploying WebLogic Server Applications.

Deploying Multiple Web Applications

In order to deploy multiple Web applications, context roots must be unique. For example, /test-1, /test-2, and so on. This prevents the context root display for Web application modules from becoming corrupted as the number of Web application modules grows.