BEA Logo BEA WebLogic Server Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

Writing a Web Application

I. Introduction
What is a Web Application?
II. Developing a Web Application
Directory structure
The ServletContext
Using deployment-time configuration
Initialization parameters
III. The deployment descriptor
Creating a deployment descriptor
Deployment-time properties
Setting up HTTP properties
Declaring a servlet
Mapping a servlet or JSP to a URL
Configuring HTTP Session behavior
Defining MIME types
Defining welcome and error pages
Defining Web Application properties
Defining context parameters
Locating a JSP Tag Library Descriptor
Identifying external resources
Setting up security constraints
Setting environment entries
Identifying EJB resources
IV. Packaging a Web Application

Related documents
Using WebLogic HTTP Servlets
Using WebLogic JSP

I. Introduction

This document describes how to write a Web Application for the WebLogic Server. It outlines the differences between developing a regular web-based application for the WebLogic Server, and developing a Web Application as defined by the Java Servlet Specification v2.2.

What is a Web Application?

"Web Application" is a term defined by the Java Servlet Specification v2.2 to describe the set of server-side resources that make up the interactive interface of an online application. These resources include:

  • Servlets
  • JavaServer Pages
  • HTML pages
  • Server side classes
  • Other resources specific to the web application
The specification defines how these resources can be packaged into a portable "Web Application aRchive" (WAR) file so they may be deployed on an application server that supports the WAR standard. A Web Application operates within a Servlet Context, that defines an environment that is separated from other Web Applications running on the same server. Each Web Application is accompanied by a deployment descriptor that ties its resources together, and describes how they are deployed on the WebLogic Server -- or another Servlet2.2 compliant application server.

The J2EE specification goes defines how a Web Application relates to the other server-side resources such as Enterprise JavaBeans, so as to constitute an entire J2EE compliant application.

WebLogic Server supports the Servlet v2.2 specification and can host multiple Web Applications.

II. Developing a Web Application

A Web Application must follow certain guidelines in order to be archived into a WAR file, or be deployed on a Servlet2.2 compliant server. The scope of a Web Application concentrates on defining the HTTP interface and logical presentation of the application.

Each Web Application is accompanied by a deployment descriptor that describes how the application is deployed on the host server. A well designed Web Application can be implemented in such a way that it is abstracted from the physical configuration or the location of external resources on the web server. The deployment descriptor can then be used to adapt the application to the environment of a host server at deployment time without the need to recompile or change any servlet source code.

Directory structure

You must develop your Web Application within a specified directory structure so that it may be archived and deployed on the WebLogic Server, or another Servlet2.2 compliant server. All servlets, classes, static files, and other resources belonging to a Web Application are organized under a directory hierarchy. The root of this hierarchy defines the document root of your Web Application. All files under this root directory may be served to the client, except for files under the special directories WEB-INF and META-INF located in the root directory.

Private files should be located under the WEB-INF directory, that is located in the root directory. All files under WEB-INF are private, and will not be served to a client. The WEB-INF directory should contain the following files:

The Web Application deployment descriptor that configures the web application.
Contains server-side classes such as HTTP servlets and utility classes
Contains .jar files used by the Web Application

Deploying on WebLogic

You may deploy the Web Application as an expanded directory hierarchy (described above), or in an archived format as a .war file on the WebLogic Server. It is useful to deploy the Web Application as an expanded set of directories during development, then deploy it as an archived war file to a production environment.

To deploy a Web Application on the WebLogic Server, add the following property to the file:

Is the context name given to the Web Application. The context name is included in the initial part of any URL request to the Web Application.
Is the root directory of the Web Application, or the location of the .war file that contains the Web Application archive.

All other configuration for your Web Application is described in the deployment descriptors.

The ServletContext

Each Web Application runs within a separate context that isolates it from other Web Applications on the host server. All servlets within a Web Application have access to shared information and resources via the ServletContext object.

