Saturday, March 27, 2010

How to use wsadminlib.py

There are several ways to make use of wsadminlib. Here are the basic ideas...

1. Reference

If you are looking for the secrets of how to issue some command, browse wsadminlib and search for it. We try to keep related methods together, so you should find similar functions nearby. If you don't find what you need, search the entire file, case-insensitive.

2. Sample code

If you find something you like, feel free to copy/paste from wsadminlib to your own scripts. wsadminlib is provided as a free sample. And if you find something you don't like, feel free to copy and change it.

3. Call from wsadmin shell

You can call methods in wsadminlib directly from the wsadmin shell. I find this really handy when I am setting up a one-time test. For example, go to a command-prompt, and open a wsadmin connection to your deployment manager.

root@ding6:~# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
WASX7031I: For help, enter: "print Help.help()"
wsadmin
>

Include wsadminlib.py:

wsadmin>execfile('/tmp/wsadminlib.py')
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
wsadmin>


Call a method. For example, list all the servers which exist. This is handy for debug when running things manually:

wsadmin>serverStatus()
Server status
=============
NODE dmgr on ding6 (linux) - Deployment manager
NODE node1 on ding6 (linux)
APPLICATION_SERVER fritzserver stopped
NODE_AGENT nodeagent running
APPLICATION_SERVER server1 stopped
APPLICATION_SERVER sippbx1 stopped
APPLICATIONS:
commsvc.pbx
commsvc.testear
fritzlet_ear
wsadmin>



4. Call from your own scripts

I write my own small script files when I need to set up a complex configuration repeatedly, and don't want to keep typing the same commands over and over. These scripts are small, because they call methods in wsadminlib.py to do all the work. Here is a a simple example of a script which starts a server. Create a python file like this:

root@ding6:/tmp# cat wsadminlib.demo.py
execfile('/tmp/wsadminlib.py')
enableDebugMessages()

# Start server1
servername = 'server1'
nodename = 'node1'
startServer(nodename,servername)


Invoke it and watch the progress:

root@ding6:/tmp# /opt/WAS70/bin/wsadmin.sh -lang jython -host ding6 -port 8879 -f /tmp/wsadminlib.demo.py
WASX7209I: Connected to process "dmgr" on node dmgr using SOAP connector; The type of process is: DeploymentManager
$Id: wsadminlib.py 104 2010-02-15 19:06:18Z ding $
[2010-0329-1341-2800] enableDebugMessages Verbose trace messages are now enabled; future debug messages will now be printed.
[2010-0329-1341-2800] startServer: starting server node1,server1
[2010-0329-1341-2800] startServer: startServer(server1,node1)
[2010-0329-1341-4300] startServer: server node1,server1 not running yet, waiting another 15 secs


Looking at the wsadminlib source code, we see the startServer() method exits silently upon success, and raises a python exception if anything goes wrong. Therefore, the server started successfully. We also see that the method checks every so often to see if the server has started. This provides reassurance that the script is still alive and just waiting for results, especially when you have a mix of fast and slow server machines.

Friday, March 26, 2010

Welcome to wsadminlib.py

Overview


wsadminlib.py is a large python file containing hundreds of methods to help simplify configuring the IBM WebSphere Application Server (WAS) product using scripting.

Where do I get it?


Update 2013-1012: An official version of wsadminlib is now available at https://github.com/wsadminlib/wsadminlib  IBM has made wsadminlib available on this popular software-sharing site for you to copy, fork, and make your own enhancements!

The original is still available here [developerWorks] and search for 'wsadminlib'.  Its official name is "The IBM WebSphere Application Server Sample Script (wsadminlib.py package)".

Design goals


wsadminlib.py was designed to simplify configuration of the IBM WebSphere Application Server (WAS) product by providing much-improved understandability and ease-of-use. The underlying scripting syntax for configuring the WAS product can be complex and challenging to understand. The wsadminlib package was created to provide simple method names and simple parameter names, and hide the underlying nonsense.

A wide variety of methods have been developed. These methods perform tasks such as creating servers, starting servers, creating clusters, installing applications, proxies, core groups, core group bridge, dynacache, shared libraries, classloaders, replication domains, security, BLA, JDBC, etc, etc, etc.

History

wsadminlib.py was originally created in 2006 by two IBM product developers who were having trouble understanding the native wsadmin syntax. They were both encountering the same problems and both spending time researching the same solutions. They joined forces to split the work and share the benefits, and the original wsadminlib.py was born.

By word of mouth, other teammates discovered the joys of wsadminlib, using it as both a code reference and in production. Eventually, many of these teammates began contributing new methods which they had researched and debugged, thus sharing solutions with others.

Community interest grew steadily over time. By 2010, several dozen people had contributed methods related to component areas they understood, and wsadminlib was being used in production by a good number of components in the current strategic agile automated test infrastructure.

Other script packages

wsadminlib is one of many sample script packages available from IBM and others. Here are some comparisons to guide your selection. Pick your favorite. Vive la difference.

- The developers of wsadminlib like having everything in one monolithic file. There is only one file to include, and only one place to search. Other script developers prefer smaller files, organized in subdirectories, in a more object-oriented fashion.

- The developers of wsadminlib strive to write methods with self-documenting names, and intuitively named parameters. They write pydoc only when necessary. Other script developers like to write verbose documentation.

- Other packages may support multiple languages. Wsadminlib is English-only.

Limitations

- Error-handling is not consistent. Some methods raise python exceptions, others use a return code.

- All wsadminlib methods work well on WAS V7 and V8 (beta). Some methods work on V6.1, but not all have been tested. WAS 6.0.2 is unknown.

- wsadminlib is not a formally-supported product. It is provided as a sample, on an as-is basis. The official disclaimer is in the prologue at the top of wsadminlib.py.

Summary

wsadminlib has been very helpful to many of us inside IBM to speed development of configuration scripts and to run testcases. We hope you find something useful too.