0% found this document useful (0 votes)
40 views

Code Coverage

Uploaded by

Saly Abdmalik
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
40 views

Code Coverage

Uploaded by

Saly Abdmalik
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 66

User’s Guide

Optimizeit ™

Code Coverage 1.5


for Java™
Borland Software Corporation
100 Enterprise Way
Scotts Valley, California 95066-3249
www.borland.com
Borland Software Corporation may have patents and/or pending patent applications covering subject
matter in this document. Please refer to the product CD or the About dialog box for the list of
applicable patents. The furnishing of this document does not give you any license to these patents.
COPYRIGHT © 1997–2003 Borland Software Corporation. All rights reserved. All Borland brand and
product names are trademarks or registered trademarks of Borland Software Corporation in the
United States and other countries. All other marks are the property of their respective owners.
For third-party conditions and disclaimers, see the Release Notes on your Borland product CD.
Printed in the U.S.A.
oi60cc 4E3R1003
0304050607-9 8 7 6 5 4 3 2 1
PDF
Contents
Chapter 1 Chapter 5
Getting Started 1 Using Method Coverage 31
When to use Code Coverage . . . . . . . . . . .1 Method Coverage window options . . . . . . . 32
Installing Code Coverage . . . . . . . . . . . . .2 Controlling the test program . . . . . . . . . . 33
Using the virtual machine wizard. . . . . . . .3 Mark and Inspector options . . . . . . . . . . . 33
Integrating Optimizeit with other tools . . . . . . .3
Running Code Coverage . . . . . . . . . . . . .4 Chapter 6
Reporting features 35
Chapter 2 Generating snapshots . . . . . . . . . . . . . 35
Defining your test program 5 Merging snapshots . . . . . . . . . . . . . . . 36
Using the Startup page . . . . . . . . . . . . . .6 Generating reports . . . . . . . . . . . . . . . 38
Choosing your program type . . . . . . . . . .7 Generating a report from within
Choosing your program location . . . . . . . .7 Code Coverage . . . . . . . . . . . . . . 38
Choosing operation options . . . . . . . . . .8 Generating a report from the
Choosing extra Java or command line . . . . . . . . . . . . . . . 39
program parameters . . . . . . . . . . . . .8 Exporting data . . . . . . . . . . . . . . . . . 40
Choosing your class path and source path . .8 Displaying console messages . . . . . . . . . 41
Using the Filters tab . . . . . . . . . . . . . . . .9
Using the Virtual Machines tab . . . . . . . . . 12 Chapter 7
Adding a virtual machine . . . . . . . . . . . 12 Setting your preferences 43
Setting virtual machine properties . . . . . . 13 Selecting default displays . . . . . . . . . . . . 43
Setting launch parameters . . . . . . . . . . . 44
Chapter 3 Setting the source code location . . . . . . . . 45
Running Optimizeit from the Changing the default source path . . . . . . 45
command line 15 Changing the class path . . . . . . . . . . . . 46
Starting from the command line . . . . . . . . . 15 Selecting a virtual machine . . . . . . . . . . . 47
Setting up the audit system . . . . . . . . . 16 Configuring servlet support . . . . . . . . . . . 48
Launching your program . . . . . . . . . . . 16
Windows audit system options . . . . . . . . 17 Chapter 8
UNIX audit system options . . . . . . . . . . 18 Troubleshooting 49
Connecting the audit system . . . . . . . . . 21 Starting your application . . . . . . . . . . . . 49
Starting on a different machine . . . . . . . . . 22 Starting your application server . . . . . . . . . 53
Using the Filter Editor . . . . . . . . . . . . . . 22 Problems during testing . . . . . . . . . . . . . 55
Starting from the test program . . . . . . . . . 25 Undoing an integration (Windows only) . . . . . 58
Adding API calls in your program . . . . . . 25
Starting your test program . . . . . . . . . . 26 Index 59
Chapter 4
Using Class Coverage 27
Controlling the test program . . . . . . . . . . . 29
Mark and Inspector options . . . . . . . . . . . 29

i
ii
Chapter

Getting Started
Chapter 1

Optimizeit Code Coverage software is a Java performance tool that enables


developers to find out precisely which part of their Java code is executed, right
down to the exact line of source code.
The following sections introduce Code Coverage and describe how it is
installed and run:
■ “When to use Code Coverage”
■ “Installing Code Coverage”
■ “Integrating Optimizeit with other tools”
■ “Running Code Coverage”

When to use Code Coverage


When code is developed over time by several developers, portions of code
and sometimes whole methods are no longer used, but remain dormant in the
code. This type of dead code makes an application longer and more difficult to
understand. Optimizeit Code Coverage makes locating dead code easy so
that you can clean-up and simplify your application. Clarity of code makes it
easier to read and more reusable.
Code Coverage also makes it easy for you to identify how much of your code
has been tested by highlighting all tested code. Understanding exactly which
classes, methods, and lines of code have not been used allows you to modify
your test plan to cover all areas of the code.

Ch ap te r 1: Get ting St arte d 1


I n s t a l l i n g C od e C o v e r a g e

Optimizeit Code Coverage lets you test applications, applets, servlets,


JavaBeans, Enterprise JavaBeans (EJBs), JavaServer Pages (JSPs), and
virtually any other Java code. Code Coverage is plug and play: there is no
need to recompile your program with a custom compiler or to modify class files
before execution. You can run your test from within Code Coverage, or you
can run testing sessions from the command line.
When you invoke your program from Optimizeit Code Coverage, the user
interface connects to the audit system running in the test application’s virtual
machine and begins providing real-time test information. Code Coverage
shows this information two ways: class coverage and method coverage. For a
description of class coverage mode, see Chapter 4, “Using Class Coverage.”
For a description of method coverage for a particular class of interest, see
Chapter 5, “Using Method Coverage.”

Installing Code Coverage


To install Optimizeit, load your Optimizeit CD. Written installation instructions
are located in the install.html file in the root directory of the CD. Optimizeit
does not support directories with spaces in the name (for example, Program
Files), so make sure there are no spaces in your installation directory name.
Make sure your software and virtual machine are supported. Refer to the
Release Notes for a complete listing of supported platforms and VMs.
Important Make sure you have installed the latest current release with all current patches
for your OS and JDK version; for example, there are some problems using
JDK version 1.3.1_02 that do not appear when JDK version 1.3.1_09 or JDK
1.4.2 are used.
If you are installing the Optimizeit Suite, you will be installing all three
Optimizeit tools, Profiler, Code Coverage, and Thread Debugger, at once. All
three tools share the same setting files and the same IDE and application
server integrations:

Because all three tools share the same settings, you can load any
Optimizeit setting file into any Optimizeit tool. For example, you can create
some classpath, source path, and virtual machine settings in Profiler, save
them, and then use these same settings with Thread Debugger.
■ If you integrate any Optimizeit tool with an IDE or an application server, all
three tools will be immediately ready to use those environments, without
any further configuration.
■ On Windows platforms, the Audit System Selector option places an icon on
your toolbar that allows you to easily switch between the three tools.
The Optimizeit root directory also contains Release Notes. These Release
Notes list added platforms and Java development environments, and describe
a subset of known problems, workarounds, and tips for Optimizeit.

2 Co de Co ver ag e Use r’s Guide


In teg ra tin g Op timize it wit h o the r too l s

Using the virtual machine wizard


By default, Optimizeit uses a Java 2 runtime. When Optimizeit is installed, a
default JRE version 1.4.2 is also installed, but as shown in the table above,
Optimizeit is compatible with many Java virtual machines.
The first time you run Optimizeit, a Java setup wizard starts automatically to
help you select a virtual machine:

Note You can also access this wizard at any time from Tools|Java Setup.
1 If you want to use the default JRE, click Cancel, and the wizard returns you
to Optimizeit.
2 If you want to configure Optimizeit to use a different virtual machine, click
Next.
3 Select the directory where you want the wizard to search for available
virtual machines. The wizard scans the selected directory or drive and lists
all available virtual machines.
Tip After you see the message Found 1 virtual machine you can click Stop to
end the scan.
4 Select the virtual machine you want to use.
5 Click Next, then click Finish.
6 After changing the default virtual machine, Optimizeit prompts you to
confirm that the new default virtual machine should be used with the current
settings. Click Yes to start using that virtual machine.

Integrating Optimizeit with other tools


As described in Chapter 2, “Defining your test program,” you can specify and
start test sessions from the Optimizeit user interface without integrating with a
web server or application server. However, to run Optimizeit from the
command line and take advantage of offline profiling you must integrate with
the Java tool used to run the application you are testing. Integration wizards

Ch ap te r 1: Get ting St arte d 3


Ru nn ing Co de C overag e

are provided for all supported web and application servers. However, since
Optimizeit can be integrated with most application servers that use compatible
virtual machines, integration instructions are provided for manually integrating
Optimizeit with a variety of different servers.
Optimizeit also integrates with several integrated development environments
(IDEs) to help speed application development and test cycles.
See the Release Notes for a list of supported web and application servers, and
IDEs, and refer to the Optimizeit Integration Guide for integration instructions
and additional information. If you have trouble integrating your tool, see
Chapter 8, “Troubleshooting.”

Running Code Coverage


Once Optimizeit is installed, you must enter your test program information so
that Optimizeit can locate the application, applet, or servlet to be tested, and
can test the appropriate areas:
■ If you have never used Optimizeit before, or have never created your own
Settings file, start with Chapter 2, “Defining your test program.”
■ If you know about settings files but need to learn how to start a test from the
command line, go to Chapter 3, “Running Optimizeit from the command
line.”
Note Each chapter builds on the information contained in the previous chapter.
Review previous chapters before beginning a new chapter, and do not skip
chapters unless you are familiar with the procedures.
To run Optimizeit Code Coverage:
1 By default, Code Coverage starts in class coverage mode, as described in
Chapter 4, “Using Class Coverage.”
2 To analyze method coverage for a particular class of interest, switch to the
method coverage, as described in Chapter 5, “Using Method Coverage.”
3 To store and analyze your coverage data, use the reporting functions
described in Chapter 6, “Reporting features.”
4 Make changes to your source code and repeat these steps until you are
satisfied with your program’s performance.
From within Code Coverage, use the menu items described in Chapter 7,
“Setting your preferences,” to choose your startup window, your default source
and class paths, and other defaults.
If you have trouble integrating or using Code Coverage, see Chapter 8,
“Troubleshooting.”

4 Co de Co ver ag e Use r’s Guide


Chapter

Defining your test program


Chapter 2

When you first start Optimizeit, it opens the Edit Settings dialog box:

Use the Settings dialog box to modify your source path, class path, filters (if
any), and virtual machines. This dialog box is a centralized location for many
configuration items, which is convenient if you are testing a program from
within the Optimizeit user interface. You can also access the Settings dialog
box with the following File menu commands:

C ha pt er 2 : D ef i ning yo ur t est prog ra m 5


Usin g t he St artu p p ag e

■ File|New —opens a new settings dialog box, with only the Optimizeit
defaults specified.

File|Open —allows you to browse for a settings file to use.

File|Open Recent —displays a list of recently accessed settings files
(generated by any Optimizeit tool) for you to choose from.
■ File|Settings—opens the current settings file, which you can either run
again or edit to run a new test.
The Settings dialog box contains the following pages:
■ Startup—this page contains the required elements for your configuration,
such as the program type, location, Class path and Source path.

Filters—if there are specific packages or classes you wish to test or ignore,
use the Filters page.
■ Virtual Machines—by default, Optimizeit tests with a Java 2 runtime. If you
want to specify a virtual machine other than the default, use the Virtual
Machines page.
Once you have configured the settings, you can save this configuration in a file
when you exit Optimizeit. By default, information from the last-saved settings
file is automatically loaded into Optimizeit when you open the program. The
same settings file can be used in Optimizeit Profiler, Code Coverage, or
Thread Debugger. Use the Save and Open commands on the File menu to
save settings files and access existing ones.