Note that the scope of a ServletContext is only shared by a Web Application per VM. That is, the ServletContext is not shared by servlets deployed from the same Web Application running on different servers in a WebLogic Cluster. Some other mechanism must be used to share data between Web Applications in a WebLogic Cluster, such as a shared database.

The context path

A Web Application's context is always reflected in the URL used to access it. The Servlet 2.2 specification breaks a URL into the following components:

 requestURI = contextPath + servletPath + pathInfo
Where the contextPath is the context name of the Web Application. This provides a new challenge for inter-referencing web pages within the same Web Application.

For example, consider a Web Application operating within a context path named catalog on a WebLogic Server running at the address A file called index.html in its document root is accessed via the URL All absolute requests to pages or servlets within the Web Application must contain the contextPath.

The above property implies that your web pages and servlets must make careful reference to other pages within the Web Application. If you want your Web Application to be truly portable, you cannot assume the name of the servlet context. This implies that all static HTML pages should only make relative references to other pages and servlets within the Web Application.

Your dynamic pages can be more flexible since they can obtain the servlet context name and the host address via the Servlet2.2 API, then use them to build dynamic absolute links to resources in the same Web Application.

Your servlets can obtain the contextPath portion of the URI using the getContextPath() method of the HttpServletRequest. Another useful method is getRequestURI(), which returns the URI that was used to request this servlet or JSP page.

Using deployment-time configuration

A major theme around the J2EE programming model is to avoid hard coding the addresses of the resources that your application uses. This is further extended in the Web Application concept with the introduction of the deployment descriptor. Many deployment-time variables can be configured in the deployment descriptor that may be accessed and incorporated into the logic of the servlets in your Web Application.

Initialization parameters

You can use initialization parameters in your Web Application to configure its behavior from the deployment descriptor at deployment time. For instance, you might use them to configure a particular table in a database, or the email address of a web-master for the Web Application.

There are two scopes for accessing initialization parameters, at the Web Application level, and at a per-servlet level.

Web Application scope

The ServletContext provides access to initialization parameters that are shared by all servlets in the Web Application. The ServletContext provides the following methods for retrieving initialization parameters:

  • public String getInitParameter(String parameterName);
  • public Enumeration getInitParameterNames();
You configure initialization parameters in the deployment descriptor using <context-param> elements.

The syntax for setting context parameters is described in more detail later under Defining context parameters. Note that WebLogic reserves all parameter names beginning with "weblogic." to configure WebLogic specific functionality. For more details, see Reserved context parameter names.

Per-servlet scope

The base class GenericServlet provides access to initialization parameters defined on a per-servlet scope. Note that an HttpServlet extends GenericServlet. You access the parameters via the following methods:
  • public String getInitParameter(String parameterName);
  • public Enumeration getInitParameterNames();
You configure initialization parameters in the deployment descriptor using <init-param> elements nested within a <servlet> element.

Be careful not to confuse the Web-Application-scope initialization parameters accessed via ServletContext with the servlet-scope initialization parameters illustrated here.

II. The deployment descriptor

You must include a deployment descriptor with your Web Application to describe how it is deployed onto the WebLogic Server. The deployment descriptor sets up many properties similar to those defined in the file, except that they only set properties for their associated Web Application. The following properties are defined in the deployment descriptor:

  • Servlet / JSP definitions and mappings
  • Session configuration
  • Initialization parameters
  • MIME type mappings
  • Welcome file list
  • Error pages
  • Security

Creating a deployment descriptor

The deployment descriptor is a simple text file, formatted using XML notation. Use a text editor to create a deployment descriptor file called web.xml under the WEB-INF directory.

The web.xml file must begin with the following header:

 "-//Sun Microsystems, Inc.//DTD Web Application 1.2//EN"
This refers to the location and version of the DTD file of the deployment descriptor. Although this header references an external URL at, The WebLogic Server contains its own copy of the DTD file, so your host server need not have access to the internet. However, you must still include this DOCTYPE element in your web.xml file, and have it reference the external URL since the version of the DTD is used to identify the version of this deployment descriptor.

The main body of the web.xml file is wrapped within a pair of opening and closing <web-app> tags, after the pattern:

  ... body defining the Web Application ...

In XML, properties are defined by surrounding a property-value (or body) with opening and closing tags as shown above. The opening tag, the body, and the closing tag are collectively called an element. Some elements do not use the surrounding tags, but instead use a single tag that contains attributes; called an empty-tag.

The body of the <web-app> element contains numerous elements that configure how the Web Application will run on the WebLogic Server. All of this information is described using an XML DTD file. However, this is not a friendly format, so we describe the tags in the rest of this document with most information on each tag's purpose. Note that the order of the tag elements within the file must follow the order specified in the DTD file. This ordering is reflected in this document, but you should refer to the DTD for the exact specification on Sun's website at:

Where an element contains other nested elements, this document illustrates the nested elements by indenting them with a blue line.

Deployment-time properties

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

<small-icon> iconfile </small-icon>
(Optional) Names a 16x16 pixel .gif or .jpg image to represent the Web Application. Currently, this is not used by WebLogic.
<large-icon> iconfile.gif </large-icon>
(Optional) Names a 32x32 pixel .gif or .jpg image to represent the Web Application. Currently, this is not used by WebLogic.
<display-name> application-name </display-name>
(Optional) Gives the Web Application a name.
<description> descriptive-text </description>
(Optional) Verbose description of the Web Application.
(Optional) Currently, this element is not used by the WebLogic Server and does not affect the deployment of a Web Application.

Setting up HTTP properties

To make your HTTP servlets accessible to a web browser, you first declare them in the deployment descriptor, then map them to a URL pattern. The scope of the servlet declarations and mappings in the deployment descriptor are specific to this Web Application. That is, properties configured in the file do not affect the behavior of a Web Application.

An exception is the MIME types set up in the file (the default servlet context) are inherited by all Web Application servlet contexts. For details on defining MIME types for a particular servlet context, see Defining MIME types. For detail on setting MIME types in the file, see Setting standard MIME types.

The convention used to declare a servlet and map it to a URL pattern in the deployment descriptor is different from the approach used in the file. It involves two steps:

  1. You declare the servlet. In this step, you give the servlet a name, declare the class file (or jsp file) used to implement its behavior, and set other servlet-specific properties.
  2. You then map your named servlet to one or more URL patterns.

It is possible to treat a JSP file as a servlet and exercise the same degree of configuration over individual JSP files; see the next section for more details.

Declaring a servlet

In the deployment descriptor, you declare a <servlet> to represent each HTTP servlet class or JSP file. The servlet declaration configures several properties specific to that servlet resource. As we mentioned above, you use a separate set of tags to map a <servlet> declaration to a URL pattern for an HTTP request.

JSP files may be requested using their file name. You do not need to map the JSPServlet explicitly in a Web Application as you would in the file. All files with the extension .jsp are implicitly handled by the JSPServlet -- the Servlet 2.2 specification states that JSP files should be handled automatically. However, an explicit JSP mapping in web.xml will take precedence over the implicit mapping.

Use the following opening and closing tags to declare a servlet:


Use a <servlet> tag to declare each servlet in your Web Application. The servlet tag body is defined by the following nested tags:

(Required) Defines the canonical name of the servlet, used to reference the servlet definition elsewhere in the deployment descriptor.

(Required) The full package name of the HTTP servlet class, or the name of a JSP file. You must use only one of these tags in your servlet body. If you specify the <jsp-file>, its location should be relative to the Web Application root directory.

(Optional) Defines an initialization parameter for the servlet at this scope. You may use a separate set of <init-param> tags for each parameter. The body is constructed of the following tags:

