Skip navigation.
Downloads | Product Documentation | Support

Developing WebLogic Server Applications

# Creating WebLogic Server Applications

The following sections describe the steps for creating WebLogic Server J2EE applications using the WebLogic split development directory environment:

- Overview of the Split Development Directory Environment
- Using the Split Development Directory Structure: Main Steps
- Organizing J2EE Components in a Split Development Directory
- Organizing Shared Classes in a Split Development Directory on page 2-11
- Generating a Basic build.xml File Using weblogic.BuildXMLGen
- Generating Deployment Descriptors Using wlddcreate
- Compiling Applications Using wlcompile
- Deploying Applications Using wldeploy
- Packaging Applications Using wlpackage
- Developing Multiple-EAR Projects Using the Split Development Directory
- Best Practices for Developing WebLogic Server Applications

# Overview of the Split Development Directory Environment

The WebLogic split development directory environment consists of a directory layout and associated Ant tasks that help you repeatedly build, change, and deploy J2EE applications. Compared to other development frameworks, the WebLogic split development directory provides these benefits:

- Fast development and deployment. By minimizing unnecessary file copying, the split development directory Ant tasks help you recompile and redeploy applications quickly without first generating a deployable archive file or exploded archive directory.
- Simplified build scripts. The BEA-provided Ant tasks automatically determine which J2EE modules and classes you are creating, and build components in the correct order to support common classpath dependencies. In many cases, your project build script can simply identify the source and build directories and allow Ant tasks to perform their default behaviors.
- Easy integration with source control systems. The split development directory provides a clean separation between source files and generated files. This helps you maintain only editable files in your source control system. You can also clean the build by deleting the entire build directory; build files are easily replaced by rebuilding the project.

## Source and Build Directories

The source and build directories form the basis of the split development directory environment. The source directory contains all editable files for your project—Java source files, editable descriptor files, JSPs, static content, and so forth. You create the source directory for an application by following the directory structure guidelines described in Organizing J2EE Components in a Split Development Directory.

The top level of the source directory always represents an Enterprise Application (`.ear` file), even if you are developing only a single J2EE module. Subdirectories beneath the top level source directory contain:

- Enterprise Application Modules (EJBs and Web Applications)

Note: The split development directory structure does not provide support for developing new Resource Adapter components.

- Descriptor files for the Enterprise Application (`application.xml` and `weblogic-application.xml`)
- Utility classes shared by modules of the application (for example, exceptions, constants)
- Libraries (compiled`.jar` files, including third-party libraries) used by modules of the application

The build directory contents are generated automatically when you run the `wlcompile` ant task against a valid source directory. The `wlcompile` task recognizes EJB, Web Application, and shared library and class directories in the source directory, and builds those components in an order that supports common class path requirements. Additional Ant tasks can be used to build Web Services or generate deployment descriptor files from annotated EJB code.

Figure 2-1 Source and Build Directories

The build directory contains only those files generated during the build process. The combination of files in the source and build directories form a deployable J2EE application.

The build and source directory contents can be place in any directory of your choice. However, for ease of use, the directories are commonly placed in directories named `source` and `build`, within a single project directory (for example, `\myproject\build` and `\myproject\source`).

## Deploying from a Split Development Directory

All WebLogic Server deployment tools (`weblogic.Deployer`, `wldeploy`, and the Administration Console) support direct deployment from a split development directory. You specify only the build directory when deploying the application to WebLogic Server.

WebLogic Server attempts to use all classes and resources available in the source directory for deploying the application. If a required resource is not available in the source directory, WebLogic Server then looks in the application's build directory for that resource. For example, if a deployment descriptor is generated during the build process, rather than stored with source code as an editable file, WebLogic Server obtains the generated file from the build directory.

WebLogic Server discovers the location of the source directory by examining the `.beabuild.txt` file that resides in the top level of the application's build directory. If you ever move or modify the source directory location, edit the `.beabuild.txt` file to identify the new source directory name.

Deploying Applications Using wldeploy on page 2-16 describes the `wldeploy` Ant task that you can use to automate deployment from the split directory environment.