Using the Startup page


This section describes how to fill out the Startup page of the Settings dialog
box in Optimizeit. The Startup page lets you specify the following settings for
testing:
■ Program type
■ Program location and working directory

Operation options

Extra Java or program parameters

Class path and source path
Once you have filled out the Startup tab, if you want to use the default virtual
machine and filters, click Start Now to begin testing. Optimizeit starts the
application and opens the default view.

See also
■ Chapter 7, “Setting your preferences,” for more information about setting
defaults.

6 Co de Co ver ag e Use r’s Guide


Usin g th e St artu p pa ge

Choosing your program type


The first option on the Startup tab of the Settings dialog box is to choose your
program type:
■ Click Application to test a Java application. Continue by choosing your
program location.
■ Click Applet to test an applet. Continue by choosing your program location.
■ Click Servlet/JSP to test a servlet or JSP. If this is the first time you have
tested a servlet with Optimizeit, the servlet wizard will start. The wizard will
guide you through the servlet configuration; see “Configuring servlet
support” on page 48 for more information. Continue by choosing your
program location.
■ Click Remote Application to test a Java application that is started from the
command line or that is located on another machine.

See also

“Connecting the audit system” on page 21 for remote testing instructions.

Choosing your program location


What you enter in the location field depends upon what you are testing:

For an application, Optimizeit expects a Program Main Class Or JAR File:

If the application is packaged in a JAR file, click Browse to select the
JAR file location.
Note To run an application from a JAR file, the .jar file of the JAR-packaged
application must have a manifest file that includes a main-class attribute.
See the Sun Microsystems Java web site for more information on JAR-
packaged applications.
■ If the application is in a ZIP file, enter the fully qualified name of the class
containing the Main method. For example:
com.reg.bar.Main

If the application is not in a JAR or ZIP file, click Browse to select the
class file that contains the main method.
■ For an applet, Optimizeit expects an Applet HTML File or URL. If the applet
is on your local disk, click Browse and select the HTML file. If the applet is a
web page, enter the URL of that page.

For a servlet, click Browse to choose the class file that contains your
servlet.
The Program working directory field is not required; you only use it if your test
points to a specific working directory.

C ha pt er 2 : D ef i ning yo ur t est prog ra m 7


Usin g t he St artu p p ag e

Choosing operation options


The Startup tab contains options to configure the behavior of your test
program on startup:
■ Generate snapshot on exit generates a snapshot when the System.exit()
method is called in the virtual machine.
■ VM Cannot Exit disables the method System.exit() in the virtual machine.
Use this option to test a command line program such as a compiler that
performs a task and then exits the running virtual machine. Use the Stop
button to exit the program when your testing session is complete.
■ Open A Console opens a console window for the program when the testing
session begins. Use this option if your program expects some input from
System.in. When this option is off, anything printed using System.out and
System.err is printed in the Optimizeit console.

Choosing extra Java or program parameters


The Extra Java Parameters and Extra Program Parameters fields are optional:

Extra Java Parameters specifies a string passed directly to the virtual
machine running the test program. Use this field to add Java virtual
machine arguments such as -Xms256m or -verbosegc.

Extra Program Parameters specifies a string passed directly to the tested
application when launched. This option is not applicable for applets.

Choosing your class path and source path


If the application requires special classes not indicated in the default CLASSPATH,
click Change under the Class Path window to choose and add the directories,
JAR files, or ZIP files containing the extra classes. You can also enter a multi-
entry class path, such as c:\classes;d:\project\xmlParser.jar in the empty
field. These additions apply only for the current test program.
The Source path lists the directories where Optimizeit will search for source
code. If you want Optimizeit to highlight relevant source code, you may need
to add your source code directories, ZIP files, or JAR files to the source path.

8 Co de Co ver ag e Use r’s Guide


Using the Filters tab

To add or change the source code location, click the Change button to bring
up the Source Path Chooser dialog box.

Use this dialog box to add, delete, and organize your source paths. Use the
browser to search for a specific directory or file, or use the empty field under
the browser if you have a multi-entry source path, such as c:\src;d:\project\
src.jar. Enter your full path information into the field. Specific files can also be
added later during the testing session. These additions apply only to the
current test program.

See also

By default, the Class Path dialog box contains the default class path as
defined by your CLASSPATH variable. This default can be changed using the
Preferences menu; see “Changing the class path” on page 46 for more
information.

By default, the Source Path dialog box is blank or contains the source path
defined using the Preferences menu; see “Setting the source code location”
on page 45 for more information.

Using the Filters tab


Filters are sets of patterns that define the packages or classes either grouped
or ignored by Optimizeit Code Coverage.
For Code Coverage, there are 2 types of filters: exclusive filters and inclusive
filters:
■ Exclusive filters specify which packages or classes should not be tested.
This allows you to test everything but specified packages or classes. For
example, by default Optimizeit Code Coverage uses exclusive filters to filter
out java base classes. The patterns for those classes are: java.*, javax.*,
and sun.*. This means that every class name that begins with java. or
javax. or sun. will not be tested.

C ha pt er 2 : D ef i ning yo ur t est prog ra m 9


Using the Filters tab

■ Inclusive filters specify which packages or classes should be tested;


everything else is filtered out. For example, an inclusive filter with the single
pattern com.borland.* will cause Optimizeit to report only the test information
for the classes with a name starting with com.borland.
Note Only one type of filter (inclusive or exclusive) can be used at a time.
Filters are very convenient for testing servlets, EJBs and JSPs. In that context,
they can be used to remove or group in one call the resources used by the
application server, allowing you to focus on your Java code.
Optimizeit provides several filters ready to use, including filters dedicated to
many application servers. The filters provided by Optimizeit are read-only. You
can only modify and delete the filters you have created.
Note Filters only remove information about resources used by code matching the
filter pattern. Filters don’t remove information about methods invoked from
filtered methods. If a filtered method calls an unfiltered method that allocates
an instance, this instance won’t be filtered. If a filtered method invokes a
method that consumes CPU time, this CPU time won’t be filtered. For
example, you can set the filter for all Jakarta Tomcat objects, but when you
read your test results you may still find Jakarta objects if these objects were
created by other methods not affected by your filters. You should not see any
filtered packages with a red star or clock next to them in a Hotspot or
Allocation View.
This section describes how to set up filters for Optimizeit using the Filters tab
on the Settings dialog box. Filters are only applicable for Profiler and Code
Coverage.
1 Start Optimizeit to open the Edit Settings dialog box by default. If Optimizeit
is already started, or opens with a different dialog box:
■ Choose File|New Settings to start a new settings file,
■ Choose File|Open Settings or File|Open Recent Settings to locate a
previous settings file to modify, or
■ Choose File|Edit Settings to edit the current configuration.

10 Co de C ove ra ge Use r ’s Guid e


Using the Filters tab

2 Click the Filters tab on the Settings dialog box to open the Filter Editor:

3 To use inclusive filters, click Include Only. If you want to use exclusive
filters, click Exclude.
4 To add a pattern, click New. The Pattern Editor dialog box opens:

5 Enter your pattern in the box and click OK. Both the asterisk wildcard
character (*) and the not character (!) are supported. Your pattern can
define packages, classes, or methods. When you are done with this pattern
click OK.
6 Remove a pattern by highlighting it in the list and clicking Delete.
7 Edit a pattern by highlighting it in the list and clicking Edit Pattern. This
opens the pattern editor.
8 When you are done with your filter selection, click on the Virtual Machines
or Startup tabs, or click Start Now to begin your test. Click OK if you just
want to save your information.
Note If you select more than one filter for a test run, Optimizeit always performs a
logical OR of all the filters you have selected. Any top-level package, class, or
method that meets any of the filter criteria is filtered.

C ha pte r 2: D efin i ng you r te st p r ogr a m 11


U s i n g t h e V i r t u a l M ac h i n e s t a b

See also
■ “Using the Filter Editor” on page 22 for instructions on using the Filter Editor
executable when testing a remote application. This executable operates
outside the Optimizeit user interface.
Custom filters are part of Optimizeit configuration files. They are saved and
loaded when using Save and Open commands from the File menu.

Using the Virtual Machines tab


At any time, you can change the virtual machine or add a virtual machine
using the Virtual Machines tab on the Settings dialog box:

The main panel lists all of the virtual machines Optimizeit recognizes on this
computer.

Adding a virtual machine


To add virtual machines to the list of machines available for Optimizeit:
1 Click Add Virtual Machines. This starts the virtual machine wizard.
2 Click Next.
3 Select the directory where Optimizeit should begin the search for available
virtual machines.
4 Click Search. Optimizeit displays the virtual machines found.
5 Click Finish to add these virtual machines to the list of available virtual
machines.

12 Co de C ove ra ge Use r ’s Guid e


Usin g t he V i rt ua l Mach ines t ab

Setting virtual machine properties


The Virtual Machine Properties are settings that may or may not be activated,
depending upon what type of virtual machine you are using. When you select
a virtual machine from the list, Optimizeit only enables the available options for
that virtual machine. For example, JRE 1.2 does not have a Hotspot
implementation, so the Hotspot option for Java runtime will not be available if
you have that JRE selected.
The Java Runtime option sets the virtual machine runtime used. The following
table shows which flag is added to the virtual machine invocation:

Option Flag added Description


Default No flag added The virtual machine uses its default runtime.
Classic -classic Optimizeit forces the virtual machine to use its
classic runtime.
Hotspot -hotspot Optimizeit forces the virtual machine to use its
Hotspot runtime.

If you want to use a JIT (Just In Time compiler) when testing, check that
option.
If you aren’t sure which options to use, or you want to return to your defaults,
click Use Default Settings.
Once you have configured the Settings dialog box to start your application,
you can save this configuration in a file when you exit Optimizeit. By default,
information from the last-saved settings file is automatically loaded into
Optimizeit when you open the program. The same settings file can be used in
Optimizeit Profiler, Code Coverage, or Thread Debugger. Use the Save and
Open commands on the File menu to save settings files and access existing
ones.

C ha pte r 2: D efin i ng you r te st p r ogr a m 13


14 Co de C ove ra ge Use r ’s Guid e
Chapter

Running Optimizeit from the


Chapter 3

command line
This chapter describes how to start, run, and configure Optimizeit from outside
the Optimizeit user interface. In addition to running your test program from
within Optimizeit, you can also run it from a command prompt.
Invoking your application from outside the Optimizeit user interface allows you
to do the following:
■ Set custom variables
■ Run the application as part of a script
■ Run the program on a different machine

Starting from the command line


To test your program from a command prompt:

Set up the Optimizeit audit system.

Launch the Optimizeit audit system, specifying your test program.

Start your selected Optimizeit tool and connect the audit system to the
Optimizeit user interface.
These steps are described in the following sections.

Ch apt er 3 : Ru nnin g Optim i ze it from th e co mm and line 15


Sta r ti ng fr o m t he c om man d l in e

Setting up the audit system