(Required) Defines the name of this parameter.
(Required) Defines a String value for this parameter.
(Optional) A verbose description of the initialization parameter.

Here is an example of an initialization parameter, within some <servlet> tags.

    <param-name> feedbackEmail </param-name>
    <param-value> </param-value>
      The email for web-site feedback.

(Optional) This property is not honored by WebLogic Server in this release.

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

(Optional) Verbose description of the role.
(Required) Defines the name of the security role or principal that is used in the servlet code.
(Required) Defines the name of the security role that is defined in a <security-role> element later in the deployment descriptor.

(Optional) Names a 16x16 pixel .gif or .jpg image to represent the servlet. Currently, this is not used by the WebLogic Server.

(Optional) Names a 32x32 pixel .gif or .jpg image to represent the servlet. Currently, this is not used by the WebLogic Server.

<display-name>My Servlet</display-name>
(Optional) Gives the servlet a name , where ApplicaitonName is the name of your Web Application.

(Optional) Verbose description of the servlet.


Here is an example servlet declaration using the above tags:


Mapping a servlet or JSP to a URL

Once you have declared your servlet or JSP using a <servlet> element, you map it to one or more URL patterns to make it a public HTTP resource. For each mapping, use a <servlet-mapping> element.

(Optional) A servlet-mapping element defines the mapping between a servlet and a URL pattern. The body of the element contains the following nested elements:
(Required) You must declare 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 in the same deployment descriptor.

(Required) Describes a pattern used to resolve requested URLs to identify a registered servlet to handle the request. The rules for resolving a pattern are clearly defined in section 10 of the Servlet 2.2 specification.

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

  <servlet-name>LoginServlet </servlet-name>

Configuring HTTP Session behavior

(Optional) Configures the behavior of HTTP sessions in your Web Application. Takes the following nested element:
(Optional) Defines the time that an inactive session remains valid in minutes.

Defining MIME types

MIME types are used to tell the web browser how to handle a page's content. You use a <mime-type> element to map a file extension to a well known MIME type. You can use this to alter the way browsers see a particular type of file in your Web Application. For instance, you may want to serve .java source files as plain text.

Your Web Application also inherits MIME types from the default context. That is, the MIME types configured from the file. For information on setting up default MIME types, see the Administrators Guide Setting up WebLogic as an HTTP server.


(Optional) Defines a mapping between a file extension and a MIME type. The body of this element must contain the following nested elements:
(Required) Where ext is the extension of the file. The extension specified is not preceded with a dot.
(Required) Where type is the well known MIME type assigned to files ending with the extension ext.

Defining welcome and error pages

These elements define what the Web Application should do in a case where the requested URL does not map to a specific file.


(Optional) A welcome-file is served when a browser requests a URL that resolves to a directory, but cannot be resolved to a servlet. If a file matching the filename of a welcome-file exists in the requested directory, that file is served back to the client. A typical welcome-file name is index.html, and might be included in some directories to prevent the client a from receiving a directory listing.

The <welcome-file-list> defines all welcome files for this Web Application.

(Required) You use one or more <welcome-file> elements to list each filename that the Web Application recognizes as a welcome-file.


(Optional) Allows you to configure the Web Application to respond with a given file in the event of an error. You may configure error pages in response to Java exceptions or HTTP error codes such as #404 File-not-found.
(Required or use <exception-type>) Sends the
(Required or use <error-code>)

Defining Web Application properties

The following parameters are related to the entire Web Application.

Defining context parameters

(Optional) Specifies a parameter that may be accessed by any servlet within the Web Application servlet context (see Initialization parameters above). You use context parameters to allow custom parts of your Web Application to be configured at deployment time. You may use multiple <context-param> tags; Each one defines a single parameter using these nested tags:
(Required) The name of the parameter.
(Required) The String value of the parameter.
(Optional) A description of the parameter purpose.

