Managing Configuration Information

There is one problem with our goal to have everything required for the application located in the working directory structure: You cannot reliably control the JDBC, JMS, and other domain-level resources available to the application without manipulating the domain definition. WebLogic Server does provide some limited ability to configure JDBC resources in the application-level weblogic-application.xml descriptor file, a topic discussed in Chapter 8, but this technique does not currently simplify the problem enough to warrant its use.

You need a reliable way for developers to share configuration information to ensure that everyone has identical JDBC, JMS, security, and other resources configured on their machine. The classic approach in which a developer makes the configuration change on his or her machine and informs everyone else via email is not reliable or scalable. At least three mechanisms exist for sharing WebLogic Server configuration information among developers: controlling the config.xml file, script-based approaches, and new techniques for configuration template creation and replay.

Controlling the config.xml Configuration File

Recall that all services and resources configured in the domain are stored as XML information in the config.xml file, located in the domain s root directory, to make them available the next time the administration or stand-alone server starts. If, for example, some developer creates a new JMS destination through the administration console on his or her machine, that developer s version of the config.xml file will include elements not present in other developers versions of the file. How does that developer propagate the new elements in config.xml to the other developers on the team?

The obvious solution is to place config.xml in source-code management, but there is a problem with this solution. WebLogic Server uses a hashing algorithm to encrypt passwords and other security information stored in the config.xml file, and the hashing algorithm depends on an encryption key that differs across domains. A config.xml file that works in one domain will fail in another domain because the other domain will not be able to decrypt the information. Because each developer has a separate domain, this clearly won t work.

We d be unable to share the config.xml file through source-code management except for a little-known fact about the password attribute: You can hand-edit the value to be a clear-text version of the password, and the administration server will read it and encrypt it again using the proper key in your domain the first time it loads the file. Checking in the config.xml file with clear-text passwords allows the other members of the development team to check it out and reboot their servers to reflect your configuration changes.

Two security- related elements in the config.xml file also contain encrypted credential information and must be removed before checking in the file:

 <EmbeddedLDAP         Credential="  {3DES}dU8ou74vb7...  " Name="bigrezdomain"/> ... <SecurityConfiguration         Credential="  {3DES}uPgUp1DsrQJ8UR0...  " Name="bigrezdomain"/> 

Fortunately, these elements are not required for proper server operation in a simple development environment and may be deleted to create a clean, encryption-free version of config.xml . The next time the server is started these elements will be recreated automatically.

The primary advantage of this technique is its simplicity. It is easy for developers to update configurations; the work of creating a clear-text version of config.xml is performed once by the developer making the change, and no additional steps are required to make or import the changes to individual domains.

Disadvantages include the danger inherent in hand-editing the config.xml file and the fact that this technique provides no extension to the more-general problem of migrating configuration information between development, test, and production environments. We strongly recommend that you avoid using config.xml files to control and distribute configuration changes between developers.

Best Practice  

Although it is possible to distribute and manage configuration information by placing the config.xml file in source-code control, this technique is not recommended.

Using MBean and WLShell Scripts

All configuration information in WebLogic Server is accessible and configurable using MBeans. Scripts that access and manipulate these MBeans can therefore be used to control and distribute configuration information across the development team in much the same way a database-creation script is used to configure and manage a database schema.

weblogic.Admin Utility

The weblogic.Admin utility provides a command-line interface for issuing appropriate GET, SET, INVOKE, CREATE, and DELETE operations on MBeans in the WebLogic Server environment. MBeans are identified using either the -mbean parameter or a combination of -type and -name parameters:

 -mbean domain:Name=xxx,Type=yyy,Server=zzz,parent=aaa 

or:

 -type yyy -name xxx 

Commands can alter permanent configuration information by modifying the administration version of the MBean or modify current information on a particular server by manipulating the Configuration MBean associated with that running server. See the online documentation for a detailed explanation of the different types of MBeans and their relationships. The important weblogic.Admin commands related to MBeans are the following:

CREATE.    Create an Administration Mbean.

DELETE.    Remove an MBean from the configuration.

GET.    Retrieve property information from an Mbean.

INVOKE.    Invoke a management method on an Mbean.

SET.    Set a property value within an Mbean.

The syntax for these commands is shown here:

 CREATE -name name -type mbean_type [-domain domain_name] DELETE {-type mbean_type-mbean mbean_name} GET [-pretty] {-type mbean_type-mbean mbean_name}     [-property property1] [-property property2] ... INVOKE {-type mbean_type-mbean mbean_name}      -method methodname [argument ...] SET {-type mbean_type-mbean mbean_name} -property property1      property1_value [-property property2 property2_value] ... 