To use the Optimizeit audit system, you need to modify your environment
variables to make certain Optimizeit files available on the CLASSPATH and the
search path for libraries.
To do this on Windows,
1 Go to the directory where you have Optimizeit installed.
In this example, it is <OptItDir>.
2 Open a command prompt.
3 Set your PATH to include the Optimizeit lib directory:
set PATH=<OptItDir>\lib;%PATH%
4 Set your CLASSPATH to include the Optimizeit optit.jar file:
set CLASSPATH=<OptItDir>\lib\optit.jar;%CLASSPATH%
To do this on UNIX,
1 Enter the directory where you have Optimizeit installed.
In this example, it is <OptItDir>.
2 Open a command prompt.
3 Set your LD_LIBRARY_PATH to include the Optimizeit lib directory:
export LD_LIBRARY_PATH=<OptItDir>/lib:$LD_LIBRARY_PATH
4 Set your CLASSPATH to include the Optimizeit optit.jar file:
export CLASSPATH=<OptItDir>/lib/optit.jar:$CLASSPATH

Launching your program


The Optimizeit audit system is a set of Java classes and native code. There
are two methods for launching the audit system: as a command or as a
command option.

To launch the audit system using the command option, use one of the
following arguments:
-Xruncci:startAudit=t
or
-Xruncci -Xbootclasspath/a:<OptItdir>\lib\oibcp.jar
intuitive.audit.Audit
Either command structure is valid. The first option allows you to append
Optimizeit start options directly to the -Xrun command using a colon. You
can add more than one option, as long as they are separated by a comma.
The second option includes -Xbootclasspath because -Xbootclasspath is a
Virtual Machine start option. In an Optimizeit command, the Virtual Machine
options must come before the Optimizeit options unless the Optimizeit
options have been appended to the -Xrun command with a colon.

16 Co de C ove ra ge Use r ’s Guid e


S ta rt i ng f r om t he comm an d line

■ To launch the audit system as a separate command, enter the following on


the command line:
On Windows:
java intuitive.audit.Audit
On UNIX:
java intuitive.audit.Audit
Note Only use one of these options in a command. If a command contains both
startAudit=t and intuitive.audit.Audit, the system returns an error message
that the audit system or port is already in use.
If you launch the audit system as a separate command, Optimizeit returns a
list of all the audit system start options. The output depends upon your
platform and which JDK version you are using. The following tables list all
available options.

Windows audit system options


The following tables list the audit system invocation options on Windows
platforms. There are two types of start command options: Virtual Machine and
Optimizeit. The VM options go before the intuitive.audit.Audit specification in a
command, and the Optimizeit options follow the audit system invocation.
Note Some command options are only available on specific JDK versions.

Table 3.1 Windows audit system Virtual Machine start options


Option Description
-classic JDK 1.2 and 1.3 only. Forces Classic runtime.
-Xruncci Starts the Optimizeit Code Coverage JVMPI
agent. You must also add a filter file specification
as shown in the examples below.
-Xrunoii Starts the Optimizeit Suite JVMPI agent. This
option is only available if you have Optimizeit
Suite installed. All Optimizeit command options,
including those that are tool-specific, can be used
with -Xrunoii.
-Xbootclasspath JDK 1.2 and newer only. Appends Optimizeit
/a:<OptItdir>\lib\oibcp.jar classes to the boot classes. Replace <OptItdir>
with the directory where you installed Optimizeit.

Table 3.2 Windows audit system Optimizeit start options


Option Description
[-startAudit] Starts the Optimizeit audit system. startAudit=t
[-intuitive.audit.Audit] or intuitive.audit.Audit is required in a
command.
[-port portNumber] Specifies the port you want to use for the
communication link between the Optimizeit audit
system and the Optimizeit user interface.

Ch apt er 3 : Ru nnin g Optim i ze it from th e co mm and line 17


Sta r ti ng fr o m t he c om man d l in e

Table 3.2 Windows audit system Optimizeit start options (continued)


Option Description
[-snapshotonexit] Generates a snapshot when the virtual machine
exits.
[-noexit] Disables the System.exit() method in the virtual
machine. This prevents the tested application
from exiting the virtual machine. The default is f.
[-filter] Specifies the filter file that Optimizeit will use for
this test. The format of the filter specification is
filter=<filter>, where <filter> is the name of
(and path to) a filter (.oif) file. Filter
specifications are required.
[-enableAPI] Enables the audit system API. When the API is
enabled, the Optimizeit tools are disabled. The
audit system waits for the test program to enable
the Optimizeit tool from Java.
[-auditOption] Specifies audit system options that are listed in
an ASCII file. The format of the file specification is
auditOption=<filename>, where <filename> is the
complete path to file containing the audit system
options. This file can contain all the Optimizeit
audit system options. Only one option is allowed
per line. The same option file may be used for
different tests.
Note: When this option is used, OISelector
settings are overridden.
[ClassName] The main class for the test program. If the test
program is an applet, use
sun.applet.AppletViewer and then add the path
of the applet HTML file or URL.
Note: With Code Coverage, you must use
oldjava instead of java to run an applet.

UNIX audit system options


The following tables list all the audit system invocation options on UNIX
platforms. There are two types of start command options: Virtual Machine and
Optimizeit. The VM options go before the intuitive.audit.Audit specification in
a command, and the Optimizeit options follow the audit system invocation.
Note Some command options are only available on specific versions of JDK.

Table 3.3 UNIX audit system Virtual Machine start options


Option Description
-classic JDK 1.2 and 1.3 only. Forces Classic runtime.
-Xruncci Starts the Optimizeit Code Coverage JVMPI
agent. You must also add a filter file specification
as shown in the examples below.

18 Co de C ove ra ge Use r ’s Guid e


S ta rt i ng f r om t he comm an d line

Table 3.3 UNIX audit system Virtual Machine start options (continued)
Option Description
-Xrunoii Starts the Optimizeit Suite JVMPI agent. This
option is only available if you have Optimizeit
Suite installed. All Optimizeit command options,
including those that are tool-specific, can be used
with -Xrunoii.
-Xbootclasspath JDK 1.2 and newer only. Appends Optimizeit
/a:<OptItdir>/lib/oibcp.jar classes to the boot classes. Replace <OptItdir>
with the directory where you installed Optimizeit.
-native JDK 1.2 on Solaris platforms only. If your virtual
machine uses green threads you should
suppress the -native option and add -
DOPTITTHR=green and -DOPTITDIR=<OptDir>
(where <OptDir> is the directory where you
installed Optimizeit). The invocation becomes:
java -native -Xnoclassgc
-Djava.compiler=NONE
-DOPTITTHR=green
-DOPTITDIR=<OptItDir>
intuitive.audit.Audit ...

Table 3.4 UNIX audit system Optimizeit start options


Option Description
[-startAudit] Starts the Optimizeit audit system. startAudit=t
[-intuitive.audit.Audit] or intuitive.audit.Audit is required in a
command.
[-port portNumber] Specifies the port you want to use for the
communication link between the Optimizeit audit
system and the Optimizeit user interface.
[-snapshotonexit] Generates a snapshot when the virtual machine
exits.
[-noexit] Disables the System.exit() method in the virtual
machine. This prevents the tested application
from exiting the virtual machine. The default is f.
[-filter] Specifies the filter file that Optimizeit will use for
this test. The format of the filter specification is
filter=<filter>, where <filter> is the name of
(and path to) a filter (.oif) file. Filter
specifications are required.
[-enableAPI] Enables the audit system API. When the API is
enabled, the Optimizeit tools are disabled. The
audit system waits for the test program to enable
the Optimizeit tool from Java.

Ch apt er 3 : Ru nnin g Optim i ze it from th e co mm and line 19


Sta r ti ng fr o m t he c om man d l in e

Table 3.4 UNIX audit system Optimizeit start options (continued)


Option Description
[-auditOption] Specifies audit system options that are listed in
an ASCII file. The format of the file specification is
auditOption=<Path to the file>. This file can
contain all the Optimizeit audit system options.
Only one option is allowed per line. The same
option file may be used for different tests.
Note: When this option is used, OISelector
settings are overridden.
ClassName The main class for the test program. If the test
program is an applet, use
sun.applet.AppletViewer and then add the path
of the applet HTML file or URL.
Note: With Code Coverage, you must use
oldjava instead of java to run an applet.

Examples
Use the following command to launch the applet contained in the file
example.html, without testing JDK classes and applet viewer classes.
On Windows:
oldjava -Xruncci:filter=<OptItDir>\filters\DefaultAllOn.oif
-Xbootclasspath/a:c:\Optimizeit\CCoverage\lib\oibcp.jar
intuitive.audit.Cover sun.applet.AppletViewer example.html
On Solaris or Linux:
oldjava -Xruncci:filter=<OptItDir>/filters/DefaultAllOn.oif
-Xbootclasspath/a:/opt/sfw/Optimizeit/CCoverage/lib/oibcp.jar
intuitive.audit.Cover sun.applet.AppletViewer
file:/usr/applet/example.html
Use the following command to test only the classes of the package com.busy of
the application com.busy.BusyApp and generate a snapshot when the application
ends.
On Windows:
java -Xruncci:filter=<OptItDir>\filters\DefaultAllOn.oif
-Xbootclasspath/a:c:\Optimizeit\CCoverage\lib\oibcp.jar
intuitive.audit.Cover -snapshotonexit com.busy.BusyApp
On UNIX:
java -Xruncci:filter=<OptItDir>/filters/DefaultAllOn.oif
-Xbootclasspath/a:/opt/sfw/Optimizeit/CCoverage/lib/oibcp.jar
intuitive.audit.Cover -snapshotonexit com.busy.BusyApp
The snapshotonexit option allows you to collect snapshot data. If you want to
see real-time data you must attach to the Optimizeit user interface, but if you
just want to collect snapshot data you do not need to attach the audit system
to the Optimizeit user interface. For example, if you want to generate a Code

20 Co de C ove ra ge Use r ’s Guid e


S ta rt i ng f r om t he comm an d line

Coverage snapshot report during nightly builds, you can insert a command in
your build script that will generate coverage data:
java -Xruncci:'filters={patternList=(!*tests.*,*Test*,*Proxy*)}'
-Xbootclasspath/a:/$optit_inst/lib/oibcp.jar intuitive.audit.Cover
-port 1472 -snapshotonexit mainClass
...

java intuitive.optit.coverage.ReportGenerator -verbose -methodInfo


-showSource -sourcePath $PATH $snapshotfile $outputfile
The first command sets the snapshot conditions, while the second command
saves the snapshot in the specified report format. You can access and view
the report within Optimizeit whenever you wish.

Connecting the audit system


Once the test program is running, you need to direct the audit system results
to the Optimizeit user interface. This procedure is called attaching Optimizeit
to the test program.
To show the audit system results:
1 In Optimizeit, choose File|New.
2 In the Settings dialog box, click Remote Application in the Program Type
section.
The Remote Application dialog box opens:

3 In the Host Name field, type either:



localhost

Ch apt er 3 : Ru nnin g Optim i ze it from th e co mm and line 21


Sta r ti ng on a d if fe re nt ma c hi ne

■ The name of your local host


■ The name of the machine where the audit system is running
■ The IP address of the machine where the audit system is running
4 In the Port Number field, enter the port number you want to use for the
communication link between Optimizeit and the audit system.
Change the default value only if you used the port option when launching
the test program.
5 To show relevant source code not found in the default source path, click
Change under the Source Path list to locate and add directories or JAR files
containing the additional source files.
Specific files can be added later during the testing session.
6 Click Attach Now.
Once you configure your test program, you can attach to the audit system by
choosing Program|Attach.

Starting on a different machine


Testing a Java program running on a different machine is similar to testing a
Java program started from the command line:
1 Set up the Optimizeit audit system, as described in “Setting up the audit
system” on page 16.
2 Launch the Optimizeit audit system, specifying your test program, as
described in “Launching your program” on page 16.
3 Start your selected Optimizeit tool and connect the audit system to the
Optimizeit user interface using Remote Application as the Program type, as
described in “Connecting the audit system” on page 21.
4 In the Host Name field, enter the name of the machine running the test
program.
5 Click OK when you have finished entering your test information in the
Settings dialog box.
6 Choose Program|Attach to attach Optimizeit to the test program.

