Java in Adaptive Server Enterprise

Chapter 6 Debugging Java in the Database

Chapter 6

Debugging Java in the Database

This chapter describes the Sybase Java debugger and how you can use it when developing Java in Adaptive Server.

Introduction to Debugging Java

You can use the Sybase Java debugger to test Java classes and fix problems with them.

How the Debugger Works

The Sybase Java debugger is a Java application that runs on a client machine. It connects to the database using the Sybase jConnect JDBC driver.

The debugger debugs classes running in the database. You can step through the source code for the files as long as you have the Java source code on the disk of your client machine. (Remember, the compiled classes are installed in the database, but the source code is not).

Requirements for Using the Java Debugger

To use the Java debugger, you need:

A Java runtime environment such as the Sun Microsystems Java Runtime Environment, or the full Sun Microsystems JDK on your machine.
The source code for your application on your client machine.

What You Can Do with the Debugger

Using the Sybase Java debugger, you can:

Trace execution - Step line by line through the code of a class running in the database. You can also look up and down the stack of functions that have been called.
Set breakpoints - Run the code until you hit a breakpoint, and stop at that point in the code.
Set break conditions - Breakpoints include lines of code, but you can also specify conditions when the code is to break. For example, you can stop at a line the tenth time it is executed, or only if a variable has a particular value. You can also stop whenever a particular exception is thrown in the Java application.
Browse classes - You can browse through the classes installed into the database that the server is currently using.
Inspect and set variables - You can inspect the values of variables alter their value when the execution is stopped at a breakpoint.
Inspect and break on expressions - You can inspect the value of a wide variety of expressions.

Using the Debugger

This section describes how to use the Java debugger. The next section provides a simple tutorial.

Starting the Debugger and Connecting to the Database

The debugger is the JAR file Debug.jar, installed in your Adaptive Server installation directory in $SYBASE/$SYBASE_ASE/debugger. If it is not already present, add this file as the first element to your CLASSPATH environment variable.

Debug.jar contains many classes. To start the debugger you invoke the sybase.vm.Debug class, which has a main( ) method.You can start the debugger in three ways:

Run the jdebug script located in $SYBASE/$SYBASE_ASE/debugger.
"A Debugging Tutorial" provides a sample debugging session using the jdebug script.
From the command line, enter:
```
java  sybase.vm.Debug
```
In the Connect window, enter a URL, user login name, and password to connect to the database.
From Sybase Central:
- Start Sybase Central and open the Utilities folder, under Adaptive Server Enterprise.
- Double-click the Java debugger icon in the right panel.
- In the Connect window, enter a URL, user login name, and password to connect to the database.

Compiling Classes for Debugging

Java compilers such as the Sun Microsystems javac compiler can compile Java classes at different levels of optimization. You can opt to compile Java code so that information used by debuggers is retained in the compiled class files.

If you compile your source code without using switches for debugging, you can still step through code and use breakpoints. However, you cannot inspect the values of local variables.

To compile classes for debugging using the javac compiler, use the -g option:

javac  -g ClassName.java

Attaching to a Java VM

When you connect to a database from the debugger, the Connection window shows all currently active Java VMs under the user login name. If there are none, the debugger goes into wait mode. Wait mode works like this:

Each time a new Java VM is started, it shows up in the list.
You may choose either to debug the new Java VM or to wait for another one to appear.
Once you have passed on a Java VM, you lose your chance to debug that Java VM. If you then decide to attach to the passed Java VM, you must disconnect from the database and reconnect. At this time, the Java VM appears as active, and you can attach to it.

The Source Window

The Source window:

Displays Java source code, with line numbers and breakpoint indicators (an asterisk in the left column).
Displays execution status in the status box at the bottom of the window.
Provides access to other debugger windows from the menu.

The Debugger Windows

The debugger has the these windows:

