Introduction

The IBM® Rational® Application Framework for WebSphere® provides infrastructure to automate installation and patching, resource management, and application deployment for IBM® WebSphere® Application Server and IBM® WebSphere® Portal. This article gives you a closer look at how you can use this tool for resource management, for example managing data sources, Java™ Message Service (JMS) queues, mail, or URL resources. These are some of the ways that you can use this Rational framework:

• Performance tuning: One of the important aspects of performance tuning is to tune the resources. For example, an administrator can figure out what is the maximum number of database connections or optimum number for prepared statement cache size that should be used to handle a real world load. After the performance testing environment is tuned, you can use the Rational framework to copy all the settings from performance testing environment and apply them to production environment.
• Automating deployment of resources: Most companies have separate teams for developing applications and for installing and managing their WebSphere infrastructure. These companies have one problem: how does a development team let the administrative team know about the resources that their application needs and provide the information required for that? They can either send email with all of the details, and someone can manually make all of those changes, or they can use IBM® Rational® Build Forge® plus the Rational Application Framework for WebSphere to create a Web-based work flow that the development or infrastructure team can use for creating resources.
• Release management: Most companies use the development environment or the integration testing environment to integrate code developed by different teams, thereby creating resources required by different applications, to make sure that everything works together. When the integration testing is successful, you can use the Rational Application Framework for WebSphere to move that release from one environment to another. For example, you can move the release from development to staging to QA (quality assurance) and, finally, to production.
• Creating resources as part of the installation process: You might want to create resources as part of installation. For example, you might want to create data sources that point to your central database or to create a couple of JMS queues as part of installing a new environment. You can use the Rational Application Framework for WebSphere to automate both the installation and creation of the resources, as part of installation

The Rational Application Framework for WebSphere is a command line tool that provides commands for automating individual resource. For example, there is one command that you can use for manipulating a Java™ Database Connectivity (JDBC) provider, another for manipulating a JDBC data source, and so on. The software is bundled with Rational Build Forge, which is build and release management software. You can use Build Forge to create a work flow that defines the steps required for creating data sources, and that work flow can call several of the Rational Application Framework for WebSphere commands. For example:

1. First, create Java™ Authentication and Authorization Service (JAAS) entry.
2. Then create a JDBC provider, and set the value for the WebSphere variable.
3. Then create a data source, and so forth.

This article is the first part in a two-part series about how you can use this framework for automating deployment of resources in WebSphere Application Server. This first part covers the basics of resource management in the Rational Application Framework for WebSphere. The second part is a step-by-step tutorial about how you can use the combination of the Rational Application Framework for WebSphere with Rational Build Forge to automate deployment of the resources. You learn how the resource configuration is stored, how to create resources of different scopes, and how to apply the concept of action modes. Then you put theory into practice by creating a Build Forge project that you can use to automate the deployment of a data source.

The four basic components

The Rational Application Framework for WebSphere tool provides commands for manipulating resources. It provides rafw.bat or rafw.sh files as entry points, and you can invoke it by using the following command line format:

        
rafw.bat/.sh -e <environment>
<Scope> <actionmode> <action> 

The rafw.bat file command line information can be divided into following four basic parts:

• Action: The Action command line parameter is used for specifying the action that you want to perform. You can manipulate the data sources by using the was_common_configure_jdbc_data sources action. Important: Notice that all of the resource configuration action names start with was_common_configure.
• Resource Configuration: The framework is designed so that one Rational Application Framework for WebSphere server can be used to manage multiple environments. For example, you can manage development, staging, QA, and the production environment from one server. Tip: Always specify the name of the environment on which you want to execute actions by using the -e command line parameter
• Action Scope: You can use the Rational framework to execute commands at different levels in the WebSphere scope. For example, if you have clustered environment with three nodes and three servers, the Rational Application Framework for WebSphere can run commands at the cell, node, cluster, or server level. You must pass the scope information through the command line so that the software can detect the scope at which this command should be executed.
• Action mode: The application framework tool uses Action modes to reduce the number of actions. For example, rather than creating separate actions for exporting the data source configuration of a running server and importing data source configuration into the running server, this software introduces concept of Action modes, which are nothing but command line switches. For example, the was_common_configure_jdbc_datasources action is used for manipulating data source. You can use it for exporting the configuration of a running WebSphere Application Server into an XML file by adding an -i (import) command line switch. But if you replace the -i command with -t (execute), the framework tool reads the data source configuration from the XML file and applies it to the running server.

