JReach is a coverage tool that monitors the execution of a Java application to determine which lines are never executed. The lines that are never reached are written to a detail file. The percent coverage of each class and the entire application are written to a summary file. An XML file is created containing the summary and detail information and can be used for custom processing or viewed by a browser.

The following files were produced by running JReach against the sample CoverageTester.java:

CoverageTester-Summary.txt (tab-delimited file best viewed with a spreadsheet program)

Source File	Unreached	TotalLines	Covered%	Message
C:\src\com\branestorm\profiler\CoverageTester.java	6	128	95%
Total lines:	6	128	95%

CoverageTester-Detail.txt (tab-delimited file best viewed with a spreadsheet program)

Source File	LineNo	UnreachedLine
C:\src\com\branestorm\profiler\CoverageTester.java	26	{ int i = 1;
C:\src\com\branestorm\profiler\CoverageTester.java	47	{ System.out.println("This statement is never reached because first is not "
C:\src\com\branestorm\profiler\CoverageTester.java	48	+ "false");
C:\src\com\branestorm\profiler\CoverageTester.java	51	{ System.out.println("This statement is never reached because second"
C:\src\com\branestorm\profiler\CoverageTester.java	52	+ " is not "
C:\src\com\branestorm\profiler\CoverageTester.java	53	+ "true");

CoverageTester.xml (XML file that can be viewed in a browser using the provided XSL style sheet. View source to see the underlying XML.)

Running JReach

Run JReach using the following command-line syntax:

java com.branestorm.profiler.JReach <options> <class> <args for class>

The available command-line options are:

-output <directory>	specifies the directory where the output files will be written
-source <directory>	specifies a source directory (can be repeated if needed)
-classpath or –cp <directory>	adds a directory to the class path (can be repeated if needed)
-exclude <class>	specifies a class exclusion filter such as java.* (can be repeated if needed)
-ignore <substring>	ignores lines containing the specified substring (can be repeated if needed)
-xsl <file>	style sheet to used when displaying the XML file
-help	displays these options

The CoverageTester files were created using the following statement:

java com.branestorm.profiler.JReach -output C:\ \temp -source C:\src\ com.branestorm.profiler.CoverageTester

Your ClassPath must include the following files:

JReach.jar	This file is shipped with this document.
jpda_home\lib\tools.jar	This file is included in SDK 1.4 and later. You can download the SDK from http://java.sun.com

JReach searches for JReach.profile in the current directory, source directories, class path directories, and the system library path. This file contains your registration information and can also be used to specify command-line options as described in the next section.

JReach.profile

The following registration information is read from the JReach.profile file:

user=<user name>	Registered user
company=<company name>	Optional company name
until=<release>	Release number requiring a new registration
lines=<line limit>	Maximum number of lines that can be monitored
key=<registration key>	Registration key

The remaining options can be specified on the command-line, in JReach.profile, or read from another file using:

import <file specification>

classpath or cp=<directory>	adds a directory to the class path (can be repeated if needed)
source=<directory>	specifies a source directory (can be repeated if needed)
exclude=<class>	specifies a class exclusion filter such as java.* (can be repeated if needed)
ignore=<substring>	ignores lines containing the specified substring (can be repeated if needed)
xsl=<file>	style sheet to used when displaying the XML file

Reports

This section shows some cases that may be unclear:

Code Sample	Coverage Detail
1 public sampleClass ( ) 2 { // Default constructor 3 }	If the default constructor is never used to create an object, then the coverage detail will show: 2 { // Default constructor
1 if (condition) 2 { // Condition is true 3 } else 4 System.out.println(“Condition is false”);	The detail report will show that line 2 is never reached even if the condition is true during execution. This happens because the Java VM allows a breakpoint to be set on line 2, but it never stops there. You can code around this bug by changing line 2 to: { int JVMbug=1; // The Java Virtual Machine won’t break here // Condition is true
1 if (condition) 2 break;	The detail report will show that line 2 is never reached even if the condition is true during execution. You can change line 2 to: { int JVMbug=1; // The Java Virtual Machine won’t break here break; }
1 try 2 { // Try block goes here 3 } catch (Exception e) 4 { throw new Exception(“sample”); 5 } 6 finally 7 { myFile.close(); 8 }	The detail report will show that lines 4 and 7 are never reached. You can code around this bug by preceding each line with: int JVMbug=1; // The Java Virtual Machine won’t break here

Troubleshooting

The most common problem is not having the needed JAR files in the class path. Because JReach launches a copy of the Java Virtual Machine, the class path could be right for one, but not the other. The following sequence shows the types of errors you will get when JAR files are not in your class path:

Example# 1:	java com.branestorm.profiler.JReach
Error:	Exception in thread "main" java.lang.NoClassDefFoundError: com/branestorm/profiler/JReach
Cause:	jreach.jar is not in the class path
Example# 2:	java –cp jreach.jar com.branestorm.profiler.JReach
Error:	Exception in thread "main" java.lang.NoClassDefFoundError: com/sun/jdi/connect/VMStartException
Cause:	tools.jar is not in the class path
Example# 3:	java –cp jreach.jar;tools.jar com.branestorm.profiler.JReach
Error:	<class> missing
Cause:	You didn’t specify the class you want JReach to monitor
Example# 4:	java –cp jreach.jar;tools.jar com.branestorm.profiler.JReach com.branestorm.profiler.CoverageTester
Error:	java.lang.NoClassDefFoundError: com/branestorm/profiler/CoverageTester
Cause:	The Java VM launched by JReach could not find CoverageTester
Example# 5:	java –cp jreach.jar;tools.jar com.branestorm.profiler.JReach –cp jreach.jar com.branestorm.profiler.CoverageTester
Error:	None
Cause:	This example runs fine because all needed class paths are specified on the command line. It is a lot easier to just add the needed JAR files to your class path!

Here are some other errors you might encounter:

Example# 6:	You get the following exception:
Error:	Exception in thread "main" java.lang.NoSuchMethodError: com.sun.jdi.Location.sourcePath()Ljava/lang/String;
Cause:	You need a version of tools.jar from SDK 1.4 or later. You can download the SDK from http://java.sun.com
Example# 7:	You get the following exception:
Error:	Exception in thread "main" java.lang.UnsupportedClassVersionError: com/sun/jdi/connect/VMStartException (Unsupported major.minor version 48.0)
Cause:	You need to recompile your application using SDK 1.4 or later, which you can download from http://java.sun.com
Example# 8:	Detail report shows lines that are obviously incorrect
Error:	Lines show that are not executable and/or on which the debugger stops if you set a break point
Cause:	This can happen if two classes map to the same source lines. For example, if classes A and B are in the same file, and you delete class A, then A.class and B.class will map to the same source lines. To resolve this problem, you must delete A.class and recompile all of your code.

Distribution Files

The following files are included in JReach.zip:

File Name	Description
coverage.xsl	Style sheet that can be used to display XML files
CoverageTester.txt	Sample Java source mentioned above
CoverageTester.xml	Sample XML file created by JReach
CoverageTester-Detail.txt	Sample Detail file created by JReach
CoverageTester-Summary.txt	Sample Summary file created by JReach
JReach.htm	This document
JReach.jar	Contains the JReach class files
JReach.profile	Registration file (demo version allowing limited use)
License.htm	License agreement

Registration

JReach is distributed as shareware. If you would like to continue using it, you can purchase it by clicking here

Support

If you have questions or comments, please e-mail them to: mail@branestorm.com