Breakpoints window - Displays the list of current breakpoints.
Calls window - Displays the current call stack.
Classes window - Displays a list of classes currently loaded in the Java VM. In addition, this window displays a list of methods for the currently selected class and a list of static variables for the currently selected class. In this window you can set breakpoints on entry to a method or when a static variable is written.
Connection window - The Connection window is shown when the debugger is started. You can display it again if you wish to disconnect from the database.
Exceptions window - You can set a particular exception on which to break, or choose to break on all exceptions.
Inspection window - Displays current static variables, and allows you to modify them. You can also inspect the value of a Java expression, such as the following:
- Local variables
- Static variables
- Expressions using the dot operator
- Expressions using subscripts []
- Expressions using parentheses, arithmetic, or logical operators.
  For example, the following expressions could be used:
```
x[i].field
q + 1
i == 7
(i + 1)*3
```
Locals window - Displays current local variables, and allows you to modify them.
Status window - Displays messages describing the execution state of the Java VM.

Options

The complete set of options for stepping through source code are displayed on the Run menu. They include the following:

Function	Shortcut key	Description
Run	F5	Continue running until the next breakpoint, until the Stop item is selected, or until execution finishes.
Step Over	F7 or Space	Step to the next line in the current method. If the line steps into a different method, step over the method, not into it. Also, step over any breakpoints within methods that are stepped over.
Step Into	F8 or i	Step to the next line of code. If the line steps into a different method, step into the method.
Step Out	F11	Complete the current method, and break at the next line of the calling method.
Stop		Break execution.
Run to Selected	F6	Run until the currently selected line is executed and then break.
Home	F4	Select the line where the execution is broken.

Setting Breakpoints

When you set a breakpoint in the debugger, the Java VM stops execution at that breakpoint. Once execution is stopped, you can inspect and modify the values of variables and other expressions to better understand the state of the program. You can then trace through execution step by step to identify problems.

Setting breakpoints in the proper places is a key to efficiently pinpointing the problem execution steps.

The Java debugger allows you to set breakpoints not only on a line of code, but on many other conditions. This section describes how to set breakpoints using different conditions.

Breaking on a Line Number

When you break on a particular line of code, execution stops whenever that line of code is executed.

To set a breakpoint on a particular line:

In the Source window, select the line and press F9.
Alternatively, you can double-click a line.

When a breakpoint is set on a line number, the breakpoint is shown in the Source window by an asterisk in the left column. If the Breakpoints window is open, the method and line number is displayed in the list of breakpoints.

You can toggle the breakpoint on and off by repeatedly double-clicking or pressing F9.

Breaking on a Class Method

When you break on a method, the break point is set on the first line of code in the method that contains an executable statement.

To set a breakpoint on a class method:

From the Source window, choose Break--> New. The Break At window is displayed.
Enter the name of a method in which you wish execution to stop. For example:
```
JDBCExamples.selecter
```
stops execution whenever the JDBCExamples.selecter( ) method is entered.

When a breakpoint is set on a method, the breakpoint is shown in the Source window by an asterisk in the left column of the line where the breakpoint actually occurs. If the Breakpoints window is open, the method is displayed in the list of breakpoints.

Using Counts with Breakpoints

If you set a breakpoint on a line that is in a loop, or in a method that is frequently invoked, you may find that the line is executed many times before the condition you are really interested in takes place. The debugger allows you to associate a count with a breakpoint, so that execution stops only when the line is executed a set number of times.

To associate a count with a breakpoint:

From the Source window, select Break-->Display. The Breakpoints window is displayed.
In the Breakpoints window, click a breakpoint to select it.
Select Break-->Count. A window is displayed with a field for entering a number of iterations. Enter an integer value. The execution will stop when the line has been executed the specified number of times.

Using Conditions with Breakpoints

The debugger allows you to associate a condition with a breakpoint, so that execution stops only when the line is executed and the condition is met.

To associate a condition with a breakpoint:

From the Source window, select Break-->Display. The Breakpoints window is displayed.
In the Breakpoints window, click a breakpoint to select it.
Select Break-->Condition. A window is displayed with a field for entering an expression. The execution will stop when the condition is true.
The expressions used here are the same as those that can be used in the Inspection window, and include the following:
- Local variables
- Static variables
- Expressions using the dot operator
- Expressions using subscripts []
- Expressions using parentheses, arithmetic, or logical operators.

Breaking When Execution Is Not Interrupted

With a single exception, breakpoints can only be set when program execution is interrupted. If you clear all breakpoints, and run the program you are debugging to completion, you can no longer set a breakpoint on a line or at the start of a method. Also, if a program is running in a loop, execution is continuing and is not interrupted.

To debug your program under either of these conditions, select Run-->Stop from the Source window. This stops execution at the next line of Java code that is executed. You can then set breakpoints at other points in the code.

Disconnecting from the Database

When the program has run to completion, or at anytime during debugging, you can disconnect from the database from the Connect window. Then, exit the Source window and reconnect to the database after the debug program terminates.

A Debugging Tutorial

This section takes you through a simple debugging session.

Before You Begin

The source code for the class used in this tutorial is located in $SYBASE/$SYBASE_ASE/sample/JavaSql/manual-examples/JDBCExamples.java.

Before you run the debugger, compile the source code using the javac command with the -g option.

See "Creating Java Classes and JARs" on page 22 for complete instructions for compiling and installing Java classes in the database.

Start the Java Debugger and Connect to the Database

You can start the debugger and connect to the database using a script, command line options, or Sybase Central. In this tutorial, we use jdebug to start the debugger. You can use any database.

Follow these steps:

Start Adaptive Server.
If Java queries have not yet been executed on your server, run any Java query to initialize the Java subsystem and start a Java VM.
Run the $SYBASE/$SYBASE_ASE/debugger/jdebug script. jdebug prompts you for these parameters:
- Machine name of the Adaptive Server
- Port number for the database
- Your login name
- Your password
- An alternate path to Debug.jar if its location is not in your CLASSPATH

Once the connection is established, the debugger window displays a list of available Java VMs or "Waiting for a VM."

Attach to a Java VM

To attach to a Java VM from your user session:

With the debugger running, connect to the sample database from isql as the sa:
```
$SYBASE/bin/isql  -Usa -P
```
You cannot start Java execution from the debugger. To start a Java VM you must carry out a Java operation from another connection using the same user name.
Execute Java code using the following statements:
```
select JDBCExamples.serverMain('createtable')
select  JDBCExamples.serverMain('insert')
select  JDBCExamples.serverMain('select')
```
The Sybase Java VM starts in order to retrieve the Java objects from the table. The debugger immediately stops execution of the Java code.
The debugger Connection window displays the Java VMs belonging to the user in this format:
```
VM#: "login_name,  spid:spid#"
```
In the debugger Connection window, click the Java VM you want and then click Attach to VM. The debugger attaches to the Java VM and the Source window appears. The Connection window disappears.
Next, enable the Source window to show the source code for the method. The source code is available on disk.

Load Source Code into the Debugger

The debugger looks for source code files. You need to make the $SYBASE/$SYBASE_ASE/sample/JavaSql/manual-examples/ subdirectory available to the debugger, so that the debugger can find source code for the class currently executing in the database.

To add a source code location to the debugger:

From the Source window, select File-->Source Path. The Source Path window displays.
From the Source Path window, select Path-->Add. Enter the following location into the text box:
```
$SYBASE/$SYBASE_ASE/sample/JavaSql/
            manual-    examples/
```
The source code for the JDBCExamples class displays in the window, with the first line of the Query method serverMain( ) highlighted. The Java debugger has stopped execution of the code at this point.
You can now close the Source Path window.

Step Through Source Code

You can step through source code in the Java debugger in several ways. In this section we illustrate the different ways you can step through code using the serverMain( ) method.

