Automate resource configuration on WebLogic Server

Every deployable J2EE component must be specifically configured on the application server to function. For WebLogic Server, developers generally complete this configuration manually by using the console, by using WebLogic Ant tasks wlconfig and wldeploy, or by using the command line tool weblogic.deployer. The Ant tasks and the command line tools need much environment-specific information for correct configuration, and WebLogic 9.0 recommends limited use of these tools.

Applications don’t have a uniform way for maintaining and communicating configuration information to application deployers, which can result in custom scripts or manual configuration. As custom scripts are difficult to maintain and manual configuration may lead to errors, achieving a smooth propagation and release mechanism for J2EE artifacts proves difficult. This complexity increases when the application must be deployed on multiple environments (development, test, and production) as it is difficult to achieve complete environment independence. Also, when the information is not maintained uniformly across applications, changing application targets on the fly becomes tedious. Hence, every application should consistently maintain its configuration information in a way that is environment-independent. In addition, a tool that can automatically read and perform configuration on the required servers—which should be part of application deployment—would add convenience. Such a tool can also be leveraged to enforce standards and guidelines.

This article provides a sample format in which configuration information should be maintained by the application. It also provides tools in the form of Ant tasks that can read the configuration and deploy it on WebLogic Server. The code samples featured with this article have been compiled and tested on J2SE 1.4.2_03 and WebLogic 8.1., and are valid for WebLogic 7.0, 8.1, and 9.0.

Types of WebLogic Server configuration

J2EE applications generally use connection pools, datasources, Java Message Service (JMS) stores (file store or Java Database Connectivity store), JMS servers, JMS destinations (queues and topics), and distributed JMS destinations. Some of these resources are created on the domain level. Sometimes applications share configuration, sometimes not. The shared configuration should not be deleted when the application is undeployed. This article’s sample Ant task and configuration take care to ensure that shared configuration is not deleted. They also do not overwrite the configuration that already exists.

Resource configuration and WLST

WebLogic creates management beans (MBeans) for every configuration. It uses Java Management Extensions (JMX) to manage and manipulate the MBeans. So, for every configuration, an MBean must be created and deployed. The parameters required for creating the MBean are its name, type, and a set of attributes.

WLST (WebLogic Scripting Tool) is a scripting tool that allows its users to access and manipulate MBeans similar to how they would navigate files on a filesystem. It is a scripting interface that developers can use to configure and interact with WebLogic Server. WLST, which has been incorporated with WebLogic 9.0, can work online as well as offline. When working online, WLST can work in three modes:

• Script mode
• Interactive mode (both command line and GUI)
• Java encapsulated mode

This article focuses on the Java encapsulated mode, a particularly desirable mode because it allows easy creation of Java-based tools (e.g., Ant tasks) for configuration based on WLST without requiring developers to learn WLST’s scripting language syntax.

Create and maintain resource configuration

The best way to maintain resource configuration is by modularizing it. Every deployable application should maintain its own resource configuration so it becomes easy to determine what resources the application requires. The application’s resource configuration can then be propagated to different environments along with the application archive. Thus, resource configurations for an organization’s multiple J2EE applications become easier to maintain and manage.

What better format to save the configuration other than XML? It provides a structured way to maintain configuration and can be governed by a schema to provide validations. The XML file will contain name, type, and set of attributes of the WebLogic Server resource. You just need to know the following information:

• Type of MBean (e.g., JDBCConnectionPool)
• Attributes of the MBean that must be set

The types never change and, usually, attributes that must be set for each MBean remain the same. Hence, it is possible to create a template for the configuration and incorporate it into most of the popular IDEs (e.g., IDEA or Eclipse). The values used in the XML file should be environment-independent, and this XML file should be version controlled. The application bundle propagated during a release should also contain its own resource configuration.

See the source code that accompanies this article for the XML Schema definition and a sample configuration file. Let’s call this XML file the WebLogic Server resource configuration XML.

Configurator task for resource configuration

Once every application starts maintaining its resource configuration, you need a custom Ant task that performs the following objectives:

• Reads the WebLogic application server’s resource configuration XML
• Provides the ability to read environment variables and other default properties from a file/URL/resource
• Runs the configuration for the given set of target servers
• Offers to fail the deployment if configuration deployment fails

This configurator task can use any open source XML binding framework (e.g., Castor, XMLBeans, or Java Architecture for XML Binding) to interpret the XML file. In my example, I used XMLBeans. Then the task needs to generate a WLST-compliant script and trigger it. To run the script online, you must connect to the administrative server, which triggers the configuration. The following are the configurator task’s input parameters:

• url: Administrative server’s URL
• username: Administrative server’s username
• password: Administrative server’s password
• configfile: Configuration file path
• action: Action (create, delete, deploy, undeploy)

The configurator task should first parse the configuration file. It should then connect to a domain’s administrative server. Depending upon the action input parameter, it should create a WLST script using the parameters provided in the XML file and then execute it in embedded mode. After all the configuration has deployed, the task should gracefully disconnect from the administrative server.

The generated WLST script should first check if the bean exists. If it does, then it will not create the configuration. The configurator task should also handle dependency (e.g., datasources depend on connection pools). During the delete, the dependency must be read backwards to ensure correct deletion.

See the samples below for the configurator’s source code.

Ant task reference

The Ant task’s name is com.tanmayambre.wls.tools.anttaskdefs.WLSTConfigurator. It has the following input attributes:

• url: Administrative server URL
• username: Administrative server username
• password: User password
• configFile: Configuration file path
• propertiesFile: File containing environment properties
• action: Create, delete, deploy, undeploy, redeploy

