Skip navigation.
Downloads | Product Documentation | Support

Avitek Medical Records Development Tutorials

# Developing the MedRec Applications

# Tutorial 5: Creating the MedRec Project Directory

This tutorial describes how to create the main project directory that holds the MedRec source files and compiled classes. The tutorial also explains the high-level directory structure and contents for the MedRec application suite components.

Tutorials that follow provide more detail about the development directory structure and WebLogic Server Ant tasks that help you easily build and deploy Enterprise Applications and their subcomponents—Web applications, EJBs, and Web services.

The preferred BEA method for building applications with WebLogic Server is Apache Ant. Ant is a Java-based build tool. One of the benefits of Ant is that is it is extended with Java classes, rather than with shell-based commands. BEA provides numerous Ant extension classes to help you compile, build, deploy, and package applications in the WebLogic Server split development directory environment.

This tutorial includes the following sections:

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

# Prerequisites

Before starting this tutorial:

- Create the MedRec domain and MedRec server, and start the MedRec administration server. See Tutorial 1: Creating a WebLogic Domain and Server Instance for Development.
- Start the PointBase database management system. See Tutorial 2: Starting the PointBase Development Database.
- Use the Administration Console to configure the resources needed to run the MedRec applications. See Tutorial 3: Configuring WebLogic Server Resources with the Administration Console.

# Procedure

To create the source directory structure for the MedRec application suite:

- Step 1: Create the tutorial project directory.
- Step 2: Unpack the project subdirectories.
- Step 3: Verify the project directory contents.
- Step 4: Verify the source directory contents.
- Step 5: Edit the install.properties file and run substitute.xml.

## Step 1: Create the tutorial project directory.

Begin by creating a top-level project directory in which you will store source and output files for the MedRec Enterprise Applications and client programs. Name the directory `medrec_tutorial`:

>     prompt> mkdir c:\medrec_tutorial

## Step 2: Unpack the project subdirectories.

BEA provides a `.zip` file that contains the entire source code of the MedRec application; the source code files are used in these tutorials. This `.zip` file also contains a build directory that contains some pre-compiled classes of the MedRec application, as well as the XML files that correspond to procedures in these tutorials.

To populate your project directory with the necessary files and directories:

1. Download the medrec_tutorial.zip (MD5 checksum) file. Save the downloaded file to the `c:\medrec_tutorial` directory.
2. Open up a command window and set your command shell environment with the MedRecDomain environment script:

>     prompt> c:\bea\user_projects\domains\MedRecDomain\bin\setDomainEnv.cmd

3. Move to the MedRec project directory and unpack the downloaded `.zip` file:

>     prompt> cd c:\medrec_tutorial

>     prompt> jar xvf medrec_tutorial.zip

## Step 3: Verify the project directory contents.

Verify that the following files and subdirectories were created:

>     prompt> dir

>      Directory of C:\medrec_tutorial

>     12/09/2005  11:39 AM    <DIR>          .
>     12/09/2005  11:39 AM    <DIR>          ..
>     12/09/2005  11:39 AM    <DIR>          build
>     12/09/2005  11:39 AM    <DIR>          dist
>     12/09/2005  11:39 AM               493 install.properties
>     12/09/2005  11:39 AM    <DIR>          lib
>     12/09/2005  11:39 AM         6,799,498 medrec_tutorial.zip
>     12/09/2005  11:39 AM    <DIR>          META-INF
>     12/09/2005  11:39 AM    <DIR>          src
>     12/09/2005  11:39 AM               996 substitute.xml

The `\build` directory contains the classes generated by the various MedRec build scripts. It does not contain editable source files or deployment descriptors, which reside in `\src`. Each subdirectory in `\build` represents the compiled classes for MedRec clients (`\clients`) or for a MedRec application (`\medrecEar`, `\physicianEar`, `\initEar`, and `\startBrowserEar` applications).