WebLogic Server 8.1 also introduces a BATCHUPDATE command that executes a series of commands contained in a script. For example, the following command line invokes the weblogic.Admin utility and executes the commands contained in the makepool.txt file:

 java weblogic.Admin -url http://localhost:7001    -username system -password weblogic  BATCHUPDATE -batchFile makepool.txt  

The makepool.txt file contains the MBean commands required to create a JDBC connection pool, for example, and target it to a specific server in the domain, as shown here:

 CREATE -name BigRezPool -type JDBCConnectionPool SET -mbean mydomain:Name=BigRezPool,Type=JDBCConnectionPool    -property DriverName oracle.jdbc.driver.OracleDriver   -property URL jdbc:oracle:thin:@localhost:1521:DEV   -property Properties "user=bigrez;protocol=thin"   -property Password bigrezpw   -property InitialCapacity 4   -property MaxCapacity 10 INVOKE -mbean bigrezdomain:Name=BigRezPool,Type=JDBCConnectionPool   -method addTarget bigrezdomain:Name=myserver,Type=Server 

It is easy to see that a master script containing the appropriate MBean commands could be used to create and manage all JDBC, JMS, and security resources in the environment. This script would be easy to manage through the source-code management system and could become part of an update or build process on developer workstations. Separate master scripts might be maintained for test and production environments to provide an automated way to modify and promote configuration information in these environments.

Advantages of this simple weblogic.Admin scripting approach include the following:

• MBean scripts are easy to manipulate, edit, and share among developers.

• MBean commands can create and modify all configuration objects and services in a domain.

• Scripts are useful for promoting configuration information to test and production environments.

Disadvantages might include the complexity of the MBean naming syntax and the lack of conditional, looping, and branching logic in these simple scripts. These disadvantages are addressed by two alternate techniques that rely on the same underlying MBean infrastructure in WebLogic Server but provide a friendlier interface for accessing the MBeans.

wlconfig Ant Task

WebLogic Server 8.1 introduced a new Ant task, wlconfig , that provides a simplified technique for accessing and manipulating MBeans in the domain. The wlconfig task includes get , set , create , delete , and query functions and uses a simpler technique for naming and referencing MBeans in the domain. For example, creating the same JDBC connection pool using wlconfig requires the following elements in the Ant build file.

 <wlconfig url=http://localhost:7001      username=system password=weblogic>   <query domain=bigrezdomain type=Server        name=myserver property=server.mbean/>   <create type=JDBCConnectionPool name=BigRezPool>     <set attribute=DriverName          value=oracle.jdbc.driver.OracleDriver/>     <set attribute=InitialCapacity value=4/>         <set attribute=MaxCapacity value=10/>     <set attribute=Properties value=user=bigrez;protocol=thin/>     <set attribute=Password value=bigrezpw/>     <set attribute=URL value=jdbc:oracle:thin:@localhost:1521:DEV/>     <set attribute=Targets value=${server.mbean}/>   </create>   ...  </wlconfig> 

Note that the query element defined a server.mbean property used later in a set element to target the connection pool to the desired server in the domain. Support for properties and the nesting of elements in other elements provide techniques for interrogating and traversing the hierarchy of MBeans in a build script.

Like weblogic.Admin scripts, wlconfig tasks placed in a master build file for the project represent a viable scripting technique for managing and sharing configuration information across developer workstations. Using the wlconfig task clearly provides better integration with build scripts in the development environment and represents an improvement over weblogic.Admin scripts in that role.

Best Practice  

The wlconfig Ant task provides a powerful technique for scripting configuration information and integrating it in the overall development build process.

Unfortunately, test and production environments are not typically managed using Ant so the wlconfig approach may not be suitable for migrating and promoting configuration information to those environments. Fortunately, there is one final scripting technique to discuss ”a technique that appears to be both appropriate and powerful across all environments: the WLShell utility.

WLShell Utility

WLShell is a free shell interface for WebLogic Server written by Paco G ³mez, an architect at BEA. It represents the hierarchy of MBeans in a domain as a directory structure and provides a Unix-like shell interface for traversing, listing, querying, and managing all MBeans in the hierarchy. For example, navigating to a JDBC connection pool and changing the maximum number of connections using WLShell requires the following commands:

 wlsh> connect localhost:7001 system weblogic wlsh> cd JDBCConnectionPool wlsh> cd BigRezPool wlsh> set MaxCapacity 20 

