Java Instrumentor - javi

Purpose

The SCI Instrumentor for Java inserts methods from a Target Deployment Port library into the Java source code under test. The Java Instrumentor is used for:

• Performance Profiling

  Code Coverage

  Runtime Tracing

Memory Profiling for Java uses the JVMPI Agent instead of source code insertion (SCI) technology as for other languages.

Syntax

javi <src> {[,<src> ]} [<options>]

where:

• <src> is one or several Java source files (input)

Description

The SCI Instrumentor builds an output source file from each input source file by adding specific calls to the Target Deployment Port method definitions. These calls are used by the product's runtime analysis features when the Java application is built and executed.

The Runtime Analysis tools are activated by selecting the command line options:

• -MEMPRO for Memory Profiling

• -PERFPRO for Performance Profiling

• -TRACE for Runtime Tracing

• -PROC and -BLOCK for Code Coverage (code coverage levels).

Note that there is no -COVERAGE option; the following rules apply for the Code Coverage feature:

• If no code coverage level is specified, nor Runtime Tracing, Memory Profiling, or Performance Profiling, then the default is to have code coverage analysis at the -PROC and -BLOCK=DECISION level.

• If no code coverage level is specified while one or more of the aforementioned features are selected, then code coverage analysis is not performed.

Detailed information about command line options for each feature are available in the sections below.

The Java Instrumentor creates the output files in a javi.jir directory, which is located inside the current directory. By default, this directory is cleaned and rewritten each time the Instrumentor is executed.

Although the Java Instrumentor can take several input source files on the command line, you only need to provide the file containing a main method for the Instrumentor to locate and instrument all dependencies.

The $CLASSPATH or $EDG_CLASSPATH environment variable must point to the native classes required by the Instrumentor. Alternatively, you can specify one or several additional classpaths by using the -CLASSPATH option of the Java Instrumentor. The -CLASSPATH option overrides the $CLASSPATH and $EDG_CLASSPATH environment variables -in that order- during instrumentation.

When using the Code Coverage feature, you can select one or more types of coverage at the instrumentation stage (see the User Guide for more information). When you generate reports, results from some or all of the subset of selected coverage types are available.

Options

-FILE= <filename>[{,<filename>}] | -EXFILE= <filename>[{,<filename>}]

-FILE specifies the only files that are to be explicitly instrumented, where <filename> is a Java source file. All other source files are ignored.

-EXFILE explicitely specifies the files that are to be excluded from the instrumentation, where <filename> is a Java source file. All other source files are instrumented.

Files that are excluded from the instrumentation process with the -EXFILE option are still analyzed. Any errors found in those files are still reported.

<filename> may contain a path (absolute or relative from the current working directory). If no path is provided, the current working directory is used.

-FILE and -EXFILE cannot be used together.

-NOFULLPATHKEY

This option forces the product to ignore the full path of files. Use this option if you need to consolidate test results when a same file can be identified with various paths, for example in a multi-user development environment using source control.

-CLASSPATH=<classpath>

The -CLASSPATH option overrides the $CLASSPATH and $EDG_CLASSPATH environment variables -in that order- during instrumentation.

In <classpath>, each path is separated by a colon (":") on UNIX systems and a semicolon (";") in Windows.

-OPP=<filename>

The -OPP option allows you to specify an optional definition file. The <filename> parameter is a relative or absolute filename.

-DESTDIR= <directory>

The -DESTDIR option specifies the location where the javi.jir output directory containing the instrumented Java source files is to be created. By default, the output directory is created in the current directory.

-PROC [=RET]

The -PROC option alone causes instrumentation of all classes and method entries. This is the default setting.

The -PROC=RET option instruments procedure inputs, outputs, and terminal instructions.

-BLOCK=IMPLICIT | DECISION | LOGICAL

The -BLOCK option alone instruments simple blocks only.

Use the IMPLICIT or DECISION (these are equivalent) option to instrument implicit blocks (unwritten else instructions), as well as simple blocks.

Use the LOGICAL parameter to instrument logical blocks (loops), as well as the simple and implicit blocks.

