Creating a Split Development Directory Environment

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 Jakarta EE 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 Oracle-provided Ant tasks automatically determine which Jakarta EE 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 Jakarta EE 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 Jakarta EE 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 4-1 Source and Build Directories

Description of "Figure 4-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 Jakarta EE application.

The build and source directory contents can be placed 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 WebLogic Remote Console) support direct deployment from a split development directory. You specify only the build directory when deploying the application to WebLogic Server.

Direct split-directory deployment requires the server process to be able to read both the build directory and the source directory identified by .beabuild.txt. These paths are resolved in the server’s filesystem. If the source tree is unavailable there, use wlpackage to create an EAR or a complete exploded EAR and deploy that packaged output.

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. After moving the source directory, update the build script’s source path and run wlcompile again to regenerate .beabuild.txt. If you edit the file manually, set its bea.srcdir property to the new source-directory path; use Java-properties escaping, or forward slashes for a Windows path. A relative bea.srcdir value is resolved against the build directory.

bea.srcdir=C:/work/helloWorldEar/source

Deploying Applications Using wldeploy describes the wldeploy Ant task that you can use to automate deployment from the split directory environment.

Figure 4-2 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 4-2 Split Directory Deployment

Description of "Figure 4-2 Split Directory Deployment"

Split Development Directory Ant Tasks

Oracle 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:

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 Building Modules and Applications Using wlappc.
wldeploy—This Ant task deploys any format of Jakarta EE 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 wldeploy Ant Task Reference.
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

In a split development directory structure, you can develop and deploy applications faster, simplify build scripts, and integrate with source control systems.

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

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 Jakarta EE modules. See Organizing Jakarta EE Components in a Split Development Directory.
Add one or more subdirectories to the EAR directory for storing the source for Web applications, EJB components, or shared utility classes. See Organizing Jakarta EE Components in a Split Development Directory and Organizing Shared Classes in a Split Development Directory.
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.
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.

Note:

On UNIX operating systems, the setWLSEnv.sh command does not set the environment variables in all command shells. Oracle recommends that you execute this command using the Korn shell or bash shell.
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.
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 for a list of default targets.

Organizing Jakarta EE Components in a Split Development Directory

The split development directory structure requires each project to be staged as a Jakarta EE enterprise application. Oracle therefore recommends that you stage even standalone 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:

The directory examples are taken from the splitdir sample application installed in ORACLE_HOME\wlserver\samples\server\examples\src\examples\splitdir, where ORACLE_HOME represents the directory you specified as the Oracle Home when you installed WebLogic Server; for example, C:\Oracle\Middleware\Oracle_Home. For more information about the WebLogic Server code examples, see Sample Applications and Code Examples in Understanding Oracle WebLogic Server.

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 4-3 Overview of Enterprise Application Source Directory

Description of "Figure 4-3 Overview of Enterprise Application Source Directory"

Enterprise Application Configuration

The following figure shows the top-level layout used by the helloWorldEar sample. It includes META-INF/application.xml and META-INF/weblogic-application.xml. Include the descriptors required by your application’s metadata and WebLogic-specific configuration; both files are not mandatory for every application. A generated build.xml can be stored here or in the output directory selected with weblogic.BuildXMLGen -d.

Figure 4-4 Enterprise Application Source Directory

Description of "Figure 4-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.

Web Applications

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

Figure 4-5 Web Application Source and Build Directories

Description of "Figure 4-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.

The wlcompile task compiles Java sources under helloWebApp/WEB-INF/src into package directories under helloWebApp/WEB-INF/classes in the build tree. To precompile JSPs, run the wlappc task against the compiled application. JSP-generated classes are separate from the application’s Java-source classes. Editable Web deployment descriptors remain in the source tree unless a custom build step copies them. The generated JSP package layout shown in Figure 4-5 is illustrative; JSP-generated classes and classes compiled from WEB-INF/src are distinct outputs.

EJBs

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

Figure 4-6 EJB Source and Build Directories