When execution pauses at a line until you provide further instructions, we say that the execution breaks at the line. The line is a breakpoint. Stepping through code is a matter of setting explicit or implicit breakpoints in the code, and executing code to that breakpoint.

Following the previous section, the debugger should have stopped execution of JDBCExamples.serverMain( ) at the first statement:

Examples

Here are some steps you can try:

Stepping into a function - press F7 to step to the next line in the current method.
Press F8 to step into the function doAction( ) in line 99.
Run to a selected line. You are now in function doAction( ). Click on line 155 and press F6 to run to that line and break:
```
String workString = "Action(" + action + ")";
```
Set a breakpoint and execute to it - select line 179 and press F9 to set a breakpoint on that line when running "isql> select JDBCExamples.serverMain('select')":
```
workString + = selecter(con);
```
Press F5 to execute to that line.
Experiment - try different methods of stepping through the code. End with F5 to complete the execution.
When you have completed the execution, the Interactive SQL Data window displays:
```
Action(select) - Row  with id = 1: name(Joe Smith)
```

Inspecting and Modifying Variables

You can inspect the values of both local variables (declared in a method) and class static variables in the debugger.

Inspecting Local Variables

You can inspect the values of local variables in a method as you step through the code, to better understand what is happening.

To inspect and change the value of a variable:

Set a breakpoint at the first line of the selecter( ) method from the Breakpoint window. This line is:
```
String sql = "select  name, home from xmp where
            id=?";
```
In Interactive SQL, enter the following statement again to execute the method:
```
select JDBCExamples.serverMain('select')
```
The query executes only as far as the breakpoint.
Press F7 to step to the next line. The sql variable has now been declared and initialized.
From the Source window, select Window-->Locals. The Local window appears.
The Locals window shows that there are several local variables. The sql variable has a value of zero. All others are listed as not in scope, which means they are not yet initialized.
You must add the variables to the list in the Inspect window.
In the Source window, press F7 repeatedly to step through the code. As you do so, the values of the variables appear in the Locals window.
If a local variable is not a simple integer or other quantity, then as soon as it is set a + sign appears next to it. This means the local variable has fields that have values. You can expand a local variable by double-clicking the + sign or setting the cursor on the line and pressing Enter.
Complete the execution of the query to finish this exercise.

Modifying Local Variables

You can also modify values of variables from the Locals window.

To modify a local variable:

In the debugger Source window, set a breakpoint at the following line in the selecter( ) method of the serverMain class:
```
String sql = "select name, home from  xmp where
            id=?";
```
Step past this line in the execution.
Open the Locals window. Select the id variable, and select Local-->Modify. Alternatively, you can set the cursor on the line and press Enter.
Enter a value of 2 in the text box, and click OK to confirm the new value. The id variable is set to 2 in the Locals window.
From the Source window, press F5 to complete execution of the query. In the Interactive SQL Data window, an error message displays indicating that no rows were found.

Inspecting Static Variables

You can also inspect the values of class-level variables (static variables).

To inspect a static variable:

From the debugger Source window, select Window-->Classes. The Classes window is displayed.
Select a class in the left box. The methods and static variables of the class are displayed in the boxes on the right.
Select Static-->&Igr;&ngr;σ&pgr;[epsiv]χ&tgr;. &Tgr;&eegr;[epsiv] &Igr;&ngr;σ&pgr;[epsiv]χ&tgr; &ohgr;ι&ngr;δ&ogr;&ohgr; ισ δισ&pgr;&lgr;αψ[epsiv]δ. &Igr;&tgr; &lgr;ισ&tgr;σ &tgr;&eegr;[epsiv] ϖαρια&bgr;&lgr;[epsiv]σ αϖαι&lgr;α&bgr;&lgr;[epsiv] &phis;&ogr;ρ ι&ngr;σ&pgr;[epsiv]χ&tgr;ι&ogr;&ngr;.

XML ResultSet Documents: Invalid XML Characters


	Expand Search