Using the Filter Editor


Filters must be specified before you run your test program, when you specify
your virtual machine. For this reason, Optimizeit has command-line functions
to create, modify, and specify filters from outside of Optimizeit. This is required
when you are testing a remote application.
The Optimizeit Filter Editor creates and edits filter files for use in remote and
offline (batch) testing. These filter files, which use a .oif extension, are
specified in an Optimizeit command.

22 Co de C ove ra ge Use r ’s Guid e


U s ing t he Filt er Edit or

Because it is used for both Profiler and Code Coverage, the Filter Editor dialog
box has columns for both Profiler and Code Coverage filter operations. Only
one column, Ignore Coverage, is applicable for Code Coverage testing. Ignore
Coverage combines the two Code Coverage filter options, Include Class and
Exclude Class, into one column.
To use this program:
1 Make sure you have integrated with an application server and chosen your
virtual machine.
2 Start the Filter Editor:
■ If you are on a UNIX machine, go to your root Optimizeit directory and
enter ./Editfilter.sh at the command prompt.
■ If you are on a Windows machine, select the Optimizeit Filter Editor from
your Optimizeit program menu, or double-click on the Filter Editor
executable icon in your Optimizeit root directory.
3 The Filter Editor opens:

Click New to create a filter, or double-click on one of your filters to edit that
filter. You can also choose an existing filter from the Filter Editor File|Open
command to use as a starting point.
4 Check the applicable column(s) for your filter:
■ To filter methods, click in the Simplification Type column.
This column has two options:
■ Group: select the Group option to condense methods of multiple
classes into one single line in your stack trace. To use this option,
specify a set of classes to filter and give it a name as an identifier.
When you access the stack trace, all calls to the filtered methods are
condensed into one entry, labeled with the name you specified.

Ch apt er 3 : Ru nnin g Optim i ze it from th e co mm and line 23


Using the Filter Editor

For example, if your unfiltered back trace lists classes such as:
org.apache.catalina.core.x...
org.apache.catalina.core.y...
org.apache.catalina.core.z...
javax.servlet.http...
Myservlet...
you can group your Apache classes under the name Apache classes,
and the filtered output for the same section shows:
Apache classes
javax.servlet.http...
Myservlet...
This is especially useful for servlets.

Eliminate: select Eliminate to filter these methods from your results.
The code matching this group is ignored, and will not show up in your
backtraces. The time spent in this eliminated group will be associated
with the caller.
Note The Eliminate simplification type is more efficient than Ignore CPU.
Typically, you should select Eliminate for Simplification Type, and not
enable Ignore CPU when enabling a filter.
■ To ignore CPU or time usage consumed by Java code matching the filter
pattern, click the Ignore CPU column.
Any time spent in the filtered method will be unaccounted for in the
backtrace. Ignore CPU is more precise than Eliminate, in that it assigns
the correct amount of time spent to the methods in the backtrace, but
Eliminate is useful in that all time is accounted for in the backtrace.
■ To enable a filter for the Memory Profiler, click the Ignore Memory
column. Optimizeit Profiler ignores object allocations performed by Java
code matching the filter pattern.
■ To enable a filter for a Code Coverage class, click the Ignore Coverage
column. This filter excludes a class from testing.
If you want the reverse (the equivalent of the Include Coverage filter
option in Code Coverage) use the not (!) character.
1 To see the patterns associated with a filter, double-click on the filter in the
table or highlight the filter and click Details.
2 Make your selections and chose the Filter Editor’s File|Save option to save
your filter file. This creates an .oif file that can be accessed by command-
line test runs.
Custom filters are part of Optimizeit configuration files. They are saved and
loaded when using Save and Open commands from the File menu.
Note If you select more than one filter for a test run, Optimizeit always performs a
logical OR of all the filters you have selected. Any top-level package, class, or
method that meets any of the filter criteria is filtered.

24 Co de C ove ra ge Use r ’s Guid e


St arting from th e te st p ro gram

You can also create and edit filters in the Filter Editor. For information on how
to create and edit filters, see “Using the Filters tab” on page 9.

Starting from the test program


In some environments, the Java virtual machine is started automatically. The
Optimizeit audit system can be invoked from the test program using the
Profiler or Code Coverage application programming interface (API). To invoke
Optimizeit from inside your test program:
1 Set up the Optimizeit audit system, as described in “Setting up the audit
system” on page 16.
This is done in exactly the same way for all command-line or batch testing.
2 Add API calls in your program, as described in “Adding API calls in your
program” on page 25.
3 Launch the Optimizeit audit system, specifying your test program, as
described in “Starting your test program” on page 26.
4 Start your selected Optimizeit tool and connect the audit system to the
Optimizeit user interface using Remote Application as the Program type, as
described in “Connecting the audit system” on page 21.
5 In the Host Name field, enter the name of the machine running the test
program.
6 Click OK when you have finished entering your test information in the
Settings dialog box.
7 Choose Program|Attach to attach Optimizeit to the test program.

Adding API calls in your program


The following example shows how to start the Optimizeit Code Coverage audit
system from Java code.
import intuitive.audit.Cover;
void startAuditSystem() {
/** Start the Optimizeit Code Coverage audit system with some default
options **/
Audit.start(1472, Cover.DEFAULT_OPTIONS);
}
Once the Code Coverage audit system has been started, Optimizeit Code
Coverage starts retrieving the test information when the Java code is
executed.

See also
■ For more information about Optimizeit Code Coverage Audit API, read the
API reference documentation.

Ch apt er 3 : Ru nnin g Optim i ze it from th e co mm and line 25


Sta r ti ng fr o m t he te s t p r ogr a m

Starting your test program


Although the test program starts the audit system, extra parameters need to
be added to the code or to the shell script that starts the virtual machine.
■ Start the Code Coverage tool with the -Xruncci command option and specify
the filter file to be used.
■ Set the bootclasspath so it includes the Optimizeit oibcp.jar file.
On Windows:
java -Xruncci:filter=<OptItDir>\filters\DefaultAllOn.oif
-Xbootclasspath/a:C:\Optimizeit\CCoverage\lib\oibcp.jar
TestProgram
On UNIX:
java -Xruncci:filter=<OptItDir>/filters/DefaultAllOn.oif TestProgram

26 Co de C ove ra ge Use r ’s Guid e


Chapter

Using Class Coverage


Chapter 4

Optimizeit Code Coverage has two ways to view results: Class Coverage and
Method Coverage. By default, when you start Optimizeit Code Coverage, the
Class Coverage view opens. To return to Class Coverage from Method
Coverage, click the Class Coverage button on the main menu bar.
Class Coverage lists all classes and the real-time test results for each class.
You can see how many lines have not been executed, and can apply filters to
test only certain classes.

Ch ap ter 4 : Usin g C l ass Co ve rage 27


Using Class Coverage

The Class Coverage table contains these columns:

Column Description
Class Name All the classes that will be tested with the selected filters. If a
class has not yet been loaded, Not Loaded appears on that
row.
Coverage % The percentage of coverage for each class. When the classes
have been compiled with line debug information (the default
when you use javac) this percentage represents the number
of lines of code that have been tested compared to the overall
number of lines of code for that class.
If the line debug information is not available (because the
classes were compiled with the -g:none option), this
percentage represents the number of methods from that class
that were executed compared to the total number of methods.
Tip: For more accurate test results, do not compile your
application using the -g:none option.
Diff. Similar to the Coverage column, but only shows the coverage
occurring since the last mark.

To sort the values in columns of the table, click on the column header.
The Filters box at the bottom allows you to select the classes that you want to
view. The classes that you exclude will still be tested, but Optimizeit will not
show them in the results.
Note This is different from the filters you set before the test is run, using the Filter
Editor. Those filters, contained in .oif files, select which classes are tested.
For example, to see only the classes from the com.sun.estore.inventory
package, enter the following in the filter box:
com.sun.estore.inventory.*
Both the asterisk wildcard character (*) and the not character (!) are
supported. It is also possible to enumerate more than one pattern using a
comma (,) separator. For example, to see all classes matching EJB except
those ending with Impl:
*EJB*, !*Impl
To see all tested classes, either clear the filter completely or type an asterisk
(*).

28 Co de C ove ra ge Use r ’s Guid e


C o n t r o l l i n g t h e t e s t p ro g r a m

Controlling the test program


The Optimizeit tool bar provides the following buttons to control the test
program run:

Starts or resumes the test program. This control is red when the test
program is running.

Pauses or resumes the test program. Use this button to freeze the
flow of execution to better study the interaction between different
parts of the tested program.
Stops testing. If you are running your test program from within the
Code Coverage user interface, the program will stop and the test will
end. If you are connected to a remote server, and the test program is
running on the remote machine, Stop will just disconnect your Code
Coverage user interface. The test program itself will keep running on
the remote server.

Mark and Inspector options


Two of the tool bar icons, Mark and Inspector, have special functions in Class
Coverage:

Click Mark to set a mark at any time. This resets the values in the Diff.
column of the Class Coverage table. If you set the mark before a
specific action in your application, you can see how this action affects
the testing of your classes.
Click Inspector to view the options for the Class Coverage display.

Ch ap ter 4 : Usin g C l ass Co ve rage 29


Ma rk and I nspe c to r op tion s

Table 4.1 Inspector options for Class Coverage


Option Description
Show Line Coverage Adds columns displaying the number of missed lines
and number of missed lines since the mark (missed
line diff). The information is displayed in the form:
missed lines / total number of lines
The Missed Lines Diff column shows the number of
lines of code that have not been executed since the
mark.
Note: These columns display N/A (Not Applicable) if
the class has been compiled without the line
information, or if the row describes coverage of an
interface.
Show All Accessible Classes Displays all the classes accessible from the
CLASSPATH and not filtered out by the specified filters.
This includes the classes not loaded in the virtual
machine.
Code Coverage reports the classes not loaded by
looking through the CLASSPATH. Any class found in
the CLASSPATH is reported if it is not filtered out by the
specified filter file. Set the java property
ccoverage.classpath if you want Code Coverage to
use a different path. The following commands start
the testing of an application and use different paths
to search for classes that are not loaded.
On Windows:
c:\ java -Xruncci:filter=<OptItDir>\filters\
DefaultAllOn.oif
-Xbootclasspath/a:c:\Optimizeit\
CCoverage\lib\oibcp.jar
intuitive.audit.Cover MyApp
c:\ java -Xruncci:filter=<OptItDir>\filters\
DefaultAllOn.oif
-Xbootclasspath/a:c:\Optimizeit\
CCoverage\lib\oibcp.jar
-Dccoverage.classpath=d:\
StoreEJBs.jar;d:\classes
intuitive.audit.Cover MyApp
On Solaris or Linux:
$ java -Xruncci:filter=<OptItDir>/filters/
DefaultAllOn.oif
-Xbootclasspath/a:/opt/sfw/Optimizeit/
CCoverage/lib/oibcp.jar
-Dccoverage.classpath=/home/
StoreEJBs.jar:/home/classes
intuitive.audit.Cover MyApp
Show Interfaces Displays the interfaces that have been loaded by the
virtual machine.

30 Co de C ove ra ge Use r ’s Guid e


Chapter

Using Method Coverage


Chapter 5

Once you have identified a class you would like to investigate in the Class
Coverage view, highlight this class in the table and either click the Method
Coverage button on the tool bar or double-click on the line in the Class
Coverage window. Optimizeit Code Coverage opens the Method Coverage
view.

C ha pte r 5: U s in g Met ho d Co ve rage 31


Me tho d Co verag e w i nd ow op tio ns

Method Coverage window options