Action

The Action represents the name of the automation work flow that you want to run on the target system. The Rational Application Framework for WebSphere framework supports following three types of actions:

1. Installation and patching: Actions that are used for installing WebSphere products and applying fixes and fix packs to those products. Actions of these types have install in their names, for example:
   was_61_install_was
2. Configuration change management: Actions that are used for configuring and managing the WebSphere server. The Configure actions work flow normally starts with this:
   was_common_configure.
3. Enterprise application deployment:Actions that are used for managing enterprise application deployments. Actions that fall under this category typically manage WebSphere enterprise applications or WebSphere portal, portlet, and page configuration.

You can use the -l command line switch to get the list of the actions that are supported by the Rational framework at a given scope level. This list is calculated dynamically, based on the server type and topology. Therefore, if you try to get a list of actions supported at the WebSphere Application Server level, it will be different from the list of actions supported by Websphere Portal Server at the server level. Also, the list of actions supported at the cell level will vary, depending on whether it is a standalone or Network Deployment (ND) installation. For example, in the ND installation, there will be actions for starting, stopping DMGR, managing work flowdes, and so forth. Figure 1 shows a screen capture that represents the list of actions supported by the Rational Application Framework for WebSphere at cell level in the WebSphere Application Server Version 6.1 environment.

Resource configuration

WebSphere Application Server provides a very user-friendly approach to managing resources. For example, when you try to configure a data source for connecting to an Apache Derby server, the only thing that it asks you for is the database name, and that information is sufficient to get you started. But if you are an advanced user, it gives you the option to configure more than 10 different properties at the Connection pool level and more than 10 different properties at the data source level. You get very granular control over the behavior of the data source.

Because it is a command line tool, it isn't possible to use Rational Application Framework for WebSphere to provide all of the configuration properties or parameters. Yet the developers wanted to give you the flexibility of fine-tuning all of the properties provided by the WebSphere Application Server, so the Rational framework uses resource configuration files. The resource configuration files are XML files that are used for storing the resource configuration in the Rational framework-specific way. Usually, there is one-to-one mapping between a resource configuration file and action. For example, JAAS configuration is stored in the JAAS.xml file and the WebSphere variable configuration is stored in the variable.xml file, but there are some exceptions. The jdbc.xml file contains configuration for both JDBC providers and data sources. You can find the fully qualified name of the resource configuration file in the Help topic for actions.

Let’s take a closer look at the Rational Application Framework for WebSphere resource configuration file concept. First, we'll look at the WebSphere Application Server Configuration (on my local machine), and then we'll look at how that configuration is stored in the framework's resource configuration file.

Figure 2 is a screen capture of the WebSphere Application Server administration console on my local machine. As you can see, I have two variables defined at the cell level: one is WAS_CELL_NAME and the other is DERBY_JDBC_DRIVER_PATH.

That WebSphere configuration (Figure 1) is represented by using the following variables.xml file shown in Listing 2 in the Rational Application Framework for WebSphere environment tree.

         
<?xml version="1.0"?>
<Variables> 
<!-- BEGIN variables -->
<VariableSubstitutionEntry symbolicName="WAS_CELL_NAME" value="LENOVO-4CB078C9Cell01"> 
</VariableSubstitutionEntry> <VariableSubstitutionEntry
 symbolicName="DERBY_JDBC_DRIVER_PATH" value="C:/software/db-derby-10.5.3.0-bin/lib" >
</VariableSubstitutionEntry> 
<!-- END variables -->
</Variables> 

As you can see, my variable.xml file has Variables as a top-level element, and it has two VariableSubstitutionEntry elements that represent two WebSphere variables. The value of symbolicName attribute represents the name of the WebSphere variable, and the value of value attribute represents the value of the WebSphere variable. You do not have to remember the format of any of the files. You can always export configuration of the current server into XML file by using the Rational Application Framework for WebSphere or else look at BuildForge\rafw\samples\xml\was directory, which has a sample XML configuration file for each of the resources. You can use the template file as starting point.