Figure 2-2, Split Directory Deployment, on page 2-4 shows a typical deployment process. The process is initiated by specifying the build directory with a WebLogic Server tool. In the figure, all compiled classes and generated deployment descriptors are discovered in the build directory, but other application resources (such as static files and editable deployment descriptors) are missing. WebLogic Server uses the hidden `.beabuild.txt` file to locate the application's source directory, where it finds the required resources.

Figure 2-2 Split Directory Deployment

## Split Development Directory Ant Tasks

BEA provides a collection of Ant tasks designed to help you develop applications using the split development directory environment. Each Ant task uses the source, build, or both directories to perform common development tasks:

- wlddcreate—Generates basic deployment descriptor files for J2EE components in the source directory. See Generating Deployment Descriptors Using wlddcreate.
- wlcompile—This Ant task compiles the contents of the source directory into subdirectories of the build directory. `wlcompile` compiles Java classes and also processes annotated `.ejb` files into deployment descriptors, as described in Compiling Applications Using wlcompile.
- wlappc—This Ant task invokes the appc compiler, which generates JSPs and container-specific EJB classes for deployment. See appc Compiler.
- wldeploy—This Ant task deploys any format of J2EE applications (exploded or archived) to WebLogic Server. To deploy directly from the split development directory environment, you specify the build directory of your application. See Deployment Tools Reference in Deploying WebLogic Server Applications.
- wlpackage—This Ant task uses the contents of both the source and build directories to generate an EAR file or exploded EAR directory that you can give to others for deployment.

# Using the Split Development Directory Structure: Main Steps

The following steps illustrate how you use the split development directory structure to build and deploy a WebLogic Server application.

1. Create the main EAR source directory for your project. When using the split development directory environment, you must develop Web Applications and EJBs as part of an Enterprise Application, even if you do not intend to develop multiple J2EE modules. See Organizing J2EE Components in a Split Development Directory on page 2-6.
2. Add one or more subdirectories to the EAR directory for storing the source for Web Applications, EJB components, or shared utility classes. See Organizing J2EE Components in a Split Development Directory on page 2-6 and Organizing Shared Classes in a Split Development Directory on page 2-11.
3. Store all of your editable files (source code, static content, editable deployment descriptors) for modules in subdirectories of the EAR directory. Add the entire contents of the source directory to your source control system, if applicable.
4. Set your WebLogic Server environment by executing either the setWLSEnv.cmd (Windows) or setWLSEnv.sh (UNIX) script. The scripts are located in the WL_HOME\server\bin\ directory, where WL_HOME is the top-level directory in which WebLogic Server is installed.
5. Use the `weblogic.BuildXMLGen` utility to generate a default `build.xml` file for use with your project. Edit the default property values as needed for your environment. See Generating a Basic build.xml File Using weblogic.BuildXMLGen on page 2-12.
6. Use the default targets in the `build.xml` file to build, deploy, and package your application. See Generating a Basic build.xml File Using weblogic.BuildXMLGen on page 2-12 for a list of default targets.

# Organizing J2EE Components in a Split Development Directory

The split development directory structure requires each project to be staged as a J2EE Enterprise Application. BEA therefore recommends that you stage even stand-alone Web applications and EJBs as modules of an Enterprise application, to benefit from the split directory Ant tasks. This practice also allows you to easily add or remove modules at a later date, because the application is already organized as an EAR.

Note: If your project requires multiple EARs, see also Developing Multiple-EAR Projects Using the Split Development Directory.

The following sections describe the basic conventions for staging the following module types in the split development directory structure:

- Enterprise Application Configuration
- Web Applications
- EJBs
- Shared Utility Classes
- Third-Party Libraries

Note: WebLogic Server does not provide additional support for developing J2EE Connectors using the split development directory.

The directory examples are taken from the `splitdir` sample application installed in WL_HOME`\samples\server\examples\src\examples\splitdir`, where WL_HOME is your WebLogic Server installation directory.

## Source Directory Overview

The following figure summarizes the source directory contents of an Enterprise Application having a Web Application, EJB, shared utility classes, and third-party libraries. The sections that follow provide more details about how individual parts of the enterprise source directory are organized.

Figure 2-3 Overview of Enterprise Application Source Directory

## Enterprise Application Configuration

The top level source directory for a split development directory project represents an Enterprise Application. The following figure shows the minimal files and directories required in this directory.

Figure 2-4 Enterprise Application Source Directory

