IBM Research
 

WBI Graphical User Interface (GUI)

The WBI GUI has been part of the WBI Developement Kit since version 4.3. It provides a convenient way to manage and administer WBI, and to help you debug the plugins and megs you are writing.

Note: The GUI requires Java Swing, which is part of Java 2 SDK, but must be installed separately for older versions of the Sun JDK. The GUI also requires that IBM's XML 4 Java Parser (lib/xerces.jar) is in your CLASSPATH. The jar file is part of the WBI download and automatically added to the classpath when using one of the provided starting scripts (e.g., Run.bat, Run.sh).

Table of Contents

  1. Features
  2. WBI Configuration
  3. Controlling WBI
  4. Handling Plugins
  5. WBI Transaction Tracing
  6. Known Problems


Features

The WBI GUI is graphical user interface to WBI. It can be used to inform the user about WBI's activity and configuration.

The WBI GUI provides old features in a new look as well as several new features: A hierarchical view (tree) of WBI's current configuration shows registered sublayers, plugins and megs, and their respective settings. Read more ...

The tree is easily navigable and displays information about individual WBI components (e.g., plugins, megs and sublayers). This is the WBI Configuration view.

WBI Configuration View

It is divided into three parts: A tree view showing the hirarchical component structure of WBI (in the upper left part of the configuration view), a textual component display in the upper right, and the output display at the bottom.

Plugins can be registered, enabled, disabled and deregistered in a more convenient way. Learn how. The user can also suspend, resume and restart WBI as needed by selecting menu items.

Tracing and messaging can be easily configured through menus, allowing the user to control how much textual information about WBI's processing will be displayed. Read more ...

In addition to mapping the old WBI console interface to a windows and menu based graphical user interface, the WBI GUI also provides transaction tracing capabilities. WBI users and programmers can now easily see whether their megs are doing the right thing through the Request Processing view. Request Processing View:

Request Processing View

The Request Processing view is divided into three parts. At the left, there is a tree view showing the current transactions processed by WBI. The upper right represents the transaction header, and the lower right represents the transaction content . Learn more about the transaction tracing.

[Back to Table of Contents]


WBI Configuration

The WBI configuration view shows the current state of WBI. It lists WBI's components in a tree view, which can be navigated using the mouse or the keyboard.

Navigating the tree view

You can navigate the tree view with the mouse or the cursor keys. A double-click (or pushing right/left cursor key) on one of tree nodes will expand or collapse the subtree under the particular node. There are two nodes under the root of the tree (WBI).

Sublayers

The Sublayers information can be found by expanding the root node (WBI). Sublayers are protocol-specific, encapsulating information about how to process particular protocols. In the current development kit, the only node under the Sublayers represents the HTTP sublayer.

Plugins

The Plugins node is the entry point for all registered plugins and their megs. When a plugin-node is selected, information about the plugin is displayed at the right, showing the plugins state (e.g., loaded and enabled/disabled) and listing the associated megs by name. Read more on how to enable, disable, register and deregister plugins.

Megs

Under the plugin node, all associated megs are represented by individual nodes. By selecting one of the meg nodes, information about the megs will be displayed (e.g., condition, priority, name). Check for information how to track what megs do during transaction processing.

[Back to Table of Contents]


Controlling WBI

The WBI GUI allows the user to control WBI's current state. Click on the File menu and select any of the following items:
  • Suspend will turn off meg processing. The proxy will stop listening for requests. To turn the proxy back on, choose Resume from the File menu.
  • Resume will turn a suspended proxy back on.
  • Restart should be used when the proxy seems to be stuck. Selecting this option will unload, reload, and reinitialize all registered plugins.
  • Clear output window allows you to reset the output buffer. This buffer is diplayed in the lower part of the configuration view. The buffer is used for textual output.

In addition to these, the Command menu offers several options to control WBI. You can choose between Tracing, Messaging, Show pending requests and Show version. All these options force (or block) output to the output buffer at the bottom the configuration view. The options Tracing and Messaging offer submenus that let the user select how much textual or tracing output appears.

  • Tracing options:
    1. No messages - Tracing output will be suspended.
    2. All messages - Verbose tracing output.
    3. Error Exceptions - Tracing output is related to errors and exceptions during transactions.
    4. Meg Routing - Tracing output is associated with the meg processing. Displays information about which megs were selected and rejected during processing. To view what each meg does during processing, you may want to switch to the transaction tracing view.
  • Messaging options:
    1. No messages - Messaging output will be suspended.
    2. All messages - Verbose messaging output.
    3. Errors - Messaging output is related to errors during transactions.
    4. Warnings - Messaging output is related to warnings issued by the proxy.
    5. Informational - Messaging output is related to informational messages issued by the proxy.

[Back to Table of Contents]


Handling Plugins

Plugins can be enabled, disabled, registered, and deregistered. The Plugins menu in the menu bar enables the user to select these actions. These can only be performed when the WBI Configuration is the active view. To switch to the configuration view, click on the tab with the label WBI Configuration.

Register a plugin

Registering a plugin means loading it into WBI such that its megs can take part in transactions. Click on the Plugins menu and select Register .... This will bring up a file -selection dialog. Pick a WBI plugin registration file with the extension *.reg and press OK. The loaded plugin will appear in the WBI configuration view as plugin node.

Deregister a plugin

