We will see later in this article how these requirements are met by the proposed solution. Let's have a look at the process itself.

Process Overview
The automated process is composed of six steps. In the first step, we need a WebLogic Server domain in its simplest form, (e.g. a nonclustered single server domain consisting of an administration server only), and we need to start the Admin Server of this domain. In the second step we extend this domain to a WebLogic Server cluster, managed by our Admin Server. We also need configurations for machines and the node managers. The third step will configure all required WebLogic Server services like JMS and JDBC resources as well as additional domain configuration settings. In a fourth step, we will copy the files of the application distribution to their target directories. In step five we start the node managers and the managed servers of the cluster. Finally, we will deploy and activate the applications. Figure 1 illustrates the six separate steps of this approach.

 

The BEA WebLogic product contains a number of tools that provide support during development and administration (i.e. WebLogic Workshop, WebLogic Builder, and the Domain Configuration Wizard). However none of these tools allows for a script-based automation for transforming an application built into a fully functional and running WebLogic Server domain.

Therefore we combine several tools. The underlying tool suite is composed of the Apache Ant build tool, the BEA WebLogic Domain Configuration Wizard, the WebLogic node manager, and WLShell, a JMX administration tool for WebLogic Server developed by Paco Gomez. Further more we make use of Unix shell scripts and SSH (Secure Shell).

We will use Ant as a basic frame for the automated process. Although we are not executing a build process in software development, there are a number of similarities where Ant seems to be the perfect choice. We want to be platform independent, we split up the whole process in separate steps which will become Ant targets and there are dependencies between these targets. Ant provides the flexibility to run the whole process in a single step or to execute individual targets separately. Furthermore there is a good integration of Ant and Java that we will use to start Java processes for the Domain Configuration Wizard and the WLShell. Ant also provides capabilities to execute shell commands and wait for proper startup of HTTP services, which comes in handy when we need to verify that the Admin Server is started.

Figure 2 shows the complete automated process.

 

The basic frame is an Ant target that executes the whole process. Thus, we satisfy the requirement for a one-step process. We name the main target rebuildAll to highlight the fact that we also want to clean up everything before building a domain. This target is composed of subtargets, which in turn can contain nested targets. This approach enables us to execute individual steps of the automated process separately, which is useful for error analysis as well as for managing an installed domain. We use three basic types of Ant targets. The first type uses Ant to work on the file system. We will use this target type to clean up a domain, to copy distribution files, and to build up the domain's directory structure. The second type executes shell scripts. This is a very convenient way to automate processes in Unix. The downside of shell scripting is its platform dependency. If we want to move to the Windows platform, we have to provide a Windows command file equivalent for every script. Furthermore, large scripts can become very complex and hard to read and maintain. The third type of Ant target calls Java programs, which are very well integrated into Ant. We use it in different situations (e.g. for executing the WLShell). The WLShell itself can read in nested WLShell scripts.

Template Approach
We want to have a single configuration file for changing domain-specific values, but we are using a number of different scripts and configuration files that need access to these values. The proposed solution is based upon the replace task from Ant. The only environment setting that we need is the path to the correct Ant executable.

We define variables with global relevance as properties in the file domain.properties that will be included by the build.xml file. If we want to use such a global variable in any other script or configuration file, we create a template file and use a replacement token for this variable instead. A replacement token is any string that is enclosed in two "@" signs.

 
Figure 3: Template approach using the Ant replacement target

Template files reside in the template.home directory. We create an Ant target trimFiles to generate the target files from the templates and place them in the project.home directory.

Step 1: Simple WebLogic Server Domain
As part of an automated domain set-up, we need a script-based approach for setting up the initial domain. WebLogic Server 7.0 since SP1 features silent install of WebLogic Server where the setup of a WebLogic Server domain is a subactivity.

We automate the creation of a domain with the Ant target buildDomain. This task requires the file silent.xml as input, containing the configuration information for the initial WebLogic Server domain. We only need the configuration for a very simple domain consisting of a single Admin Server. However, it must contain the correct values for the domain name, listen address and port, system user and password, and the correct path to the BEA Home and WebLogic Home. Since these values are domain specific we define them in the domain.properties file and use the template approach to generate the silent.xml file. The Ant target buildDomain calls the dmwiz.sh shell script, from the WebLogic distribution, which creates a new WebLogic Server domain from scratch in silent mode. Prior to this, it checks that all base directories exist and deletes any old domains at these locations. Since deleting open files can cause a lot of trouble on Unix systems, we verify that no process of that domain is running (e.g., we kill the node managers and all WebLogic Server instances). A successful execution of this Ant target will provide us with a newly created WebLogic Server domain that is ready to boot.

From now on, every configuration activity will be JMX based. Therefore we need to start the Admin Server of the new domain. We will use the Ant target startAdmin to call the shell script startAdmin.sh. This is a tailored version of the file startWebLogic.sh and contains some domain-specific information, i.e., domain name, listen address and port. Consequently we generate this script, using the template approach. Furthermore, we generate the file boot.properties, containing user and password, which prevents the Admin Server from prompting for this information. The Admin Server will be started with the "nohup" option; thus, it will continue to run even if we terminate its parent shell. But now we need to detect when to continue with the next step of the automated deployment. We have to wait until the Admin Server is running and accepting JMX commands. We implement the Ant target waitForAdmin, which realizes a very simple busy waiting loop, based on the Ant tasks wait for and HTTP. As soon as the Admin Server answers to a HTTP request, this loop terminates and we can continue with the JMX-based configuration.

