13 Customization

This chapter describes customizations that can be made in the JavaTest harness appearance and function. Customizations not documented in this guide are described in the appropriate Javadoc tool (API) documentation.

While most of this guide describes customization, this chapter describes advanced customization beyond that usually required to configure and execute a test suite. In this chapter, topics discussed include:

Customization API
Internationalization
Customizing the Splash Screen
Customizing Menus
Customizing Toolbars

For architects, this chapter is most useful either after you have developed a basic version of a test suite and want to customize harness capabilities or as an overview to see exactly how much of the harness can be customized.

Customization API

Several sections in this chapter refer to methods present in the ContextManager API with many of the harness customization features described in this chapter controlled by the ContextManager class (com.sun.javatest.exec.ContextManager). The harness queries this class to determine if a particular feature is enabled and if it is necessary for the supporting classes or objects to realize the customization.

An architect can create a single custom ContextManager implementation class for their test suite and override any methods as needed. The only thing required inside a custom implementation of MyContextManager is overriding the appropriate methods for the customized features. No additional implementation is required beyond that provided by the base class. The base class is not abstract and the default implementation provides the default behavior intended for the harness.

Architects then provide the custom ContextManager class to the harness by adding a value as part of the TestSuite properties (see TestSuite.getTestSuiteInfo(String)). The property name that should be provided is tmcontext. This can be done programmatically in the TestSuite class, but is more easily accomplished by placing the value in the testsuite.jtt file (see Chapter 8) of the test suite. For example:

tmcontext=com.yourdomain.jtharness.MyContextManager

That class should be available to the harness in the classpath value that is also provided in the testsuite.jtt file. See Chapter 8 for more information about this file.

Note:

The classpath value in testsuite.jtt is a space separated value.

Internationalization

Many harness APIs refer to resource bundles (java.util.ResourceBundle) and String keys instead of raw strings for presentation. For example, in the JavaTestToolBar API the default implementation of getName() and getDescription() make it easier to provide a resource bundle instead of overriding the methods. The API documentation for JavaTestToolBar.getDescription() states:

Get the long description of this toolbar's purpose.
May be multiple sentences if desired. This is automatically
retrieved from the supplied resource bundle by combining it with 
the toolbar ID with getID(()), e.g. it will try to retrieve 
getId().tb.desc from the resource bundle.

In the custom code that the test suite provides, there will be a line of code which creates the toolbar, JavaTestToolBar. The constructors for that class require passing a ResourceBundle and a String key.

public JavaTestToolBar(ResourceBundle bundle, String resourceID)

Assuming that the code creating the toolbar (provided by the test suite) is in package foo.bar and is called MyContextManager, it is common in the harness to write code similar to the following example:

package foo.bar;
import com.sun.javatest.util.I18NResourceBundle;
class MyContextManager extends ContextManager {
    ... {
       toolbar = new JavaTestToolBar(i18n, "mytoolbar");
    }
    private static I18NResourceBundle i18n =
        I18NResourceBundle.getBundleForClass(MyContextManager.class);
}

This i18n object can then be reused throughout the lifetime of that custom context manager for any necessary purpose. In this case it is passed to the toolbar being customized.

Continuing with the code example and how JavaTestToolBar would use it, when getDescription() on that toolbar object is called by the harness, it attempts to retrieve getId().tb.desc from the resource bundle. In the example, the harness loads the string named mytoolbar.tb.desc from the file (on the classpath) foo/bar/i18n.properties. The content of foo/bar/i18n.properties might be:

# i18n file for package foo.bar
mytoolbar.tb.desc=This is my great toolbar for you to use.
mytoolbar.tb.name=My Tools

It is typical to provide each package with its own i18n.properties file and then use a single instance of I18NResourceBundle object within that package, passing it around as needed. See the java.util.ResourceBundle API documentation for more information about how it automatically resolves the name of the resource file to load and for the format of the entries in the bundle.

Customizing the Splash Screen

Instead of using the default JavaTest harness splash screen, architects can insert a custom test suite splash screen for users.

To use a custom splash screen, test suite architects must accomplish the following actions:

Insert a splash.properties file that specifies the custom splash image in the test suite lib/ directory (below javatest.jtt).

Refer to Example of splash.properties File" for the content and format of a splash.properties file.
Insert the splash image file in a location relative to the splash.properties file.

Acceptable image formats for the splash screen are GIF, JPEG and PNG.

Once the splash.properties and the splash image files are integrated in the test suite lib/ directory, the JavaTest harness will display the custom splash screen instead of the default when starting.

In the current implementation, the JavaTest harness displays the custom splash screen when users start the harness with -ts or -testsuite flags to specify the specific test suite. In the future additional flags might be used to start the harness with the custom splash screen.

Example of `splash.properties` File

The following is an example of the required format of the splash.properties file. In this example, the custom image name is splashMyProduct.gif.

# comment
splash.icon=splashMyProduct.gif

Notes About the Implementation

Because the splash screen must be capable of being internationalized, the testsuite.jtt file is not used to directly specify the splash screen. This capability of being internationalized requires that it should go through the standard ResourceBundle searching. The standard ResourceBundle searching is facilitated by using the splash.properties file. Other options for specifying the custom splash screen were not utilized because they increase the startup overhead of the harness by requiring it to perform additional file operations.

Customizing Menus

Test suite architects can customize the GUI menus in the Test Manager (ExecTool) by using the API provided by the harness. Common uses of this customization are to turn on and off frequently used test suite options or to trigger customized informational dialogs. The API provides limited access to the menu structure of the Test Manager, but relatively unlimited capabilities for the menu items themselves (such as the ability to insert multi-level menus, enable or disable a menu item, or provide a checkbox menu item). In addition, the popup menu available on the main test tree can also be customized.

Adding Menu Items to Test Manager Menus

Menu additions are managed by the JavaTestMenuManager (com.sun.javatest.exec.JavaTestMenuManager) provided by the ContextManager (com.sun.javatest.exec.ContextManager). The menu manager class provides an abstract class for the architect to populate. The most important part of the class are the set of constants that it defines. These constants define a set of logical positions within the Test Manager's menu structure. Instead of allowing the architect to determine the exact position of the menu items, which makes it virtually impossible to make future harness menu changes, the API defines the logical positioning with which the harness will determine the final position of a custom menu item.

The constants take the form of <logical menu>_<logical position>, such as HELP_ABOUT. If the architect wanted to add a menu item labeled About My Test Suite, they would use the HELP_ABOUT menu position. In the same manner, for the FILE_OTHER position, the architect would use file related label or a related label that logically belongs in a location on the File menu.

See the JavaTestMenuManager API documentation provided by the harness for detailed implementation information.

Adding Menu Items to the Tree Popup Menu

Similar to customizing the main Test Manager menus, the ContextManager must provide a class to manage the popup menu items. However, unlike the JavaTestMenuManager, it does not manage the position of items or serve as a container of multiple menus. Instead, JavaTestContextMenu represents a single menu item (in the Swing sense) that is activated on demand. The class manages the underlying JMenuItem and the rules for displaying that item.

Note:

This class assumes that the context menu is displayed in the context of a test folder or single test (such as a folder in the test tree or a test in the test tree). It cannot be used to insert context menus at other locations within the harness GUI and the availability of the custom menu items is limited to certain locations.

The most important considerations for this class are the rules for deciding whether or not to display the tree popup menu:

1) Is this menu item applicable to test entities, folders, or both?

2) Is the item applicable for cases in which multiple items (multiple tests for example) are selected?

For example, by using these rules, an architect can create popup menu items that appear only on tests, such as a menu item that says Configure Test. An architect can also create a menu item, such as Delete, that acts on homogeneous selection sets.

See the JavaTestContextMenu API documentation provided by the harness for more details.

Customizing Toolbars

The architect can add custom toolbars to the Test Manager, which are combined with the toolbars provided by the harness. The harness provides a default toolbar manager (com.sun.javatest.exec.ToolBarManager) which is suitable for most uses. Using either the default context manager or preferably a custom ContextManager (see Customization API), the toolbar manager is retrieved through the getToolBarManager() method. The API on this object allows the test suite to add and remove toolbars of the type com.sun.javatest.exec.JavaTestToolBar, which is a subclass of Swing's JToolBar.

On the JavaTestToolBar API, methods are provided that enable the harness to query the toolbar for its name, description and optional behavior. These methods enable the harness to automatically manage the toolbar, especially in the case of presenting menus which control visibility. Architects should pay attention to the internationalization practices that the harness enforces (see Internationalization). See the API documentation for JavaTestToolBar methods getId(), getDescription(), and getName().