Here is an example definition of a context parameter:

    This parameter defines the email address of the webmaster

Reserved context parameter names

All context parameter names beginning with "weblogic." are reserved for WebLogic Server related properties. For example:

Setting this context parameter will configure the WebLogic Server to wait the given number of seconds between checking for modified servlet classes. This reserved context parameter is also available to your servlets in the same way as non-reserved context parameters via the ServletContext.getInitParameter() method. For details on accessing context parameters and servlet parameters from your servlets and JSP pages, see the section Using deployment-time parameters.

These are reserved WebLogic context parameter names and their function:

Where the <param-value> gives the interval in seconds that WebLogic checks for modified servlet classes. For more details on this property see the equivalent property in the file in the Administrators Guide under Reloading servlet classes

Where the <param-value> specifies the fully qualified class name of a servlet that is used to handle a URL request that cannot be resolved to any other servlet. For more details on the default servlet, see the Administrators Guide, "Setting WebLogic Properties" section Setting a default servlet.

Where the <param-value> redefines the location of the document root for this servlet context. The default document root is the root directory of the Web Application.

Where the <param-value> redefines the servlet classpath where the Web Application loads its servlet classes from. This defaults to the WEB-INF/classes directory. This classpath is treated by the WebLogic Server as the equivalent to the servlet classpath.

Locating a JSP Tag Library Descriptor

(Optional) Associates the location of a JSP Tag Library Descriptor (TLD) with a URI pattern. This level of indirection allows the location of the TLD to be configured at deployment time. In fact, the JSP page can directly reference the TLD relative to the WEB-INF directory without using this element, but it is advised to use this level of indirection for flexibility during deployment. Use a separate element for each TLD. The URI pattern and the TLD location are defined by the following elements:
(Required) Gives a string pattern. This is matched against the URI string used in the JSP page, in the taglib directive, such as:
<%@ taglib uri="string_pattern" prefix="taglib" %>

For more details, see the Developers Guide,
"Writing JSP extensions".

(Required) Gives the filename of the tag library descriptor relative to the document root. That is, the root directory of the Web Application. It is wise to store the tag library descriptor file under the WEB-INF directory so it is not available over HTTP request.

Identifying external resources


(Optional) 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 wired 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.

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

<res-type>Java class</res-type>
(Required) The Java type of the resource that corresponds to the reference name. Use the full package name of the Java type.

<res-auth> CONTAINER | SERVLET</res-auth>
(Required) Used to control the resource sign-on for security.

Setting up security constraints

A Web Application that uses security requires the user to login in order to access its resources. The user's credentials are verified against a security realm, and once authorized, the user has access to specific url resources within the Web Application.

Security in a Web Application is configured using three elements. The <login-config> element specifies how the user is prompted to login and the location of the security realm. If this element is present, the user must be authenticated in order to access any resource in the web application. A <security-constraint> is used to define the access privileges to a collection of resources via their URL mapping. A <security-role> element represents a group or principal in the realm. This security role name is used in the <security-constraint> element and can be linked to an alternative role name used in servlet code via the <security-role-ref> element.


(Optional) This element contains the following nested elements. You may use one or more of these elements to define access privileges on certain resources in the Web Application.


(Required) Each <security-constraint> element must have one or more <web-resource-collection> elements. These define the area of the Web Application that this security constraint is applied to.
(Required) You must give this group of web resources a name so that it may be identified.

(Optional) A verbose description of this security constraint.

(Optional) You may use one or more of these elements to declare which URI patterns that this security constraint applies to. Please see the Servlet2.2 specification for a description of how to construct the URI pattern. If you do not use at least one of these elements, this <web-resource-collection> is ignored by WebLogic.

<http-method>GET | POST</http-method>
(Optional) You may use one or more of these elements to declare which HTTP methods are subject to the authorization constraint. If you omit this element, the default behavior is to apply the security constraint to all HTTP methods.


