Split Directory Development

WebLogic 8.1 introduces a split development directory structure to facilitate the iterative development of applications on a single WebLogic instance. This development methodology allows you to very quickly create, build, and deploy applications to WebLogic Server. The essence of the methodology, as the name suggests, is a split development directory. In other words, the files within the enterprise application are spread across two directories:

• A source directory that contains the source for the enterprise application and all its modules, including the deployment descriptor files
• A build directory that contains the compiled classes generated by the build process.

Even though it is the build directory that is deployed, WebLogic can recognize the split directory deployment and automatically locate information from both the source and build directories.

The split development directory structure is applicable only to enterprise applications that exist in exploded form. If you are developing web applications or EJB modules only, you easily can organize them in an enterprise application and still benefit from the split development directory approach. The best way to illustrate the technique is by example, and the following sections look at all aspects of the development. We also examine the directory layout, and the various Ant tasks (wlcompile, wlappc, wldeploy, wlpackage) used to support this scheme.

You don't have to use the split development directory scheme if you already have established a build process that prepares the enterprise application and all the necessary modules. However, the split directory layout does let you set up an easily manageable and quickly deployable development environment.

12.6.1 Directory Layout

The most important part of the split directory development approach is the structure of the source and build directories. Example 12-5 illustrates the layout of a sample split development directory.

Example 12-5. A split development directory structure

myappdev/build.xml myappdev/src myappdev/src/myappEar/APP-INF/lib/log4j-1.2.6.jar myappdev/src/myappEar/META-INF/application.xml myappdev/src/myappEar/META-INF/weblogic-application.xml myappdev/src/myappEar/myEJB/META-INF/ejb-jar.xml myappdev/src/myappEar/myEJB/META-INF/weblogic-ejb-jar.xml myappdev/src/myappEar/myEJB/src/com/oreilly/wlguide/MyEJB/MyEJB.java myappdev/src/myappEar/myEJB/src/com/oreilly/wlguide/MyEJB/MyEJBBean.java myappdev/src/myappEar/myEJB/src/com/oreilly/wlguide/MyEJB/MyEJBHome.java myappdev/src/myappEar/www/index.jsp myappdev/src/myappEar/www/WEB-INF/lib/dom4j.jar myappdev/src/myappEar/www/WEB-INF/src/com/oreilly/wlguide/MyServlet.java myappdev/src/myappEar/www/WEB-INF/lib/somelib.jar myappdev/src/myappEar/www/WEB-INF/web.xml myappdev/src/myappEar/www/WEB-INF/weblogic.xml myappdev/build

As you can see, the files within the enterprise application have been split across two directories:

src

The src directory holds the source files for the application and all its modules, including their deployment descriptors. In the example, the src folder includes the web resources for a web application, the source Java files for any servlets and JSP pages, the source Java files for an EJB, and their deployment descriptors. In fact, the src directory also contains any support libraries that may be required by the enterprise application or the web application. In the example, we have placed a dom4j library in the WEB-INF/lib folder, and a log4j library in APP-INF/lib folder.

build

The build directory holds the compiled classes generated by the supplied Ant tasks during the build process. You must refer to this directory when deploying the enterprise application. In the example, we've placed the build directory right next to the src folder. It could be placed anywhere so long as it's accessible to the WebLogic server on which you are going to eventually deploy the application.

WebLogic's split development directory layout provides you with a number of benefits:

• As far as WebLogic Server is concerned, the enterprise application is split across two directories. Hence, the source files never need to be copied over to the deployment directory. WebLogic will automatically locate the required source files, such as the deployment descriptors, JSP pages, and third-party libraries, from their source locations.
• The output generated as a result of compiling the EJBs, servlets, and JSPs is placed in the separate build directory. This clean separation makes for a neater development environment, and lends itself to a more intuitive integration with existing source code version control systems.
• You continue to develop your enterprise application using the exploded directory format. This means that you can make any changes to the source files, without having to synchronize these changes. WebLogic will pick up these changes automatically, and avoid a full redeployment of the application or module. This behavior is similar to the auto-deploy feature we discussed earlier.

12.6.2 Building an Application

To compile the source Java files within an application that uses the split development directory layout, you should use the wlcompile Ant task. Here is an excerpt from an Ant build file that can be used with our example directory layout:

Running this Ant target will compile all the Java files located under the application's src directory, including the source code for the web application under WEB-INF/src and all the EJB modules. The compiled classes will be placed in the build directory. Thus, if you invoke this Ant target on our example application, the following class files are generated in the build directory:

myappdev/build/myappEar/.beabuild.txt myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/MyEJB.class myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/MyEJBBean.class myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/MyEJBHome.class myappdev/build/myappEar/www/WEB-INF/classes/com/oreilly/wlguide/MyServlet.class

The .beabuild.txt file shouldn't be removed because it points back to the source directory and allows WebLogic's deployment machinery to access the source files and deployment descriptors. You can further refine which modules get compiled using the includes and excludes attributes. These attributes should be set to a comma-separated list of modules that you want to explicitly include (or exclude) during the compile. For example, to only compile the EJB module, invoke the wlcompile task as follows:

includes="myEJB" />

Similarly, to compile all application source files except for certain modules, you could invoke the wlcompile task like this:

The wlcompile task simply compiles the source Java files within the application. You also can run the appc compiler over the modules, which goes a step further and compiles the JSP pages and generates the container classes for all EJB modules. If you omit this step, this compilation would otherwise occur at runtime or deploy time. In order to invoke the appc compiler, we've used the wlappc Ant task from within the build script as follows:

In our example, the following additional files will be generated:

myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/stateless_7ismqx_EOImpl.class myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/stateless_7ismqx_EOImplRTD.xml myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/stateless_7ismqx_HomeImpl.class myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/stateless_7ismqx_HomeImplRTD.xml myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/stateless_7ismqx_Impl.class myappdev/build/myappEar/myEJB/com/oreilly/wlguide/MyEJB/stateless_7ismqx_Intf.class myappdev/build/myappEar/www/WEB-INF/classes/jsp_servlet/_ _index.class myappdev/build/myappEar/www/WEB-INF/classes/jsp_servlet/_ _new.class

12.6.3 Deploying an Application

Once you have compiled the enterprise application, you are ready to deploy it to WebLogic Server. Once again, you can either use the Administration Console or invoke the wldeploy Ant task, which functions much like the Deployer tool. The following snippet from an Ant script shows how to deploy the application in the example:

action="deploy" source="${dest.dir}" name="myappEar" />

Notice how we've specified the build directory as the source for the application. Similarly, if you use the Administration Console to deploy the application, again you must refer to the build directory so that WebLogic can detect the split development directory layout. Use the action attribute to specify a particular deployment action. The wldeploy task can perform the same actions as the Deployer tool, so you can specify all of the following values for the action attribute: deploy, undeploy, redeploy, cancel, start, stop, and distribute. The wldeploy task supports other attributes that have the same semantics as the Deployer tool, including the Boolean-valued attributes debug, verbose, failonerror, nowait, nostage, and remote attributes, and the string-valued attributes id, name, and targets. The next example shows how to verbosely redeploy just the web application to a particular server:

12.6.4 Packaging an Application

You also can generate a more traditional EAR from the split development directory layout of your application. The wlpackage task extracts the relevant application files from the source and build directories and packages these into an EAR, either in archived form or exploded directory form. The following two targets show how to package an application that uses the split development directory scheme:

toDir="${dist.dir}/${app.name}" />

Strictly speaking, you don't need to invoke the wlpackage task during the development life cycle. Still, it provides a useful way to package the application, perhaps when it needs to be delivered for testing or used in a production environment.

12.6.5 Generating the Build File

To ease the creation of the build script, WebLogic provides a utility that can automatically generate a build file for compiling, building, deploying, and redeploying the application. All you need to do is simply point the utility to an application's split development directory layout. Here is how we created the build file for the example directory layout:

java weblogic.BuildXMLGen -projectName myappEar -d . -user system -password psst123 srcmyappEar

The user, system, and projectName arguments are made into Ant properties, which subsequently are used in the wlpackage, wldeploy, and wlcompile Ant tasks. The -d argument simply tells the utility where to place the generated build.xml file. The build script is equipped with all the tasks that you could wish for. Here is a list of targets captured by the resulting build file for the example directory structure:

Main targets: appc Runs weblogic.appc on your application build Compiles myappEar application and runs appc build.myEJB Builds just the myEJB module of the application build.www Builds just the www module of the application clean Deletes the build and distribution directories compile Only compiles myappEar application, no appc deploy Deploys (and redeploys) the entire myappEar application descriptors Generates application and module descriptors ear Packages a standard J2EE EAR for distribution redeploy.myEJB Redeploys just the myEJB module of the application redeploy.www Redeploys just the www module of the application undeploy UnDeploys the entire myappEar application

Some of these targets, such as the redeploy.myEJB target, will work only if the application's classloader scheme permits it.