The Rational Application Framework for WebSphere framework tool is very configuration file-centric. If you want to create a new variable, you open your variable.xml file and add one VariableSubstitutionEntry element with the correct values to it, and then import it into the WebSphere Application Server. Similarly, if you want to update the value of a WebSphere variable, you modify the variable.xml file to set the correct value and then import it into WebSphere Application Server by using the Rational Application Framework for WebSphere. You can delete a variable by deleting the VariableSubstitutionEntry element that represents it from the variable.xml file, and then importing it into the WebSphere Application Server by using the Rational framework tool. You will get a closer look at this during the discussion about action modes. But before you do that, you must learn about the concept of action scopes.

Note:
Under the hood, WebSphere Application Server also uses the .xml file to store the resource configuration. The resource configuration XML files are stored in the profiles_home/<profilename>/config/ directory. This is how the variable.xml file, as Listing 3 shows.

         
<?xml version="1.0" encoding="UTF-8"?> 
<variables:VariableMap xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:variables="http://www.ibm.com/websphere/appserver/schemas/5.0/variables.xmi"
xmi:id="VariableMap_1"> 
<entries
    xmi:id="VariableSubstitutionEntry_1261708415953" symbolicName="WAS_CELL_NAME"
    value="LENOVO-4CB078C9Cell01"/> <entries
    xmi:id="VariableSubstitutionEntry_1261760108343" symbolicName="DERBY_JDBC_DRIVER_PATH"
    value="C:/software/db-derby-10.5.3.0-bin/lib"/>
</variables:VariableMap> 

As you can see from Listing 3, there are also entries for storing two variables. There are few differences in how the Rational Application Framework for WebSphere stores configuration, compared to how the WebSphere Application Server stores configuration:

• The first is that the configuration files in the Rational framework are more user-friendly, because users are supposed to work with these files directly. In the case of the WebSphere Application Server, users are not supposed to worry about how the configuration is stored. Instead, they should use either the WebSphere Application Server admin console or WSAdmin script to modify resources.
• The second difference is that there is work flow one-to-one mapping in the .xml file in the WebSphere Application Server and the Rational Application Framework for WebSphere. For example, WebSphere Application Server stores resource configuration for multiple resource types (such as JDBC, JMS, mail, and URL resources) in the resources.xml file, but the Rational Application Framework for WebSphere has a separate .xml file for each of the resource types. The Rational framework stores JAAS entries in the jaas.xml file, but in WebSphere Application Server, JAAX entries are stored in the security.xml file in addition to several other security-related configuration files.

Action scope

The WebSphere Application Server concept of scope is used for controller visibility of the resource. For example, if you create a data source at the cell level, it will be available to all of the applications running in that cell. But if you create a data source at the server level, it will be available only to the applications that are running inside of that particular server. Not all resources support the concept of scope. For example, the JAAS entries are always created at the cell level, but the data source, WebSphere variables, and JDBC providers can be created at different levels. If the resource that you are creating supports multiple scopes, the WebSphere Application Server admin console will display a Scope Select box at the top of the page, and it will require that you choose one of the scopes before creating resource.

The Rational framework also supports the concept of scope by using the environment tree, which is a directory structure used for storing resource configuration files. The framework stores resource configuration files at the appropriate scope level. For example, I have one jdbc.xml file at the cell level, one at the cell level, and one at server level. The jdbc.xml file that is at the cell level has data sources defined at the cell level; whereas, the jdbc.xml file at the server level has the definitions for data sources at the server level. Figure 3 shows how the environment tree looks on my machine.

You will need to specify fully qualified scope information while executing any command. For example, you can run the was_common_configure_jdbc_data sources command at the cell level bu using this syntax:
rafw.bat -e env -c <cellname> -t was_common_configure_jdbc_data sources

And you can run the same command at the server level by using this syntax:
rafw.bat -e env -c <cellname> -n <nodename> -s <servername> -t was_common_configure_jdbc_data sources

The basic idea is that to fully qualify the server name, you must know the cell name, node, and server name, so you must specify those values on the command line. The Rational Application Framework for WebSphere framework supports the following four scope levels:

1. Cell level: You can execute an action at the cell level by using this syntax:
   rafw.bat -e <env_name> -c <cell_name> -t <action_name>
   When you do that, the Rational Application Framework for WebSphere will use the resource configuration file stored in the user\environments\<env_name>\cells\<cell_name> directory.
2. Node level: You can execute an action at node level by using this syntax:
   rafw.bat -e <env_name> -c <cell_name> -n <node_name> -t <action_name>
   When you do that, the framework will use the resource configuration file stored in this directory:
   user\environments\<env_name>\cells\<cell_name>\work flowdes\<node_name>
