WebSphere Application Server wsadmin script development using the PyDev plugin for Eclipse

IBM® WebSphere® Application Server administrators often resort to using a text editor for wsadmin script development based on Jython. However, text editors do not provide language-specific support for Jython. PyDev is a plugin for Eclipse that is specifically tailored to Python and Jython program development. PyDev has the usual language-specific features you expect in an integrated development environment (IDE) to enhance your Jython scripting productivity. The PyDev plugin needs some special configuration to support the specifics of wsadmin scripting. This article describes how to configure the PyDev plugin for Eclipse specifically for Jython and wsadmin scripting. The PyDev capabilities will improve your wsadmin scripting productivity by cutting down on errors, such as improper indenting, incorrect syntax, and undefined variable usage. This content is part of the IBM WebSphere Developer Technical Journal.

Peter Van Sickel (pvs@us.ibm.com), Consulting I/T Specialist, IBM

Peter Van Sickel is a Consulting I/T Specialist with IBM Software Services for WebSphere. Mr. Van Sickel has over 15 years of experience with distributed systems software development. He got his start in distributed system software with DCE and later the Encina OLTP monitor from Transarc Corporation, which was acquired by IBM. For the past 10 years he has focused on Java EE and WebSphere Application Server based systems including WebSphere Process Server. Mr. Van Sickel holds a Masters degree in Industrial Administration from Carnegie Mellon University, a Masters degree in Computer Engineering from Stanford University, and a B.S. in Electrical Engineering from Pennsylvania State University. Mr. Van Sickel is one of the authors of WebSphere Application Server Step by Step.



12 September 2012

Also available in Chinese

Introduction

IBM WebSphere Application Server administrators usually develop wsadmin based scripts using Jython. Many administrators resort to using a text editor as their primary Jython development tool. However, text editors do not provide language-specific support for Jython. PyDev is a plugin for Eclipse that is specifically tailored to Python and Jython program development. PyDev has numerous features built into its editor that speed the development process, including syntax high-lighting, automatic indenting and indent checking, code completion and automatic syntax analysis, and many other features typically provided by an integrated development environment (IDE).

Taking advantage of PyDev features will improve your wsadmin scripting productivity, and improve the quality of your wsadmin scripts in general. Eclipse and PyDev are available as free downloads, so licensing costs are not an impediment to adopting these tools. The PyDev plugin can be used in any Eclipse-based IDE such as IBM Rational Application Developer for WebSphere Software V8.0 or V8.5.

This article describes how to setup the PyDev plugin for Eclipse to support wsadmin script development for WebSphere Application Server.

Prerequisites

This article assumes that an Eclipse IDE and a Java runtime environment are already installed and available. During the development of this article the PyDev plugin has been used in the Eclipse Juno release (v4.2) and the Eclipse Indigo release (v3.7). It has also been used in IBM Rational Application Developer for WebSphere Software V8.5, which is based on the Eclipse Helios release (v3.6). The IBM JRE V1.6 was used in the testing that was performed for developing this article.

The instructions presented here were tested using a SuSE 11 SP 2 64-bit Linux machine and a Windows 7 64-bit machine. However, unless otherwise specified, this information is platform independent.

A sample archive named GeneratePyPredefs.zip accompanies this article. It holds a top level Jython script named GeneratePyPredefs.py along with its supporting scripts. The GeneratePyPredefs script is used to create some “predefined completion” files that are used to configure the Jython interpreter for the PyDev plugin so that it works well with wsadmin.

Setting up PyDev