(Optional) Use this element to define which groups or principals have access to the collection of web resources defined in this security constraint.
(Optional) A verbose description.

<role-name>group | principal</role-name>
(Optional) This is the user principal or group defined in the security realm associated with the <login-config> element.


(Optional) This element defines how the client should communicate with the server.
(Optional) A verbose description.

<transport-guarantee>NONE | INTEGRAL | CONFIDENTIAL</transport-guarantee>
(Optional) The following description is taken from the servlet2.2 specification ...

Where NONE means that the application does not require any transport guarantees. A value of INTEGRAL means that the application requires that the data sent between the client and server be sent in such a way that it can't be changed in transit. CONFIDENTIAL means that the application requires that the data be transmitted in a fashion that prevents other entities from observing the contents of the transmission. In most cases, the presence of the INTEGRAL or CONFIDENTIAL flag will indicate that the use of SSL is required.




(Optional) This element configures how the user is authenticated. If this element is present, the user must be authenticated in order to access any resource in the Web Application. Once authenticated, they may be authorized to access other resources with access privileges.

<auth-method>BASIC | FORM | CLIENT-CERT</auth-method>
(Optional) Specifies the method used to authenticate the user.

(Optional) The name of the realm that is referenced to authenticate the user credentials. If omitted, the WebLogic realm is used by default.

(Optional) Use this element if you configure the <auth-method> to FORM.
(Required) 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 that conforms to a specific naming convention.


(Required) The URI of a web resource relative to the document root, sent to the user in response to a failed authentication login.


(Optional) Use one or more of these elements to declare user roles.

(Optional) A verbose description of this security role

(Optional) The role name.

Setting environment entries


(Optional) Used to declare an environment entry for an application. Use a separate element for each environment entry.
(Optional) A textural description.

(Required) The name of the environment entry.

(Required) The value of the environment entry

(Required) The type of the environment entry. Can be set to one of the following standard Java types:
  • java.lang.Boolean
  • java.lang.String
  • java.lang.Integer
  • java.lang.Double
  • java.lang.Float

Identifying EJB resources


(Optional) Defines a reference to an Enterprise JavaBean resource, allowing a virtual JNDI name used in the servlet code to be wired to the actual location of the EJB at deployment time. Use a separate <resource-ref> element to define each reference EJB name. The external EJB lookup name is mapped to the actual JNDI location at deployment time in the WebLogic-specific deployment descriptor weblogic.xml.

(Optional) A textural description.

(Required) The name of the EJB used in the JNDI Tree. Servlets in the Web Application use this name to look-up a reference to the EJB.

<ejb-ref-type>Entity | Session</ejb-ref-type>
(Required) The type of the EJB. Use either Entity or Session.

(Required) The fully qualified class name of the EJB home interface.

(Required) The fully qualified class name of the EJB remote interface.

(Optional) The ejb-name of an EJB in an encompassing J2EE application package.

IV. Packaging a Web Application

Packaging a Web Application involves creating an archive .war file that can be ported to another application server.

The WebLogic Server can host a Web Application from a .war file or from an unpacked directory structure from a .war file. The ability to run the Web Application from the unpacked directory structure is useful during development. The ability to create a .war archive is useful for transferring your Web Application from a development environment to a live production environment.

To create a .war archive, you must structure your Web Application as described in the section Directory structure.

Open a command shell, and change to the root directory of your Web Application. In this example, we assume that your Web Application is called myapp for this example, and that it is located in the directory /weblogic/myserver/myapp.

In the command shell, ensure that you have a JDK in your path. Now, run the following commands (given here for NT):

 $  cd C:\weblogic\myserver\myapp
 $  jar cf myapp.war *

The manifest file created as part of the JAR file and any other files under the META-INF directory will not be accessible when deployed on the WebLogic Server. For more information on packaging and signing JAR files, see the Java Tutorial section on JAR files.


Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.
Last updated 12/30/1999