If you look at the contents of the `\build` directory, you'll notice that many of the classes that make up the MedRec application have already been built for you. In particular, all `medrecEar` and `startBrowserEar` applications, and the Web Services in the `physicianEar` application, have been pre-compiled. The parts of the `physicianEar` application that have not been pre-compiled are those that you will be working with in these tutorials, namely EJBs and Web applications. This pre-compilation is for your convenience, so you can browse many of the directories and compiled classes of the MedRec application right away without having to build it yourself. Later tutorials demonstrate how to re-compile parts, and then all, of the MedRec application using the WebLogic Ant tasks, such as `wlcompile` and `jwsc`, as part of the normal development process.

The `\src` directory contains the full source for all MedRec applications. You will be working in this directory for most remaining tutorials. Step 4: Verify the source directory contents. describes the subdirectories in `\src`.

`\build` and `\src` together represent a WebLogic Server split development directory. You can deploy individual MedRec applications to a development server by targeting an application subdirectory in `\build` (such as `\build\medrecEar`) using `weblogic.Deployer` or the `wldeploy` Ant task described in Tutorial 9: Deploying MedRec from the Development Environment. WebLogic Server locates the necessary deployment descriptors (available in `\src`) by examining the `.beabuild.txt` file located in the appropriate `\build` subdirectory.

The `\dist` directory is also an output directory—it will store the archived `.ear` files or exploded `.ear` directories created by the `wlpackage` task in Tutorial 14: Packaging MedRec for Distribution. Right now it contains only a few JAR files corresponding to some of the pre-compiled classes in the `\build` directory. The `\dist` directory will eventually store complete, exploded `.ear` directories for the different MedRec applications. The `\dist` directory is not considered part of the split development directory structure, because it is not required for compiling or deploying applications during development. It is used only for storing final, completed applications—`.ear` files or exploded `.ear` directories—that you generate after completing the development process.

The `\lib` directory contains precompiled, third-party `.jar` files that several of the MedRec applications require. This includes supporting `.jar`s for struts and log4j.

## Step 4: Verify the source directory contents.

The `\src` subdirectory contains the full application source for the MedRec applications, and it is the subdirectory in which you will spend the most time during the remaining tutorials. Take a look at the installed `\src` directory:

>     prompt> dir src

>      Directory of C:\medrec_tutorial\src

>     12/09/2005  11:39 AM    <DIR>          .
>     12/09/2005  11:39 AM    <DIR>          ..
>     12/09/2005  11:39 AM            19,736 build.html
>     12/09/2005  11:39 AM             2,938 build.xml
>     12/09/2005  11:39 AM    <DIR>          clients
>     12/09/2005  11:39 AM    <DIR>          common
>     12/09/2005  11:39 AM    <DIR>          initEar
>     12/09/2005  11:39 AM             4,550 medrec.properties
>     12/09/2005  11:39 AM    <DIR>          medrecEar
>     12/09/2005  11:39 AM    <DIR>          physicianEar
>     12/09/2005  11:39 AM    <DIR>          security
>     12/09/2005  11:39 AM    <DIR>          startBrowserEar

The `build.xml` file in the top level of the `medrec_tutorial` directory is a project-wide build file. It:

- Cleans up previously-built versions of MedRec before compiling
- Builds the contents of each application subdirectory into the `\build` directory by calling each application's `build.xml` file
- Packages each application as an exploded `.ear` file into the `\dist` directory

You will use this project-level `build.xml` before moving the WebLogic Server instance into production mode in Tutorial 13: Compiling the Entire MedRec Project. However, do not try to use it yet—you need to complete the next few tutorials to create the application-level `build.xml` files that this script calls.

The `\src` directory also contains a `medrec.properties` file that defines property values used by the project-level `build.xml` file, as well as the `build.xml` files used in each applications subdirectory.

The subdirectories of `\src` represent either deployable MedRec applications or MedRec components that are used by those applications:

- `\clients` holds source files for the Java and C# clients of MedRec Web Services.
- `\common` holds source files for Java classes shared between the MedRec Enterprise Applications. These include:

- Shared constants and JNDI names
- The ServiceLocator class, used to access MedRec services in the service tier
- Factories for creating EJBs and JMS connections
- Value objects, which represent data passed between tiers of the MedRec application
- Image files and Struts action classes shared across MedRec web components

