Writing a Web Application
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:
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.
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:
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 weblogic.properties file:
All other configuration for your Web Application is described in the deployment descriptors.
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 + pathInfoWhere 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 http://www.beasys.com. A file called index.html in its document root is accessed via the URL http://www.beasys.com/catalog/index.html. 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.
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:
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 scopeThe 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:
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 weblogic.properties file, except that they only set properties for their associated Web Application. The following properties are defined in the deployment descriptor:
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:
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 1.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">This refers to the location and version of the DTD file of the deployment descriptor. Although this header references an external URL at java.sun.com, 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:
<web-app> ... body defining the Web Application ... </web-app>
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.
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.
Setting up HTTP propertiesTo 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 weblogic.properties file do not affect the behavior of a Web Application.
An exception is the MIME types set up in the weblogic.properties 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 weblogic.properties 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 weblogic.properties file. It involves two steps:
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 weblogic.properties 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:
Here is an example servlet declaration using the above tags:
<servlet> <servlet-name>LoginServlet</servlet-name> <servlet-class<admin.servlets.Login</servlet-class> <init-param> <param-name>webmaster</param-name> <param-value>firstname.lastname@example.org</param-value> </init-param> </servlet>
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.
Here is an example of a <servlet-mapping> for the <servlet> declaration example we used earlier:
<servlet-mapping> <servlet-name>LoginServlet </servlet-name> <url-pattern>/login</url-pattern> </servlet-mapping>
Configuring HTTP Session behavior<session-config>
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 weblogic.properties file. For information on setting up default MIME types, see the Administrators Guide Setting up WebLogic as an HTTP server.
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.
Defining Web Application properties
Defining context parameters<context-param>
Here is an example definition of a context parameter:
<context-param> <description> This parameter defines the email address of the webmaster </description> <param-name>Webmaster</param-name> <param-value>email@example.com</param-value> </context-param>
Reserved context parameter names
All context parameter names beginning with "weblogic." are reserved for WebLogic Server related properties. For example:
<context-param> <param-name>weblogic.servlet.reloadCheckSecs</param-name> <param-value>10</param-value> </context-param>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:
Locating a JSP Tag Library Descriptor<taglib>
Identifying external resources
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.
Setting environment entries
Identifying EJB resources
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
Copyright © 2000 BEA Systems, Inc. All rights reserved.