The deploy and redeploy actions internally invoke create to create the configuration first. The attributes can be environment variables. Example target definition:

 
<target name="create-configuration" depends="init-demo">
   <echo message=">>>>>> Creating the Configuration"/>
   <wlsconfig
      username="${weblogic.user}" password="${weblogic.passwd}"
      url="${weblogic.url}"
      configFile="${basedir}/samples/wlsconfig/example.xml"
      propertiesFile="${basedir}/samples/wlsconfig/environment.properties"
      action="create"/>
</target>
<target name="delete-configuration" depends="init-demo">
   <echo message=">>>>>> Deleting the Configuration"/>
   <wlsconfig
      username="${weblogic.user}" password="${weblogic.passwd}"
      url="${weblogic.url}"
      configFile="${basedir}/samples/wlsconfig/example.xml"
      propertiesFile="${basedir}/samples/wlsconfig/environment.properties"
      action="delete"/>
</target>
<target name="deploy-application" depends="init-demo">
   <echo message=">>>>>> Deploying the application"/>
   <wlsconfig
      username="${weblogic.user}" password="${weblogic.passwd}"
      url="${weblogic.url}"
      configFile="${basedir}/samples/wlsconfig/example.xml"
      propertiesFile="${basedir}/samples/wlsconfig/environment.properties"
      action="deploy"/>
</target>
<target name="undeploy-application" depends="init-demo">
   <echo message=">>>>>> UNDeploying the application"/>
   <wlsconfig
      username="${weblogic.user}" password="${weblogic.passwd}"
      url="${weblogic.url}"
      configFile="${basedir}/samples/wlsconfig/example.xml"
      propertiesFile="${basedir}/samples/wlsconfig/environment.properties"
      action="undeploy"/>
</target>
<target name="redeploy-application" depends="init-demo">
   <echo message=">>>>>> Redeploying the application"/>
   <wlsconfig
      username="${weblogic.user}" password="${weblogic.passwd}"
      url="${weblogic.url}"
      configFile="${basedir}/samples/wlsconfig/example.xml"
      propertiesFile="${basedir}/samples/wlsconfig/environment.properties"
      action="redeploy"/>
</target>

Achieving environment independence

Certain runtime configurations can differ across diverse environments. For example, the user ID and password used for connecting to a database in the production environment may differ for the test environment. Writing a configuration file for each environment is a tedious task for developers; they must be aware of all the configurations on all the environments.

Instead, a more efficient approach would abstract that information from the configuration file and maintain it as a separate properties file (or as environment variables). This file should be maintained by the system administrators; developers then just need to use those properties in the configuration file.

The configurator uses a property reader (com.tanmayambre.wls.tools.utils.PropertiesReader) that reads properties from various locations. The properties are read in the order listed below. Those properties read later will overwrite those read earlier (in the case of the same property).

• System properties
• Environment variables
• Properties from a file

Environment variables can be declared for common variables, e.g., environment names and domain names. The properties file contains default values, e.g., user IDs, passwords, maximum capacity, minimum capacity. This file is environment-specific; hence, separate properties files should be maintained for different environments.

Authors of the resource configuration XML file should not use any environment-specific values in the XML. They should use the variables declared as system or environment variables, or as properties in the environment-specific properties file.

This strategy’s advantage is that a developer or an application assembler only writes the configuration once for all environments. The sample code consists of one such property reader that reads the environment-related properties. The configurator task uses the property reader to replace environment variables in the resource configuration XML. This strategy resembles the approach employed by Maven to read environment variables.

Resource naming conventions

Since we are making the resource configuration file environment-independent, we can enforce developers and application deployers to standardize on the names used for the resources. This will enforce uniformity across environments and help in effectively maintaining the sanity of the environments. Naming conventions should be published, well-documented, and agreed upon by developers and deployers. Some guidelines on naming conventions are:

• Domain-level resources such as connection pools and JMS stores are deployed across service instances and, hence, shouldn’t use server-specific variables
• Hungarian notation should be followed while giving names
• Application names in the resource names should be used for application-specific resources

Process

The steps below outline the process for developing and maintaining the configuration:

1. Create an environment-specific properties file for every environment (one-time activity).
2. Publish guidelines for resource naming conventions.
3. Create a WebLogic Server resource configuration file as part of application development.
4. Incorporate Ant tasks for creating and deleting resource configuration, and for deploying and undeploying an application in the application’s build.xml file. Make the deployment-related tasks dependent on resource configuration tasks.
5. Check WebLogic Server configuration and build.xml in the version control system.
6. Make application developers aware of the available environment variables.
7. During the release, release the WebLogic Server release configuration.
8. Deploy using Ant tasks. The configurator task provides the ability to create resource configuration as well as deploy applications.

Advantages

The proposed solution comprehensively automates and maintains WebLogic Server configuration. This approach has the following advantages:

• Modular WebLogic Server configuration for each application. Deploying applications on the fly proves easy.
• A structured way of maintaining the configuration.
• WebLogic 9.0 has made WLST official.
• Minimal work required for creating the configuration file.
• Because the tool is in the form of Ant tasks, integrating it with Maven is easy.

Conclusion

In this article, you have seen how to encapsulate WebLogic Server resource configuration within an application. This is achieved by maintaining a resource configuration XML file and using a configurator task to deploy applications along with their required resource configuration. You have also seen how to make the resource configuration file environment-independent. This strategy will help organizations completely automate J2EE application deployment and redeployment, while reducing the scope for errors. Adding version control to resource configuration XML will further help track changes made to application resources.