Level: Intermediate Scott Lepech, Principal IT Architect, Real Solutions of North America
25 Jul 2007 This article shows how to use Jython to create
wsadmin scripts to query and modify the Dynamic Operations and Extended Manageability features of your WebSphere™ Application Server Extended Deployment V6 configuration.
Introduction
WebSphere Extended Deployment (WebSphere XD) extends WebSphere Application Server Network Deployment (WebSphere ND), providing an enhanced quality of service in four primary areas: dynamic operations, extended manageability, high performance computing, and business grid. Although the WebSphere admin console GUI is fine for daily administration of WebSphere XD,automation can simplify many repetitive administration tasks, such as creating Dynamic Clusters (DC) and configuring all DC settings in the DC template. Jython scripts, run using the wsadmin command line tool, are ideal for automating WebSphere XD administration tasks. In fact, all WebSphere XD administration tasks can be performed programmatically using wsadmin.
This article shows you how to use Jython scripting to automate the Dynamic Operations and Extended Manageability features of WebSphere XD 6.0.2. It provides an overview of how to interact with WebSphere XD using Jython and describes two sample scripts to show step by step how to query and update your WebSphere XD configuration. Although this articledescribesversion 6.0.2, the concepts will continue to apply to future versions of WebSphere XD.
This article is intended for WebSphere administrators who are familiar with system administration for WebSphere ND or WebSphere XD V6. You should have a good understanding of XD administration and Jython scripting. For more information, see the WebSphere XD Information Center and the IBM Redbook Using WebSphere Extended Deployment V6.0 To Build an On Demand Production Environment (see Resources).
Background
Jython
Jython is an implementation of Python written in Java. It has a very clear, readable syntax. Those new to Jython can learn it quickly, while experienced Jython developers can rapidly develop and deploy scripts. You can easily write Jython scripts and applications with a simple text editor.
Jython is an interactive language, and you can run Jython commands interactively in the Jython interpreter. Jython commands run in the interpreter are dynamically compiled into Java byte code. It's often helpful to execute a Jython program interactivelyto troubleshoot an existing Jython program or to test a new Jython program line by line.
Jython and Java can interact seamlessly. Jython scriptscan import Java classes , and Java programs can call Jython scripts.
Jython's object-orientation gives you the ability to extend existing java classes and use abstract classes. The ability to do static compilation of Jython allows you to turn your Jython scripts into applets, servlets, JavaBeans, or even standalone Java programs.
The wsadmin tool supports both the Jython and Jacl scripting languages. However, as of WebSphere v6.1, Jacl is deprecated. In this article, all of the example scripts are written in Jython.
MBeans
MBeans are managed beans; they are Java objects that represent resources to be managed. The JMX specification defines the APIs and available services for application management and monitoring in Java. More information on JMX can be found in the Sun Microsystems article Java Management Extensions (JMX) Technology Overview (see Resources).
MBeans can programmatically manipulate WebSphere XD components and can expose specific events, which can be monitored. They are used for creating and configuring dynamic clusters and for configuring runtime properties for the autonomic controllers. The Jython scripts described in this article use MBeans to query, create, modify and delete WebSphere XD components.
For a complete list of the public WebSphere XD Mbeans, search for "public JMX" in the WebSphere XD Information Center.
Not all WebSphere XD components are exposed via MBeans. Use the configuration service to manipulate components and artifacts that are not exposed via Mbeans.
The Configuration Service
The configuration service provides an interface you can use to query and modify your WebSphere Application Server configuration. All WebSphere ND and XD objects and their unique properties are stored in XML documents. The configuration service allows you to traverse these documents to find the XML element in the XML document that represents the object you want to query or modify.
Ways to run scripts with wsadmin
When you connect to a WebSphere XD cell, you must run wsadmin connected to a running deployment manager. Do not run wsadmin in local mode (-conntype NONE) and do not connect to any node other than the deployment manager. WebSphere XD has many configuration listeners that make autonomic changes based on changes to the configuration documents. We recommended that you make configuration changes only when connected to a running deployment manager node.
You can execute wsadmin scripts in three different ways, as shown below. All examples are assumed to be run out of the <WAS_HOME>/bin directory where <WAS_HOME> is the install root of WebSphere XD on the deployment manager node. The -lang Jython option specifies that you are using Jython.
- Execute scripting commands contained in a file with the
-f option. This takes a filename as an input and executes the commands in the file silently.
$wsadmin.sh -lang jython-f createNodeGroup.py
The -f createNodeGroup.py option specifies that you are running a file named createNodeGroup.py
- Execute scripting commands as individual commands with the
-c option followed by the individual command to run.
$ wsadmin.sh -lang jython -c 'AdminApp.list()'
|
The -c'AdminApp.list()' option specifies that you are running the Jython command AdminApp.list().
- Execute scripting commands interactively by running without the
-f or -c options.
$ wsadmin.sh -lang jython
After issuing this command, you can enter wsadminstatements one at a time.
Examples
The two examples in this section show how to use Jython scripts to administer WebSphere XD. The first exampleshows how to list all configured WebSphere XD health policies. The second exampleshows how to create a DC and validate it. The code for both scripts is available in the download section.
Example 1: Listing health policies
WebSphere XD introduces a new feature called Health Management. Health Management is a policy-driven approach to monitoring application servers in the cell and taking defined actions when the policy is violated.
Health policies define the health conditions to monitor in the cell.
Health conditions are:
- Excessive response time
- Excessive request timeout
- The volume of work performed by a server
- Storm drain detection
- The age of the server
- Excessive memory consumption
Depending on the health condition, various actions may be taken, such as restarting the server, taking JVM thread dumps, or taking JVM heap dumps.
The complete Jython script for is shown in Listing 1. Listing 2 shows the XML file (healthclass.xml) that the script parses. Each part of the script is then described in detail.
Listing 1. wsadmin script HealthPolicy.py to list all health policies
listHP=AdminConfig.list("HealthClass").split("\n")
if (listHP != ['']):
for eachHP in listHP:
hpname = eachHP.split("(")[0]
print
print hpname
print "---------------------------------------------------"
listAttrib = AdminConfig.showall("" +eachHP+
"").split("\n")
for attrib in listAttrib:
str = attrib.replace('[','' ).replace(']','')
print str
#endFor
#endFor
#endIf
|
Listing 2. healthclass.xml showing the health policy details
<?xml version="1.0" encoding="UTF-8"?>
<healthpolicy:HealthClass xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:healthpolicy="http://www.ibm.com/websphere/appserver/schemas/6.0/healthpo
licy.xmi" xmi:id="MemoryLeak_HP" name="MemoryLeak_HP" description=
" This is a memory leak health policy" reactionMode="3">
<HealthCondition xmi:type="healthpolicy:MemoryLeakAlgorithm"
xmi:id="MemoryLeakAlgorithm_1176986316757" level="NORMAL"/>
<targetMemberships xmi:id="TargetMembership_1176986316758" memberString="XDPRODUCTION"
type="4"/>
<healthActions xmi:id="HealthAction_1176986316757" actionType="HEAPDUMP"/>
<healthActions xmi:id="HealthAction_1176986316758"/>
</healthpolicy:HealthClass>
|
The script first obtains a list of all the health policy configuration object IDs created in the cell and assigns it to a variable called listHP. The listHP variable holds an array of the object IDs for all the health policy XML documents. For readability, we split the array elements by the new line (\n) character.
listHP=AdminConfig.list("HealthClass").split("\n")
|
Next, the script makes sure that the list is not empty.
In the loop below, the variable eachHP is set to the configuration object ID of the health policy. The script uses this ID to reference each individual health policy. The first attribute is the health policy name. The script splits this attribute, then prints the name followed by a simple dividing line to separate the name from the attributes.
Next the script loops through and list all the attributes of the health policy with its assigned value. This is done by using the AdminConfig.showall operation and passing the eachHP variable. It loops back and repeats until it has looped through all the configured Health Policies.
for eachHP in listHP:
hpname = eachHP.split("(")[0]
print
print hpname
print "---------------------------------------------------"
listAttrib = AdminConfig.showall("" +eachHP+
"").split("\n")
for attrib in listAttrib:
str = attrib.replace('[','' ).replace(']','')
print str
#endFor
#endFor
|
Output and description
The output of the script is shown in Listing 3.
Listing 3. Output from the HealthPolicy.py script
MemoryLeak_HP
---------------------------------------------------
HealthCondition "level NORMAL"
Description"Thisis a memory leak health policy"
healthActions "actionType HEAPDUMP actionType RESTART"
name MemoryLeak_HP
reactionMode 3
targetMemberships "memberString XDPRODUCTION
type 4"
|
The memoryLeak_
HP attribute details are listed below.
Name : This is a text value specified by the user when the health policy is created. In this example, the health policy name is MemoryLeak_HP.
Monitoring level: This is called HealthCondition in the healthclass.xml document. There are three levels of monitoring: aggressive, normal, and conservative. This value is specified when the health policy is created. The memory leak monitoring level for this health policy is "normal."
Description: The description is a text value entered by the user when the health policy is created. For this example, the description is "This is a memory leak health policy."
HealthActions: There are three types of actions that can be taken: restart the server, take a thread dump, and take a heap dump. These are pre-selected depending on the type of health policythat is created.
The health actions for this health policy are to create a heap dump and then restart the server. See the table below for the all heath action types with the corresponding numeric values.
Reaction mode: The reaction mode specifies what action WebSphere XD takes. This value is selected when the health policy is created. There are three possible values:
- REACTION_MODE_DETECT_ONLY (1)
- REACTION_MODE_SUPERVISED (2)
- REACTION_MODE_AUTOMATIC (3)
For this example, the reaction mode is 3, which means the health policy is in automatic mode.
Type: The type of the health condition. This value is selected when the health policy is created.There are seven types:
- AGE_CONDITION(1)
- WORKLOAD_CONDITION(2)
- RESPONSETIME_CONDITION (3)
- MEMORY_CONDITION (4)
- LEAK_CONDITION (5)
- TIMEOUT_CONDITION (6)
- STORMDRAIN_CONDITION (7)
In this example, the health condition type is 4, whichmeans it is a memory condition.
Example 2: Creating a Dynamic Cluster
WebSphere XD introduces a new container type called a dynamic cluster (DC). A DC extends the static cluster in WebSphere ND and is associated with a single node group. A DC differs from a static cluster in that its membership is dynamically managed by WebSphere XD. WebSphere XD automatically creates and removes dynamic cluster members based on the node group that the dynamic cluster is associated with. If there are non-WebSphere XD nodes in the node group, WebSphere XD ignores them.
A DC is managed centrally by a DC server template. Any changes made to the DC server template are automatically propagated out to each DC member.
WebSphere ND contains a default node group that is configured out of the box. Any nodes added to the WebSphere cell are added to the default node group. Because of this, WebSphere XD does not allow DCs to be associated with the default node group; a new node group that contains WebSphere XD nodes must first be created.
The major steps to create a DC are:
- Creating a node group
- Add node group members
- Create the DC
- Validate that the DC was created successfully
The complete Jython script is shown in Listing 4.
Listing 4. complete wsadmin script createDC.py to create a DC
#Create Node Group
AdminTask.createNodeGroup('sampleNodeGroup')
#Create Node Group Members
AdminTask.addNodeGroupMember( 'sampleNodeGroup', '[-nodeName tsti05Node01]')
AdminTask.addNodeGroupMember( 'sampleNodeGroup', '[-nodeName tsti06Node01]')
#Create DC
NG="sampleNodeGroup"
DC="sampleDC"
mb=AdminControl.queryNames('type=DynamicClusterConfigManager,process=dmgr,*')
AdminControl.invoke(mb, "createDynamicCluster", NG + " " +DC+ " \"\" \"\" ")
#Save configuration Changes
AdminConfig.save()
#check for new DC
ClusterID=AdminConfig.getid("/ServerCluster:"+DC+"/")
#getDC Members
DCMemberList= AdminConfig.list("ClusterMember", ClusterID).split("\n")
print DCMemberList
|
First, the script creates a node group called sampleNodeGroup.
AdminTask.createNodeGroup('sampleNodeGroup')
|
Next, itadds nodes tsti05Node01 and tsti06Node01 to the sampleNodeGroup
AdminTask.addNodeGroupMember( 'sampleNodeGroup', '[-nodeName tsti05Node01]')
AdminTask.addNodeGroupMember( 'sampleNodeGroup', '[-nodeName tsti06Node01]') |
The script sets variables to hold the DC name and the node group name. A more robust scriptmight pass the DC and node group name as arguments to the script.
NG="sampleNodeGroup"
DC="sampleDC" |
The script gets an instance of the DynamicClusterConfigManager MBean and invokes the Mbean operation createDynamicCluster with the DC and node group as parameters. It then saves the configuration changes.
mb=AdminControl.queryNames('type=DynamicClusterConfigManager,process=dmgr,*')
AdminControl.invoke(mb, "createDynamicCluster", NG + " " +DC+ " \"\" \"\" ")
AdminConfig.save() |
Finally the script validates that the DC was created successfully. It
gets the object ID of the DC and lists the members.
ClusterID=AdminConfig.getid("/ServerCluster:"+DC+"/")
|
It invokes the AdminConfig list operation with the ClusterID name as a parameter, splits the result for readability, andprints the results.
DCMemberList= AdminConfig.list("ClusterMember", ClusterID).split("\n")
Print DCMemberList |
Listing 5. Output from the CreateDC.py script
['sampleDC_tsti05Node01(cells/XDTEST/clusters/sampleDC|cluster
.xml#ClusterMember_1179780138157)',
|
The newly created sampleDC XML document is located in <WAS_HOME>/profiles/<PROFILE NAME>/config/cells/XDTEST/clusters/sampleDC/cluster.xml
Listing 6. cluster.xml from the DC the script created
<?xml version="1.0" encoding="UTF-8"?>
<topology.cluster:ServerCluster xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI" xmlns:topology.cluster=
"http://www.ibm.com/websphere/appserver/schemas/5.
0/topology.cluster.xmi" xmi:id="ServerCluster_1179780130879" name="sampleDC"
preferLocal="false" nodeGroupName="sampleNodeGroup">
<members xmi:id="ClusterMember_1179780144964" memberName="sampleDC_tsti05Node01"
weight="2" uniqueId="1179780138157" nodeName="tsti05Node01"/>
<members xmi:id="ClusterMember_1179780147862" memberName="sampleDC_tsti06Node01"
weight="2" uniqueId="1179780145352" nodeName="tsti06Node01"/>
</topology.cluster:ServerCluster>
|
Conclusion
This article introduced, with examples, how to programmatically interact with WebSphere XD to query and modify the configuration the Dynamic Operations and Extended Manageability features of using the wsadmin scripting tool with Jython. The techniques described here can be used to automate many other WebSphere XD administrative tasks.
Download | Description | Name | Size | Download method |
|---|
| Sample Jython scripts | XDscripts.zip | | HTTP |
|---|
Resources
About the author  | | |
Scott Lepech is a Principal IT Architect with Real Solutions of North America, Inc. a software consulting company specializing in WebSphere ND and XD, SAP, and Microsoft Dynamic's Solutions. He has been working with WebSphere Application Server since version 2.You can reach Scott at slepech@realsolutions-us.com |
Rate this page
| 