To remove a plugin from WBI --- that is, to stop a plugin from processing transactions --- click on the Plugins menu and select Deregister .... If any plugins are currently registered, a dialog box will appear, providing a dropdown list of the registered plugins. The user can choose to deregister All plugins or any individual plugin. After clicking OK, the selected plugin(s) are unloaded from WBI and removed from the plugin tree in the configuration view.

Disable a plugin

Sometimes it is necessary or helpful to test a particular plugin by itself. The WBI GUI allows the user to disable any currently registered plugins. Click on the Plugins menu and select Disable .... This will bring up a dialog that shows a list of all the registered plugins that are loaded and enabled. Choose an indivdual plugin or all plugins and press OK. The selected plugins will be disabled. Clicking on a node that represents a disabled plugin now shows that it is indeed disabled.

Enable a plugin

You can also bring plugins back to life by clicking on the Plugins menu and selecting Enable .... This will bring up a dialog with a list of all currently disabled plugins. If all the plugins are enabled, a message window will tell you so (close the window by acknowledging the message and you can continue).

Since version 4.4 of the WBI development Kit the functionality of enabling, disabling or deregistering a plugin is also provided through a popup menu. The popup menu can be activated by performing a right mouse click on a plugin entry in the WBI configuration tree.

[Back to Table of Content]


WBI Transaction Tracing

Transaction Tracing is a new feature of the WBI GUI. It allows the user to track what's going on during a transaction. In many cases, especially when things aren't going smoothly, it is helpful to see what individual megs did during a transaction. The Request Processing view allows you to keep track of such things.

Transaction tracing can be turned on and off by selecting:

Requests -> "Request Tracing enabled"

from the WBI GUI menu bar.

When transaction tracing is enabled, the Request Processing view displays information about the individual transactions in a tree-like structure at the left.

The tree shows the transactions hierarchically, displaying which megs were involved in the particular transaction, and what exactly the megs took as input and what exactly they produced as output. When you click on the input/output nodes, the transaction header and content are displayed in the two views at the right.

The lower right displays part of or all of the transaction content. This can be configured by selecting

Requests -> "Displayable Content Length"

and then selecting one of the options in the submenu. This allows the user to maintain control over the processing overhead at runtime, as often it is not necessary to look at all the content. The content can be displayed as binary data or as text data depending on the content type of the transaction content. (The WBI GUI automatically detects the content type.)

Since many HTML pages contain links to lots of images or stylesheets, all of these items are requested by a browser and therefore listed as a request in the viewer. Using this option makes the request tree much clearer and easier to debug. By chosing

Requests -> "Request Blocking"

and then checking or unchecking one or more of the choices the user can turn off request tracing for certain content types (e.g. GIF images or JPEG images).

The request processing view displays up to 100 requests in the tree view and then clears itself, keeping the last 20 transactions in the tree. The user can manually clear the tree view by selecting

Requests -> "Clear Request View"

or using the keyboard shortcut CTRL-C.

[Back to Table of Contents]


Known Problems

Request Processing View
We have noticed that in very few cases of forwarded requests that the WBI GUI does not display the Meg Input and Meg Output nodes in the right location, such as:

     WBI Requests
       |
       |____ <request number>: <request id>
         |
         |____ Meg: <meg name>
           |
           |____ Meg Input
           |
           |____ Meg Output
           |
           |____ Meg Output
           |
           |____ Meg: <meg name>
             |
             |____ Meg Input

What appears to be a bug in WBI is purely a presentation error. When a meg forwards a request the correct presentation would be the following:

     WBI Requests
       |
       |____ <request number>: <request id>
         |
         |____ Meg: <meg name>
           |
           |____ Meg Input
           |
           |____ Meg Output
           |
           |____ Meg: <meg name>
             |
             |____ Meg Input
             |
             |____ Meg Output

We are investigating this problem and provide a patch for the GUI as soon as possible.

WBI GUI, JDK and Swing
The WBI GUI is based on Swing. Depending on the Java Development Kit (JDK) version you are using, you may be required to take extra actions in order to run and use the WBI Gui.
If you are using the JDK version 1.2 or newer, the Swing classes are already part of the JDK and everything should be fine.
For earlier version of the JDK you need to download the separate Swing package and add the jar file Swingall.jar to your classpath, for example, on Windows systems:

set classpath=%CLASSPATH%;Swingall.jar

XML 4 Java Parser
The WBI GUI also requires an XML parser. We are currently shipping a XML 4 Java parser (Xerces, version 3.0.) with the WBI Development Kit version 4.5. No other version of the parser will work with WBI DK 4.5. We provide the necessary jar file (lib/xerces.jar) as part of the download. Make sure that this jar file is part of your classpath when you do not use the provided startup scripts (e.g., Run.bat or Run.sh).

Repaint Problems on Windows 95/98
We have seen repaint problem on some Windows 95/98 systems. After clicking on menus or buttons, the application's windows are not repainted properly. This is a known bug in Java (bug number 4196958) --- see Sun's Java Developer Connection for more information. In any event, there are several fixes:
  • Windows 98: Add the following command line option when launching WBI:
    -Dsun.java2d.noddraw
    (to use this as a default on Windows 98 systems, we advise you to modify the Run.bat file.)
  • Windows 95: The Windows 98 solution does not always do the trick on Windows 95 systems, especially when you are using special cursors (Microsoft Plus!). To fix the repaint problem, turn off the special cursors and use the default.

[Back to Table of Contents]