The Enterprise Application directory will also have one or more subdirectories to hold a Web Application, EJB, utility class, and/or third-party Jar file, as described in the following sections.

Notes: You can automatically generate Enterprise Application descriptors using the ddinit Java utility or `wlddcreate` Ant task. After adding J2EE module subdirectories to the EAR directory, execute the command:

>     java weblogic.marathon.ddinit.EarInit \myEAR

For more information on ddinit, see Using the WebLogic Server Java Utilities.

## Web Applications

Web Applications use the basic source directory layout shown in the figure below.

Figure 2-5 Web Application Source and Build Directories

The key directories and files for the Web Application are:

- `helloWebApp\` —The top level of the Web Application module can contain JSP files and static content such as HTML files and graphics used in the application. You can also store static files in any named subdirectory of the Web Application (for example, `helloWebApp\graphics` or `helloWebApp\static`.)
- `helloWebApp\WEB-INF\` —Store the Web Application's editable deployment descriptor files (`web.xml` and `weblogic.xml`) in the `WEB-INF` subdirectory.
- `helloWebApp\WEB-INF\src` —Store Java source files for Servlets in package subdirectories under `WEB-INF\src`.

When you build a Web Application, the `appc` Ant task and `jspc` compiler compile JSPs into package subdirectories under `helloWebApp\WEB-INF\classes\jsp_servlet` in the build directory. Editable deployment descriptors are not copied during the build process.

## EJBs

EJBs use the source directory layout shown in the figure below.

Figure 2-6 EJB Source and Build Directories

The key directories and files for an EJB are:

- `helloEJB\` —Store all EJB source files under package directories of the EJB module directory. The source files can be either `.java` source files, or annotated `.ejb` files.
- `helloEJB\META-INF\` —Store editable EJB deployment descriptors (ejb-jar.xml and weblogic-ejb-jar.xml) in the `META-INF` subdirectory of the EJB module directory. The `helloWorldEar` sample does not include a `helloEJB\META-INF` subdirectory, because its deployment descriptors files are generated from annotations in the `.ejb` source files. See Important Notes Regarding EJB Descriptors.

During the build process, EJB classes are compiled into package subdirectories of the `helloEJB` module in the build directory. If you use annotated `.ejb` source files, the build process also generates the EJB deployment descriptors and stores them in the `helloEJB\META-INF` subdirectory of the build directory.

### Important Notes Regarding EJB Descriptors

EJB deployment descriptors should be included in the source `META-INF` directory and treated as source code only if those descriptor files are created from scratch or are edited manually. Descriptor files that are generated from annotated `.ejb` files should appear only in the build directory, and they can be deleted and regenerated by building the application.

For a given EJB component, the EJB source directory should contain either:

- EJB source code in `.java` source files and editable deployment descriptors in `META-INF`

or:

- EJB source code with descriptor annotations in `.ejb` source files, and no editable descriptors in `META-INF.`

In other words, do not provide both annotated `.ejb` source files and editable descriptor files for the same EJB component.

# Organizing Shared Classes in a Split Development Directory

The WebLogic split development directory also helps you store shared utility classes and libraries that are required by modules in your Enterprise Application. The following sections describe the directory layout and classloading behavior for shared utility classes and third-party JAR files.

## Shared Utility Classes

Enterprise Applications frequently use Java utility classes that are shared among application modules. Java utility classes differ from third-party JARs in that the source files are part of the application and must be compiled. Java utility classes are typically libraries used by application modules such as EJBs or Web applications.

Figure 2-7 Java Utility Class Directory

Place the source for Java utility classes in a named subdirectory of the top-level Enterprise Application directory. Beneath the named subdirectory, use standard package subdirectory conventions.

During the build process, the wlcompile Ant task invokes the javac compiler and compiles Java classes into the APP-INF/classes/ directory under the build directory. This ensures that the classes are available to other modules in the deployed application.

## Third-Party Libraries

You can extend an Enterprise Application to use third-party .jar files by placing the files in the APP-INF\lib\ directory, as shown below:

Figure 2-8 Third-party Library Directory

Third-party JARs are generally not compiled, but may be versioned using the source control system for your application code. For example, XML parsers, logging implementations, and Web Application framework JAR files are commonly used in applications and maintained along with editable source code.

During the build process, third-party JAR files are not copied to the build directory, but remain in the source directory for deployment.

## Class Loading for Shared Classes

The classes and libraries stored under `APP-INF/classes` and `APP-INF/lib` are available to all modules in the Enterprise Application. The application classloader always attempts to resolve class requests by first looking in `APP-INF/classes`, then `APP-INF/lib`.

# Generating a Basic build.xml File Using weblogic.BuildXMLGen

After you set up your source directory structure, use the weblogic.BuildXMLGen utility to create a basic build.xml file. weblogic.BuildXMLGen is a convenient utility that generates an Ant build.xml file for Enterprise applications that are organized in the split development directory structure. The utility analyzes the source directory and creates build and deploy targets for the Enterprise application as well as individual modules. It also creates targets to clean the build and generate new deployment descriptors.

The syntax for weblogic.BuildXMLGen is as follows:

>     java weblogic.BuildXMLGen [options] <source directory>

where options include:

- -help—print standard usage message
- -version—print version information
- -projectName <project name>—name of the Ant project
- -d <directory>—directory where build.xml is created. The default is the current directory.
- -file <build.xml>—name of the generated build file
- -username <username>—user name for deploy commands
- -password <password>—user password

After running weblogic.BuildXMLGen, edit the generated `build.xml` file to specify properties for your development environment. The list of properties you need to edit are shown in the listing below.

Listing 2-1 build.xml Editable Properties

>     <!-- BUILD PROPERTIES ADJUST THESE FOR YOUR ENVIRONMENT -->
>       <property name="tmp.dir" value="/tmp" />
>       <property name="dist.dir" value="${tmp.dir}/dist"/>
>       <property name="app.name" value="helloWorldEar" />
>       <property name="ear" value="${dist.dir}/${app.name}.ear"/>
>       <property name="ear.exploded" value="${dist.dir}/${app.name}_exploded"/>
>       <property name="verbose" value="true" />
>       <property name="user" value="USERNAME" />
>       <property name="password" value="PASSWORD" />
>       <property name="servername" value="myserver" />
>       <property name="adminurl" value="iiop://localhost:7001" />

In particular, make sure you edit the `tmp.dir` property to point to the build directory you want to use. By default, the `build.xml` file builds projects into a subdirectory `tmp.dir` named after the application (`/tmp/helloWorldEar` in the above listing).

The following listing shows the default main targets created in the `build.xml` file. You can view these targets at the command prompt by entering the `ant -projecthelp` command in the EAR source directory.

Listing 2-2 Default build.xml Targets

>     appc 			Runs weblogic.appc on your application
>     build 			Compiles helloWorldEar application and runs appc
>     clean 			Deletes the build and distribution directories
>     compile 			Only compiles helloWorldEar application, no appc
>     compile.appStartup 			Compiles just the appStartup module of the application
>     compile.appUtils 			Compiles just the appUtils module of the application
>     compile.build.orig 			Compiles just the build.orig module of the application
>     compile.helloEJB 			Compiles just the helloEJB module of the application
>     compile.helloWebApp 			Compiles just the helloWebApp module of the
>     			application
>     compile.javadoc 			Compiles just the javadoc module of the application
>     deploy 			Deploys (and redeploys) the entire helloWorldEar
>     			application
>     descriptors 			Generates application and module descriptors
>     ear 			Package a standard J2EE EAR for distribution
>     ear.exploded 			Package a standard exploded J2EE EAR
>     redeploy.appStartup 			Redeploys just the appStartup module of the application
>     redeploy.appUtils 			Redeploys just the appUtils module of the application
>     redeploy.build.orig			Redeploys just the build.orig module of the
>     			application
>     redeploy.helloEJB 			Redeploys just the helloEJB module of the application
>     redeploy.helloWebApp 			Redeploys just the helloWebApp module of the
>     			application
>     redeploy.javadoc 			Redeploys just the javadoc module of the application
>     undeploy 			UnDeploys the entire helloWorldEar application

# Generating Deployment Descriptors Using wlddcreate

The wlddcreate ant task is provided as a method for generating deployment descriptors for applications and application modules. It is an ant target provided as part of the generated build.xml file. It is an alternative to the weblogic.marathon.ddinit commands. The following is the wlddcreate target output:

<target name="descriptors" depends="compile" description="Generates application

and module descriptors">

<ddcreate dir="${dest.dir}" />

</target>

# Compiling Applications Using wlcompile

You use the wlcompile Ant task to invoke the javac compiler to compile your application's Java components in a split development directory structure. The basic syntax of `wlcompile` identifies the source and build directories, as in this command from the `helloWorldEar` sample:

>     <wlcompile srcdir="${src.dir}" destdir="${dest.dir}"/>

The following is the order in which events occur using this task:

1. wlcompile compiles the Java components into an output directory:

WL_HOME\samples\server\examples\build\helloWorldEar\APP-INF\classes\

where WL_HOME is the WebLogic Server installation directory.

2. wlcompile builds the EJBs and automatically includes the previously built Java modules in the compiler's classpath. This allows the EJBs to call the Java modules without requiring you to manually edit their classpath.
3. Finally, wlcompile compiles the Java components in the Web application with the EJB and Java modules in the compiler's classpath. This allows the Web applications to refer to the EJB and application Java classes without requiring you to manually edit the classpath.

## Using includes and excludes Properties

More complex Enterprise applications may have compilation dependencies that are not automatically handled by the wlcompile task. However, you can use the include and exclude options to wlcompile to enforce your own dependencies. The includes and excludes properties accept the names of Enterprise Application modules—the names of subdirectories in the Enterprise application source directory—to include or exclude them from the compile stage.

The following line from the `helloWorldEar` sample shows the `appStartup` module being excluded from compilation:

>     <wlcompile srcdir="${src.dir}" destdir="${dest.dir}"
>        excludes="appStartup"/>

## wlcompile Ant Task Options

Table 2-1 contains Ant task options specific to wlcompile.

Table 2-1 wlcompile Ant Task Options

Option | Description
srcdir | The source directory.
destdir | The build/output directory.
classpath | Allows you to change the classpath used by wlcompile.
includes | Allows you to include specific directories from the build.
excludes | Allows you to exclude specific directories from the build.

## Nested javac Options

The wlcompile Ant task can accept nested javac options to change the compile-time behavior. For example, the following `wlcompile` command ignores deprecation warnings and enables debugging:

>     <wlcompile srcdir="${mysrcdir}" destdir="${mybuilddir}">
>        <javac deprecation="false" debug="true"
>        debuglevel="lines,vars,source"/>
>     </wlcompile>

# Deploying Applications Using wldeploy

The `wldeploy` task provides an easy way to deploy directly from the split development directory. `wlcompile` provides most of the same arguments as the `weblogic.Deployer` directory. To deploy from a split development directory, you simply identify the build directory location as the deployable files, as in:

>     <wldeploy user="${user}" password="${password}"
>     	action="deploy" source="${dest.dir}"
>     	name="helloWorldEar" />

The above task is automatically created when you use `weblogic.BuildXMLGen` to create the `build.xml` file.

See wldeploy Ant Task in Deploying WebLogic Server Applications for a complete command reference.

# Packaging Applications Using wlpackage

The `wlpackage` Ant task uses the contents of both the source and build directories to create either a deployable archive file (`.EAR` file), or an exploded archive directory representing the Enterprise Application (exploded `.EAR` directory). Use `wlpackage` when you want to deliver your application to another group or individual for evaluation, testing, performance profiling, or production deployment.

## Archive versus Exploded Archive Directory

For production purposes, it is convenient to deploy Enterprise applications in exploded (unarchived) directory format. This applies also to stand-alone Web applications, EJBs, and connectors packaged as part of an Enterprise application. Using this format allows you to update files directly in the exploded directory rather than having to unarchive, edit, and rearchive the whole application. Using exploded archive directories also has other benefits, as described in Exploded Archive Directories in Deploying WebLogic Server Applications.

You can also package applications in a single archived file, which is convenient for packaging modules and applications for distribution. Archive files are easier to copy, they use up fewer file handles than an exploded directory, and they can save disk space with file compression.

The Java classloader can search for Java class files (and other file types) in a JAR file the same way that it searches a directory in its classpath. Because the classloader can search a directory or a JAR file, you can deploy J2EE modules on WebLogic Server in either a JAR (archived) file or an exploded (unarchived) directory. See Archive versus Exploded Archive Directory.

## wlpackage Ant Task

In a production environment, use the wlpackage Ant task to package your split development directory application as a traditional EAR file that can be deployed to WebLogic Server. Continuing with the MedRec example, you would package your application as follows:

>     <wlpackage toFile="\physicianEAR\physicianEAR.ear" srcdir="\physicianEAR"

>     destdir="\build\physicianEAR"/>

>     <wlpackage toDir="\physicianEAR\explodedphysicianEar" srcdir="\src\physicianEAR"

>     destdir="\build\physicianEAR" />

# Developing Multiple-EAR Projects Using the Split Development Directory

The split development directory examples and procedures described previously have dealt with projects consisting of a single Enterprise Application. Projects that require building multiple Enterprise Applications simultaneously require slightly different conventions and procedures, as described in the following sections.

Note: The following sections refer to the MedRec sample application, which consists of three separate Enterprise Applications as well as shared utility classes, third-party JAR files, and dedicated client applications. The MedRec source and build directories are installed under WL_HOME`/samples/server/medrec`, where WL_HOME is the WebLogic Server installation directory. See also the Avitek Medical Records Development Tutorials for information about the MedREc directory layout and build process.

## Organizing Libraries and Classes Shared by Multiple EARs

For single EAR projects, the split development directory conventions suggest keeping third-party JAR files in the `APP-INF/lib` directory of the EAR source directory. However, a multiple-EAR project would require you to maintain a copy of the same third-party JAR files in the `APP-INF/lib` directory of each EAR source directory. This introduces multiple copies of the source JAR files, increases the possibility of some JAR files being at different versions, and requires additional space in your source control system.

To address these problems, consider editing your build script to copy third-party JAR files into the `APP-INF/lib` directory of the build directory for each EAR that requires the libraries. This allows you to maintain a single copy and version of the JAR files in your source control system, yet it enables each EAR in your project to use the JAR files.

The MedRec sample application installed with WebLogic Server uses this strategy, as shown in the following figure.

Figure 2-9 Shared JAR Files in MedRec

MedRec takes a similar approach to utility classes that are shared by multiple EARs in the project. Instead of including the source for utility classes within the scope of each ear that needs them, MedRec keeps the utility class source independent of all EARs. After compiling the utility classes, the build script archives them and copies the JARs into the build directory under the `APP-INF/LIB` subdirectory of each EAR that uses the classes, as shown in figure Figure 2-9.

## Linking Multiple build.xml Files

When developing multiple EARs using the split development directory, each EAR project generally uses its own `build.xml` file (perhaps generated by multiple runs of `weblogic.BuildXMLGen`.). Applications like MedRec also use a master `build.xml` file that calls the subordinate `build.xml` files for each EAR in the application suite.

Ant provides a core task (named `ant`) that allows you to execute other project build files within a master `build.xml` file. The following line from the MedRec master build file shows its usage:

>     <ant inheritAll="false" dir="${root}/startupEar" antfile="build.xml"/>

The above task instructs Ant to execute the file named `build.xml` in the `/startupEar` subdirectory. The `inheritAll` parameter instructs Ant to pass only user properties from the master build file tot the `build.xml` file in `/startupEar`.

MedRec uses multiple tasks similar to the above to build the `startupEar`, `medrecEar`, and `physicianEar` applications, as well as building common utility classes and client applications.

# Best Practices for Developing WebLogic Server Applications

BEA recommends the following "best practices" for application development. Also, see the various "Best Practices" sections in the MedRec Tutorials.

- Package applications as part of an Enterprise application. See Packaging Applications Using wlpackage.
- Use the split development directory structure. See Organizing J2EE Components in a Split Development Directory.
- For distribution purposes, package and deploy in archived format. See Packaging Applications Using wlpackage.
- In most other cases, it is more convenient to deploy in exploded format. See Archive versus Exploded Archive Directory.
- Never deploy untested code on a WebLogic Server instance that is serving production applications. Instead, set up a development WebLogic Server instance on the same computer on which you edit and compile, or designate a WebLogic Server development location elsewhere on the network.
- Even if you do not run a development WebLogic Server instance on your development computer, you must have access to a WebLogic Server distribution to compile your programs. To compile any code using WebLogic or J2EE APIs, the Java compiler needs access to the `weblogic.jar` file and other JAR files in the distribution directory. Install WebLogic Server on your development computer to make WebLogic distribution files available locally.