Avitek Medical Records Development Tutorials

Developing the MedRec Applications

Tutorial 8: Walkthrough of Web Application Deployment Descriptors

This tutorial examines the deployment descriptor files that define the resources and operating attributes of the MedRec Web applications.

Like most WebLogic Server Web Applications, each MedRec Web application uses two deployment descriptor files, web.xml and weblogic.xml. These files reside in the WEB-INF folders that are part of the directory structure of WebLogic Server Web Applications.

A web.xml deployment descriptor file is a J2EE standard XML document that sets properties for a Web Application. These properties are defined by the Servlet 2.4 Deployment Descriptor XML Schema.

A weblogic.xml deployment descriptor file is an XML document that defines WebLogic Server-specific properties for Web applications. These properties are defined by the XML Schema at http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd.

MedRec's Web Applications are developed using Struts, which is an open source Web framework developed by the Apache Struts. The Struts framework has its own configuration file, called struts-config.xml, located in the same directory as the Web application deployment descriptor (WEB-INF). This configuration file is defined by the Struts 1.2 DTD. These tutorials do not describe the Struts framework; for more information, see the Apache Struts site.

The tutorial includes the following sections:

Prerequisites

Before starting this tutorial:

Create the MedRec domain and MedRec server. See Tutorial 1: Creating a WebLogic Domain and Server Instance for Development.
Create the MedRec project directory. See Tutorial 5: Creating the MedRec Project Directory.
Read about MedRec's split directory structure. See Tutorial 7: Compiling Split Development Directory Applications with Ant Tasks.

Procedure

The following procedure walks you through the contents of the web.xml and weblogic.xml files.

Step 1: Examine a web.xml file.

In this section, examine how the web.xml file from mainWebApp Web Application (of the medrecEar Enterprise application) configures mainWebApp's resources. mainWebApp responds to HTTP requests in MedRec, either creating HTTP responses or forwarding requests to other Web components.

web.xml can define following attributes for a Web Application:

Register servlets
Define servlet initialization attributes
Register JSP tag libraries
Define security constraints
Define other Web Application attributes

In a text editor, open the web.xml file that configures mainWebApp:

prompt> notepad c:\medrec_tutorial\src\medrecEar\mainWebApp\WEB-INF\web.xml

Note the required element in the heading of the file, which sets the version and encoding:

<?xml version="1.0" encoding="UTF-8"?>

The elements described in the following steps reside within the web-app element that they modify.

<web-app xmlns:j2ee="http://java.sun.com/xml/ns/j2ee">

....

</web-app>

Note the registration of servlets in web.xml. The servlet element and its servlet-class attributes set the name of the servlet and the location of the compiled class that executes the servlet.

The following listing names a servlet called action and associates it with a class: <servlet> <servlet-name>action</servlet-name> <servlet-class> org.apache.struts.action.ActionServlet </servlet-class>

The init-param attribute is part of the servlet element; in this case, of the servlet defined in the previous step. The servlet reads its init-param values when it is invoked.

<init-param>
  <param-name>config</param-name>
  <param-value>/WEB-INF/struts-config.xml</param-value>
</init-param>

The servlet-mapping element determines how the MedRec application invokes a servlet.

<servlet-mapping>
  <servlet-name>action</servlet-name>
  <url-pattern>*.do</url-pattern>
</servlet-mapping>

The welcome-file-list element defines the Web application's welcome files.

<welcome-file-list>
  <welcome-file>index.jsp</welcome-file>
</welcome-file-list>

The taglib child element of the jsp-config element defines the tag libraries that are available to the application:

<taglib>
  <taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
  <taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
</taglib>

See web.xml Deployment Descriptor Elements in Developing Web Applications for WebLogic Server for a description of the other elements in the web.xml file, such as filter and filter-mapping.

Step 2: Examine a weblogic.xml file.

In this section, examine the contents of the weblogic.xml file that configures the physicianWebApp of the physicianEar application. Physicians and nurses log in to the physician Web Application to search and access patient profiles, create and review patient medical records, and prescribe medicine to patients.

A WebLogic Server Web Application's weblogic.xml file can set, among other things, the following major properties:

JSP properties
JNDI mappings
Context root
URL mappings
Security role mappings
HTTP session attributes

In a text editor, open the weblogic.xml file that configures physicianWebApp:

prompt> notepad  c:\medrec_tutorial\src\physicianEar\physicianWebApp\WEB-INF\weblogic.xml