MBeans can also be addressed directly using a syntax much like a fully qualified path to a file:

 wlsh> set /JDBCConnectionPool/BigRezPool/MaxCapacity 20 

Like the other scripting techniques, WLShell features the typical get, set, invoke, create, and delete commands for manipulating MBeans, but it provides many additional features as well. These features include the following:

• Powerful scripting language with loops , conditionals, variables , and many other features

• Shell environment featuring auto-completion and a command history

• Java explorer interface for viewing MBean hierarchy and contents

• Graphical monitoring tools to track any run-time MBean value or delta

• A config-to-script utility, c2w , capable of reading a config.xml file and creating the set of WLShell commands required to replicate the environment

As a simple example, the WLShell script required to create the BigRezPool JDBC resource looks like this:

 connect localhost:7001 system weblogic // create and target the pool md /JDBCConnectionPool/BigRezPool cd /JDBCConnectionPool/BigRezPool set DriverName oracle.jdbc.driver.OracleDriver set URL jdbc:oracle:thin:@localhost:1521:DEV set Properties (java.util.Properties) user=bigrez;protocol=thin set Password bigrezpw set InitialCapacity 4 set MaxCapacity 10 invoke addTarget /Server/myserver // save domain information to config.xml invoke $savedom bigrezdomain 

Space does not permit a detailed discussion of the many features of this tool. You are encouraged to download WLShell from its Web site, http://www.wlshell.com , and give it a try. While not a supported part of the WebLogic Platform as this time, it provides a much-needed command-line interface for administering WebLogic Server and appears to be a very solid application. WLShell works with WebLogic Server 6.1 and later.

Sharing and controlling configuration information would be straightforward using a master WLShell script for each environment. Like the previous alternatives, developers would modify the master script to reflect the changes made to their environment and then check in the modified script for use by the rest of the team.

One advantage of the full scripting language in WLShell is the ability to define resource-definition scripts with variables rather than hard-coded values and then combine these scripts with short scripts that define the parameters. In this way, it might be possible to share scripts between environments if the only differences involve configuration values, resource names, and other things that can be defined as variables. You could also write a script that interrogates the cluster for the names of all servers in the cluster and then loop through these names to perform some action on each server.

The bottom line is that WLShell scripts represent a very good technique for sharing and controlling configuration information in the development, test, and production environments. The tool itself is also very useful as a command-line management, administration, and monitoring utility.

Best Practice  

The WLShell utility provides a powerful Unix-like shell interface to WebLogic Server and a scripting language well suited for managing configuration information in development, test, and production environments.

Template Building/Replay Wizards

The three scripting techniques discussed in the previous section have one thing in common: They are all based on creating and managing resources by interacting with MBeans in the domain. A new technique for managing domain and application configuration involves using the WebLogic Configuration Wizard that comes with WebLogic Server 8.1. The wizard allows you to create a new domain using templates, essentially replaying a prebuilt template to creating the new domain. This wizard also allows you to merge templates that contain application-specific configuration information into an existing domain.

The new WebLogic Configuration Template Builder allows you to create new custom domain templates that define resources, applications, security information, startup and shutdown scripts, and other domain-level information. This tool allows you to create new, preconfigured domains for your application s environment and use the WebLogic Configuration Wizard to replay them. This replay capability provides an easy way to bootstrap new domains that already contain the configuration information needed by your application.

You can also use the WebLogic Configuration Template Builder to create application-specific templates that contain only application components and their related resource information. These application-specific templates, known as configuration extensions, can be used to apply a set of changes to existing domains. This allows you to migrate applications and related resources as a unit or, when combined with an existing domain template, to create a new custom domain template.

Because this capability is new to WebLogic Server 8.1 SP1, it is too early to determine just how effective this will be as a mechanism for either sharing configuration information across developers or migrating configuration data from development, through test, and on to production environments. Given the fact that this appears to be BEA s direction for addressing these issues, it should have some distinct advantages over scripting techniques.

• The Configuration Template Builder and Configuration Wizard are easy-to-use GUI applications providing a step-by-step process for creating and replaying templates. A silent replay mode is available from the command line to support the build and promotion process.

• This technique is likely to understand and support the different products in the WebLogic Platform, meaning that it should handle configuration templating and replay for products like WebLogic Portal and WebLogic Integration, as well as WebLogic Server domains.

Your best bet is to try out the new template creation and replay capabilities and see how they work in your environment. We will now return to the development process itself and discuss one of the key aspects in any development effort, the establishment of a flexible and reliable build process.