Chapter 16. Version 7.0 Scripting Libraries

Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

Chapter 16. Version 7.0 Scripting Libraries

“Every library is an arsenal.”

—Robert Green Ingersoll

One of the differences between Version 6.x and Version 7.0 of the product is the addition of some script libraries to version 7.0 that provide routines to assist with common administration functions. This chapter is primarily a reference to these modules, with some comments about their structure and use. We would have preferred to include lots of examples with this chapter, but due to space limitations, we chose to have a section in the companion website (http://www.wasscripting.com) for these examples.

Library Organization

In the installation directory structure, you will find a new directory under the <WAS_HOME> directory named scriptLibraries. Within this directory, there are the following sub-directories:

• application

• resources

• security

• servers

• system

• utilities

Each of these sub-directories contain (either directly or indirectly)¹ a directory named V70, which in turn contains one or more Jython script files with a filename extension of .py. Using a recursive directory listing of files with this extension, you can find the complete list of script library files shown in Listing 16.1.²

¹ The resources subdirectory contains four directories (J2C, JDBC, JMS, and Provider), each of which contains a V70 directory.

² One way to do this on *ix type systems would be to execute (find . -name "*.py") from the scriptLibraries directory.

Listing 16.1 scriptLibrary Files³

³ The directory prefix was removed to allow the filenames to better display within this book.

How are these files made available to your scripts? Well, when the wsadmin command is started, these directories are automatically added to the sys.path variable. The fact that these directory names are added to the sys.path variable can be shown using a trivial loop construct, as seen in Listing 16.2.⁴

⁴ The <WAS_HOME>optionalLibrariesjythonLib directory contains the standard Jython class files, and the last entry (i.e., <WAS_HOME>scripts) was added by the WAuJ.py profile.

Listing 16.2 Displaying sys.path Contents

Is there anything else? Oh, yeah. All of the Jython files in these directories are automatically imported during the wsadmin environment initialization. You can see this using the dir() command when wsadmin is first started, as shown in Listing 16.3.⁵

⁵ Remember that both nested_scopes and wasroot were added by the WAuJ.py profile.

Listing 16.3 Autoloading of scriptLibraries

Some of the items returned by the dir() command prove quite useful. For example, if you print <moduleName>.__file__, where <moduleName> is the name of the scripting library file, the result is the fully qualified path and filename to the file from which the code was imported. With having just looked at the scripting libraries directory structure, it should be no surprise to see from where these files were imported.

The steps outlined here illustrate the fact that all of the *.py files within these directories are automatically imported and are shown in Listing 16.4.

1. Create a trivial Jython file containing a function and save it in one of these directories, or you can even create a new subdirectory under scriptLibraries directory (lines 1–7).

2. Start an interactive wsadmin scripting environment (lines 8–11). Note how the print statements from the script file are displayed during the initialization phase of wsadmin (lines 10–11).

3. Use the dir() command to verify that the new module exists and contains the defined function (lines 14–17).

Listing 16.4 Example: Adding Your Own Library

OK, this shows that you can “add your own” library modules and have them automatically loaded by wsadmin when it starts. In fact, you can also decide whether you want to include all, or even any, of the existing script libraries. If not, you only need to move, remove, or rename the files (so they no longer have an extension of .py).⁶

⁶ Remember, though, that the *.py files are compiled to filename$py.class in the same directory, so these too need to be moved, removed, or renamed.

Warning

If you choose to do this, it will make your environment different from the one created as part of the product installation process. As such, it could potentially interfere with a future product update (such as installation of a Fix Pack or cumulative fix). Be sure to document any and all changes to the scriptLibraries directory and provide a process for reliably duplicating the expected and required environmental changes. It would also be reasonable to include a mechanism for verifying that the expected files and changes are in place and possibly restoring the original directory structure and contents prior to a product update.

This raises an interesting question, specifically, “What’s the best way to make libraries available for a scripting environment?” Let’s review the options:

1. You could specify a file as a command-line option when wsadmin is started, using, for example, something like wsadmin -profileName myLibrary.py ....

2. You could modify the appropriate wsadmin.properties file and include the fully qualified path and filename on the com.ibm.ws.scripting.profiles directive, as was suggested in Chapter 7, “Introduction to Admin Objects,” where the WAuJ.py profile script was discussed.

3. You could create a new library file in an existing (or in a new) directory under scriptLibraries.

4. You could create a scripts directory under <WAS_HOME> and place the library files in it. This directory, if it exists, is added to the sys.path variable by the WAuJ.py profile script.⁷

⁷ WAuJ.py was covered in the first section of Chapter 7.

What’s the difference between placing a module in this scripts directory and placing it in a subdirectory under scriptLibraries? The main difference is that during the initialization of wsadmin, only the files with an extension of .py under the scriptLibraries directory are automatically loaded (imported). Consequently, all of these modules and their objects become immediately available for use by your scripts. For modules in the scripts directory to be made available, just as with the library routines provided with Jython, one of the various import statements would need to be used.

Is this a big deal? To some, it can be. Some people and organizations prefer the simplified approach of not automatically loading library files. This means that before a library routine can be used, the presence of an import statement documents which library routines or objects will be used by a script. If you tend to execute many, small scripts and do not require the collection of script library files, then the overhead associated with the automatic loading might not be to your liking.

On the other hand, you or your organization might prefer to standardize a set of library routines and objects that must be available for your scripting environment. In this case, you might prefer to use, expand, or extend modules in the scriptLibraries directory structure.

Scripting Library Help

In Chapter 7, we used some scripts to display the help text for the wsadmin scripting objects. You can do the same sort of thing for the script library modules. Each module includes a help() method that can be used to:

• Display the help text and methods for the module (should the optional method/procedure name be unspecified) or

• Display the help text for a specific module method/procedure name (should a valid method/procedure name be provided).

We were hoping that it would be as useful as those seen earlier in Chapter 7. Unfortunately, the help text for the script library modules does not have as much detail about the parameters as expected. The parameters are not identified as required or optional, nor is any description about the parameters provided. That’s the bad news. The good news is that we have the source code to each of the library modules to examine should we need to understand the following:

• A specific parameter and whether it is required or optional

• How the parameters are used within the method

• The wsadmin scripting objects that are used to implement the method

• How the library method parameters are related to the scripting object method parameters

The script that was used to display all of the script library help text is available on the download page and is named ScriptLibrariesHelp.py. The sample output file that was generated when the script was run is also available from the download page and is named ScriptLibrariesHelp.out. Listing 16.5 shows one way to execute this script and some abbreviated output.⁸

⁸ If you choose to execute this script yourself, you are encouraged to redirect the output to a file because the output generates more than 4,000 lines of text.

Listing 16.5 Example Output of ScriptLibrariesHelp.py Script

One of the things that you can note about this script is how it refers to each of the script library modules as an object. This is true even though the library modules are written in Jython, instead of Java, which is pretty neat.

Because each of the library modules includes a help method, and each help method acts in the same way, the help methods for the library modules are not discussed here.

Default Failure Action

Almost all of the script library methods have an optional last parameter called failonerror that has a default value of 'false', which is interpreted by each routine as an indication that errors should cause an exception to be thrown. If, instead, you prefer to have the library method terminate with a failure message, specify 'true' for this value. Listing 16.6 shows an example use of the default failonerror parameter (lines 3–11), as well as what happens if a value of 'true' is provided (lines 12–22). Note how the interactive wsadmin session is terminated by the uncaught exception.

Listing 16.6 Example Use of failonerror

Because this option parameter is on each and every one of the methods to be discussed, we won’t describe it each and every time.

AdminApplication Script Library Module

Let’s start by looking at the one of the library modules in more detail. The first in the list is applicationV70AdminApplication.py, the help for which identifies its role as “providing script procedures that configure, administer, and deploy applications.”

One of the big differences between the script library files and the “other” wsadmin scripting objects is that you have access to the source code to see exactly how things are implemented.⁹ One of the similarities is that like the AdminTask object, many of the script library methods are associated together into groups. For example, in the AdminApplication object, in both the source code comment block at the beginning of the file and in the help text, the 53 methods are associated into the following six command groups:

⁹ Warning: Unfortunately, these script library files have some lines indented using spaces and others using tab characters. This is not a best practice, and a product defect has been opened to get this fixed. This warning is provided in case you use an editor that uses other than the “default” operating system tab stops.

Group 1: Install and uninstall applications (13 methods)

Group 2: Queries application configurations (8 methods)

Group 3: Update applications (14 methods)

Group 4: Export applications (3 methods)

Group 5: Configure application deployment (9 methods)

Group 6: Administer applications (6 methods)

AdminApplication Group 1—Install and Uninstall Applications

Looking at either the comment block at the beginning of the source file or at the associated help text, you find the following methods in this group:

What do you notice about these method names? Some of them are extremely long! It would be very unlikely that anyone could type those long names without making at least one mistake. Thank goodness for copy and paste. The good news about the long names, though, is the fact that the purpose of the method is more likely to be understood just by looking at the method name.

Another thing that might catch your attention when you first look at these methods is the fact all of them have something to do with installing or removing an application. What do these methods do that the AdminApp.install() method does not? Nothing. In fact each of these methods uses the specified parameters to perform a specialized form of the AdminApp.install() method. That is what these scripting libraries are all about—showing you how you might want to build your own collection of specialized routines to perform actions for your environment in a way that conforms to your policies and procedures.

What other differences exist between these methods and those found in the other scripting objects? Unlike the other scripting objects, the scripting library methods:¹⁰

¹⁰ Other than the help() method, which returns the appropriate help text.

1. Display a message block with the method name and all specified parameter values.

2. Automatically save the configuration if the method changes the configuration.

3. Use positional parameters in the method signature, which forces all parameters to be specified in the statements where the methods are called.

4. Display a message, upon exit, indicating the success or failure of the requested action.

What does this message block look like? Listing 16.7 shows an example interactive session where one of the AdminApplication install methods gets invoked. Please note that this example does something that I do not expect you to do, which is assign a reference to the function to be called to a variable (fun, for example). The only reason for using this technique in this example was to shorten the statement where the function was called to fit on a single line in this book without having the line wrapped.

Listing 16.7 Sample AdminApplication.install

The good thing about the installation methods in the AdminApplication module is that they show how easy it can be to develop modules and methods that suit your particular needs. If your workplace has guidelines for applications, they can be implemented and enforced by library methods such as these. For example, you might be asked to use a specific set of installation options or even use a particular naming convention for items. With scripting libraries like these, you can enforce any kind of protocol or convention that is appropriate for your team, organization, or business.

Yet another thing to consider is the value of grouping related methods together in a module. In the case of this group of methods in the AdminApplication module, almost all of them can be used to install an application. The only method that is not is the one that can be used to remove an application (AdminApplication.uninstallApplication(), for example). Because the application already exists, the only parameter that needs to be provided is the name of the application to be removed.

Looking at the code used to implement the uninstallApplication() method, you can see exactly how it does its job:

1. It verifies that the appName parameter value is not an empty string.

2. It verifies that the specified application is a deployed object (using the AdminConfig.getid() method).

3. A message banner is displayed that identifies the task being performed and the values being used to do the job.

4. It uses the AdminApp.uninstall() method to remove the application.

5. It uses the AdminConfig.save() method to save the configuration changes.

6. A status message is displayed indicating the success or failure of the task.

Almost all of the methods in the script library modules follow this same format. Those methods with more parameters require more instructions to verify that every required parameter is valid, but the concept is the same. One of the really nice things about the fact that these library modules is that should you decide that you do not like something (for example, the ubiquitous banner messages that get displayed by each library method), you have a number of options:

1. You could edit the script library files (for example, to remove or disable the messages).¹¹

¹¹ This is not recommended because the script library files could be replaced during some product update.

2. You could create your own library files containing the same methods but in a different library files that have your own versions of the code (such as without the messages). This option has definite possibilities because these would be “new” library files and would be unlikely to be replaced by a product update.

3. You could delete the scriptLibraries directory and all of its contents. This option appeals to some because of the reduced number of module imports to be performed during the wsadmin initialization phase.

4. You could leave the scriptLibraries in place but not make use of any of the library files or the methods contained therein. This option appeals to those interested in developing their own script libraries, using their own standards and practices.

AdminApplication Group 2—Query Application Configurations

The variety of tasks performed by this group of methods is a bit more diverse than the previous group. However, the method names again are quite straightforward:

The checkIfAppExists() method is also easily understood. Given an application name, it uses the AdminConfig.getid() method to see if an application of this name exists in the configuration as having been deployed. If so, the method returns true; otherwise, false.¹²

¹² In addition to true and false, there is a possibility of -1 being returned should an error be encountered. In addition, an exception may also be raised. So you might want to consider calling these methods within a try/except statement.

Sometimes, though, a scripting library method can be surprising. For example, if the AdminApplication.getAppDeployedNodes() method is called with the name of a deployed application, the result is a list of the nodes on which the application is deployed.¹³ So far, so good. We were very surprised, however, when we called the same method and specified the name of a non-existent application. We expected an empty list to be returned. Unfortunately, an exception was thrown. So here is an example of multiple ways to handle the same situation. If you choose to use the script libraries, you are going to have to write your programs to deal with the way that these methods handle “error” conditions. If you write your own library methods, you might decide that for your organization, a different implementation might be more appropriate.

¹³ Unfortunately, there is a mistake in the code. In AdminApplication on line 4336, the value to be appended should be nodeName, instead of node. So, if the getAppDeployedNodes() method is called to display the nodes on which an application is deployed, and the application is deployed on a cluster, a NameError exception will be generated.

Similarly, the AdminApplication.getAppDeploymentTarget() method can be used to determine the deployment target attribute for an application. What does that mean? Well, under the covers, this method uses the AdminConfig.getid() method to verify that the specified application has been deployed and at the same time get the configID of the deployment configuration object for this application. Then, the AdminConfig.showAttribute() method is used to obtain the deployment targets attribute for this given configID. And finally, the returned value is converted to a list.

The list*() methods in this group (i.e., listApplications(), listApplicationsWithTarget(), and listModulesInAnApp()) are very similar to each other. The first, listApplications() needs no parameters and simply uses AdminApp.list() to generate the list of deployed applications. The main difference between these two methods is that AdminApp.list() returns a string, and AdminApplication.listApplications() returns a list of strings (as well as printing out information about the specific method that was called).

The next method, listApplicationsWithTarget(), can be used to list the deployed applications on a specific node. You need only to specify the node name and server name parameters. The last, listModulesInAnApp(), can be used to list the modules in a given application. If you want to find the module information for a specific application that is not deployed upon a specific server, specify the second parameter (such as serverName) as an empty string ('').

AdminApplication Group 3—Update Applications

It should be relatively easy to guess what kind of methods would be put into this group given the two-word abstract:

The updateApplicationUsingDefaultMerge() method performs a simple call to the AdminApp.install() method, specifying the '-update' and '-appName' options. So the only parameters needed by this method are the name of the EAR file and the name of the existing application.

The updateApplicationWithUpdateIgnoreNewOption() method makes sense if you are familiar with the update.ignore.new AdminApp installation option. This option is applicable for the AdminApp.install() method, as long as the 'update' option is specified, and the item being updated is a module file or an application. It requests that bindings from the new version of the item being updated are ignored, thus leaving existing (configured) bindings intact.

The updateApplicationWithUpdateIgnoreOldOption() method is very similar and only differs from the preceding method in that the 'update.ignore.old' option is used so that existing (configured) bindings are overridden by those in the new version of the item being updated.

The addSingleFileToAnAppWithUpdateCommand() method shows how to call the AdminApp.update() method and add a file with associated contentURI, a specified application. The updateSingleFileToAnAppWithUpdateCommand() method acts in a very similar fashion and is used to update (replace) an existing file within a specific application. And the deleteSingleFileToAnAppWithUpdateCommand() method¹⁴ does what you probably suspect and removes the specified file from the indicated application.

¹⁴ I’m surprised that these grammatically incorrect names are used. I would have thought that they would be named something like updateSingleFileInAnAppWithUpdateCommand() and deleteSingleFileFromAnAppWithUpdateCommand().

The next few methods deal with a single module file within an application:

The first of these, the addSingleModuleFileToAnAppWithUpdateCommand() method, as the name implies, adds a single module file to an existing application using the AdminApp.update() method (command). The parameters of this method are as follows:

• The application name

• The fully qualified path and file name to be added

• The URI of the content

Looking at the implemen.ation of the method, however, it is surprising to see that the BindJndiForEJBNonMessageBinding option is being used. The next method, updateSingleModuleFileToAnAppWithUpdateCommand(), is used in a similar fashion to update a single module file within an application using the AdminApp.update() method. Again, looking at the implementation, it is surprising to see the use of the DataSourceFor20EJBModules option by this routine.

The next method, addUpdateSingleModuleFileToAnAppWithUpdateCommand(), makes use of the addupdate operation to either add a module file, if it does not exist within the application, or to update a module file if present within the application. Interestingly enough, this method does not include any unexpected AdminApp.update() options in the routine.

You can use the last of these four methods, deleteSingleModuleFileToAnAppWith-UpdateCommand(), to remove a single module file from an application. To do so, you must provide the application name, the fully qualified path and filename, and the content URI for the specific file within the application.

The next few methods deal with manipulating (that is, adding, updating, or deleting) partial applications to a deployed application. To do this, an input archive file (normally with a zip extension) must be prepared. Then, one of the following methods should be executed:

• addPartialAppToAnAppWithUpdateCommand()

• updatePartialAppToAnAppWithUpdateCommand()

• deletePartialAppToAnAppWithUpdateCommand()

The addPartialAppToAnAppWithUpdateCommand() method uses the contents of the specified archive file to add things to a specific application. To do this, only the name of the application to be updated and the (fully qualified) name of the input archive file need to be specified.

Likewise, the updatePartialAppToAnAppWithUpdateCommand() method will also use the AdminApp.update() method to modify existing portions of a particular application. It does so using the contents of the specified archive file, and the deletePartialAppToAnAppWithUpdateCommand() method uses the specified archive file to remove parts of an existing application.

The last method in this group, that is, updateEntireAppToAnAppWithUpdateCommand(), also uses the AdminApp.update() method and an input archive file to modify an existing application. However, it’s not certain why it was decided that the following options be included on this call:

usedefaultbindings
nodeployejb
MapWebModToVH

AdminApplication Group 4—Export Applications

This is the smallest group within the AdminApplication library and contains only three methods:

• exportAnAppToFile()

• exportAllApplicationsToDir()

• exportAnAppDDLToDir()

The first of these, exportAnAppToFile(), can be used to export the contents of an application to an archive file. To use this method, you need only specify the name of a deployed application and the fully qualified path to the archive file to be created.

The next method, exportAllApplicationsToDir(), is even simpler to use. It only needs to be passed the fully qualified path to a directory into which all of the applications will be exported as archive files, each having an extension of *.ear.

The last method in this group, exportAnAppDDLToDir(), is a simple wrapper to the AdminApp.exportDDL() method, which lets you export the data definition language (DDL) from a specified application to a specific directory of your choice.

AdminApplication Group 5—Configure Application Deployment

The penultimate AdminApplication group deals specifically with the configuration of different parts of deployed applications. Some of these methods show how an individual attribute of a configured item can be modified. For example, the configureStartingWeightForAnApplication() method can be used to change the starting weight attribute for a specific application. As you might expect, the only values needed by the method are the application name and the starting weight. Unfortunately, the method does not check, or properly handle, the situation where a numeric startingWeight is specified by the user. So instead of “doing the reasonable thing,” the following, cryptic, error message is displayed:¹⁵

¹⁵ The reason this exception gets generated is because the method includes code to display the parameter values and to do so has each parameter name displayed and tries to use the string concatenation operator ('+') to concatenate the parameter name with the parameter value. Unfortunately, this operator does not allow a number to be concatenated to a string; only two strings may be concatenated.

Exception: exceptions.TypeError __add__ nor __radd__ defined for these operands

So in order to use these scripting library routines, be sure that you are going to provide (pass in) values of the appropriate datatype. If you are going to be writing your own methods, it would be wise to include tests for “reasonable datatypes” and to handle them appropriately.

Likewise, the following methods may be used to assign new values for specific application attributes. Unfortunately, each of these methods does minimal parameter checking,¹⁶ so use them with caution:

¹⁶ A test is made to see if the parameter is an empty string or not. A non-empty string is “presumed valid.”

1. configureClassLoaderPolicyForAnApplication()—Can be used to modify the 'warClassLoaderPolicy' attribute for a deployed application. The only valid settings are "SINGLE" and "MULTIPLE".

2. configureClassLoaderLoadingModeForAnApplication()—Can be used to modify the classloader loading 'mode' attribute for a deployed application. The only valid settings are "PARENT_FIRST" and "PARENT_LAST".

3. configureApplicationLoading()—Can be used to modify the 'enable' value for the 'targetMappings' attribute of a deployed application. Only true or false should be specified.

4. configureLibraryReferenceForAnApplication()—Create a shared library reference (such as 'LibraryRef') for a deployed application.

The next set of methods in this group has a few parameters in addition to the name of a specific application for which the configuration changes are intended.

1. configureEJBModulesOfAnApplication()—This method can be used to specify the startingWeight, and indicate whether or not the EBJ Modules should be enabled for the specified application.

2. configureWebModulesOfAnApplication()—This method can be used to specify the startingWeight, and the classloader mode (for example, 'PARENT_FIRST' or 'PARENT_LAST') for a specific web module of a specific application.

3. configureConnectorModulesOfAnApplication()—This method can be used to configure the following connector module attributes for a specific application:

• j2cconnFactory

• jndiName

• authDataAlias

• connTimeout

The last method in this group has been saved for last because it is significantly different from the other methods in the group due to the number of parameters it requires. The configureSessionManagementForAnApplication() method creates a sessionManagement object, with all of its attributes, for a specified application. That’s why the method has so many parameters, one for each sessionManagement attribute. Unfortunately, like the other methods in this group, this method does minimal checking on the parameter values. Each parameter value is checked to verify that it is not an empty string.¹⁷ If you need this kind of capability, you might need to write some functions that allow you to create and modify individual sessionManagement attributes for an application.

¹⁷ This is really unfortunate because the online documentation (http://publib.boulder.ibm.com/infocenter/wasinfo/v7r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/rxml_7libapp4.html) indicates that the enableSSLTracking attribute has been deprecated and suggests that an empty string be specified.

AdminApplication Group 6—Start/Stop Applications

The last group of methods can be used to start or stop applications. The first of these methods, startApplicationOnSingleServer(), can be used to start an application on a single application server. The good news is that it includes checks for things such as the following:

• Is the application already running?

• Is the application manager active? (If it is not, then applications can’t be stopped or started.)

Unfortunately, along with the good news, there appears to be some bad news: The user is required to specify the nodeName for the specified application server. This makes sense if the script is connected to a Deployment Manager, but not if the connection is to an unmanaged node.

These methods can be used to start or stop an application on various application servers. Fortunately, the names are explicit enough for you to discern which method to use based upon your specific need.

startApplicationOnSingleServer()
startApplicationOnAllDeployedTargets()
stopApplicationOnSingleServer()
stopApplicationOnAllDeployedTargets()
startApplicationOnCluster()
stopApplicationOnCluster()

For both the startApplicationOnSingleServer() and the stopApplicationOnSingleServer() methods, you need to provide the application name, the node name, and the server name. For the startApplicationOnAllDeployedTargets() and the stopApplicationOnAllDeployedTargets() methods, you only need to specify the application name and the server name. Similarly, for the startApplicationOnCluster() and the stopApplicationOnCluster() methods, you only need specify the application name and the cluster name.

Business-Level Applications (AdminBLA)

The next script library module deals with business-level applications, which are a new concept in version 7.0 of the product. A business-level application is a configuration entity, similar to an enterprise application, that can be used to hold the definition of an application from a business perspective. One of the scripting library files, AdminBLA.py,¹⁸ contains a group of methods that can be used to create, manipulate, and delete business-level application related items.

¹⁸ Remember that the file can be found under the scriptLibraries directory under the WebSphere Application Server installation directory, e.g., <WAS_HOME>scriptLibrariesapplicationV70AdminBLA.py.

The help() method was described in general terms in the “Scripting Library Help” section, so we do not need to discuss it again. The remainder of the methods in the AdminBLA library module deal with one of the following types of BLA-related items:

Business-Level Applications (BLA) Asset—An asset represents one or more (binary) application files that are stored in an asset repository.

CompUnit—A composition unit represents an asset in the BLA. A CompUnit enables the asset contents to interact with other assets in the BLA. It also enables the BLA runtime to load and execute asset contents.

The BLA-related methods in this library module are as follows:

• listBLAs(blaName='', includeDescription='')—This easily understood method can be used to either list all of the business-level applications (if no parameters are specified) or a single BLA (if the BLA name is specified). A second optional (boolean) parameter can be used to include the BLA description in the result (should one exist).

The result is a list of string values. Each BLA name will start with 'WebSphere: blaname='. If the request specifies that descriptions should also be included, then descriptions that exist will follow the BLA name in the list. So if you are going to process the list of all BLA names, be prepared to handle the BLA entries for which no description exists.

• createEmptyBLA(blaName, description='')—This method can be used to create a new BLA and specify an optional description for it. The first parameter is required and specifies the name of the BLA to be created. This method will either return a string containing the BLA configuration ID, or an exception will be raised if the specified BLA can’t be created (for example, if the specified BLA name already exists or an invalid name was specified).

• deleteBLA(blaName)—This method has only one required parameter, which is the name of the BLA to be removed. The result of calling this method will either be a string containing the configuration ID of the BLA that was deleted, or an exception will be raised to indicate an error occurred.

• startBLA(blaName)—This method has only one required parameter, which is the name of the BLA to be started. The result of calling this method will either be a string containing a message indicating that the BLA that was started successfully (even if the BLA was previously started), or an exception will be raised to indicate an error occurred.

• stopBLA(blaName)—This method has only one required parameter, which is the name of the BLA to be stopped. The result of calling this method will either be a string containing a message indicating that the BLA that was stopped successfully (even if the BLA was previously stopped), or an exception will be raised to indicate an error occurred.

The Asset-related methods in this library module are as follows:

• importAsset(sourcePath, storageType='')—This method has only one requiredparameter; that is, the (complete, or fully qualified) sourcePath (path and filename) to the asset file to be imported into the domain configuration. The optional parameter is used to identify what information from the specified file should be saved in the asset repository. The allowed values are as follows:

• 'FULL'—Stores the complete binaries from the source file (this is the default value).

• 'METADATA'—Stores only the metadata portion of the binary files.

• 'NONE'—Stores no binaries in the asset repository.

• exportAsset(assetID, fileName)—This method has two required parameters—the name of the asset to be exported and the name of the destination file into which the asset information should be written.

• editAsset(assetID, description, destinationURL, typeAspect, relationship, filePermission, validate)—This method is used to modify options specified when the asset was imported. It has seven required parameters, which makes it one of the most complex methods in the scripting libraries. Unfortunately, the banner message displayed by this method says that only the assetID is required, but this is not the case. If less than seven parameters are specified, an error message is displayed indicating that seven parameters are required.¹⁹ The parameters to this routine are as follows:

¹⁹ If the author of the method had actually wanted there to be optional parameters, then a default value should have been specified for each (e.g., description=""). A product defect has been opened to get this issue corrected.

• assetID—Specifies the name of the asset to be modified.

• description—Specifies new descriptive text to be associated with the asset.

• destinationURL—Specifies a new destination URL to be associated with the asset.

• typeAspect—Specifies a new type aspect to be associated with the asset.

• relationship—Specifies a new asset relationship.

• filePermission—Specifies a new asset filePermission configuration.

• validate—Specifies whether the asset should be validated (true), or not (false, the default).

• listAssets(assetID='', includeDescription='', includeDeployUnit='')—This method has no required parameters. If specified, the assetID is the name of the asset to be listed. If this parameter is empty, all registered assets are listed. The other two optional parameters are boolean values, and each defaults to false. If the includeDescription parameter is specified as true, the asset description is returned (should one exist). If the includeDeployUnit parameter is specified as true, information about the deployable units within the asset are returned.²⁰

²⁰ Remember that Jython has a really nice feature where you can use keywords to assign a single optional parameter by name, rather than by position. For example, you could execute a command such as AdminBLA.listAssets (includeDescription='true').

• deleteAsset(assetID)—This method is used to remove the specified asset from the asset repository. The parameter is required and must exist. The fully qualified assetID is returned to indicate that the removal operation was a success.

• viewAsset(assetID)—This method is used to display the asset settings stored in the repository. Only the asset name, or ID, is allowed, and it must be specified.

The methods in the AdminBLA library module related to composition units are as follows:

• addCompUnit(blaName, cuSourceID, deployUnits, cuName, cuDescription, startingWeight, server, activationPlan)—This method is used to add a composition unit to a specific BLA. It has eight required parameters, even though the banner message displayed by this method says that only the blaName and cuSourceID are required. The parameters to this routine are as follows:

• blaName—The name of the BLA to which the composition unit is to be added.

• cuSourceID—The configuration ID of the composition unit to be added.

• deployUnits—The name of the deployable unit for the asset.

• cuName—The name of the composition unit to be added.

• cuDescription—The descriptive text for the composition unit to be added.

• startingWeight—The starting weight of the composition unit to be added.

• server—The name of the server to which the composition unit is to be mapped.

• activationPlan—Specifies the activation plan runtime components.

• listCompUnits(blaName, includeDescription='')—This method can be used to list the composition units associated with a specific business-level application. The second, optional (boolean) parameter can be used to indicate that the description should be included.

• editCompUnit(blaName, compUnitID, cuDescription, startingWeight, server, activationPlan)—This method is used to modify the options specified when the composition unit was created. All six parameters are required. The parameters to this routine are as follows:

• blaName—The name of the BLA with which the composition unit is associated.

• compUnitID—The configuration ID of the composition unit.

• cuDescription—The descriptive text for the composition unit.

• startingWeight—The starting weight of the composition unit.

• server—The name of the server to which the composition unit is to be mapped.

• activationPlan—The activation plan runtime components.

• deleteCompUnit(blaName, compUnitID)—This method is used to remove the specified composition unit from the indicated BLA.

• viewCompUnit(blaName, compUnitID)—This method is used to display information about the specific composition unit associated with the indicated BLA.

Java 2 Connector (AdminJ2C) Library Module

This library module contains methods related to J2C resources. The three types of operations associated with these types of resources are list, install, and create.

You will be better able to understand the differences between these operations when we take a look at the methods. Because we have already discussed the help method, the next easiest to understand are the ones used to list or display information about J2C resources. These methods are as follows:

• listMessageListenerTypes(j2cRAConfigID)—This method can be used to list the message listener types associated with the required J2C Resource Adapter identified.

• listConnectionFactoryInterfaces(j2cRAConfigID)—In the same way, this method can be used to list the connection factory interfaces associated with the required J2C Resource Adapter identified.

• listAdminObjectInterfaces(j2cRAConfigID)—Similarly, this method can be used to list the administrative object interfaces associated with the required J2C Resource Adapter identified.

• listJ2CResourceAdapters(j2cRAName='')—This method can be used to list all of the configured J2C Resource Adapters (if no parameter is specified) or to list a specific one given a Resource Adapter Name.

• listJ2CConnectionFactories(j2cRAConfigID, cfInterface)—This method can be used to list the J2C connection factories associated with a specific (required) J2C Resource Adapter configuration ID and the (also required) connection factory interface name.

• listJ2CActivationSpecs(j2cRAConfigID, msgListenerType)—This method can be used to list the J2C activation specifications associated with a specific (required) J2C Resource Adapter configuration ID, and a specific (required) message listener type.

• listJ2CAdminObjects(j2cRAConfigID, aoInterface)—This method can be used to list the J2C administration objects associated with a specific (required) J2C Resource Adapter configuration ID and a specific (required) administration object interface.

• installJ2CResourceAdapter(nodeName, rarPath, J2CRAName, otherAttrsList=[])—This method can be used to install a J2C Resource Adapter to the configuration. The nodeName, rarPath, and J2CRAName parameters are required and specify the name of the node with which the resource adapter is to be associated, the fully qualified path of the RAR file to be installed, and the name of the J2C Resource Adapter to be installed.

The last parameter is optional and can be used to provide a collection of name, value pairs to be used during the installation of the resource adapter.

• createJ2CConnectionFactory(j2cRAConfigID, j2cCFName, cfInterface, jndiName, otherAttrsList=[])—This method can be used to create a J2C connection factory. The first four parameters are required and specify the following:

• The J2C Resource Adapter configuration ID

• The J2C Connection Factory Name

• The Connection Factory interface

• The JNDI Name

The last parameter is optional and can be used to provide a collection of name, value pairs to be used during the creation of the connection factory.

• createJ2CActivationSpec(j2cRAConfigID, j2cASName, msgListenerType, jndiName, otherAttrsList=[])—This method is used to create a J2C Activation Specification. The first four parameters are required and specify the following:

• The J2C Resource Adapter configuration ID

• The J2C Activation Specification Name

• The Connection Factory interface

• The JNDI Name

The last parameter is optional and can be used to provide a collection of name, value pairs to be used during the creation of the activation specification.

• createJ2CAdminObject(j2cRAConfigID, j2cAOName, aoInterface, jndiName, otherAttrsList=[])—This method is used to create a J2C Administrative Object. The first four parameters are required and specify the following:

• The J2C Resource Adapter configuration ID

• The J2C Administrative Object Name

• The Administrative Object interface

• The JNDI Name

The last parameter is optional and can be used to provide a collection of name, value pairs to be used during the creation of the activation specification.

AdminJDBC Library Module

This library module contains methods for performing DataSource and JDBCProvider-related tasks. Some of the methods can be used to query information about these kinds of resources, and the remainder can be used to create these kinds of resources. The query methods are as follows:

• listDataSources(datasourceName="")—This method can be used to list one or all the configured DataSource configuration IDs. If no name is specified, then the result is a list of all of the configured DataSource configIDs. If a single DataSource name is specified, only it is used to query if the resource exists. The result could be an empty list.

• listDataSourceTemplates(templateName="")—This method can be used to list one or all of the configured DataSource Template IDs. If no name is specified, then the result is a list of all the configured DataSource Template IDs. If a single template name is specified, only it is used to query if the resource exists. The result might be an empty list.

• listJDBCProviders(JDBCName="")—This method can be used to list one or all of the configured JDBCProvider configIDs. If no name is specified, the result is a list of all the configured provider IDs. If a single provider name is specified, only it is used to query if the resource exists. The result might be an empty list.

• listJDBCProviderTemplates(templateName="")—This method can be used to list one or all the configured JDBCProvider template object IDs. If no name is specified, the result is a list of all the configured template object IDs. If a single template name is specified, only it is used to query if the resource exists. The result might be an empty list.

The creation-related methods are the following:

• createDataSource(nodeName, serverName, JDBCName, datasourceName, otherAttrsList=[])—This method can be used to create a DataSource and has the following required parameters:

• nodeName—Defines the name of the node on which this resource is to be created.

• serverName—Defines the name of the server on which this resource is to be created.

• JDBCName—Defines the JDBC provided to be used for the creation.

• datasourceName—Defines the name of the DataSource to be created.

In addition, an optional parameter, otherAttrsList, is provided that allows other attributes that are used for the creation of the resource to be specified.

• createDataSourceUsingTemplate(nodeName, serverName, JDBCName, templateID, datasourceName, otherAttrsList=[])—Similarly, this method can be used to create a DataSource using an existing DataSource Template ID and has the following required parameters:

• nodeName—Defines the name of the node on which this resource is to be created.

• serverName—Defines the name of the server on which this resource is to be created.

• JDBCName—Defines the JDBC provided to be used for the creation.

• templateID—Defines the template ID to be used for the creation.

• datasourceName—Defines the name of the DataSource to be created.

In addition, an optional parameter, otherAttrsList, is provided that allows other attributes that are used for the creation of the resource to be specified.

• createJDBCProvider(nodeName, serverName, JDBCName, implClassName, otherAttrsList=[])—This method can be used to create a JDBCProvider and has the following required parameters:

• nodeName—Defines the name of the node on which this resource is to be created.

• serverName—Defines the name of the server on which this resource is to be created.

• JDBCName—Defines the JDBC provided to be created.

• implClassName—Defines the name of the implementation class to be used for the creation.

In addition, an optional parameter, otherAttrsList, is provided that allows other attributes that are used for the creation of the resource to be specified.

• createJDBCProviderUsingTemplate(nodeName, serverName, templateID, JDBCName, implClassName, otherAttrsList=[])—Similarly, this method can be used to create a JDBCProvider using an existing JDBCProvider Template ID and has the following required parameters:

• nodeName—Defines the name of the node on which this resource is to be created.

• serverName—Defines the name of the server on which this resource is to be created.

• templateID—Defines the ID of the template to be used for the creation request.

• JDBCName—Defines the JDBC provided to be used for the creation.

• implClassName—Defines the name of the implementation class to be used for the creation.

In addition, an optional parameter, otherAttrsList, is provided that allows other attributes that are to be used for the creation of the resource to be specified.

AdminJMS Library Module

This library module contains methods that can be used to query or configure Java Messaging Service (JMS)-related items:

• listJMSProviderTemplates(templateName="")—This method can be used to list the configured JMSProvider templates. If no template name is provided, all of the configured template IDs are returned in a list. If a name is specified, a list is returned with the matching template IDs if any exist.

• listGenericJMSConnectionFactoryTemplates(templateName="")—Thismet hod can be used to list the generic JMS connection factory templates. If no template name is provided, all of the configured template IDs are returned in a list. If a template name is specified, a list is returned with the matching template IDs if any exist.

• listGenericJMSDestinationTemplates(templateName="")—This method can be used to list the generic JMS destination templates. If no template name is provided, all of the configured template IDs are returned in a list. If a template name is specified, a list is returned with the matching template IDs if any exist.

• listWASQueueTemplates(templateName="")—This method can be used to list the WebSphere Application Server queue templates. If no template name is provided, all of the configured template IDs are returned in a list. If a template name is specified, a list is returned with the matching template IDs if any exist.

• listWASQueueConnectionFactoryTemplates(templateName="")—This method can be used to list the WebSphere Application Server queue connection factory templates. If no template name is provided, all of the configured template IDs is returned in a list. If a template name is specified, a list is returned with the matching template IDs if any exist.

• listWASTopicTemplates(templateName="")—This method can be used to list the WebSphere Application Server topic templates. If no template name is provided, all of the configured template IDs are returned in a list. If a template name is specified, a list is returned with the matching template IDs if any exist.

• listWASTopicConnectionFactoryTemplates(templateName="")—This method can be used to list the WebSphere Application Server topic connection factory templates. If no template name is provided, all of the configured template IDs are returned in a list. If a template name is specified, a list is returned with the matching template IDs if any exist.

• listJMSProviders(JMSProviderName="")—This method can be used to list the configured JMS providers. If no provider name is provided, all of the configured provider IDs are returned in a list. If a provider name is specified, a list is returned with the matching provider IDs if any exist.

• listGenericJMSConnectionFactories(JMSCFName="")—This method can be used to list the generic JMS connection factory IDs. If no JMS connection factory name is provided, all of the configured factory IDs are returned in a list. If a connection factory name is specified, a list is returned with the matching factory IDs if any exist.

• listGenericJMSDestinations(JMSDestName="")—This method can be used to list the generic JMS destination IDs. If no destination name is provided, all of the configured destination IDs are returned in a list. If a destination name is specified, a list is returned with the matching destination IDs if any exist.

• listWASQueues(WASQueueName="")—This method can be used to list the WebSphere Application Server queue IDs. If no queue name is provided, all of the configured queue IDs are returned in a list. If a queue name is specified, a list is returned with the matching queue ID if one exists.

• listWASQueueConnectionFactories(WASQueueCFName="")—This method can be used to list the WebSphere Application Server queue connection factory IDs. If no queue connection factory name is provided, all of the configured IDs are returned in a list. If a queue connection factory name is specified, a list is returned with the matching queue connection factory ID, if one exists.

• listWASTopics(WASTopicName="")—This method can be used to list the WebSphere Application Server topics. If no topic name is provided, all of the configured topic IDs are returned in a list. If a topic name is specified, a list is returned with the matching topic ID if one exists.

• listWASTopicConnectionFactories(WASTopicCFName="")—This method can be used to list the WebSphere Application Server topic connection factory IDs. If no topic connection factory name is provided, all of the configured IDs are returned in a list. If a topic connection factory name is specified, a list is returned with the matching ID, if one exists.

• listJMSConnectionFactories(jmscfName="")—This method can be used to list the configured JMS connection factory IDs. If no connection factory name is provided, all of the configured IDs are returned in a list. If a JMS connection factory name is specified, a list is returned with the matching ID, if one exists.

• listJMSDestinations(jmsdestName="")—This method can be used to list the configured JMS destination IDs. If no destination name is provided, all of the configured IDs are returned in a list. If a JMS destination name is specified, a list is returned with the matching ID, if one exists.

• createJMSProvider(nodeName, serverName, JMSProviderName, extInitContextFactory, extProviderURL, otherAttrsList=[])—This method can be used to create a JMS provider. The five required parameters are as follows:

• nodeName—Defines the node on which the provider is to be created.

• serverName—Defines the server on which the provider is to be created.

• JMSProviderName—Defines the name of the provider to be created.

• extInitContextFactory—Defines the Java class name of the initial context factory.

• extProviderURL—Defines the provider URL for external JNDI lookups.

The optional parameter, otherAttrsList, can be used to specify name/value pairs of values to be used during the resource creation.

• createJMSProviderUsingTemplate(nodeName, serverName, templateID, JMSProviderName, extInitContextFactory, extProviderURL, otherAttrsList=[])—This method can be used to create a JMS provider using a pre-existing template ID. The required parameters are as follows:

• nodeName—Defines the node on which the provider is to be created.

• serverName—Defines the server on which the provider is to be created.

• templateID—Defines the template ID to be used during the creation.

• JMSProviderName—Defines the name of the provider to be created.

• extInitContextFactory—Defines the Java class name of the initial context factory.

• extProviderURL—Defines the provider URL for external JNDI lookups.

The optional parameter, otherAttrsList, can be used to specify name/value pairs of values to be used during the resource creation.

• createGenericJMSConnectionFactory(nodeName, serverName, JMSProviderName, JMSCFName, jndiName, extJndiName, otherAttrsList=[])—This method can be used to create a generic JMS connection factory. The required parameters are as follows:

• nodeName—Defines the node on which the provider is to be created.

• serverName—Defines the server on which the provider is to be created.

• JMSProviderName—Defines the name of the provider with which the connection factory is to be associated.

• JMSCFName—Defines the name of the connection factory to be created.

• jndiName—Defines the JNDI name to be used to bind the connection factory to the namespace.

• extJndiName—Defines the JNDI name to be used to bind the queue into the application server namespace.

The optional parameter, otherAttrsList, can be used to specify name/value pairs of values to be used during the resource creation.

• createGenericJMSConnectionFactoryUsingTemplate(nodeName, serverName, JMSProviderName, templateID, JMSCFName, jndiName, extJndiName, otherAttrsList=[])—This method can be used to create a generic JMS connection factory using an existing template. The required parameters are as follows:

• nodeName—Defines the node on which the provider is to be created.

• serverName—Defines the server on which the provider is to be created.

• JMSProviderName—Defines the name of the provider with which the connection factory is to be associated.

• templateID—Defines the template to be used for the creation.

• JMSCFName—Defines the name of the connection factory to be created.

• jndiName—Defines the JNDI name to be used to bind the connection factory to the namespace.

• extJndiName—Defines the JNDI name to be used to bind the queue into the application server namespace.

The optional parameter, otherAttrsList, can be used to specify name/value pairs of values to be used during the resource creation.

• createGenericJMSDestination(nodeName, serverName, JMSProviderName, JMSDestName, jndiName, extJndiName, otherAttrsList=[])—This method can be used to create a generic JMS destination. The required parameters are as follows:

• nodeName—Defines the node on which the provider is to be created.

• serverName—Defines the server on which the provider is to be created.

• JMSProviderName—Defines the name of the provider with which the connection factory is to be associated.

• JMSDestName—Defines the name of the destination to be created.

• jndiName—Defines the JNDI name to be used to bind the connection factory to the namespace.

• extJndiName—Defines the JNDI name to be used to bind the queue into the application server namespace.

The optional parameter, otherAttrsList, can be used to specify name/value pairs of values to be used during the resource creation.

• createGenericJMSDestinationUsingTemplate(nodeName, serverName, JMSProviderName, templateID, JMSDestName, jndiName, extJndiName, otherAttrsList=[])—This method can be used to create a generic JMS destination using an existing template. The required parameters are as follows: