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:
- First, create Java™ Authentication and Authorization Service (JAAS) entry.
- Then create a JDBC provider, and set the value for the WebSphere variable.
- 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:
Listing 1. The Rational Application Framework for WebSphere 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 sourcesaction. Important: Notice that all of the resource configuration action names start with
- 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
-ecommand 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_datasourcesaction 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
-t(execute), the framework tool reads the data source configuration from the XML file and applies it to the running server.
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:
- 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:
- Configuration change management: Actions that are used for configuring and
managing the WebSphere server. The Configure actions work flow normally starts with
- 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.
Figure 1. List of actions supported at the cell level
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
Figure 2. List of actions supported at the cell level
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.
Listing 2. variable.xml 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
elements that represent two WebSphere variables. The value of
symbolicName attribute represents the name of the WebSphere variable, and the
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
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
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.
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.
Listing 3. variable.xml in the WebSphere Application server configuration directory
<?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
WSAdminscript 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.
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.
Figure 3. Configuration file at a different scope level
You will need to specify fully qualified scope information while executing any command. For
example, you can run the
command at the cell level bu using this syntax:
rafw.bat -e env -c <cellname> -t
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:
- 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
- Node level: You can execute an action at node level by using this
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:
- 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:
- 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:
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.
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.
- Import the WebSphere variables of the target system into an variable.xml file at the cell scope.
- You can modify the variable.xml configuration file by adding one
VariableSubstitutionEntryelement into it.
- 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
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.
You can execute an action in the help mode by using the
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.
Figure 4. Help mode
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
- 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
- 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
file, as well as the XML element that is used for representing a data source element:
- 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
- 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
JDBCDataSourcesin that file.
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
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.
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.
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
Figure 5. The Rational Application Framework for WebSphere Compare mode
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 sourcesaction in execute mode to modify the WebSphere Application Server configuration, in which case the
SampleAlias2object gets created in the running WebSphere Application Server.
- Or by running the
was_common_configure_jdbc_data sourcesaction in import mode, in which case the
SampleAlias2object gets deleted from my jdbc.xml file.
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.
Figure 6. Preview mode
As you can see, when I run the
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.
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.
|Sample Source code for this article||RAFWAppender.jar||13KB|
- 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®.
- Participate in the discussion forum.
- Check out developerWorks blogs and get involved in the developerWorks community.