Oracle WebLogic Server Support: Using WebLogic Scripting Tool (WLST)

This document describes the following:

  1. Configuring Projects for WLST
  2. Creating New WLST Files
  3. Editing WLST Script
  4. Adding WLST Templates
  5. Navigating MBean Structures
  6. Using WLST Console
  7. Executing WLST
  8. Debugging WLST Script
  9. Importing Existing WLST Script into OEPE
  10. Known Issues and Limitations
  11. Related Information

WLST is a scripting tool for monitoring, managing, and configuring Oracle WebLogic Server from the command line. WLST is based on Jython programming language with WebLogic WLST libraries. The execution can happen in the following three modes: scripting, interactive, and embedded. WLST can be enabled for online and offline connection modes and can act as a JMX client.

OEPE provides tooling for WLST that enable editing, executing, debugging, WebLogic MBean access and navigation, as well as a built-in help for WLST commands.


1. Configuring Projects for WLST

Using OEPE, you can add WLST facet to your Java projects that run on Oracle WebLogic Server. Note that Utility projects are most suitable for this funtionality.

To configure your project for WLST, follow this procedure:

  1. Either add the WLST facet when you create a faceted project, or add the facet to an existing project by right-clicking your project in the Project Explorer and selecting Properties from the drop-down menu. This opens the Properties dialog, as Figure 1 shows.



    Figure 1.     Project Properties Dialog



  2. In the Properties dialog, select Project Facets on the left panel, and then select WLST from the Project Facet list, as Figure 2 shows.



    Figure 2.     Selecting WLST Support in the Project Properties Dialog


  3. Optionally, you may click Further configuration available... link to open the Modify Faceted Project > Configure WebLogic Scripting Tools dialog that Figure 3 shows. This dialog allows you to configure WLST script source path and targeted runtime.



    Figure 3.     Modify Faceted Project - Configure WebLogic Scripting Tools Dialog


  4. Click OK on the Modify Faceted Project > Configure WebLogic Scripting Tools dialog.

  5. By clicking Apply > OK on the Properties dialog, you will complete adding WLST support to your project, as Figure 4 shows.



    Figure 4.     WLST in Project View



2. Creating New WLST Files

You can create a new WLST script as follows:
  • In the Project Explorer, right-click your WLST-enabled project and select New > Other from the drop-down menu. On the New dialog, select WebLogic > WLST Script, as Figure 5 shows, and then click Next to open the New WebLogic WLST Script > WLST Script dialog, shown in Figure 6.



    Figure 5.     Creating New WLST File




    Figure 6.     Creating New WLST File Dialog


  • Using the New WebLogic WLST Script > WLST Script dialog, specify location for the new WLST file, as well as the template to use by clicking Browse for the Template field to open the TemplateName dialog that Figure 7 shows. You may choose one of the standard templates such as a default one, or a custom template of a module scope that you defined yourself.



    Figure 7.     Selecting Template



  • Click Finish on the New WebLogic WLST Script > WLST Script dialog.

Upon completion, a new WLST script file is created in the specified location, as Figure 7 shows.



Figure 7. WLST File in Project Explorer


You can execute this file, as well as edit it using either the source editor, or a WLST file editor provided by OEPE.


3. Editing WLST Script

OEPE provides an editor for WLST files. The editor features the following:
  • Syntax highlighting.

  • Code completion for Jython and WLST built-in functions.

  • WLST Help view that includes detailed WLST command reference materials.

To access the editor, double-click your WLST file.

Figure 9 shows the editor and its Help view that you access by selecting Window > Show View > Other from the main menu, and then selecting WebLogic > WLST Help View in the Show View dialog. To view help topics for a command, you double-click that command in the WLST source editor.



Figure 9. WLST Source Editor and Help View



4. Adding WLST Templates

OEPE provides templates that you can use to create WLST files.

