The following sections describe the steps for creating a WebLogic Server split development directory that you can use to develop a J2EE application or module:
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:
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:
Note: | The split development directory structure does not provide support for developing new Resource Adapter components. |
application.xml
and weblogic-application.xml
).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.
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
).
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 and Packaging from a Split Development Directory describes the wldeploy
Ant task that you can use to automate deployment from the split directory environment.
Figure 3-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.
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:
wlcompile
compiles Java classes and also processes annotated .ejb
files into deployment descriptors, as described in Compiling Applications Using wlcompile.
The following steps illustrate how you use the split development directory structure to build and deploy a WebLogic Server application.
WL_HOME
\server\bin\
directory, where WL_HOME
is the top-level directory in which WebLogic Server is installed.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.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.
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:
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.
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.
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.
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 use the basic source directory layout shown in the figure below.
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 use the source directory layout shown in the figure below.
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.
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:
In other words, do not provide both annotated .ejb
source files and editable descriptor files for the same EJB component.
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.
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.
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.
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:
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.
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
.
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>
-librarydir <directories>
—create build targets for shared J2EE libraries in the comma-separated list of directories. See Creating Shared J2EE Libraries and Optional Packages.
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.
<!-- 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.
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 application
redeploy.javadoc Redeploys just the javadoc module of the application
undeploy Undeploys the entire helloWorldEar application
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. |
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.
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 3-9.
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.
BEA recommends the following "best practices" for application development.
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.