By default, the Instrumentor instruments implicit blocks.

-NOTERNARY

This option allows you to abstract the measure from simple blocks. If you select simple block coverage, those found in ternary expressions are not considered as branches.

-NOPROC

Specifies no instrumentation of procedure inputs, outputs, or returns, and so forth.

-NOBLOCK

Specifies no instrumentation of simple, implicit, or logical blocks.

-COUNT

Specifies count mode. By default, the Instrumentor uses pass mode. See the User Guide.

-COMPACT

Specifies compact mode. By default, the Instrumentor uses pass mode. See the User Guide.

-UNIT=<name>[{,<name>}] | -EXUNIT=<name>[{,<name>}]

-UNIT specifies Java units whose bodies are to be instrumented, where <name> is an Java package, class or method which is to be explicitly instrumented. All other units are ignored.

-EXUNIT specifies the units that are to be excluded from the instrumentation. All other Java units are instrumented.

-UNIT and -EXUNIT cannot be used together.

-DUMPINCOMING= <service>[{,<service>}]

-DUMPRETURNING= <service>[{,<service>}]

-MAIN= <service>

These options allow you to precisely specify where the SCI dump must occur. -MAIN is equivalent to -DUMPRETURNING.

-COMMENT= <comment>

Associates the text from either the Code Coverage Launcher (preprocessing command line) or from you with the source file and stores it in the FDC file to be mentioned in coverage reports. In Code Coverage Viewer, a magnifying glass is put in front of the source file. Clicking this magnifying glass shows this text in a separate window.

-NOCVI

Disables generation of a Code Coverage report that can be displayed in the Code Coverage Viewer.

-JTEST | -NOJTEST

The -JTEST option provides UML sequence diagram output for Component Testing for Java with HCL OneTest Embedded. -NOJTEST disables this output.

-NOCLEAN

When this option is set, the Instrumentor does not clear the javi.jir directory before generating new files.

-FDCDIR= <directory>

Specifies the destination <directory> for the .fdc correspondence file, which is generated for Code Coverage after the instrumentation for each source file. Correspondence files contain static information about each enumerated branch and are used as inputs to the Code Coverage Report Generator. If <directory> is not specified, each .fdc file is generated in the directory of the corresponding source file. If you do not use this option, the default .fdc files directory is the current working directory. You cannot use this option with the -FDCNAME option.

-FDCNAME= <name>

By default, the instrumentor generates one .fdc static correspondence file for each source file involved in the code to be instrumented. Use this option to specify a single static file for all source files in order to avoid file access conflicts, for example when a parallel build is involved. When this option is specified, the generated .fdc file contains one FDC section per source file. You cannot use this option with the -FDCDIR option.

-NO_UNNAMED_TRACE

With this option, anonymous classes are not instrumented.

-PERFPRO

This option activates Performance Profiling instrumentation. This produces output for a Performance Profile report.

-TRACE

This option activates Runtime Tracing instrumentation. This produces output for a UML sequence diagram.

-TSFDIR=<directory>

Specifies the destination <directory> for the .tsf static trace file, which is generated for Code Coverage after the instrumentation of each source file. If <directory> is not specified, each .tsf static trace file is generated in the directory of the corresponding source file. If you do not use this option, the default .tsf static trace file directory is the current working directory. You cannot use this option with the -TSFNAME option.

-TSFNAME=<filename>

Specifies the <name> of the .tsf static trace file that is to be produced by the instrumentation. You cannot use this option with the -TSFDIR option.

-INSTRUMENTATION=[FLOW|COUNT|INLINE]

Choose specifies the instrumentation mode. By default, count mode is used, which is a compromise between the flow mode (everything is a call to the Target Deployment Package) and the inline mode (when possible, the code is directly inserted into the generated file).

Warning: Inline mode must be used only in pass mode. Do not use this option if you want to know how many times a branch is reached.

-NOINFO

Asks the Instrumentor not to generate the identification header. This header is normally written at the beginning of the instrumented file.

-STUDIO_LOG

This option is for internal usage only.

Return Codes

After execution, the program exits with the following return codes

All messages are sent to the standard error output device.