Description of "Figure 4-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. Use .java source files; these may contain Jakarta Enterprise Beans annotations.
helloEJB/META-INF/—Store the EJB module’s editable deployment descriptors here. The helloWorldEar sample includes both ejb-jar.xml and weblogic-ejb-jar.xml in this directory. Its build script copies these descriptors to helloEJB/META-INF in the build tree; wlcompile itself compiles the Java sources. See Important Notes Regarding EJB Descriptors.

Figure 4-6 retains an older sample layout. In the current helloWorldEar sample, both EJB descriptors are maintained in the source tree and copied by the sample build script.

During the build process, EJB classes are compiled into package subdirectories of the helloEJB module in the build directory.

Important Notes Regarding EJB Descriptors

Keep manually maintained EJB deployment descriptors in the source module’s META-INF directory. Jakarta Enterprise Beans annotations in .java files can define metadata without an ejb-jar.xml descriptor when the specification permits it; deployment descriptors can supplement or override annotation metadata. wlcompile compiles Java sources and does not generate descriptors from .ejb files. If a separate generation step is part of your own build, keep its generated descriptors in the build tree and do not maintain a second conflicting copy as source.

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 4-7 Java Utility Class Directory

Description of "Figure 4-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 4-8 Third-party Library Directory

Description of "Figure 4-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. When searching the application’s own classpath, the application classloader searches APP-INF/classes before JARs in APP-INF/lib. Class resolution also follows the classloader delegation rules and configured package preferences; this ordering does not guarantee that an application class overrides a class visible from a parent classloader. See Understanding WebLogic Server Application Classloading. Understanding WebLogic Server Application Classloading

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 a target to clean the build directory.

BuildXMLGen scans application and module manifests for optional-package references and attempts to resolve them against libraries registered from -librarydir. Resolved references are added as nested library elements in generated wlcompile and wlappc tasks. Put the referenced library in a library search directory and pass that directory when generating the build file. An unresolved reference is not converted into a usable library element.

For example, when lib/echolib.jar is a resolvable optional package, a generated task includes a library element for that JAR. This illustrative path is relative to the generated build file’s project directory.

<target name="appc" description="Runs weblogic.appc on your application">
  <wlappc source="${dest.dir}" verbose="${verbose}">
    <library file="lib/echolib.jar"/>
  </wlappc>
</target>

The generated wlcompile and applicable module targets use the same resolved library.

Substitute actual absolute paths for the illustrative /work paths. Choose an output directory that does not already contain the selected build filename:

java weblogic.BuildXMLGen -librarydir "/work/helloWorldEar/lib" -d "/work/helloWorldEar" "/work/helloWorldEar/source"

weblogic.BuildXMLGen Syntax

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.
-librarydir <directories>—Comma-separated list of directories in which to register and search for shared libraries and optional packages used by application references. Generated library targets correspond to the references found, not every JAR in each directory.
-username <username>—User name for deploy commands.

These values are written into the generated build file. For reusable or source-controlled build files, use the stored-credential customization below instead of supplying or committing a password.
-password <password>—User password.

These values are written into the generated build file. For reusable or source-controlled build files, use the stored-credential customization below instead of supplying or committing a password.
-adminurl <url>
—Administration Server URL written to the generated adminurl property; default iiop://localhost:7001. Set this to the endpoint used by your development domain.

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:

Example 4-1 Properties to Customize After Generation

<!-- 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="servername" value="myserver" /> 
<property name="adminurl" value="iiop://localhost:7001" />

Choose tmp.dir as a writable parent directory for generated files. The generated dest.dir is ${tmp.dir}/${app.name}; dist.dir defaults to ${tmp.dir}/dist. The -d option chooses where the Ant build file is written and does not choose dest.dir. src.dir identifies the source tree; use an absolute source-directory argument when generating a build file in another directory.

The following listing shows selected common targets in the generated build file. Run ant -f <generated-build-file> -projecthelp to list the targets in that file.

Run this example from a project root containing source/. The ant output directory must not already contain build.xml.</p> <codeblock outputclass="language-sh">mkdir -p ant java weblogic.BuildXMLGen -projectName helloWorldEar -d "$PWD/ant" "$PWD/source" ant -f "$PWD/ant/build.xml" -projecthelp