3. Server level:You can execute an action at the server level by using this syntax:
   rafw.bat -e <env_name> -c <cell_name> -n <nodede_name> -s <server_name> -t <action_name>
   When you do that, the Rational Application Framework for WebSphere will use the resource configuration file stored in this directory:
   user\environments\<env_name>\cells\<cell_name>\nodes\<node_name>\servers\<server_name> directory
4. Cluster level: You can execute action at the cluster level by using this syntax:
   rafw.bat -e <env_name> -c <cell_name> -u <cluster_name> -t <actionaname>
   When you do that, the Rational Application Framework for WebSphere will use the resource configuration file stored in this directory:
   user\environments\<env_name>\cells\<cell_name>\clusters\<cluster_name>

Note:
If you look at the WebSphere Application Server installation on your local machine, you will notice that it also maintains the topology information in the form of a directory structure inside of the profiles\<profilename>\config directory. At the top level, it will have a cells directory with one directory for each cell. Every cell directory will have one nodes directory that will have one directory for each of the work flows in your cell, and so forth. You will find multiple versions of the resources.xml and variables.xml files at every level. If you define the data source at the cell level, the data source configuration will get stored in the resources.xml file at the cell level directory.

Action modes

The concept of exporting the configuration of the current system into an XML configuration file and importing the configuration from the XML configuration file into a target system form the basics of the resource management in the Rational Application Framework for WebSphere framework. For example, you will need to follow these steps if you want to create a WebSphere variable at the cell level.

1. Import the WebSphere variables of the target system into an variable.xml file at the cell scope.
2. You can modify the variable.xml configuration file by adding one VariableSubstitutionEntry element into it.
3. Then you can export the configuration from the XML configuration file into the targeted system. At that time, the Rational Application Framework for WebSphere framework will either add, update, or delete the variables in the target system to make sure that they are in sync with the variables.xml file.

This concept of importing and exporting is used for managing every type of resource. Rather than creating a separate action for import and export, the Rational Application Framework for WebSphere uses the concept of action modes, which are essentially command line switches. For example, the was_common_configure_variables action is used for manipulating the WebSphere variables. You can import the configuration of target system into the Rational Application Framework for WebSphere by using the -i command line switch, which is also called as running the action in import mode. But if you want to export the current the Rational Application Framework for WebSphere configuration into a target system, you can use -t switch. As you can guess, it is called as an import mode. In addition to import and export, the Rational framework also has compare mode in which case the Rational Application Framework for WebSphere does not make any changes in the configuration but just compares the framework configuration to the target WebSphere Application Server configuration. Let's take a closer look at each of these modes.

Help mode

You can execute an action in the help mode by using the -d switch. When you do that, the Rational Application Framework for WebSphere will provide detailed help for that action. Figure 4 shows what the Help screen for was_common_configure_jdbc_data sources looks like.

The action help is divided into following parts:

• Description: This section provides a dynamic description of what this action does. the screen capture represents the help at cell scope, so it says "The action is supported on all currently supported WebSphere Application Server versions and relies on the jdbc.xml file in the environments tree at the cell level." This help will change, based on the scope.
• Required data: The required data section displays a list of required data that must be set into various configuration files to run this action. It can be divided into two parts:
  • Environment data: The first part displays the list of data that is required at the environment level. Things such as the configure.properties must have values for WAS_USERNAME, WAS_PASSWORD properties.
  • Configuration data: The second part of the required data section contains information about the fully qualified path of the resource configuration file. It relies on the entries existing in the D:\IBM\BuildForge\rafw/user/environments/dev/cells/LENOVO-4CB078C9Cell01/jdbc.xml file, as well as the XML element that is used for representing a data source element: JDBCDataSources
• Supported modes: This section lists which modes are supported by this action.
• Notes: This section provides notes about the work of this action. In my screen capture, it is describing that when you execute was_common_configure_jdbc_data sources, it will iterate through the jdbc.xml file and create one data source for evey JDBCDataSources in that file.

Execute mode

You can execute an action in execute or export mode by using the -t command line switch. In the execute mode, the Rational Application Framework for WebSphere framework will read the XML configuration file and apply the configuration to the targeted server. When you execute the was_common_configure_jdbc_data sources action in Execute mode, the Rational framework first find the appropriate jdbc.xml file for the current scope level. Next, it will delete all of the data sources in the server at the appropriate level, and then it will iterate through all of the JDBCDataSources elements in the jdbc.xml file and create one data source for every JDBCDataSources element by using the values specified in the element. As a result, at the end of the Execute mode, the configuration of the running server will be same as that of the jdbc.xml file.

