Building the MedRec Applications

Tutorial 6: Understanding the WebLogic Server Split Directory Structure

Several subdirectories in the medrec_tutorial project directory—medrecEar, physicianEar, startupEar—use the WebLogic Server split development directory structure for storing source files. The split development directory consists of a directory layout and supporting ant tasks that help you easily build, deploy, and package Enterprise Application files while automatically maintaining classpath dependencies. The directory structure is split because source files and editable deployment descriptors reside in one directory while compiled class files and generated deployment descriptors reside in a separate directory.

The split development directory structure is a valuable tool to use for developing your own applications. Because source files and generated files are kept separate, you can easily integrate your development projects with source control systems. The split development directory also allows you to easily deploy your applications without having to first copy files and stage applications—WebLogic Server automatically uses the contents of both the build and source directories to deploy an application.

This tutorial explains the layout and function of the source directory structure used in the MedRec application suite. The next tutorial describes the build directory structure, which is produced when you compile an Enterprise Application using the wlcompile task. The source and build directories together make up a WebLogic split development directory, which you will deploy and package in later tutorials.

This tutorial includes the following sections:

- Prerequisites
- Procedure
- Best Practices
- The Big Picture
- Related Reading

Prerequisites

Before starting this tutorial:

- Create the project directory and unpack the MedRec tutorial source files to it using the instructions in Tutorial 5: Creating the MedRec Project Directory.

Procedure

The following procedure guide you through the source directory structure for the MedRec application suite:

- Step 1: Examine the Enterprise Application directory structure.
- Step 2: Examine the Web Application component directory structure.
- Step 3: Examine the EJB component directory structure.

Step 1: Examine the Enterprise Application directory structure.

The WebLogic split development directory stores source files starting at the Enterprise Application (EAR) level. Even if you are developing only a single Web Application or EJB, you store the relevant component in a top-level directory that represents an Enterprise Application. For example, examine the contents of the startupEar subdirectory, which stores the source code for a single Web Application in the MedRec application suite:

>     cd c:\medrec_tutorial\src\startupEar

>     dir

>      Directory of C:\medrec_tutorial\src\startupEar

>     01/23/2003  08:43a      <DIR>          .

>     01/23/2003  08:43a      <DIR>          ..

>     01/23/2003  08:43a               3,368 build.xml

>     01/23/2003  08:41a      <DIR>          META-INF

>     01/23/2003  08:24a      <DIR>          startupWebApp

Because this Web Application must be packaged independently of the other MedRec applications, it is placed in its own source directory represented by an EAR file. The META-INF subdirectory holds deployment descriptors for the Enterprise Application itself (application.xml and optional weblogic-application.xml files).

Other source subdirectories in the project directory represent more typical Enterprise Applications having both Web Applications and EJBs, such as physicianEar. Move to the physicianEar subdirectory and examine its contents:

>     cd c:\medrec_tutorial\src\physicianEar

>     dir

>      Directory of C:\medrec_tutorial\src\physicianEar

>     01/23/2003  08:43a      <DIR>          .

>     01/23/2003  08:43a      <DIR>          ..

>     01/20/2003  05:00p      <DIR>          APP-INF

>     01/23/2003  08:43a               5,447 build.xml

>     01/23/2003  08:41a      <DIR>          META-INF

>     01/23/2003  08:41a      <DIR>          physicianWebApp

>     01/23/2003  08:24a      <DIR>          sessionEjbs

>     01/23/2003  08:24a                 218 wlcompile_tutorial.xml

>     01/23/2003  08:24a                 287 wldeploy_tutorial.xml

>     01/23/2003  08:24a                 293 wlpackage_tutorial.xml

>     01/23/2003  08:24a                 393 ws_ejb_client_tutorial.xml

As you can see from the directory listing, the Physician application contains both a Web Application component (stored in physicianWebApp) and EJB components (stored in sessionEjbs). The split development directory structure requires that each EAR component reside in a dedicated source directory. You can name the ear directory and component subdirectories as you see fit, because the wlcompile ant task automatically determines the type of component during compilation.

Step 2: Examine the Web Application component directory structure.

The source directory structure allows you to easily manage the different file types that constitute a Web Application. Move to the physicianWebApp subdirectory of the physicianEar source directory and examine its contents:

>     cd physicianWebApp

>     dir

>      Directory of C:\medrec_tutorial\src\physicianEar\physicianWebApp

>     02/17/2003  10:01a      <DIR>          .

>     02/17/2003  10:01a      <DIR>          ..

>     02/17/2003  09:57a               1,588 Confirmation.jsp

>     02/17/2003  09:57a               4,538 CreateRx.jsp

>     02/17/2003  09:57a               9,836 CreateVisit.jsp

>     02/17/2003  09:57a               2,107 Error.jsp

>     02/17/2003  09:57a               2,837 Login.jsp

>     02/17/2003  09:57a               3,770 PatientHeader.jsp

>     02/17/2003  09:57a               1,940 PhysicianHeader.jsp

>     02/17/2003  09:57a               2,927 Search.jsp

>     02/17/2003  09:57a               3,338 SearchResults.jsp

>     02/17/2003  09:57a               2,840 stylesheet.css

>     02/17/2003  09:57a               3,549 ViewProfile.jsp

>     02/17/2003  09:57a               6,443 ViewRecord.jsp

>     02/17/2003  09:57a               4,846 ViewRecords.jsp

>     02/17/2003  10:01a      <DIR>          WEB-INF

The top level of the Web Application subdirectory contains the JSPs that make up the application. You could also store .html files or other static content such as image files here, but it is less cumbersome to store such content in a dedicated subdirectory like \images.

Java source files for Web Application components, such as Servlets or supporting utility classes, are stored in package directories under the component's WEB-INF\src subdirectory. For example, a utility class for the Physician Web Application is stored in C:\medrec_tutorial\src\physicianEar\physicianWebApp\WEB-INF\src\com\bea\medrec\utils\PhysConstants.java.

The wlcompile task automatically compiles the contents of the WEB-INF\src subdirectory into the WEB-INF\classes subdirectory of application's output directory, so that all components of the Web Application can access those classes.

The WEB-INF subdirectory also stores deployment descriptors for the Web Application component (web.xml and the optional weblogic.xml).

Step 3: Examine the EJB component directory structure.

Java source files for EJB components are stored in subdirectories that reflect the EJB's package structure. For example, the source for the Physician Application's session EJB is stored in C:\medrec_tutorial\src\physicianEar\physSessionEjbs\com\bea\medrec\controller\PhysicianSessionEJB.ejb.

Deployment descriptors for EJB components (such as ejb-jar.xml and the optional weblogic-ejb-jar.xml) can be stored in the component's META-INF subdirectory. However, if you look at the physSessionEjbs subdirectory, you will notice there is no META-INF subdirectory. This is because all EJBs in the MedRec application suite use ejbgen tags in their JavaDoc comments, rather than defining them in deployment descriptor files. The wlcompile ant task uses these tags to generate the EJB deployment descriptors automatically when you compile the application.

Best Practices

- Use the same source directory structure with your own J2EE application projects, so you can utilize the WebLogic Server build scripts to compile and deploy your applications. The following summarizes the contents of a simple source directory that follows the WebLogic split development directory structure format:

>     \myProject

>     \myProject\myEar

>     \myProject\myEar\META-INF\application.xml

>     \myProject\myEar\myEjb\com\*\*.java

>     \myProject\myEar\myWebApp\*.jsp

>     \myProject\myEar\myWebApp\WEB-INF\web.xml

>     \myProject\myEar\myWebApp\WEB-INF\src\com\*\*.java

- Use a source control system to manage the files in the source directory hierarchy. The source directory contains your working files—Java files and deployment descriptors—and should be regularly backed up to maintain a history of your development project.
- Never store user-generated files in the \build directory. The \build directory is intended to store only compiled classes for your J2EE applications. You should be able to rebuild the entire \build directory simply by recompiling your application.
- You can store deployment descriptor files either in the top level of a J2EE component subdirectory, or in the customary J2EE subdirectory for the component's descriptor files—\myWebApp\WEB-INF or myEjb\META-INF.

The Big Picture

The MedRec application suite uses three split development directories to hold the source for the medrecEar, physicianEar, and startupEar applications. Utility classes shared among these applications reside in a dedicated directory, common, with a custom build script that does not use the split directory structure. Security components are also staged in a custom build directory.

The top-level build.xml file iterates through the MedRec source directories and coordinates building all of the components at once.

Although the wlcompile task automatically manages most component dependencies during a build, certain split development directories, such as the medrecEar and physicianEar subdirectories, hard-code the build order to enforce dependencies. The source directory structure that you created during the tutorial contains intermediate build steps, which allow you to focus on using the new WebLogic Server ant tasks without worrying about the dependencies.

Related Reading

- Developing WebLogic Server Applications
- Developing Web Applications for WebLogic Server
- Programming WebLogic Server Enterprise JavaBeans