The absolute file paths are illustrative; substitute the actual protected user configuration and key file paths. servername must match the target server used by module-redeployment targets.

"language-sh">ant -f /work/helloWorldEar/ant/build.xml \ -Dwls.userConfigFile=/private/credentials/wls-user.config \ -Dwls.userKeyFile=/private/credentials/wls-user.key deploy

"language-xml"><wldeploy action="deploy" source="${dest.dir}" name="${app.name}" adminurl="${adminurl}" userConfigFile="${wls.userConfigFile}" userKeyFile="${wls.userKeyFile}"/>

Create a WebLogic user-configuration file and its matching key file using storeUserConfig as described with the stored-credential examples in Chapter 2. Keep the pair outside source control and restrict access. In every generated wldeploy task, including deploy, undeploy, module-redeploy and any library targets, remove both user and password attributes and add userConfigFile="${wls.userConfigFile}" and userKeyFile="${wls.userKeyFile}". Remove the unused user/password property declarations as well. Supply the two file paths when invoking a deployment target.

Example: Common Targets in a Generated build.xml

appc Runs weblogic.appc on your application build Compiles helloWorldEar application and runs appc clean Deletes the build directory compile Only compiles helloWorldEar application, no appc deploy Deploys (and redeploys) the entire helloWorldEar application ear Package a standard Java EE EAR for distribution ear.exploded Package a standard exploded Java EE EAR config.server Configure server with resources required by application undeploy Undeploys the entire helloWorldEar application

This is a selected list. The generator also emits compile.<directory> and redeploy.<directory> targets for top-level source directories other than META-INF and APP-INF. For this sample the source directories are appStartup, appUtils, helloEJB and helloWebApp. Use module-redeployment targets only for actual deployable modules, such as helloEJB or helloWebApp; utility-source directories do not become Jakarta EE modules because a target exists. Keep unrelated directories outside the source root. The config.server target is a customization placeholder and does not configure server resources until you implement it. The clean target leaves distribution archives in dist.dir; remove those separately when needed.

Developing Multiple-EAR Projects Using the Split Development Directory

The preceding examples use a single enterprise application. A project that builds multiple EARs can share library and utility-class inputs and coordinate the EAR build files, as described in the following sections.

Note:

The retained MedRec diagram is a historical illustration of the multiple-EAR sharing pattern. Its directory and JAR names are not the installed sample layout for this release. Consult the installed sample’s own instructions for its current source location and build commands.

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 4-9 Shared JAR Files in MedRec

Description of "Figure 4-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 4-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 main build.xml file that calls the other 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 main build.xml file. The following line from the MedRec main 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 main build file to 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

The WebLogic Server documentation library includes a number of recommended best practices for application development, including topics such as packaging, distribution, deployment, and more.

For the Ant split development directory workflow described in this chapter, use the following practices. Other supported build workflows, including Maven, can use their own source layouts.

Organize this split-directory project as an enterprise application, including when it contains only one Web or EJB module. See Organizing Jakarta EE Components in a Split Development Directory.Organizing Jakarta EE Components in a Split Development Directory
Use the source/build separation and the corresponding split-directory Ant tasks described in this chapter.
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.
Set the compile-time classpath to the APIs used by your application. Applications using only standard Jakarta EE 11 APIs can compile against the Jakarta EE 11 API dependency without installing WebLogic Server on the compilation machine. In Maven, use jakarta.platform:jakarta.jakartaee-api:11.0.0 with provided scope; the target server supplies these APIs at runtime. Do not bundle the platform API JAR in the application. WebLogic-specific APIs and the WebLogic Ant tools used in this chapter require the corresponding WebLogic Server distribution classes and environment.

Using the WebLogic Maven Plug-In

<dependency>
  <groupId>jakarta.platform</groupId>
  <artifactId>jakarta.jakartaee-api</artifactId>
  <version>11.0.0</version>
  <scope>provided</scope>
</dependency>

Optional Maven compile-time API dependency:

4 Creating a Split Development Directory Environment