In the top pane, the Method Coverage table lists all the methods of the
selected class. All the methods appear in the same order as in the class file.
The table contains these columns:

Column Description
Method Name Name of the method
Note: This name includes the signature of the method if the
Show Method Signatures option in the Inspector is selected.
Coverage % Percentage of code tested for the method, computed as:
tested lines / total number of lines
for that method.
Note: If the class file for the selected class does not include
the debug line information, the method table only displays the
method name and invocation count. To include the line
information in your class files, use the -g option when
compiling.
Invocation Count Number of times the method has been called.
Missed Lines Number of lines not tested.

In the bottom pane, the source code table displays the source code for the
class being reviewed. The lines that have been tested are highlighted in
yellow. If you select any method in the method table, the source code table
displays that particular method.
The table contains these columns:

Column Description
# Line numbers in the file, retrieved from the debug line
information included in the class files. In the class file not all
lines of code are significant, so the compiler does not generate
bytecode for all the lines of code. The lines that do not
correspond to bytecode will have no number of calls reported
in the source code table and are disregarded when computing
the coverage.
Source code Percentage of code tested for the method, computed as:
tested lines / total number of lines
for that method.
Note: If Optimizeit Code Coverage cannot find the source file
for that class from the source path, it displays a message that
the source file could not be found. Click the Browse button to
search for the source file manually.
Calls Number of times each line of code has been called.

Note If the class file for the selected class does not include the debug line
information, the source code table displays a message explaining that the

32 Co de C ove ra ge Use r ’s Guid e


C o n t r o l l i n g t h e t e s t p ro g r a m

class was compiled without the debug line information. To include the line
information in your class files, use the -g option when compiling.
You can refresh the values in the tables by selecting File|Reload.

Controlling the test program


The Optimizeit tool bar provides the following buttons to control the test
program run:

Starts or resumes the test program. This control is red when the test
program is running.

Pauses or resumes the test program. Use this button to freeze the
flow of execution to better study the interaction between different
parts of the tested program.
Stops testing. If you are running your test program from within the
Code Coverage user interface, the program will stop and the test will
end. If you are connected to a remote server, and the test program is
running on the remote machine, stop will just disconnect your Code
Coverage user interface; the test program itself will keep running on
the remote server.

Mark and Inspector options


Two of the Optimizeit tool bar icons, mark and inspector, have special
functions when the Method Coverage window is open.

Click Mark on the tool bar to set a mark. This resets the Invocation
Count and Missed Lines columns in the method table, and the Diff
column in the source code table. The source code table only contains
a Diff column if you choose the Show Difference option in the
Inspector.
Click Inspector to view the options for Method Coverage display:

Table 5.1 Inspector options for Method Coverage


Option Description
Real Time Switches the coverage information to real time in the
tables.
Show Method Signatures Includes the signatures of the methods in the Name
column of the method table.

C ha pte r 5: U s in g Met ho d Co ve rage 33


Ma rk and I nspe c to r op tion s

Table 5.1 Inspector options for Method Coverage (continued)


Option Description
Show Difference Adds the Invocation Count Difference and Missed
Lines Difference columns to the method table. These
columns show the information since the last mark.
Also adds the Diff column in the source code table.
This column shows how many times each line of
code has been executed since the last mark was set,
if the line information is available for that class.
Highlight Since Mark Causes the source code table to highlight the lines of
code that have been tested since the last mark.

34 Co de C ove ra ge Use r ’s Guid e


Chapter

Reporting features
Chapter 6

This chapter describes the features available in Optimizeit Code Coverage to


generate reports and other types of information from your test runs. These
reporting features include the following:
■ Snapshots, binary files that you can reopen in Optimizeit at a later date to
compare test results
■ Test reports, HTML or ASCII files that contain all the test data for the
current test run, regardless of which view you are currently in
■ Data exports, HTML or ASCII files that contain just the test information
from your current, open view
The following sections explain how to use Optimizeit’s reporting features:

“Generating snapshots”

“Merging snapshots”

“Generating reports”
■ “Exporting data”
■ “Displaying console messages”

Generating snapshots
At any time, Optimizeit Code Coverage allows you to save test information into
a snapshot. You can then reload the snapshot later for further analysis. This is
useful, for example, when you are testing several different classes in one test
pass. Snapshots are generated from within the Optimizeit user interface or

Ch ap ter 6 : Re port i ng fe atu re s 35


M e rg i n g s n a p s h o t s

with a specific command option when running Code Coverage from the
command line.
To generate a snapshot
1 Choose File|Generate Snapshot.

2 In the Directory field, enter the directory where you would like the snapshot
to be saved.
3 In the Name field, enter the name for the snapshot.
4 If you would like to have the time and date added to the end of the name
you have chosen, check Append Time And Date When Saving.
5 Use the Notes area to add any comments.
6 Click Write Snapshot to create the snapshot.
To open a snapshot:
1 Choose File|Open snapshot or File|Open recent snapshots.
2 Double-click a recent snapshot, or highlight a snapshot and click Open, to
view the snapshot’s test results. It may take a few moments to load,
because a snapshot uses a VM to display data. The VM installed with
Optimizeit is used to load the snapshot.
3 You can navigate through all available modes, but you cannot perform real-
time actions such as starting or pausing the test run or setting a mark.
Snapshots are binary files that can only be opened from within Optimizeit user
interface. If your snapshot takes a long time to load, and your connection
times out before the load is completed, you can increase the connection time-
out using the Launch option from Edit|Preferences.

Merging snapshots
Code Coverage includes a command-line executable, Snapmerge.
Snapmerge creates merges of selected snapshots. This is useful, for
example, if you have QA teams testing different areas of the product. The QA

36 Co de C ove ra ge Use r ’s Guid e


Mergin g sn ap shot s

teams can merge their test snapshots to give a complete view of the tested
classes. To use:
1 Create a series of snapshots during a testing session. These snapshots
could be of different time points in your test session, or of different functions
in the same product.
2 Note the names of the snapshots you want to merge.
3 From a command prompt, access the root directory for your Optimizeit
installation. For example, /home/OptimizeitSuite.
4 Enter the following command:
snapmerge mergefile.snp snap1.snp snap2.snp snap3.snp
where mergefile is the name of the file for all the merged snapshots and
snapx are the filenames of the snapshots you want to merge. Include all file
extensions, or the program will not be able to access your files.
Any warnings are displayed by default. If you do not want to see any error
or warning messages, use -noWarnings in your command.
■ A command example on Windows:
c:\Optimizeit\OptimizeitSuite\snapmerge.exe snapmerged.snp
snapshot1.snp snapshot2.snp snapshot3.snp
This command merges the three snapshots c:\MyApp\snapshot1.snp, c:\
MyApp\snapshot2.snp and c:\MyApp\snapshot3.snp into the new snapshot c:\
MyApp\snapmerged.snp.
■ A command example on Solaris or Linux:
/user/local/OptimizeitSuite/snapmerge - noWarnings
/home/MyApp/snapmerged.snp /home/MyAp/snapshot1.snp
/home/MyApp/snapshot2.snp /home/MyApp/snapshot3.snp
This command merges the three snapshots /home/MyApp/snapshot1.snp, /
home/MyApp/snapshot2.snp, and /home/MyApp/snapshot3.snp into the new
snapshot /home/MyApp/snapmerged.snp and turns off Optimizeit snapmerge
warning and error messages.
5 To view your merged snapshot, re-enter Code Coverage.
Note Make sure you have stopped any testing sessions, because Code
Coverage cannot open snapshots when the virtual machine is running.
6 Choose one of the Open Snapshot commands from the File menu and
browse for your merge file.
7 Double-click on the merge file to open it in Code Coverage. You will see a
merge of test information from the snapshots you selected.
Any merged snapshot can be reopened in Optimizeit Code Coverage (see
“Generating snapshots” on page 35), merged again with other snapshots, or
used to generate a report.

Ch ap ter 6 : Re port i ng fe atu re s 37


Gen erat i ng re po rt s

Generating reports
Code Coverage supports both command line- and user interface-accessed
report functions.

Generating a report from within Code Coverage


If you are testing an application, or if you have opened a snapshot, the Report
option within Code Coverage allows you to save the test information in either
ASCII or HTML.
To generate a report, choose File|Generate Report or click Generate Report:
Note Although this button looks the same as the Optimizeit Profiler Export button, in
Code Coverage it is used for reports.
To export data, choose File|Export Data.

1 In the Directory field, enter the directory where the report will be created.
2 In the Name field, enter the filename of the report.
3 Check Append Time And Date When Saving to have the current time and
date appended to the name of the report.
4 In the Generate Report As field, select which type of file is to be used for
the report: HTML or ASCII.
5 In the Options section, check the options you want to use for this report:

Check Include Method Coverage if the method coverage should be
included in the report. When this option is not selected, only coverage for
the classes is included in the report.
■ Check Include Source Code if the source code should be included in the
report.

38 Co de C ove ra ge Use r ’s Guid e


Gen erat i ng re po rt s

■ Check Show Difference to include the Diff columns, showing the test
information since the last mark. Both class coverage and method
coverage marks are included.
■ Check Show Method Signature to include the signature in the name of
the method.
6 Add any additional text, such as a description of the context of the test
session, in the Notes field.
7 Click Write Report to generate your report.
After generating a report with the specified filename, Optimizeit Code
Coverage opens the report file in your default editor or web browser.

Generating a report from the command line


At the command line, you can generate a report from a testing snapshot using
the ReportGenerator class. A coverage report presents the test information for
all covered classes. You can customize your report with ReportGenerator
options.
To generate a report from a snapshot, modify your environment variables:

On Windows:

add <OptItDir> to the PATH

add <OptItDir>\lib\optit.jar to the CLASSPATH

On UNIX:

add <OptItDir>/lib to the LD_LIBRARY_PATH

add <OptItDir>/lib/optit.jar to the CLASSPATH
After you have modified you environment variables, invoke the Optimizeit
Code Coverage ReportGenerator class:
java intuitive.optit.coverage.ReportGenerator [-methodInfo] [-showDiff]
[-showSignatures] [-reportType FileType] [-verbose] [-showSource]
[-sourcePath SourcePath] snapshot report
This table describes the ReportGenerator options:

Option Description
-methodInfo Includes the method test information. For each
tested class, the report includes a table with the
test results for each method of the class.
-showDiff Includes the diff information, which is the test
information since the mark.
-showSignatures Displays the full name of methods, including their
signatures.
-reportType Should be followed by a document type (either
HTML or ASCII). Specifies the type of the report
generated. The default value is HTML.

Ch ap ter 6 : Re port i ng fe atu re s 39


Expo rting da ta

Option Description
-verbose Prints information about the status of the report
generation.
-showSource Includes the source code (when available) and
line coverage for the tested classes. (This option
is only effective with the -methodInfo option.)
-sourcePath Should be followed by the path to the source files
of the classes tested. This option should be used
to specify the location of the source code when
the -showSource option is used.

Examples
The following command generates the report stressTest.html from the
snapshot stressTest.snp, including the method coverage information.
On Windows:
java intuitive.optit.coverage.ReportGenerator -methodInfo c:\Test\
stressTest.snp c:\Test\stressTest.html
On Solaris or Linux:
java intuitive.optit.coverage.ReportGenerator -methodInfo /home/jay/
Test/stressTest.snp /home/jay/Test/stressTest.html
The following command generates the report EJBs_coverage.html from the
snapshot test5.snp, including the method information. The methods display
with their full signature. The source code with line coverage information is
included. The source file for the tested classes is located under the directory
c:\EJB_src.
On Windows:
java intuitive.optit.coverage.ReportGenerator -methodInfo -
showSignatures -showSource -sourcePath c:\EJB_src test5.snp
EJBs_coverage.html
On UNIX:
java intuitive.optit.coverage.ReportGenerator -methodInfo -
showSignatures -showSource -sourcePath /home/jay/EJB_src test5.snp /home/
jay/EJBs_coverage.html