- The `\initEar` subdirectory contains an application that implements and registers a custom MBean that polls the database every 6 seconds to check for new users to be added to the system. You can use this application to register your own custom MBean.
- The `\medrecEar` and `\physicianEar` subdirectories store the main Enterprise Applications that make up the MedRec application suite. These subdirectories use the WebLogic Server 9.1 Development Directory structure and Ant tasks for building and deploying, and are described in detail in the next tutorials.
- `The \security` subdirectory contains the MedRec authentication provider shared across applications.
- `The \startupBrowserEar` subdirectory contains the listener class that automatically boots the browser and loads MedRec's main index JSP when you start MedRec on a Windows machine. You do not work directly with this application in the tutorials that follow. However, the application is compiled as part of the overall MedRec build process.

## Step 5: Edit the install.properties file and run substitute.xml.

The top-level project directory into which you unzipped the ZIP file contains a file called `install.properties` that specifies information local to your environment, such as the name of the computer which hosts WebLogic Server and the MedRec domain directory. After editing this file with information specific to your environment, run the `substitute.xml` Ant file which uses this properties file to substitute your local values for the place-holders in the files you unzipped.

1. Use a text editor to open the properties file:

>     prompt> notepad c:\medrec_tutorial\install.properties

2. Edit the `SERVER_HOSTNAME` property to point to the computer that hosts WebLogic Server:

>     SERVER_HOSTNAME=myhost.mycompany.com

3. If you did not use `7101` and `7102` as the administration server port numbers when creating the `MedRecDomain` in Tutorial 1: Creating a WebLogic Domain and Server Instance for Development, edit the `SERVER_PORT` and `SERVER_SSL_PORT` properties to point the appropriate ports:

>     SERVER_PORT=7101
>     SERVER_SSL_PORT=7102

4. Edit the `WL_HOME` property to point to your WebLogic Server installation directory (`c:/bea/weblogic91` by default):

>     WL_HOME=c:/bea/weblogic91

5. Edit the `MEDREC_HOME_DIR` property to point to your new project directory:

>     MEDREC_HOME_DIR=c:/medrec_tutorial

6. Edit the `MEDREC_DOMAIN_DIR` property to point to the MedRecDomain directory you created (c:/bea/user_projects/domains/MedRecDomain by default):

>     MEDREC_DOMAIN_DIR=c:/bea/user_projects/domains/MedRecDomain

7. Save and close the `install.properties` file.
8. Go to the `c:\medrec_tutorial` directory and run the `substitute.xml` script:

>     prompt> cd c:\medrec_tutorial

>     prompt> ant -f substitute.xml

The substitution script may take a few seconds to complete, at the end of which you should see output similar to the following:

>     Buildfile: substitute.xml

>     replace:

>     BUILD SUCCESSFUL

>     Total time: 23 seconds

# Best Practices

- Smaller J2EE projects may not require the nested subdirectories found in the MedRec project directory. For example, a project that produces a single Enterprise application file can have minimal subdirectories such as:

- `\myProject`—top-level project directory
- `\myProject\myEarBuild`—output directory for storing compiled and generated files
- `\myProject\myEarSrc`—source files and editable content for the Enterprise Application

This minimal directory structure still allows you to develop your application by using the WebLogic split development directory structure and Ant tasks described in Tutorial 6: Understanding the WebLogic Server Split Directory Structure.

# The Big Picture

The MedRec application suite consists of three separate applications for the patient, physician, and administrator user roles. Using a separate application for each user role allows you to distribute each application function across different WebLogic Server instances as needed. For example, the MedRec sample domain (optionally installed with WebLogic Server) deploys all three applications on a single server instance for easy demonstration purposes. The MedRec tutorials also deploy the applications in a single-server domain, which is typical for development environments. However, you can also deploy the MedRec and Physician applications on two different server instances (in separate domains) to illustrate the use of Web Services between the applications.

The MedRec project directory also contains subdirectories for compiling the client applications that access MedRec via Web Services.

# Related Reading

- Creating a Split Development Directory Environment in Developing Applications with WebLogic Server
- Overview of WebLogic Server Application Development in Developing Applications with WebLogic Server
- Apache Ant in Developing Applications with WebLogic Server