You add a new WLST template as follows:

  • Select Window > Preferences from the top-level menu to open the Preferences dialog.

  • On the Preferences dialog (see Figure 10) expand the Pydev > Editor node, and then select Templates to open the list of available templates.



    Figure 10.     Templates View


  • Click New on the Preferences > Templates screen to open the New Template dialog that Figure 11 shows.



    Figure 11.     New Template Dialog


  • Enter the following information about your new template:

    • The template's name.

    • The template's scope: editor or module. If you select the module scope, your new template will appear in the selection list of templates when you create a new WLST script (see Figure 7).

    • A brief description.

    • A pattern on which to base the template. You can define a custom pattern, or select one from the list of predefined patterns by clicking Insert Variable.

  • Click OK to close the completed New Template dialog (see Figure 12).



    Figure 12.     Completed New Template Dialog


    Notice that your new template is now listed in the Preferences > Templates dialog, as Figure 13 shows.



    Figure 13.     New Template Listed


  • Click Apply > OK on the Preferences > Templates dialog.

5. Navigating MBean Structures

When writing WLST script, you often need to navigate WebLogic runtime MBean structures. OEPE enables you to view the MBean hierarchy in the Servers pane, as illustrated in Figure 14.



Figure 14. MBean Hieracrchy in the Servers pane


To add or generate WLST code from MBean Hierarchy:

  1. Open your WSLT file.
  2. Click the Servers tab to open the Servers pane.
  3. Start WLS by choosing Start from the context menu.
  4. In the Servers view, expand the MBean Hierarchy node.
  5. Right-click any child node and select Generate WSLT Code from the context menu.

    Note: This menu item is enabled only when the WSLT file is in focus.



6. Using WLST Console

You can launch WLST in interactive mode in the Console view. This allows you to manage the Oracle WebLogic Server life cycle, monitor the server status, and prototype WLST script using WLST commands in the command line.

You use WLST console, activate the Console tab, and then select WLST > Oracle WebLogic Server Version from the tab menu, as Figure 15 shows.



Figure 15. Creating New WLST File



WLST Console will display output similar to the following:




To interact with the server, type WLST commands. Figure 16 shows output produced upon entering help().



Figure 16. Interacting with Server Using WLST Console


To stop WLST, click Terminate on the Console menu.


7. Executing WLST

To execute the WLST script, right-click the file in the Project Explorer, and select Run As > WLST Run, as Figure 17 shows.



Figure 17. Executing WLST Script



WLST will be launched and the output displayed on the Console view.


8. Debugging WLST Script

To debug the WLST script, right-click the file in the Project Explorer, and then select Debug As > WLST Run, as Figure 18 shows.



Figure 18. Debugging WLST Script


WLST debugger will start and the output will be displayed on the Console view.

The Pydev debugger allows you to do the following:

  • set break point in the WLST source file;

  • step over;

  • examine variables using the Variables view.

Note that WLST script is executed with Jython interpreter in debug mode, as opposed to the weblogic.WLST interpreter.


9. Importing an Existing WLST Script into OEPE

If you import wlstModule into default name space using the from wlstModule import * statement, the global object cmo will not be available in this mode. You can work around this condition by either importing wlstModule with its own namespace:

import wlstModule as wl

or by creating a local cmo object from the return of cd() statement:

cmo=cd( MBEAN_PATH )

When importing existing WLST scripts into OEPE, be aware of the fact that Eclipse may flag WLST commands with "undefined variable" error.

To work around this problem, add following conditional import statement in the beginig of the file:

if __name__ == '__main__':
       from wlstModule import *

This statement is intended to help the builder to locate the WLST command. The wlstModule will be imported only when the script is executed with Jython interpereter.


10. Known Issues and Limitations

If you use WebLogic Server 9.2 on Windows Vista or Windows 7 operating system, you should avoid using Jython variable os.environ in your WLST script. Instead, you have to manually change the value of BEA_HOME and WL_HOME variables in the generated WLST script.


11. Related Information