Exporting data
Optimizeit can export test data as ASCII, HTML, or Importable ASCII. After the
data is exported it can be printed, compared, and archived.
To export the contents of a screen:

40 Co de C ove ra ge Use r ’s Guid e


Disp laying co nso l e me ssa ge s

1 Choose File|Export Data. The Export Data dialog box opens:

2 In Export, choose the coverage type you want in your report, such as Class
Coverage or Method and Source Code Coverage. Your options will depend
upon what view is active.
3 In Export As, choose the output of the file format. Select HTML to produce
an HTML document that presents data in the same format as the Optimizeit
views. Select ASCII for a more compact file. Select Importable ASCII if you
expect to use the output as input to another tool.
4 In the Filename field, enter the full path name of the file.
5 If this file already exists, and you want to append the new data at the end of
the file, check Append Data At The End Of The File.
6 Use Title to insert a description at the top of the exported document.
7 If you wish, use the Comments section for information such as additional
text to distinguish this test from others.
8 Click OK to export the data.
After exporting the data into the specified file, Optimizeit opens the file with the
default editor or web browser.

Displaying console messages


The Console button prints audit system messages as well as the test program
standard output and standard error messages. Use the console output to read
messages from the test program or to see errors if the Java program does not
start.
Note If you add Open A Console to your start options, the standard output and the
standard error messages of the test program won’t be redirected to the
Optimizeit Code Coverage console.

Ch ap ter 6 : Re port i ng fe atu re s 41


42 Co de C ove ra ge Use r ’s Guid e
Chapter

Setting your preferences


Chapter 7

This chapter describes how to use the Edit|Preferences menu option to set
defaults for Optimizeit Code Coverage. You can set these defaults:
■ Selecting default displays
■ Setting launch parameters
■ Setting the source code location
■ Changing the class path
■ Selecting a virtual machine
■ Configuring servlet support
Your choices will appear in the Settings dialog box, where they can be
customized for each applet or application you are testing.

Selecting default displays


Although the Edit Settings dialog box opens by default when you enter Code
Coverage, you can set a new default using the Startup option on the
Preferences pull-down menu. You can also determine the mode that testing
will begin in.

C ha pte r 7: Se tt in g you r pref eren ce s 43


S e t t i n g l a u n c h p a r a m et e r s

The Preferences dialog box, Startup view determines the default mode once
testing begins. Click Default display to choose your default workspace, such
as Class Coverage or Console.

Click the After Startup, Open pull-down menu to choose which window opens
in the default workspace:
■ Settings Editor—choose Settings Editor if your settings change depending
upon which test case you are running.
■ Attach Panel—choose Attach Panel if you usually test your programs from
outside of Optimizeit.
■ Nothing—choose Nothing if you rarely change your default settings, and
want to go directly to the default view when you open Code Coverage.
Click OK to close the form. The next time you open Optimizeit, your new
defaults are activated.

Setting launch parameters


The Launch menu option lets you set your connection time-out and default
port:
■ By default, the connection time-out is set at ten seconds. If your connection
is timing out before you can access all the required information (for
example, when you are loading a large snapshot), then you can make this
option larger.
■ The default port for Code Coverage is 1472.
Important Make sure to use the correct port when you attach.
When you integrate Optimizeit with an application server, you start the
Optimizeit audit system inside the virtual machine of the application server. By
attaching the Optimizeit GUI to the audit system, you test the virtual machine
of your application server and get the test information for your servlets/JSPs/
EJBs.

44 Co de C ove ra ge Use r ’s Guid e


Se ttin g t he source code loca tion

Optimizeit uses a port to get the test information from the audit system running
in your application server. This port is only used by Optimizeit and is not
related to any port of your application server. The default value for that port is
1472. If you start your application with Optimizeit from a script, the port is
specified in the script. If you use the Optimizeit servlet to start the audit
system, the port is specified from the servlet.

Setting the source code location


When Optimizeit Code Coverage has access to the source code for an
application, it highlights the relevant lines as they are run. If the source code is
not accessible, Optimizeit Code Coverage can still provide testing results for
Java classes.
Optimizeit Code Coverage maintains a source path, which is a list of
directories containing source code. When it requires a source file, Optimizeit
Code Coverage searches each directory in the source path in the order
specified.

Changing the default source path


The Preferences panel can be used to change the default source path:
1 Choose Edit|Preferences.
2 Click on Default Source Path in the top selection box.
3 Click the Edit button. The Source Path Chooser opens.
4 In the top box, either:
■ Use the browser to search for and select the directory, JAR file, or ZIP
file you want to add.
If you select a directory, choose the directory that contains the top-level
package of your Java source code. If you aren’t sure, select any Java file
in your application and Optimizeit Profiler adds the appropriate directory.
If you select a JAR or ZIP file, Optimizeit looks for a source file from the
root of the JAR or ZIP content or from the src directory in the package.
■ Use the empty field under the browser if you have a multi-entry source
path, such as c:\src;d:\project\src.jar. Enter your full path information
into the field.
5 Click the Down Arrow button to add your selection to the source path. If you
entered a multi-entry source string, Optimizeit adds all the entries to the
source path.
6 Repeat these steps for other directories you would like to add to the source
path.
7 Click the OK button.
8 Click the OK button again to close the Preferences dialog box.

C ha pte r 7: Se tt in g you r pref eren ce s 45


Ch an ging t he class p at h

Note When Optimizeit Code Coverage is testing an application, if a Java file is not
available, you will be prompted to locate the file. After you locate the missing
Java file, a dialog box prompts you to add the file’s directory to the default
source path.
To set a different source path for an applet, servlet, or application that you are
testing with Optimizeit Code Coverage, define the changes to the default
source path in the Settings dialog box.

Changing the class path


When Optimizeit launches your applet or application, the Java virtual machine
needs the location of all classes your application uses. By default, Optimizeit
points to the classes that are defined in your CLASSPATH environment
variable.
The CLASSPATH environment variable is a list of directories containing class
files. Optimizeit searches each directory in the class path in the order they
appear. If there are certain classes, ZIP files or JAR files that you would like to
always be available for all test programs, add them to the default Optimizeit
class path using the Settings dialog box or the Edit|Preferences menu option.
To customize the CLASSPATH using Edit|Preferences:
1 Choose Edit|Preferences.
2 Click on Default Class Path in the top selection box:

3 Uncheck the Use CLASSPATH Environment Variable option.


4 Click the Edit button.
The Class Path Chooser opens.
5 In the top box, either,

Use the browser to search for and select the directory, JAR file, or ZIP
file you want to add to the class path. If you select a directory, choose
the directory that contains the top-level package of the source tree.

46 Co de C ove ra ge Use r ’s Guid e


S e l e c t i n g a v ir t u a l m a c h i n e

■ Use the empty field under the browser if you have a multi-entry class
path, such as c:\classes;d:\project\xmlParser.jar. Enter your full path
information into the field.
6 Click the Down Arrow button to add your selection to the class path. If you
entered a class path string, Optimizeit adds all the entries to the class path.
7 Click the OK button.
8 Click the OK button again to close the Preferences dialog box.

Selecting a virtual machine


You can add and set your virtual machine using the Virtual Machines tab on
the Settings dialog box, and you can also set your default virtual machine and
add virtual machines from the Virtual machine option of the Preferences dialog
box:
1 Choose Edit|Preferences from the main menu bar.
2 Click on Virtual Machine in the top selection box:

3 Click Setup.
This starts the virtual machine wizard.
4 Click Next.
5 Select a directory.
Optimizeit will begin the search for a virtual machine from this point.
6 Click Search.
Optimizeit Code Coverage displays the virtual machines found.
7 Click Finish to add these virtual machines to the list of available virtual
machines.
8 Highlight the virtual machine you would like to be the default, and click OK
to set the default.

C ha pte r 7: Se tt in g you r pref eren ce s 47


Co nf ig uring se rvle t su pp ort

Configuring servlet support


The Servlet option on the Preferences menu allows you to configure servlet/
JSP testing.
1 Choose Edit|Preferences from the top menu.
2 Click on Servlet in the top selection box:

3 The Path To The Tomcat 4 Server Used field contains the current path to
your Tomcat installation, if any. You can enter a path or change the existing
path to point to this application, which is required for direct servlet/JSP
testing.
4 If you are unsure of the correct directory for your Tomcat application, click
Servlet Setup to open the Setup wizard and browse for the correct location.
5 Edit the Directory Used For Temporary Files field if the default location is
too small or is not easily accessible.
6 By default, Code Coverage filters out Tomcat classes so you can
concentrate on the testing of your application. Uncheck this option if you
need to see the interaction between your tested application and Tomcat
classes.
7 In the Tomcat configuration section, you can choose to either automatically
generate the server.xml file (the default option), or you can use an existing
server.xml file if you already have one that you have used for other Tomcat
operations. You can browse for the correct file and double-click to select it,
or you can enter it in the file path field directly.
8 When you start the direct testing of a servlet or JSP, Code Coverage runs
your servlet in a servlet runner. The default port used by the servlet runner
is 8080. If you have another application that already uses that port, change
the value of the port in the Port Used By Tomcat field.
9 Click OK to save your changes.

48 Co de C ove ra ge Use r ’s Guid e


Chapter

Troubleshooting
Chapter 8

Starting your application


1 My application starts correctly, but an alert explaining that Optimizeit failed
to attach is displayed.
2 My application ran successfully, but the Optimizeit tools are not working
correctly. Most of the buttons are disabled, and the views do not contain
information.
3 When starting my application, I get an alert reporting a Class not found.
4 When starting my application, the console reports that my JDK is not
supported.
5 When starting my applet, the console returns
java.util.MissingResourceException: Can’t find resource at
java.util.ResourceBundle.getObject.
6 My application or applet cannot be started from the Optimizeit user
interface. What should I do next?
7 When starting my application, the console reports a
java.lang.UnsatisfiedLinkError.
8 When starting my application, the console returns an error message that it
cannot find or could not locate an entry point or field.
9 (Windows only) When starting my application, the console appears but
closes immediately, Optimizeit times-out and I get a warning that Optimizeit
was not able to attach to my application.

C ha pt er 8 : T r ou bl es h oo ti ng 49
Sta r ting you r ap plicat ion

10 (UNIX only) I cannot start Optimizeit. The Optimizeit script fails with the
error Class not found: intuitive.optit....
11 (Solaris only) Does Optimizeit support JDK 1.2.x? When configuring
Optimizeit to use JDK 1.2.x, an error box reports that JDK is incompatible
with Optimizeit.
12 (Solaris only) Does Optimizeit support JDK 1.3? When configuring
Optimizeit to use JDK 1.3, an error box reports that JDK is incompatible
with Optimizeit.
1 My application starts correctly, but an alert explaining that Optimizeit
failed to attach is displayed.
Optimizeit uses a default connection time-out of 60 seconds on Windows or
20 seconds on UNIX machines to attach to the virtual machine.
In some environments, the Optimizeit audit system may require more than
the default time-out to initialize. If this happens, choose Edit|Preferences,
select the Launch section and increase the connection time-out value.
2 My application ran successfully, but the Optimizeit tools are not
working correctly. Most of the buttons are disabled, and the views do
not contain information.
Optimizeit’s audit system runs inside the same virtual machine as the
tested application. If the tested application ends, the virtual machine exits
and Optimizeit loses contact with its audit system and cannot retrieve data
(a Test program exited alert pops up in Optimizeit).
To resolve this problem, Optimizeit provides an option to disable the Java
method System.exit(). This option can be enabled either by using the VM
Cannot Exit or Disable Exit option in the Settings dialog box or by using the
command line option -noexit (java ... intuitive.audit.Audit -noexit ...).
That way the virtual machine will not exit when your application ends. Use
the Stop button in Optimizeit to exit the program when your testing is
complete.
If you are starting your test from the command line, or testing remotely, the
-Xrunoii argument uses the configuration of the Audit System Selector.
Make sure your Audit System Selector is not set to none. On Windows
machines, your selected tool appears in the Windows icon tray. The
Optimizeit icon is red for Profiler, green for Thread Debugger, and blue for
Code Coverage.
If you have integrated Optimizeit with an application server, make sure that
you are attaching the correct tool to the Audit process started with your
application server. If, for example, the Audit System Selector has the
Thread Debugger tool selected and you started your WebLogic tool with
Thread Debugger, then you must attach with the Thread Debugger tool.
3 When starting my application, I get an alert reporting a Class not
found.
This error is very likely related to a CLASSPATH setting problem. Open the
Settings dialog box, and make sure that the Class Path window includes
the paths to the packages and classes required by your application.