STEP 2: CLUSTER CONFIGURATION
As a prerequisite for the cluster configuration, we need to have a WebLogic Server domain with a running Admin Server. The domain configuration is contained in the config.xml file. We could configure a domain by editing this file but that would require a complete domain restart, because changes to the domain configuration are saved by the Admin Server periodically but are loaded only at start time.

We prefer to use a JMX-based approach here and define server and cluster via JMX commands using WLShell. Our working directory of the WLShell is the project home. We name the script that configures the cluster cluster.wlsh. We would expect this script to contain domain-specific information inserted by the template approach. Instead, we use only variables here and read in a further WLShell script, which we name connect.wlsh. connect.wlsh sets all domain-specific variables and connects to the Admin Server. It will be reused in all WLShell tasks. Therefore cluster.wlsh is not a template script (e.g., following the template approach) while connect.wlsh is. cluster. wlsh defines a cluster, managed servers, and adds managed servers to the cluster.

In order to be able to start the domain via the node manager, we need to assign managed servers to machines. The script cluster.wlsh is the perfect place for this, since it defines the managed server and its attributes. However, using a bug of the WLShell version prevents this. As a workaround, we use the WebLogic Admin Utility which gets called by the script admin.sh. The corresponding Ant target is assignMachine. Since all JMX commands can also be issued by the WebLogic Admin Utility, this approach presents a general workaround for all potential WLShell bugs. But since the Admin Utility in BEA WebLogic Server 7.0 has no batch mode, and every JMX call has to be issued separately, this solution comes at the price of increased processing time.

Step 3: JMS and JDBC Configuration
The configuration of J2EE resources like JMS and JDBC is very straightforeward. We use the Ant target buildJMS and buildDB here. Both Ant targets call WLShell scripts, which in turn read in connect.wlsh. connect. wlsh establishes the connection to the Admin Server and defines all relevant variables for the JMS and JDBC configuration. Since connect.wlsh is a template file, we can define all required variables in the domain.properties and feed them into connect. wlsh during the execution of the Ant target trimFiles.

Step 4: Copy Distribution
In this step we copy all application distribution files to the application directory of the domain home, thus making them available to BEA WebLogic Server. The distribution includes all EAR and WAR archives of the business application as well as additional libraries.

If we operate in a multimachine environment, we copy the whole domain (i.e., the domain root directory and all subdirectories) to the participating machines using FTP scripts or SCP (Secure Copy) in batch mode. We introduce a good level of redundancy, since only a subset of files is needed on the nodes that do not run the Admin Server. However, if the Admin Server node fails for some reason, we can quickly start the Admin Server on any of the other machines.

Step 5: Node Manager and Managed Server Start
In this step we want to start the managed servers of the domain. As a prerequisite we need to start the node manager on all involved machines. We use the Ant target startNodeManager, which calls a shell script startNodeManager.sh. This script must contain domain-specific settings (i.e., the listen port and the node manager home), so we use the template approach to generate it. For all remote machines of this BEA WebLogic Server domain, we use SSH commands for remote node manager starts.

Now we can start the managed servers using the Ant target startManaged. Since we want to start a domain with multiple managed servers we use the Ant task parallel, that provides fan-out capabilities and greatly reduces the startup time of a whole domain.

There was a customer project where we had to exclude some managed servers from the parallel server start, since they hosted a JMS service that was required by all other managed servers. Consequently, we fired off these managed servers first. We used the script startManaged.wlsh to start the managed servers via JMX commands.

Step 6: Application Deployment
This is the final step of the automated domain setup. We deploy and activate the business applications on all nodes via JMX commands. We use the Ant target deployApps, which calls the WLShell script deploy.wlsh. We do not have to wait until the managed servers have switched to running mode, because we are connected to the Admin Server, which is already running. The Admin Server starts a deployment task and takes care of the application deployment and activation.

Conclusion
The documented process has already proven it's usability during various customer projects.

Revisiting the requirements, we can state that the proposed solution satisfies "full automation", "single-place configuration", and "domain isolation". Platform independence is not fully satisfied because there are still various shell scripts, which are not directly supported on Windows platforms. However, projects can address this point by using Unix shell implementations for Windows, e.g. cygwin.

The presented solution was developed and tested with BEA WebLogic Server 7.0. WebLogic Server 8.1 introduces some interesting features that we might want to exploit to streamline this process. These features include a tighter integration with Ant, the Configuration Template Builder, and a batch mode of the Admin Utility.

The proposed approach to setting up a BEA WebLogic Server domain can easily be extended to automate some aspects of domain administration and management as well. In some customer projects, we included Ant targets to bounce individual servers or the whole domain. During load tests, we implemented Ant targets to change performance-relevant settings like JDBC connection pool sizes, number of worker threads, or JVM configurations for a whole cluster in a single step.

References

REPRODUCED WITH PERMISSION FROM BEA SYSTEMS.