The major tasks involved in getting your Eclipse-based IDE working with PyDev and supporting wsadmin script development are:

  1. Install the Jython interpreter runtime

    It is OK to use the latest version of the Jython interpreter to support the PyDev plugin. If you want to run your wsadmin scripts from your desktop using a wsadmin “thin client” and the latest version of Jython, see Using the latest Jython with a WebSphere Application Server wsadmin thin client.

    On Linux, this installation is typically done as root, but that is not a requirement provided you have write access to the directory where Jython is to be installed.

    1. Get the Jython installation JAR from the Jython download site.
    2. Use java -jar to start up the installer and follow the instructions presented by the Jython installer:
      java -jar jython_installer-2.5.2.jar
    3. Choose the “standard” Jython installation.
    4. Choose an installation directory; for example, /opt/jython-2.5.2 for Linux or C:\jython2.5.2 for Windows.
    5. On Linux, after the install completes, set the Jython cachedir directory permissions so that the users of the Jython interpreter can read and write items in that directory. The command, chmod a+rw cachedir will set the directory permissions as needed. This translates to “mode bits” set to 755 for user, group, and all. When Jython runs, the user needs to be able to write into the cachedir.
  2. Install the PyDev plugin into your Eclipse IDE

    If you are familiar with Eclipse, the main thing you need is the URL for PyDev software updates: http://www.pydev.org/updates.

    1. Under the Help menu in your Eclipse IDE, select Install new software.
    2. Add the PyDev repository by clicking on the Add button. In the dialog, provide the name (for example, PyDev IDE) and the PyDev update URL, http://www.pydev.org/updates.
    3. After a few seconds you should see PyDev and PyDev Mylyn Integration show up as items that can be installed (Figure 1).
      Figure 1. PyDev plugin installation begins
      Figure 1. PyDev plugin installation begins

      Select PyDev and click the Next button.

    4. Eclipse will determine the requirements and dependencies and present a review screen. Click Next on the review screen. Accept the license agreement and click Finish to kick off the installation.
    5. When the installation is complete, you will need to restart your Eclipse IDE to complete the installation of the PyDev plugin.
  3. Configure the PyDev plugin to use the Jython interpreter

    Once the PyDev plugin has been installed, it needs to be configured to use the Jython interpreter. See the Configure Interpreter section of the PyDev Manual.

    • Under the Window menu in your Eclipse IDE, select Preferences. Expand the PyDev entry and select Interpreter - Jython (Figure 2).
      Figure 2. Configuring the Jython interpreter for the PyDev plugin
      Figure 2. Configuring the Jython interpreter for the PyDev plugin
    • Click on the New button in the upper right corner next to the Jython interpreter definition pane.
    • In the interpreter definition dialog, provide a name (for example, Jython 2.5.2) and the path to the jython.jar, based on where you installed Jython in the earlier steps (for example, /opt/jython-2.5.2/jython.jar for Linux or C:\jython2.5.2\jython.jar for Windows). Click OK.
    • During the interpreter configuration, you will see a dialog asking you to select folders to be added to the SYSTEM pythonpath. Accept the defaults and click OK (Figure 3).
      Figure 3. Use default PYTHONPATH configuration
      Figure 3. Use default PYTHONPATH configuration
    • Once the Jython interpreter configuration completes, you will see a list of items that are included in the PYTHONPATH that include the two Jython Lib directories, along with many JARs from the Java runtime you are using (Figure 4). At this point, your Jython interpreter is configured.
      Figure 4. PYTHONPATH for the Jython interpreter
      Figure 4. PYTHONPATH for the Jython interpreter
  4. Customize the Jython interpreter for wsadmin

    Now that the Jython interpreter used by PyDev is installed and configured, it must be customized to support wsadmin scripting. PyDev needs to be made aware of the implementation of the admin objects that implement the wsadmin commands AdminConfig, AdminControl, AdminApp and AdminTask. To do this, you need to apply predefined completion files to provide the Jython interpreter what it needs during development to recognize admin object command invocations as legitimate. Without the predefined completion files, the Jython interpreter marks admin object command invocations as an error, since it has no way of recognizing the command name.

    You can create your own predefined completion files, or you can use the sample script, GeneratePyPredefs.py, provided with this article. The script creates four files, one for each of the admin objects in the directory provided as an argument to the script. Each of these files is a predefined completion file, with a .pypredef extension, that holds a simple command signature and help text for each command implemented by the given admin object. If you are familiar with Java, predefined completion files are comparable to an interface definition in Java. Once you run the script you can examine the content of each file to get a clear understanding of what is in it.

    To run the GeneratePyPredefs script, you need to be logged into a machine where you can run wsadmin connected to a deployment manager or a “base” application server.

    The predefined completion files will be different for each version of WebSphere Application Server, as well as for stack products, because AdminTask tends to get new commands with each release of WebSphere Application Server as well as for the stack products.

    These naming conventions are used in the instructions which follow:

    • <WAS_HOME> is a place holder for the “home directory” of a WebSphere Application Server installation (for example, /opt/IBM/WebSphere/AppServer on Linux or C:\Program Files\IBM\WebSphere\AppServer on Windows).
    • <DM_HOST> is the name of the host machine where a deployment manager is running.
    • <SOAP_PORT> is the SOAP port used by the deployment manager process.
    • <PREDEFINED_COMPLETIONS> is the directory path where the admin object predefined completion files are located.

    Be aware that the wsadmin command line is shown on multiple lines for clarity; in actual use, it must be entered on one line.

    To create the predefined completion files using the sample GeneratePyPredefs.py script:

    1. Run the GeneratePyPredefs.py script for the four admin objects:
      1. Unzip the GeneratePyPredefs.zip download file on a machine where you can run wsadmin. The archive includes GeneratePyPredefs.py as well as the supporting modules that it imports and a help text file.
      2. Open a command window (shell) and change directories so you are in the directory where the GeneratePyPredefs.py script is located.
      3. Assuming wsadmin is in the user’s PATH, the command line will look like:
        wsadmin.bat/sh -host <DM_HOST> -port <SOAP_PORT> 
        	-profile WSAdminProfile.py
        	-f GeneratePyPredefs.py	
        	-pypredefsDir <PREDEFINED_COMPLETIONS>
      4. You will be prompted for a WebSphere Application Server user name and password.
      5. The script will create the directory path provided for the pypredefsDir, if it does not already exist.
      6. The AdminConfig, AdminControl and AdminApp pypredef files are created very quickly because they don’t have very many commands. The creation of the AdminTask.pypredef file will take about 20 to 30 seconds because AdminTask has a large number of commands. When the script finishes you should see the message:
        __main__(438) main : Successfully completed creation of pypredef files.
      7. If you need to copy the pypredef files to another machine where you do your script development, then create an archive of the pypredefs directory and extract it on your script development machine.
      8. Make a note of the <PREDEFINED_COMPLETIONS> directory path. It is needed for an upcoming step.
    2. If you do not have WebSphere Application Server installed on the machine where you are performing your script development, copy the wsadmin client JAR from a WebSphere Application Server installation to a directory on your machine. The wsadmin client JAR is in <WAS_HOME>/runtimes and the name of the JAR is specific to each version of WebSphere Application Server (for example, com.ibm.ws.admin.client_7.0.0.jar or com.ibm.ws.admin.client_8.0.0.jar or com.ibm.ws.admin.client_8.5.0.jar).
    3. Back in the Jython interpreter customization window for your Eclipse IDE, add the wsadmin client JAR to the PYTHONPATH:
      1. Click on the New Jar/Zip(s) button next to the window pane that displays the items in the PYTHONPATH.
      2. Browse to com.ibm.ws.admin.client_#.#.#.jar where #.#.# represents the version of WebSphere Application Server you are using (for example, 7.0.0, 8.0.0 or 8.5.0). Once you have browsed to the JAR, click Open.
      3. The wsadmin client JAR will show up at the end of the list of items in the PYTHONPATH.
    4. Add the wsadmin abmin objects to the “forced builtins.”
      1. Select the Forced Builtins tab.
      2. Click the New button to the right of the forced builtins pane.
      3. Add the four admin objects: AdminConfig, AdminControl, AdminApp, AdminTask and click OK (Figure 5). The four admin objects will show up at the top of the builtins list.
        Figure 5. Adding the four wsadmin "admin objects" to the Jython interpreter builtins
        Figure 5. Adding the four wsadmin admin objects to the Jython interpreter builtins
    5. Specify the directory path where you put the set of predefined completion definitions for the admin objects. The directory path used in this step needs to be the pypredefs directory on your development machine.
      1. Select the Predefined tab.
      2. Click the New button and browse to the directory where the admin object pypredef files are located.
    6. Click on the OK button in the Preferences window to complete the configuration of the Jython interpreter.
    7. Stop and restart your Eclipse IDE to force a reload of the predefined completions files.

At this point you have completed the steps to configure the PyDev plugin to be used with the wsadmin admin objects. Now, import statements for AdminConfig, AdminControl, AdminTask and AdminApp should not be flagged with an error, nor should any of the admin object commands used in your scripts.


Getting started with PyDev projects

Here are some brief pointers for getting started using the PyDev plugin. (See the PyDev Manual for more information.)

  • Configure the PyDev plugin for your preferences

    Like any other Eclipse plugin, PyDev has a lot of configuration options, including some that might be of immediate interest to a Jython script developer:

    1. Under the PyDev > Editor configuration settings, you can specify the number of spaces to indent code blocks. The default is 4, but 2 might be preferable to keep your scripts more compact. Notice the default setting to convert tab characters to spaces when typing; it is a really good idea to avoid using tab characters in Jython source code.
    2. Under PyDev > Editor > Code Style there are a couple of items that you might be interested in:
      • Locals and attributes format: The default is the Python convention. If you have Java roots you may prefer “camel case” with the first character lower case.
      • Methods format: The default is the Python convention. Again, if you are used to Java conventions you may prefer camel case with the first character lower case.
    3. Under PyDev > Editor > Code Style > Docstrings, you can set the docstring delimiter character to double quote. The default is single quote.

    Explore the many other areas of configuration to set additional preferences.

  • Create a PyDev project for wsadmin scripting

    Once your Eclipse IDE has been has be configured as described above you can create PyDev projects for your wsadmin scripts:

    1. In your Eclipse IDE, under File > New > Other, scroll down in the pop-up window to the PyDev folder and select PyDev Project (Figure 6). Click Next.
      Figure 6. Creating a new PyDev project
      Figure 6. Creating a new PyDev project
    2. In the PyDev project dialog, enter or select:
      • Project name
      • Jython as project type
      • 2.7 as grammar version
      • the Jython interpreter you configured above

      Click Finish.

    3. Open the PyDev perspective when prompted.
    4. By default, the project folder is also a PyDev source folder. If you prefer, you can create a source folder inside your project that is the root of your packages and modules.
  • Convert a non-PyDev project to a PyDev project

    If you have existing projects in your IDE that you want to convert into a PyDev project, this is very simple to do:

    1. Right-click on the project folder. Under the PyDev options, select Set as PyDev Project (Figure 7).
      Figure 7. Using the context menu PyDev options to convert an existing non-PyDev project into a PyDev project
      Figure 7. Using the context menu PyDev options to convert an existing non-PyDev project into a PyDev project
    2. You will be prompted to configure the Python interpreter. Select Manual config. The workspace preferences window will display. Select the Jython interpreter and click on OK. (This doesn’t seem to actually configure the Jython interpreter. See next step.)
    3. Despite the actions taken in the previous step, there is likely to be an error in your newly converted project that indicates PyDev is not configured. To clear up this error, edit the project properties and configure the project to use the Jython interpreter that you defined earlier (Figure 8).
      Figure 8. Configuring a PyDev project to use the Jython interpreter
      Figure 8. Configuring a PyDev project to use the Jython interpreter
  • Define an external wsadmin script library for a PyDev project

    If you have a wsadmin script library that you want to use for your top level scripts, you can define an external library for a PyDev project. You can then use import statements to include modules from the script library in the newly developed scripts in the project. There are a couple of approaches to defining an external library. The approach shown here uses a string substitution variable. This provides a level of indirection that might make it easier to administer projects that are moved among different installations of Eclipse. (The example shown here is contrived in that the external library is ultimately a project in the same workspace as the project using the library, but it illustrates the steps.)

    1. Edit the project properties by right-clicking on the project and selecting the Properties item in the context menu.
    2. In the dialog, select the PyDev - PYTHONPATH item.
    3. In the viewing pane for PyDev - PYTHONPATH, select the String Substitution Variables tab.
    4. Create a new string substitution variable and provide a name and a value. Be careful when running your Eclipse IDE on Windows to use the backslash path separator (Figure 9).
      Figure 9. The dialog for creating a string substitution variable
      Figure 9. The dialog for creating a string substitution variable
    5. Once you have created the string substitution variable, select the External Libraries tab and click on the Add based on variable button.
    6. Enter the value for the library path using the string substitution variable syntax. Again, when working on Windows, be sure to use the backslash path separator (Figure 10).
      Figure 10. Adding an external library reference using a string substitution variable
      Figure 10. Adding an external library reference using a string substitution variable
    7. Click OK in the Properties window to finish defining the external library.

    In this example, the library referenced is in the same workspace as the project that references it. Another approach that would achieve the same effect is to edit the project properties, and under Project References, select the project that holds the library.


Troubleshooting

In case you encounter any difficulties in your testing, here are some troubleshooting tips:

  • Occasionally, you might open your IDE and then open a Jython file for editing, and find that all the Jython/Python built-ins are flagged as an error. (The built-ins are things such as None, Exception, str(), len(), and any of the other built-in objects or functions provided by Jython.) Although the root cause of this issue is unclear, the workaround is straightforward. Open the PyDev preferences (Window > Preferences > PyDev) and select the Jython interpreter. Click the Apply button in the lower right corner of the Preferences window. (You may have to scroll to expose the Apply button.) A dialog will display requesting that you select the interpreter that you want to restore. Check the Jython interpreter and click OK. The interpreter will be “restored” and the errors associated with the Jython built-ins should be removed.
  • Should you change the configuration of a project (for example, add a project reference, or a reference to an external library) while a file from that project is open in the editor window, you might encounter errors. Close the file and reopen it to reset.
  • There are certain circumstances that occur when you need to close Eclipse and restart it to clear up errors. (At least that seems the most expedient thing to do.) If that bothers you, consider it analogous to rebooting your Windows machine to clear up “odd” problems.

Conclusion

This article provided information to help you begin leveraging Jython specific development features in the PyDev development environment for your wsadmin script development. PyDev has many features built into its editor that speed the development process. The PyDev capabilities will improve your wsadmin scripting productivity by cutting down on errors, such as improper indenting, incorrect syntax, and undefined variable usage. You will more confidently move into the testing phase knowing that your scripts are syntactically correct and well formed. You will avoid spending valuable testing time discovering missing import statements, typos in variable or method names, missing colons, improper indentation, and all the other common problems encountered when using text editors for wsadmin script development. .


Download

DescriptionNameSize
File samplesGeneratePyPredefs.zip231 KB

Resources

Learn

Get products and technologies

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=834558
ArticleTitle=WebSphere Application Server wsadmin script development using the PyDev plugin for Eclipse
publish-date=09122012