50 Co de C ove ra ge Use r ’s Guid e


St artin g you r ap plica tion

4 When starting my application, the console reports that my JDK is not


supported.
The virtual machine you are using is not supported by Optimizeit. See the
Release Notes for a complete list of supported JDKs. Make sure to select a
supported virtual machine in the Virtual Machines tab of the Settings dialog
box.
5 When starting my applet, the console returns
java.util.MissingResourceException: Can’t find resource at
java.util.ResourceBundle.getObject.
Optimizeit starts your applet in the Sun applet viewer in order to test it. The
applet viewer throws that error when the HTML file of your applet specifies
the size of your applet in percent. Make sure that the HTML file you are
using to start your applet uses hard values for the width and height.
6 My application or applet cannot be started from the Optimizeit user
interface. What should I do next?
The best way to investigate the cause of the problem is to start your
application from the command line. This may give more information. For
complete instructions on how to start Optimizeit from the command line and
all available start options, please see Chapter 3, “Running Optimizeit from
the command line.”
If that still does not help, contact Borland Technical Support. Remember to
include the version of the operating system you are running, the version of
Optimizeit and the version of the JDK you are using, and give as much
information as possible about the problem. The more information you
provide the quicker and more effective the response from the support team!
7 When starting my application, the console reports a
java.lang.UnsatisfiedLinkError.
This error may happen if for some reason Optimizeit loads a library of an
older version of Optimizeit. If you have a previous version of Optimizeit
installed, make sure that your LD_LIBRARY_PATH does not point to this older
version.
On Windows machines, this problem can also happen if you have
integrated a previous version of Optimizeit with an IDE or an application
server. When you integrate Optimizeit with an IDE or an application server,
the wizard that performs the integration may copy the Optimizeit library
oii.dll in the Windows directory or in the IDE directory. The PATH may still
reference the IDE directory causing the old oii.dll to be used, even if you
have uninstalled the previous version of Optimizeit. To make sure the
correct oii.dll is used, perform a find on your hard drives for the oii.dll
library. Remove any oii.dll that is not located under the Optimizeit
directory.
8 When starting my application, the console returns an error message
that it cannot find or could not locate an entry point or field.
This error may happen if you have two versions of the dynamic link library
oii.dll on your system. This can also occur if you have an older oibcp.jar

C ha pt er 8 : T r ou bl es h oo ti ng 51
Sta r ting you r ap plicat ion

or optit.jar in the CLASSPATH or bootclasspath and/or you are loading the


older oii.dll, pri.dll, or auditjni.dll instead of the newer ones. When you
upgrade to a new version of Optimizeit, make sure all older versions of
these files are deleted.
9 (Windows only) When starting my application, the console appears
but closes immediately, Optimizeit times-out and I get a warning that
Optimizeit was not able to attach to my application.
The console may flash when you are using a JDK or JRE located in a path
with spaces in the path name. In the Virtual Machines tab of the Settings
dialog box, make sure to select a virtual machine located in a path without
spaces.
10 (UNIX only) I cannot start Optimizeit. The Optimizeit script fails with
the error Class not found: intuitive.optit....
If your DISPLAY environment variable is set to a display that does not exist,
the Optimizeit script fails with the message Class not found:
intuitive.optit.toolclassname. This message is sent by the virtual machine
that Optimizeit uses and is not accurate. Make sure to set your DISPLAY to a
correct value.
For example on a machine named asterix, the DISPLAY is set with the
command:
export DISPLAY=asterix:0
11 (Solaris only) Does Optimizeit support JDK 1.2.x? When configuring
Optimizeit to use JDK 1.2.x, an error box reports that JDK is
incompatible with Optimizeit.
You may be running the JDK 1.2.x production release. Optimizeit for
Solaris does not support this JDK. The JDK 1.2.x production release does
not implement JVMPI well. JVMPI is the low-level API from Sun used to
retrieve information from the virtual machine. Optimizeit fully supports the
JDK 1.2.x reference implementation.
12 (Solaris only) Does Optimizeit support JDK 1.3? When configuring
Optimizeit to use JDK 1.3, an error box reports that JDK is
incompatible with Optimizeit.
JDK 1.3 is not supported by Optimizeit for Solaris. JDK 1.3 only comes with
a Hotspot runtime on Solaris, and the Hotspot runtime has several bugs in
its JVMPI implementation. JVMPI is a low-level API from Sun used to
retrieve information from the virtual machine. Because of these bugs,
Optimizeit cannot test reliably with the JDK 1.3.
These problems have been fixed in JDK 1.3.1 (j2se 1.3.1). Make sure to
either configure Optimizeit with JDK 1.3.1, or to use the JDK 1.2.2
reference implementation.
JDK 1.3.1 can be downloaded from http://java.sun.com/j2se/1.3/
download.html.
JDK 1.2.2 can be downloaded from http://java.sun.com/products/jdk/1.2/
download-solaris.html.

52 Co de C ove ra ge Use r ’s Guid e


Sta rt i ng yo ur ap plicat ion se rver

Starting your application server


1 (Windows only) Starting the testing in the VisualAge WebSphere Test
environment does not work. The browser reports an error message Error
503: Application is currently unavailable for service.
2 (Solaris only) When starting my application server with the parameters
required by Optimizeit, it fails to start and displays the error Cannot find
JVMPI(-3).
3 (UNIX only) My application server no longer starts since I configured it with
Optimizeit.
4 My application server starts, but when I try to attach from Optimizeit I get a
crash or an error dump.
5 Why can’t I attach from the Optimizeit GUI? Which port should I use to
attach? Why is no test information displayed when I attach?
6 (Windows only) Starting an applet from JBuilder does not work. Optimizeit
displays virtual machine not found error messages.
1 (Windows only) Starting the testing in the VisualAge WebSphere Test
environment does not work. The browser reports an error message
Error 503: Application is currently unavailable for service.
This problem happens if the JSPs are enabled in the web application you
are trying to test with Optimizeit. Unfortunately testing JSPs is only possible
inside VisualAge. So when you want to run the WebSphere Test
Environment with Optimizeit, you need to disable the JSPs. To do that, edit
the file <VisualAge_Dir>\ide\project_resources\IBM WebSphere Test
Environment\hosts\default_host\default_app\servlets\default_app.webapp.
In this file, comment out the deployment information for the JSP servlet. To
do that, add <!-- before the section:
<servlet>
<name>jsp</name>
<description>JSP support servlet</description>
and --> after the section:
<autostart>true</autostart>
<servlet-path>*.jsp</servlet-path>
</servlet>
2 (Solaris only) When starting my application server with the
parameters required by Optimizeit, it fails to start and displays the
error Cannot find JVMPI(-3).
This problem happens because you are using the JDK 1.2.x production
release. Optimizeit for Solaris does not support this JDK. The JDK 1.2.x
production release does not implement JVMPI well. JVMPI is the low-level
API from Sun used to retrieve information from the virtual machine.
Optimizeit fully supports the JDK 1.2.x reference implementation.

C ha pt er 8 : T r ou bl es h oo ti ng 53
Sta r ti ng y ou r ap pl i c at i on s er v e r

Note: To know if a JDK 1.2.x is a reference implementation or a production


release, type with this JDK:
java -version
If this command returns a line starting with “Solaris VM” you are running the
production release (not supported by Optimizeit), if it starts with “Classic
VM” you are running the reference implementation (fully supported by
Optimizeit).
3 (UNIX only) My application server no longer starts since I configured it
with Optimizeit.
First, make sure to check the outputs and/or log files of your application
server for any error message. Here are the most common issues:
■ On Solaris machines, you may be using the JDK 1.2.x or JDK 1.3
production release rather then the JDK 1.2.x reference
implementation or another supported virtual machine. Make sure to
read the JDK 1.2 section for more information.

In your application server configuration, the LD_LIBRARY_PATH (or native
library path) does not include the Optimizeit lib directory. When you
configure an application server with Optimizeit, you add the parameter -
Xrunoii. When the virtual machine is started with this parameter, it loads
the Optimizeit library liboii.so. If it cannot find it in the LD_LIBRARY_PATH,
the virtual machine fails to start. Make sure that the LD_LIBRARY_PATH, or
the library path of your application server points to the Optimizeit lib
directory.
4 My application server starts, but when I try to attach from Optimizeit I
get a crash or an error dump.
This could be caused by one of the following issues:
■ You are using an unsupported JVM. Check the Optimizeit list of
supported virtual machines in the Release Notes and make sure that
Optimizeit has access to a supported JVM. If you have integrated with
an application server, make sure that the application server is also using
a supported JVM.
■ Your bootclasspath does not contain oibcp.jar.
■ Your classpath does not contain optit.jar.
■ There is an older version of the oii.dll on the machine.

You have a Solaris machine and have not included the -Xboundthreads
option in your command.
5 Why can’t I attach from the Optimizeit GUI? Which port should I use to
attach? Why is no test information displayed when I attach?
When you integrate Optimizeit with an application server, you start the
Optimizeit audit system inside the virtual machine of the application server.
By attaching the Optimizeit GUI to the audit system, you test the virtual
machine of your application server and get the testing information for your
servlets/JSPs/EJBs. Optimizeit uses a port to get the testing information
from the audit system running in your application server. This port is only

54 Co de C ove ra ge Use r ’s Guid e


Proble ms du rin g te sting

used by Optimizeit and is not related to any port of your application server.
The default value for that port is 1470. If you start your application with
Optimizeit from a script, the port is specified in the script. If you use the
Optimizeit servlet to start the audit system, the port is specified from the
servlet. Make sure to use the correct port when you attach.
Make sure that the process running on the remote machine is running on
the port that you are attaching to. Also make sure that no other Optimizeit
user interface is trying to attach to that same audit system. Only one
Optimizeit user interface can attach to an audit system.
If you have other versions of Optimizeit, make sure that you have the same
versions of Optimizeit installed and running on both the host and remote
machine. For example, you cannot attach the Optimizeit Profiler 6.0 user
interface to an Optimizeit audit system from version 4.1.
If you change test parameters (for example, you check the Disable Memory
Profiler option), you must re-start your application server before beginning a
new test. You must also re-start your application server to connect with
another tool. For example, if you have been testing an application with
Profiler and want to run a test against the same application with Thread
Debugger, you must
a Shut down your Profiler test.
b Shut down your application server.
c Use the oiselector (Audit System Selector) to select Thread Debugger.
d Restart your application server.
e Start Optimizeit and attach to your test program.
For a test script, make sure that you use the correct -Xrun version for your
chosen tool: -Xrunpri for Profiler, -Xruncci for Code Coverage, and -Xruntdi
for Thread Debugger.
6 (Windows only) Starting an applet from JBuilder does not work.
Optimizeit displays virtual machine not found error messages.
When you define a new virtual machine within JBuilder, make sure to select
the executable java.exe in the bin directory, not in jre/bin.
Optimizeit uses oldjava.exe to start applets; this executable does not exist
inside the jre/bin directory.

Problems during testing


1 While testing my application, my application stops or crashes unexpectedly.
2 While testing my application, the application stops, the console shows a
java.lang.OutOfMemoryError.
3 Why can’t I test applets with my JRE?
4 (Windows only) During a testing session, the Optimizeit user interface
becomes unresponsive, and the Optimizeit window is all white.

C ha pt er 8 : T r ou bl es h oo ti ng 55
Prob le ms durin g t estin g

5 The Optimizeit GUI looks wrong. The text is clipped, the windows are the
wrong size.
6 Optimizeit seems to run slowly. Are there some strategies to improve
performance?
1 While testing my application, my application stops or crashes
unexpectedly.
Take a look at the external console. It may give more information on what
went wrong. If you do not have an external console, it means you have not
selected the Open A Console option in the Settings dialog box. Make sure
to select the option, and start the testing again.
Also, try running the same test using the default JDK installed with
Optimizeit. Sometimes, errors are related to the JVM used.
2 While testing my application, the application stops, the console
shows a java.lang.OutOfMemoryError.
The virtual machine ran out of memory. You can increase the size of the
java heap by using the extra java parameters -Xms and -Xmx. For example, -
Xms128m -Xmx128m sets the size of the java heap to 128 Mb.
If you are starting the testing from Optimizeit, add those parameters in the
Extra Java Parameters field on the Settings dialog box.
If you are starting your application from the command line, add those
parameters to your command. For example, the following command starts
the testing of BusyApp with the JDK 1.3, setting the size of the java heap to
256 Mb:
java -classic -Xrunoii:filter=<OptIt_Dir>/filters/DefaultAllOn.oif
-Xbootclasspath/a:<OptItDir>/lib/oibcp.jar -Xms256m -Xmx256m
intuitive.audit.Audit BusyApp
3 Why can’t I test applets with my JRE?
When you test applets with JDK 1.2 or 1.3, Optimizeit runs your applet in
the applet viewer using oldjava rather than java, to avoid security
exceptions. The JRE 1.2 and 1.3 do not include oldjava. This is why
Optimizeit requires a JDK to test applets.
However, you can still test applets with a JRE from Optimizeit by following
these steps:
a Edit the java.policy file of your JRE located under the lib\security
directory of your JRE.
b At the end of the file include the following lines:
grant codeBase "file:<OptItDir>/lib/optit.jar" { permission
java.security.AllPermission; };
c Replace <OptItDir> with the directory where you installed Optimizeit,
using / instead of \ (for example: c:/Optimizeit/OptimizeitSuite).
d Set the environment variable OI_APPLET_JRE to true.
4 (Windows only) During a testing session, the Optimizeit user interface
becomes unresponsive, and the Optimizeit window is all white.

56 Co de C ove ra ge Use r ’s Guid e


Proble ms du rin g te sting

This problem can occur if the Optimizeit user interface runs out of memory.
Optimizeit is a Java program. By default the virtual machine is created with
a minimum heap set to 8 Mb and a maximum heap set to 64 Mb.
You can override these default values by using the following environment
variables:
■ OIMINHEAP
■ OIMAXHEAP
These variables should be set to a new memory size. The notation should
be compatible with the virtual machine options -ms and -mx. For example,
12000 means 12000 bytes, 64K means 64 Kb and 64M means 64 Mb.
To increase the max heap to 128 Mb on Windows NT:
a From the Start menu, select the Settings menu and then Control Panel.
b Double-click on the System icon.
c Select the Environment tab.
d In the Variable field, enter OIMAXHEAP.
e In the Value field, enter 128M.
f Click on Set, and then Apply.
If increasing the heap size does not help, use the following procedure to
troubleshoot the issue:
g Open Windows Explorer.
h Browse and select the directory containing Optimizeit.
i Select the jre directory.
j Double click on startOptimizeit.bat to start Optimizeit with a console
window.
k Recreate the issue. Please send any error message / exception to
Borland Technical Support.
You may need to increase the console window buffer size to capture the
whole error message:
l Choose Properties from the console window.
m Select the Layout tab.
n Enter a larger value in the Screen buffer size height field.
5 The Optimizeit GUI looks wrong. The text is clipped, the windows are
the wrong size.
Some X-servers, including Exceed, have problems with Swing applications,
such as over-large fonts or wrong-sized windows. The best way to test
remotely is to run the Optimizeit GUI locally. If you test remotely from your
Windows platform on your UNIX machine, make sure to use Optimizeit for
Windows on the Windows platform.
To configure Exceed 7 to display the right fonts with Optimizeit:

C ha pt er 8 : T r ou bl es h oo ti ng 57
Un do i ng an i nt eg ra ti on ( W i nd ow s o nl y )

■ Open the Exceed Xconfig window from the Windows Start menu,
Hummingbird.../Exceed/Xconfig.

Double click the Font icon to open the Font Settings dialog box.

Click the Font Database button.

Unselect the Automatic Font Substitution option then click OK.

Restart Exceed.
6 Optimizeit seems to run slowly. Are there some strategies to improve
performance?
To improve Optimizeit performance:
■ Check the command line argument (shown in the console if you are
running from the user interface) and make sure there are no debugging
arguments passed into the JVM. The JVMPI and the debugging
interface cannot work simultaneously, so this will slow down
performance.

Are you using a Hotspot runtime? This can sometimes degrade
performance.
■ For Profiler, make sure you do not set the minimum heap size to a high
value. This causes the heap to be resized less often. For better
performance, use approximately a 4:1 ratio for RAM:Heap size. You can
use a 2:1 ratio as long as you also add RAM to cover non-heap VM use
and Optimizeit user interface overhead. disabling the garbage collector
will slow down the backtrace view in both Tree and Graph modes
because the instance count keeps increasing. This affects the time it
takes to compute the backtrace views.
■ For Profiler, you can improve performance by disabling the Memory
Profiler when you are testing CPU, or disabling the CPU Profiler when
you are testing memory use.

Undoing an integration (Windows only)


1 How do I undo the integration with VisualCafe?
2 How do I undo the integration with IBM VisualAge?
1 How do I undo the integration with VisualCafe?
Delete the file <CafeDir>\Bin\Components\oivcplugin.jar.
Also, VisualCafe stores some classes and other archives in a repository.
This repository can sometimes hold a reference to plug-ins. Rename the
file <CafeDir>\local.rps to <CafeDir>\local.rps.old and then start Cafe.
When a dialog appears, click yes. Cafe rebuilds the repository and the
problem goes away.
2 How do I undo the integration with IBM VisualAge?
Remove the directory <VisualAge>\ivjtools\tooldata\OptimizeitPlugin and
the directory <VisualAge>\ide\tools\OptimizeitPlugin.

58 Co de C ove ra ge Use r ’s Guid e


Index
Symbols Code Coverage
installing 2
! not character 11 integrating 3
# column 32 running 4
* wildcard character 11 using 1
command line, testing from 15
A command-line reports 39
configuration file 6, 13, 24
adding a virtual machine 12 configuring servlet support 48
adding API calls in your program 25 connection timeout 44
appending date and time console button 41
report names 38 console options 8
snapshot names 35 controlling the test program
applet pause 29, 33
testing 7 start 29, 33
application stop 29, 33
testing 7 coverage % column
application programming interface (API) 25 class 28
Attach panel 44 method 32
attaching the audit system 21
audit API 25
audit system
D
attaching 21 data export 40
configuring 44 debug line information 32
description 16 default
audit system start options class path 8
native 18 port 44
source path 45
C default display
class path 46
Calls column 32 setting 43
changing the default class path 46 virtual machine 47
changing the default source path 45 diff column 28
choosing displaying console messages 41
class path and source path 8
extra Java or program parameters 8
operation options 8
E
program location 7 Edit Settings dialog box 5, 43, 46
program type 7 environment variables 16, 39
class coverage examples
button 27 command line with JDK 1.2 20
mode 4 reports 40
options 28 exclude Filter option 11, 23
class name column 28 exclusive filters 9
class path 46 exporting data 40
class path window 8 extra Java parameters 8
classic runtime 13 extra program parameters 8
CLASSPATH environment variable 16, 30, 39, 46

I nde x 59
F M
File Export options 38 Mark button 29, 33
filter box 28 merging snapshots 36
Filter Editor 22 method coverage
Filter Editor columns 23 button 31
filters mode 4
creating 9 window options 32
editing 11 method name column 32
methodInfo report option 39
G missed lines column 32
g N
none option 28
generate snapshot on exit 8 native start option 18
generating reports not character 11
from the command line 39
within Code Coverage 38 O
generating snapshots 35
oibcp.jar 26
H Open A Console 8
Optimizeit
highlight since mark option 33 Integration Guide 3
host name 22
Hotspot runtime 13 P
I Pattern Editor 11
pause button 29, 33
ignore coverage column 23 port 44
include only Filter option 11, 23 used between the audit system and UI 17, 19
inclusive filters 10 port number 22
Inspector button 29, 33 preferences 4
inspector options default class path 46
highlight since mark 33 default source code 45
real time 33 launch 44
show diff 33 servlet 48
show method signature 33 startup 43
installing Code Coverage 2 virtual machine 47
integrating Optimizeit 3 preferences menu 8, 43
Integration Guide 3 program
intuitive.audit 25 location 7
invocation count column 32 options 8
types 7
J working directory 7
JAR files 46 R
Java 2 runtime 3
Java runtime option 13 readme file 2
Java setup wizard 3 real time option 33
JIT compiler 13 Release Notes 2
remote application
L connecting the audit system 21
testing 7, 21, 22
launch parameters 44 Report button 38
location field 7

60 Co de C ove ra ge Use r ’s Guid e


ReportGenerator options starting your test program 26
methodInfo 39 startup option 43
reportType 39 startup tab 6
showDiff 39 stop button 29, 33
showSignatures 39 System.err 8
showSource 39 System.in 8
sourcePath 39 System.out 8
verbose 39
reporting functions 4 T
reportType report option 39
running Code Coverage 4 testing
a program running on another machine 22
S applets 7
applications 7
selecting a virtual machine 47 remote applications 7, 21
selecting default displays 43 servlets 7
selecting test options 6 testing a program from the command line 15
servlet
testing 7 U
servlet testing 48
setting the source code location 45 using
setting up the audit system 16 Class Coverage view 27
setting virtual machine properties 13 Filter Editor 22
Settings dialog box 5, 46 Method Coverage 31
Settings Editor option 44 virtual machine wizard 3
Settings file 4
settings file 6, 13 V
show diff option 33
verbose report option 39
show method signature option 33
virtual machine
showDiff report option 39
adding 12
showSignatures report option 39
classpath 46
showSource report option 39
runtime 13
snapmerge executable 36
selecting 47
snapshots
setting properties 13
generating 35
starting automatically 25
merging 36
wizard 3
source code
Virtual Machines tab 12
directories 9
vm cannot exit 8
location 9, 45
vm options 8
table 32
Source Code column 32
source path 22 W
chooser 9, 45 when to use Code Coverage 1
sourcePath report option 39 wildcard character 11
start button 29, 33 working directory 7
starting from the test program 25
starting Optimizeit and connecting the audit
system 21

I nde x 61
62 Co de C ove ra ge Use r ’s Guid e

You might also like