Note the heading that sets the encoding and references the location of the XML Schema file:

<?xml version="1.0" encoding="UTF-8"?>

<weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90">

This URL is the directory that contains the current WebLogic Server 9.1 XML Schema for Web Applications.

The elements and attributes in the weblogic.xml file are members of the weblogic-web-app element that opens and closes every instance of weblogic.xml:

<weblogic-web-app>

....

</weblogic-web-app>

The session-descriptor element contains session parameters for the Web Application's servlet sessions. The names of the child elements are defined in weblogic-web-app.xsd, whose values can be set within the same session-descriptor element:

  <session-descriptor>
    <timeout-secs>600</timeout-secs>
    <invalidation-interval-secs>60</invalidation-interval-secs>
    <persistent-store-type>
       replicated_if_clustered
    </persistent-store-type>
  </session-descriptor>

The timeout-secs child element sets the number of seconds the server waits before timing out a session.
The second child element, invalidation-interval-secs, is a performance-related setting that specifies the number of seconds the server waits before checking to determine if a session is invalid or has timed out.
The value assigned to the third child element, persistent-store-type, determines the persistent store method for servlet sessions. The current value, replicated_if_clustered, means that sessions on this server are stored in accordance with the value set for the cluster of servers to which this server belongs—if the Web Application is deployed to a cluster. Absent a clustered server configuration, servlet sessions default to the memory PersistentStoreType, in which sessions are not stored persistently.

The virtual-directory-mapping element sets the location that the servlet checks first when fulfilling HTTP image requests. Its child elements, local-path and url-pattern, map the URL pattern of an incoming request to a physical location.

<virtual-directory-mapping>
     <local-path>c:/medrec_tutorial/src/common/web</local-path>
     <url-pattern>images/*</url-pattern>
</virtual-directory-mapping>

The context-root element in a weblogic.xml file sets the context root directory for a Web Application. The context root is the base path of a Web application relative to the server's base URL. For example, MedRecServer's base URL is http://host:7101 and the Web application's context root is physician. Users access components of the physician Web application relative to http://host:7101/physician.

The setting physician means that users access the physicianWebApp when they specifically request it. <context-root>physician</context-root>

See weblogic.xml Deployment Descriptor Elements in Developing Web Applications for WebLogic Server for descriptions of all possible elements of the weblogic.xml file.

Best Practices

Use an XML editor to edit XML files, rather than a text editor. It is easy to mishandle XML code, and you will save time by using an editor that validates your work.
Use WebLogic Server tools to generate and edit XML deployment descriptors. DDInit generates descriptors for JARs, WARs, and EARs—see DDInit.

The Big Picture

The MedRec application contains five Web Applications:

physicianWebApp (in the physicianEar application)
patientWebApp (in the medrecEar application)
adminWebApp (in the medrecEar application)
mainWebApp (in the medrecEar application)
startBrowserWebApp (in the startBrowserEar application)

The resources and attributes of these Web Applications are defined by deployment descriptor files. This tutorial describes the function of these deployment descriptors, specifically web.xml, the standard J2EE Web application deployment descriptor file, and weblogic.xml, the WebLogic Server-specific Web application deployment descriptor file.

Deployment descriptor files configure properties for MedRec's applications, EJBs, and Web Services, as well as its Web applications.

For example, physicianEar, the application to which physicianWebApp belongs, also contains a session EJB component, physSessionEJBs. physSessionEJBs's deployment descriptor files, generated into the C:\medrec_tutorial\build\physicianEar\physSessionEjbs\META-INF directory, are the standard J2EE EJB deployment descriptor file ejb-jar.xml, and the WebLogic Server-specific EJB deployment descriptor file, weblogic-ejb-jar.xml.

Similarly, the physicianEar also contains a Web Service called PhysicianWebServices, whose deployment descriptor files are generated into the C:\medrec_tutorial\build\physicianEar\PhysicianWebServices\META-INF directory. The Web Service deployment descriptors include the J2EE standard webservices.xml, as well as the WebLogic-specific weblogic-webservices.xml. Because the PhysicianWebServices service is implemented with an EJB, the META-INF directory also contains EJB-related deployment descriptor files.

medrecEar, the main MedRec application, is configured by a standard J2EE application deployment descriptor file, application.xml, located at C:\medrec_tutorial\src\medrecEar\META-INF.

You are encouraged to examine the EJB, Web Service, and application deployment descriptor files and the XML Schema files that they reference.