Import mode

You can use the Execute action in the import mode by specifying the -i command line switch. For example, when you execute the was_common_configure_jdbc_data sources action in the import mode, the Rational Application Framework for WebSphere will connect to the running server to determine which data sources it has at the specified scope level. For example, if you run this action at the cell scope, it will find out what data sources the server has at the cell scope, and then it will create one JDBCDataSources entry for every data source element that it finds in the jdbc.xml at the cell level.

Compare mode

You can execute an action in the Compare mode (see Figure 5) by specifying the -r command line switch. This mode compares the differences between configuration data in the Rational Application Framework for WebSphere environment tree and the actual WebSphere configuration data at a particular scope level for the action that you specify. Compare mode is for configuration actions only. The result of the comparison displays the differences in configuration data between the environment tree and WebSphere data.

The screen capture in Figure 5 represents the output when I tried to run the was_common_configure_jdbc_data sources action on a local machine in Compare mode. When I tried executing the action, there was a difference in the configuration of data sources in WebSphere Application Server data and my jdbc.xml file. The jdbc.xml file had a definition of sampleAlias2 data source, but that data source was not defined in the WebSphere Application Server, so it was giving a "objects don't match, differences are..." error report, because there was a missing object.

After I figure out the difference, I can correct it in either of these ways:

• By running the was_common_configure_jdbc_data sources action in execute mode to modify the WebSphere Application Server configuration, in which case the SampleAlias2 object gets created in the running WebSphere Application Server.
• Or by running the was_common_configure_jdbc_data sources action in import mode, in which case the SampleAlias2 object gets deleted from my jdbc.xml file.

Preview flag

You can execute an action in the preview flag by specifying the -z switch. The Preview mode is not a separate mode as such. Instead, it is more of debugging tool. When you add the -z command line switch, the Rational Application Framework for WebSphere tool will display the syntax for the scope and the action specified, but it will not run the action. This information is shown as a part of the output for the action. Figure 5 shows the screen when I tried executing the was_common_configure_jaas action in execute mode and added the -z command line switch.

As you can see, when I run the was_common_configure_jaas execute action in the Preview mode, it shows detailed information about what the execute mode will do. For example, first, it will decode the password, set variables, and then call the jaas.py with jaas.xml as input. You can find out the fully qualified path name of the jaas.xml, as well as the WSAdmin script that is used for modifying the WebSphere Application Server configuration. The preview mode is a very nice tool to use to learn about the internal workings of the Rational Application Framework for WebSphere or to debug any errors that you get.

Summary

This article covered the basics of managing resources by using Rational Application Framework for WebSphere. What I like most about this software is that, after you learn these basics of resource management and use it to manipulate one type of resource, such as data sources, you can apply that knowledge to any other type of resource, such as JMS queues, mail, and URL resources. You can use the Help mode to find information about how to manage a particular resource, such as what action name should be used, what modes are supported by that action, or where to find a template file for resource of particular type. In Part 2 of this two-part article, you will apply this concept to automate deployment of a data source resource.

Back to top

Download

Information about download methods

Resources

Learn

• Rational Application Framework For WebSphere Info Center.
  
  
• Rational Build Forge Info Center.
  
  
• In the Rational Build Forge area on developerWorks, get the resources that you need to advance your skills.
  
  

Get products and technologies

• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

About the author

Sunil Patil is a Java portlet developer who works for Ascendant Technology in San Francisco, California. He is the author of "Java Portlets 101" (SourceBeat, April 2007) and has written numerous articles published by O'Reilly Media, IBM developerWorks, and JavaWorld. In addition to being an IBM Certified WebSphere Portal Server Application Developer for Version 5.0, 5.1, 6.0, and 6.1 and an IBM Certified WebSphere Portal Sever Administrator for V6.1, he is a Sun Microsystems Certified Java Programmer, a web component developer, and a business component developer. He also writes a blog called "Sunil's WebSphere Application and Portal Server Notes" (wpcertification.blogspot.com).

Rate this article

Comments

Back to top

Table of contents

• Introduction
• The four basic components
• Action
• Resource configuration
• Action scope
• Action modes
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers