Using the latest Jython with a WebSphere Application Server wsadmin thin client

Current versions of IBM® WebSphere® Application Server ship with Jython v2.1, which is behind the most current release of Jython. Jython 2.5.2 (the current version as of this writing) has improved language features, libraries, and performance relative to Jython 2.1. Fortunately, WebSphere Application Server is designed in such a way that using the latest Jython is relatively straightforward. This article describes how to set up a wsadmin thin client to use the latest Jython for your wsadmin scripts. Using the wsadmin thin client configured with the latest Jython enables you to write scripts that leverage the latest language features and improvements. Once you have completed the setup described in this article on one machine, you can replicate it readily to any similar machine in your environment.

Introduction

This article explains how you can set up a wsadmin thin client in IBM® WebSphere® Application Server to use the latest release of Jython. Using the latest release of Jython provides the opportunity for you to leverage new language features added since Jython 2.1, such as:

• Try-except-finally code blocks where exceptions need to be handled.
• The with construct for conveniently working with connections and locks.
• Improvements in various libraries; the threading library in particular.
• Performance improvements built into the latest Jython runtime.

Included with this set of instructions are samples of some artifacts that are needed to run the thin client:

• Wrapper script for Windows®, called thinClient.bat, that is used to invoke wsadmin in the thin client.
• Wrapper script for Linux® and AIX®, called thinClient.sh, that is used to invoke wsadmin in the thin client. (This is a bash shell script.) This script is named thinClient.sh to distinguish it from wsadmin.sh that could be used to launch wsadmin from a server profile.
• A wsadmin.properties file configured to work with the thin client.
• Profile script for wsadmin, called ThinClientProfile.py, that is provided with the –profile option for wsadmin. This profile is required to set up the Admin objects correctly and to properly load library modules when the script library option wsadmin.jython.libraries is used.
• A bash script called addAdminObjectImport.sh that modifies the WebSphere Application Server Jython library admin modules to include an import statement for the Admin objects (AdminConfig, AdminControl, AdminTask, and so on) that are used by the module. This script makes it easy to set up the WebSphere Application Server Jython script library to be used with a version of Jython that is different than the one that comes with the WebSphere Application Server installation. (If you are familiar with Windows scripting, you will likely be able to create a comparable script for Windows.)

Applicable versions

At the time this writing, the latest release was Jython 2.5.2, but the steps described here should be equally applicable to any newer release. See Resources for a comprehensive list of features new to Jython 2.5.

The steps described here were tested on Linux®, AIX®, and Windows® using thin clients derived from WebSphere Application Server V7, V8, and V8.5 environments.

Creating the wsadmin thin client environment

General instructions for creating a wsadmin thin client environment are available in the WebSphere Application Server Information Center. The steps listed below are based on the Information Center instructions, but contain minor modifications that specifically address using a different version of Jython.

Java compatibility

The wsadmin thin client needs an IBM Java™ runtime for ORB compatibility with the JVM running the deployment manager to which the wsadmin thin client will connect. (Configuring another vendor’s JVM to use the IBM ORB is possible but the details of doing so are beyond the scope of this article.) One way to get the correct IBM Java is to install an appropriate WebSphere Application Server client (AppClient) on the machine where you want to set up the wsadmin thin client. The AppClient comes with the “supplements” part of the WebSphere Application Server product distribution and can be installed without incurring additional license costs. Alternatively, and usually more simply, you can copy the IBM Java from a machine where WebSphere Application Server is already installed, provided the OS and word size on both machines are the same. The instructions in this article use the latter approach. (Incidentally, you can use a wsadmin client running on a 32-bit Java with a deployment manager running on a 64-bit Java, and vice versa.)

Below are naming conventions used throughout this article to help make this information easier to understand:

• <PROFILE_HOME> refers to the root directory of a WebSphere Application Server profile from which certain files are copied to create the thin client run time environment. (During the testing of this information, items were copied from a deployment manager profile, but you could use a node profile instead.)
• <WAS_HOME> refers to the root directory of a full WebSphere Application Server installation that is used to copy certain artifacts into the thin client run time environment.
• <THIN_CLIENT_HOME> is used to refer to the root directory of the thin client run time environment.

To create the wsadmin thin client environment:

1. Create a top level directory where the thin client environment will be located. In this example, the top level directory is /opt/IBM/WebSphere/ThinClient, although you can put the directory anywhere. (On a Windows machine, do not put the thin client directory in the Program Files path due to the space character in the path name, which can be an annoyance at times.) The top level directory where the thin client is located is referred to generically in these instructions as <THIN_CLIENT_HOME>.

Warning for Windows autorun.inf file

When copying Java from one machine to another in a Windows setting using remotely mounted files, you will likely get a warning about not being able to copy or make changes to the autorun.inf file in the java/docs directory. In this case, you can skip copying the autorun.inf file.

2. From an existing WebSphere Application Server environment, copy Java over to <THIN_CLIENT_HOME> by either:
   • Using cp –R to copy <WAS_HOME>/java.
   • Using the old-school approach of using tar –cvf to create an archive of <WAS_HOME>/java. Copy the archive to <THIN_CLIENT_HOME> and extract it with tar –xvf.
   • In a Windows environment, copy the <WAS_HOME>/java folder to <THIN_CLIENT_HOME>, either by dragging and dropping, or by creating a compressed (.zip) archive, followed by a copy and extraction of the archive.
   You should acquire Java from an existing WebSphere Application Server installation, because when the wsadmin thin client starts up, it looks for IBM ORB classes to connect to the deployment manager process. The ORB class used is com.ibm.CORBA.iiop.ORB. You can copy an IBM Java from any WebSphere Application Server environment running on a machine that is compatible with the machine where the wsadmin thin client is being configured; that is, same OS, same word size, and so on.

Java and Jython

A Java runtime is needed to install Jython, and, of course, a Java runtime is needed to run Jython. If Java is installed on the wsadmin thin client machine and already in the system path, then you can use that Java to install Jython. Otherwise, you can use the Java that you just copied over from the <WAS_HOME> directory to <THIN_CLIENT_HOME>/java. During the installation of Jython, you will be prompted for a path to a Java runtime. To avoid confusion, use the Java runtime installed in <THIN_CLIENT_HOME>, which will also be used to run wsadmin.

3. Create a directory named lib in <THIN_CLIENT_HOME>. This is where the latest Jython will be installed.
4. Copy the jython_installer-2.5.2.jar to <THIN_CLIENT_HOME>.
5. Install the latest Jython into the <THIN_CLIENT_HOME>/lib directory. You will find complete instructions for installing Jython on the Jython site. When installing Jython, be sure to:
   • Use this command to kick off the installer:

     java -jar jython_installer-2.5.2.jar

   • Use the default standard installation.
   • Specify this directory when you are prompted for the location in which to install Jython:

     <THIN_CLIENT_HOME>/lib/jython

   • (Optional, but recommended) Select Other when you are prompted for the path to the Java installation to use with Jython, then navigate to the Java located at <THIN_CLIENT_HOME>/java.
6. Copy the following JARs to <THIN_CLIENT_HOME>/lib:
   • com.ibm.ws.admin.client_#.#.0.jar from <WAS_HOME>/runtimes (where #.# is 7.0, 8.0, or 8.5 depending on the WebSphere Application Server version)
   • com.ibm.ws.security.crypto.jar from <WAS_HOME>/plugins
7. Create a directory named properties in <THIN_CLIENT_HOME>. This is where some message and configuration files will be located.

Windows to UNIX

For files that are included with this article and copied to a UNIX® platform (such as thinClient.sh), it is a good idea to run the dos2unix utility on those files to be sure you don’t run into problems due to differences in newline characters between the two operating systems.

8. From an existing WebSphere Application Server profile, copy the properties files listed below from <PROFILE_HOME>/properties to <THIN_CLIENT_HOME>/properties, and make any changes specified:
   • ipc.client.props: supports IPC connections.
   • soap.client.props: supports SOAP connections.

     Modifications

     • Change com.ibm.SOAP.securityEnabled to true.
   • sas.client.props: supports JSR160RMI connections (preferred).
   • ssl.client.props: supports encrypted connections.

     Modifications

     • Change the value of user.root to <THIN_CLIENT_HOME>.
     • In this file, use forward slashes in the path to <THIN_CLIENT_HOME>. Java will interpret the path correctly depending on the platform.
     • Under the Default self-signed certificate properties section, check that the subject DN (Distinguished Name) is appropriate for your site. (Specifically, you will need to change the organization attribute and, possibly, the country.)
   • wsjaas_client.conf: supports secured connections.

Check the drive letter

For the Windows platform, when modifying paths in any of the properties files (for example, wsadmin.properties, ssl.client.props, and so on), be sure the drive letter is appropriate for the machine from which you are running the wsadmin thin client. If you get run time errors indicating that wsadmin can’t write its traceout and valout logs, the problem could be due to the drive letter. The rest of the path is usually correct.

9. Copy the wsadmin.properties file included with this article into <THIN_CLIENT_HOME>/properties. This sample properties file has already been appropriately configured. Alternatively, you can get a wsadmin.properties file from an existing WebSphere Application Server profile from the <PROFILE_HOME>/properties directory.
10. In the wsadmin.properties file, check the parameters listed here to see if you need to adjust their values:
    • (optional) com.ibm.ws.scripting.connectionType=JSR160RMI

      JSR160RMI is the recommended connection type, although in some cases you may find that you need to use the SOAP connection type.

    • (optional) com.ibm.ws.scripting.port=0

      This is set to a bogus port to avoid accidental connection to a deployment manager.

    • (optional) com.ibm.ws.scripting.host=localhost
    • com.ibm.ws.scripting.defaultLang=jython
    • (required) com.ibm.ws.scripting.traceFile

      Set this value to a path that uses <THIN_CLIENT_HOME>/logs.

    • (required) com.ibm.ws.scripting.validationOutput

      Likewise, this parameter must also specify a path that uses <THIN_CLIENT_HOME>/logs.

    • (optional) com.ibm.ws.scripting.traceString

      Default is disabled.

    • (optional) com.ibm.ws.scripting.validationLevel

      Default is NONE.

    The values in this file will be overridden by the values in the wsadmin.properties file in the user’s home directory. These values can also be overridden by corresponding command line options, such as -host, -port, and so on.
11. Create a directory named etc in <THIN_CLIENT_HOME>. This is where the thin client key and trust store files will be created for use with encrypted connections to remote deployment managers. (See the ssl.client.props file in the properties directory for configuration details.)
12. Copy the sample thinClient.sh or thinClient.bat script provided with this article to <THIN_CLIENT_HOME> and modify it to work with your thin client installation:
    1. Modify the value of WAS_HOME to include the full path to the directory where you are creating your thin client (which is otherwise referred to as <THIN_CLIENT_HOME>). (In the thinClient.bat script, remember to use back slashes in the path names.)
    2. Similarly, modify USER_INSTALL_ROOT to the directory where you are creating your thin client (<THIN_CLIENT_HOME>).
    3. Make sure JAVA_HOME makes sense for the Java you are using. If you are using a Java installed somewhere other than <THIN_CLIENT_HOME>/java, then you will need to update the value of JAVA_HOME accordingly.
    4. (Optional) Modify wsadminHost to be the default host for the deployment manager you want to connect to. (You can provide the –host argument on the command line when you launch the thin client and that will override the value provided in the wrapper script.) If you wish, you can provide a bogus hostname to avoid accidentally connecting to some WebSphere Application Server process.
    5. (Optional) Uncomment the wsadminConnType that you want to be the default connection type. In general, it is strongly recommended that this be JSR160RMI. This can be overridden by using the –conntype argument when launching the thin client.
    6. (Optional) Modify wsadminPort to be the default port for the JSR160RMI connection for the default deployment manager. (The default JSR160RMI port for deployment managers is 9809, which is the same as the “bootstrap” port.) This can be overridden with the –port argument when launching the thin client. If you wish, you can provide a bogus port number to avoid accidentally connecting to some WebSphere Application Server process.
    7. In the script line that sets up the classpath (search for "client_"), modify the name of the com.ibm.ws.admin.client_#.#.0.jar to reflect the version of WebSphere Application Server you are using; that is, replace #.# with 7.0, 8.0 or 8.5.
13. Create a logs directory in <THIN_CLIENT_HOME>. Make it writable by all. This directory is used for trace files when wsadmin tracing is enabled.

Using wsadmin.jython.libraries

The Java class that implements the wsadmin shell updates sys.path, but also automatically preloads Jython modules found in directory trees specified by wsadmin.script.libraries. This causes import problems for Jython libraries with module interdependencies, as well as dependencies on the wsadmin Admin* objects. To avoid these issues, the ThinClientProfile.py uses wssamin.jython.libraries instead of wsadmin.script.libraries. The ThinClientProfile.py only modifies sys.path and does not preload any Jython modules it finds in the libraries specified with wsadmin.jython.libraries. The ThinClientProfile will load multiple libraries, if there are multiple paths specified with wsadmin.jython.libraries separated by a semi-colon. Any scripts using modules in the specified libraries must have a proper import statement to load desired modules from the libraries.

14. Create a directory named profiles in <THIN_CLIENT_HOME>. Copy the ThinClientProfile.py file into this directory. This profiles directory is a convenient place to keep a copy of the ThinClientProfile.py file, which does a couple of important things:
    • It loads the Admin objects into sys.modules so they are visible to your modules, making import statements for these objects resolve properly.
    • It will properly set up sys.path with any library directories that have Jython modules in them when libraries are specified with the wsadmin.jython.libraries Java option. When libraries are to be used, the thinClient command line will include the -javaoption as follows:

      -javaoption “-Dwsadmin.jython.libraries=<path_to_library>”

      where <path_to_library>is the path to the root directory where the Jython library is located in the file system.

    • In ThinClientProfile.py, search for WebSphereVersion and modify the value to 7.0, 8.0, or 8.5 depending on which version of WebSphere Application Server you are using.
15. (Optional) For convenience, put <THIN_CLIENT_HOME> in your path. This will enable the thinClient wrapper script to be executed without using its full path.
16. (Optional) If you use the wsadmin script libraries (written in Jython) that come with WebSphere Application Server, then:
    1. Create an archive of the scriptLibraries directory in an existing WebSphere Application Server installation. On UNIX machines this is done with the tar command:

       cd <WAS_HOME>
tar –cvf scriptLibraries.tar scriptLibraries

    2. Copy the scriptLibraries archive to <THIN_CLIENT_HOME>.
    3. Extract the scriptLibraries archive. On UNIX machines this is done with the tar command:

       tar –xvf scriptLibraries.tar

    4. In order for these libraries to be loaded properly with the thin client using the newer Jython, the root directory name of the libraries needs to be changed to something other than scriptLibraries. In this example, the directory is renamed to wasScriptLibraries.
    5. Make sure all the class files are deleted so they get recompiled with the new Jython. From the <THIN_CLIENT_HOME> directory:

       find ./wasScriptLibraries –name “*.class” | xargs rm

    6. You also need to go through all the script library modules and modify them to include an import statement that imports any of the Admin objects used by that module. The import statement is needed to avoid name errors on the Admin objects when the script library modules are used. For UNIX machines there is a bash script that adds the proper import statement to all of the Admin modules in the WebSphere Application Server Jython library. See sample script addAdminObjectImport.sh in the download materials (this script was tested on a Linux platform).
    7. When launching thinClient.sh use the following option:

       –javaoption “-Dwsadmin.jython.libraries= <THIN_CLIENT_HOME>/wasScriptLibraries”

       where <THIN_CLIENT_HOME> is the root directory of your thin client installation. You may use the same option with a path to other in-house script libraries that you may be accustomed to using
    8. Use the –profile option with a path to the ThinClientProfile.py when launching thinClient.sh in order to properly construct sys.path with libraries specified by wsadmin.jython.libraries. For example:

       -profile <THIN_CLIENT_HOME>/profiles/ThinClientProfile.py

       where <THIN_CLIENT_HOME> is the root directory to your thin client installation.
17. On UNIX platforms, you will likely want to change the ownership of the <THIN_CLIENT_HOME> directory tree to the user and group that makes sense for the wsadmin thin client machine. The chown command with the -R option can be used to change the user and group ownership for the entire directory tree.

That completes the initial setup. You can now launch the thin client using the thinClient wrapper appropriate for your platform.

Back to top

Invoking the thinClient

This article assumes that wsadmin.properties has the default language set to jython and conntype set to JSR160RMI or SOAP. When that is the case, the only two arguments needed are a port and a host. You can also set up the port and host in wsadmin.properties to provide a default, but that is not recommend because it can lead to unintended connection to a deployment manager.

Assuming a JSR160RMI default connection type, invoking the thin client on Windows (without running a Jython script) looks like this:

thinClient.bat –port 9809 –host mydmgrhost

Likewise, the minimum command line for invoking the thin client on Linux looks like this:

thinClient.sh –port 9809 –host mydmgrhost

The above command examples will get you into a wsadmin “listener” connected to a deployment manager. (Of course, you will need to provide a valid port number and host name for your environment.)

When you run a script, you can use all the same options (-f, -profile) that you use for wsadmin, as well as any arguments that are intended for your script.

On Windows, be sure to use forward slashes in any path names that you provide to thinClient.bat to enable Java to work properly. If you must use back slashes, you’ll have to use double back slashes.

Running thinClient the first time

The first time you run the wsadmin thin client, Jython will populate its cachedir with class objects that it uses on later startups. Jython will create a temp/cachedir directory in <THIN_CLIENT_HOME> for this object cache. You will see messages for every JAR that gets processed.

The first time you connect to a remote deployment manager, a key and trust store will be created. You will be prompted to add a public certificate from the deployment manager into your thin client trust store. The certificate properties will be displayed for your examination. The first time you use the wsadmin thin client to connect to a different deployment manager, you will be prompted again to add a public certificate for that deployment manager. See the ssl.client.props file for the characteristics and location of the key and trust store. (The key and trust store are created in <THIN_CLIENT_HOME>/etc if you stick with the default configuration.)

Back to top

Troubleshooting

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

• Check JAVA_HOME in thinClient.bat or thinClient.sh

  If JAVA_HOME is not set properly, and there is no java.exe at the expected location, then the thinClient.bat or thinClient.sh script will not start correctly. On Windows, if the java.exe isn’t correct when launching thinClient.bat from a DOS shell, you will get the message, "The system cannot find the path specified."

• UNIX problems

  On UNIX platforms, it is a good idea to run dos2unix on thinClient.sh and ThinClientProfile.py. Odd problems have been cleared up by doing so.

• Use forward slashes in arguments to thinClient.bat

  Even on Windows, use forward slashes in the script arguments to thinClient.bat or any Jython scripts you launch via thinClient.bat. If you want to use back slashes you will need to use two together in order for them to be interpreted properly by wsadmin.

• Network visibility of the target host

  Make sure:

  • You can ping or traceroute from the host where the thin client is running to the host where the deployment manager is running.
  • The deployment manager host name resolves correctly. If you are having trouble getting a connection when using the host name, try the raw IP address in its place.
  • You are using the correct port of SOAP or JSR160RMI for the target host. You can check the port by looking at the deployment manager ports from the admin console.
• Enabling trace for wsadmin thin client

  If you want to turn on trace for launching the thin client, you can modify the traceString attribute in wsadmin.properties. You cannot control trace from the command line.

• Problems with JSR160RMI

  If you cannot get JSR160RMI to work, then try SOAP.

• Typos in host name and file paths

  Make sure you do not have any typos in the host name or port number for the remote deployment manager that you are trying to connect to. On Windows machines, make sure the drive letter is correct. (It is easy to visually ignore the drive letter when the rest of the path is correct.)

• Problems with SSL configuration

  If you don’t have SSL configured properly, then you might see this error:

  WASX7023E: Error creating "SOAP" connection to host "localhost"; exception 
  information: com.ibm.websphere.management.exception.ConnectorNotAvailableException:
  [SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: 
  javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: 
  java.security.InvalidAlgorithmParameter Exception: the trustAnchors parameter must 
  be non-empty; 
  targetException=java.lang.IllegalArgumentException: Error opening socket: 
  javax.net.ssl.SSLException: java.lang.RuntimeException: Unexpected error: 
  java.security.InvalidAlgorithmParameterException: the trustAnchors parameter must 
  be non-empty]

  This is usually caused by misconfiguration of the user.root property in the ssl.client.props file. If the thin client can’t get to where it expects to find the key and trust store, then it won’t be able to create them when it first starts up and it won’t be able to connect to the deployment manager.

Back to top

Configuring the thin client for use on another machine

Once you have gone through the initial configuration described here, you can zip or tar up the root directory of the thin client and move it to another machine; for example, another administrator’s desktop. To reconfigure the thin client on another machine:

1. Unzip or untar the wsadmin thin client in the file system of the machine.
2. If the target machine needs a different Java (for example, 32-bit rather than 64-bit), then you need to delete the <THIN_CLIENT_HOME>/java directory and get a Java from a WebSphere Application Server installation of the same architecture as the target machine. Copy that Java into the new <THIN_CLIENT_HOME> directory.
3. Modify thinClient.bat or thinClient.sh to make sure the WAS_HOME variable at the top of the file reflects the new installation root of the thin client. (All the other file paths in the script are based on WAS_HOME, so that is the only variable that needs to be changed.)
4. In the wsadmin.properties file in <THIN_CLIENT_HOME>/properties, modify the traceFile and validationOutput properties to make sure they are correct for the new thin client home.
5. In the <THIN_CLIENT_HOME>/etc directory, delete the key.p12 and trust.p12 store files. These will get recreated for the new host.
6. Edit ssl.client.props in <THIN_CLIENT_HOME>/properties to modify the user.root property to reflect the new home of the thin client. This is important in order for the key and trust store to be properly regenerated and used when the thin client is invoked.
7. If you are using soap.client.props to provide a user and password, then you might need to modify the user and password to use the identity of the administrator that is going to use this instance of the wsadmin thin client.

After making these changes, your new wsadmin thin client should be ready to run. You can test it by running thinClient.bat or thinClient.sh from a shell.

Back to top

Moving forward with Jython

As you continue to use the newer version of Jython, there are a few things you will want to keep in mind to make sure your transition and future processing go smooth:

• The newer Jython uses Unicode strings. This will present an issue if you have tests in your wsadmin scripts for string types that use type(“”) . You will need to add an additional test that uses type(u””).
• The newer Jython supports newer language features that are not backward compatible with the Jython that is presently built into WebSphere Application Server. Once you start using these newer language features in your wsadmin scripts, be aware that you won’t be able to run those same scripts in a standard WebSphere Application Server wsadmin environment.

Back to top

Conclusion

This article provides a way for you to use the latest version of Jython without disturbing your existing WebSphere Application Server installations. By setting up a wsadmin thin client with the latest Jython, you can develop and run wsadmin scripts that take advantage of the latest in Jython language features and improvements.

转自: http://www.ibm.com/developerworks/websphere/library/techarticles/1207_vansickel/1207_vansickel.html