JVM Languages

Configuring J2EE Deployment Descriptors

Source Code Accompanies This Article. Download It Now.

Deployment descriptors are J2EE components that manage data connections when connecting to databases or maintaining unique transactions between web sessions.

Steve is president and CTO of Catalyst Systems. He can be contacted at steve.taylor@openmake.com.

If you're a Java developer transitioning to J2EE, you'll encounter many new coding standardsand none are more important than learning to configure "deployment descriptors." Deployment descriptors are J2EE components that manage data connections when connecting to databases or maintaining unique transactions between web sessions.

Managing J2EE deployment descriptor files in large, enterprise environments can be tedious because deployment descriptors are unique to the web server to which they are deployed. When creating WARs and EARs from within an IDE, the IDE allows for the configuration of the deployment descriptor for a single web server. However, large enterprise environments often manage multiple web servers running in development, testing, and production. For each server, deployment descriptors must be updated to reflect the correct configuration for that server. Because IDEs do not handle the creation of multiple deployment descriptors for multiple configurations, the process must be handled manually, outside of the IDE. The result is an error-prone process that requires manual manipulation of the file for each server to which it is deployed. However, there are more efficient methods of managing deployment descriptors than the familiar brute-force method.

If you haven't started J2EE development, and don't understand why these files could cause such an immediate production headache, consider this: A deployment descriptor can be understood by comparing an EAR file to a ZIP file. Imagine that you have a ZIP file containing 1000 files. You want to copy that ZIP file to five different locations, but first you must change some of the text in 10 of the zipped-up files, and the changes are different for each location where you need a copy. This task requires recreating the ZIP file by uniquely configuring the 10 text files and rezipping them five times. Then you copy each ZIP file to the correct location according to the changes made. Essentially, this is the exact process required for deploying a J2EE application to an enterprise environment where multiple server configurations are required.

In most enterprise environments I have worked with, it is common to require a minimum of three different deployment descriptors for a single J2EE application. For example, your J2EE application connects to a database. The name of the database in development is "DEV-DB," in testing it is "QA-DB," and in production "PROD-DB." Your J2EE EAR or WAR needs to have three different versions of the deployment descriptor, one for each database name.

This is a simple example and in many cases the changes between the deployment descriptors go far beyond the name of the database. Regardless, even one change to the deployment descriptor requires that the EAR or WAR be recreated to support multiple servers. When this is the case, I like to know that the correct version of the EAR or WAR is being deployed to the correct server. This problem is not entirely the fault of the J2EE specifications, but largely the result of increased use of third-party modules and interconnectivity of enterprise applications and services. A single application running on a production server may require parameters that specify multiple database connections, log file locations, message queues, security information, CICS HASH(0x180be78), and other server-specific information. Put that same application on a second production server for a different business unit and all of these values could be different. It is not unusual to see applications where as many as 100 values might change. Take an application using parallel development that has five production servers and a few test and development servers and the problem is compounded.

In most J2EE development environments I've worked on, creating multiple deployment descriptors is manual and occurs during a final build or assembly process. The manual task requires that you create a reproducible process to update the runtime values in the deployment descriptors, after development has completed, for each server in the enterprise with its unique configuration, constructing an EAR or WAR file for each environment, and delivering each to the correct environment.

Unlike C or C++, where the runtime environment configuration information can be contained in a separate configuration file and deployed along with the executable, J2EE requires all deployment descriptors and other files be archived into the EAR or WAR file, just like my ZIP file example. It is important to keep in mind that this use of configuration files transfers the problem from being a "deployment" issue, such as the case with C or C++, and squarely into being a "build" issue. This is because an EAR or WAR file must be built for each uniquely configured server. In other environments (such as C or C++), the application team could build one executable and deploy it to multiple servers along with an initialization file (INI). With J2EE, a separate executable (the EAR or WAR file) must be built for each server so that the unique configuration contained in the deployment descriptors is archived into the EAR or WAR file.

Assembling Multiple EARs and WARs

Before you go too far down the path of J2EE development, look beyond what your IDE can provide in the assembly of multiple EARs or WARs. IDEs only allow the creation of one version at a time of your EAR or WAR. If you plan on staying within the IDE, this means you need to adopt a process of building your EAR or WAR multiple timesone for each configuration that your installation requires. The need for automating the process eventually becomes apparent as you quickly tire of this point-and-click assembly method.

To address this complexity, you need to define a solution to build and deploy the EARs or WARs that contain an application and the runtime-specific configuration parameters. This customization requires planning. If you choose to write an in-house solution, get ready for Perl and Ant/XML scripting, along with documentation and providing training to all developers who may be involved in the final assembly process. Also, you can expect to deal with the pains of trial-and-error before coming up with the correct solution that works for your organization. But all of this effort is worth it because the alternativerisking your production environmentis unthinkable for most developers. Here are some tips that will assist you with this process and keep you from the dead ends I've seen many J2EE development shops go down.

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Video

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!