This chapter describes how to perform the following tasks in the Cosmo Code development environment:
Getting Started
Using Breakpoints
Examining Data
Browsing Classes
Browsing Methods
Viewing and Switching Threads
Running Queries
The Cosmo Code interface is a window containing two decks: the Debug deck and the Query deck. Each deck contains tabbed cards that represent different debugging tools. Cards on the Debug deck contain tools for examining aspects of your program as it runs. Cards on the Query deck contain tools for performing static queries and viewing class structure and interaction. The Source card on the Debug deck appears in the interface when you first start Cosmo Code.
 | Note: Although the Query deck (Static Analysis subsystem) is installed by default, installation is optional and the Query deck may not be available in your configuration. |
To display a card containing a different debugging tool, click the left mouse button on the tab for the tool you want to view.
To move to a different deck of cards, click the left mouse button on one of the deck icons to the right of the card tabs.
You can view multiple cards or decks:
To view more than one card at the same time, clone an additional card by moving the mouse cursor over the tab for the card, pressing the right mouse button and selecting “Clone Card” from the menu. The card appears in a different window.
To view more than one deck at the same time, clone an additional deck by moving the mouse cursor over one of the card tabs in the deck or over the button for the deck, pressing the right mouse button and selecting “Clone Deck” from the menu. The deck appears in a different window.
To attach a program, type the pathname to the program in the Program field. This field also provides status information on your program.
To run, suspend, stop, or step through a program, use the control buttons below the card deck.
To debug a program at the command line, type debugging commands at the jdev prompt in the command-line debugging area.
To view the threads in your JavaTM program, run the program. Thread information is displayed in the Thread bar at the bottom of the window.
You can get more information on using the development environment in the following ways:
Select an option from the Help menu on the main menu bar.
Pass the cursor over an area of the window to get a one-line Quick Help string at the bottom of the window.
Type help in the command-line interface to get a list of available commands with syntax.
Make sure your JavaTM program has compiled successfully and generated .class files.
Choose one option below, depending on whether you are running an applet or a standalone Java application:
Click the Run button to run the program.
-or-
From the Admin menu, choose “Attach...”
In the dialog that appears, type the pathname to your program and click the OK button.
Click the Run button to run the program.
| Note: You can specify which program to run when you start Cosmo Code by typing jdev classname for a Java application or jdev filename.html for an applet. |
In the Source card on the Debug or Query deck:
Use the File Finder below the source display area to open a file in one of the following ways:
Type the pathname and filename into the text field, and press <Enter>.
Drag and drop a file into the drop pocket to the left of the text field.
Click the Recycle icon to view a file whose contents you have previously displayed.
The file status is shown to the right of the File Finder.
To view or edit the file, choose “Make Read Only” or “Make Editable” from the File menu.
-or-
In the Overview card on the Query deck:
In the Source card on the Debug or Query deck:
Display the source file.
Click Apply.
The Source card scrolls to the first occurrence of the element, and highlights all other occurrences.
Scroll to other occurrences in one of the following ways:
Use the Next and Previous buttons in the Search dialog
Use the location markers in the scroll bar of the Source card
Use the middle mouse button to click a marker to scroll to that point.
-or-
In the Source card on the Debug or Query deck:
| Note: You can view line numbers in a source file by setting the Show Line Numbers preference in Preferences dialog available from the Admin menu. |
In any card:
In the Cosmo Code Preferences dialog, use the Preference Category menu to choose the card for which you want to set preferences.
Set the preferences.
Click Apply to apply your choices and leave the window open, or click Close to apply your choices and close the window.
To browse classes or perform queries in your application, you need to create a database to represent the application. The database is created from a fileset, a text file called jdev.fileset that contains the list of .class files that make up your program.Your fileset should contain only .class files. The database is generated when you first switch to the Query deck or perform a query from the Source card.
In any card:
Click the Class check button below the file list to quickly select all .class files in the current directory.
Click the Add button to include the files in the fileset.
To include files from additional directories, click the directory name in the file list, or type the directory name in the Browsing Directory field, then click the Add button.
All files in the directory are added to the fileset.
Click Save to generate the fileset.
In the Source card on the Debug deck:
Using the File Finder, open the source file in which you want to set a breakpoint.
Scroll, or choose “Search...” from the Source menu, to find the point in the file where you want to set the breakpoint.
Place the cursor next to the line of source code in the column to the left of the Source Display area.
Click the left mouse button to set the breakpoint.
The line of source code is highlighted and a downward arrow appears in the column to the left of the source code. A breakpoint indicator also appears in the scroll bar to the right of the source code.
When the breakpoint is reached, all threads in your program are suspended.
In the Command-Line Debugging area:
Identify the file, class, or method in which you want to set a breakpoint.
Type in one of the following stop commands to set a breakpoint:
stop at class:line stop at file file.java:line stop at line stop in class:method
| Note: You can view line numbers in a source file by setting the Show Line Numbers preference in the Preferences dialog available from the Admin menu. |
In the Source card on the Debug deck:
Using the File Finder, display the source file containing the breakpoint you want to delete.
Find the breakpoint by scrolling the file or by clicking the middle mouse button on the breakpoint indicator in the scroll bar to jump to the breakpoint location.
Place the cursor in the Annotation column on the breakpoint arrow icon.
Click the left mouse button to delete the breakpoint.
In the Breakpoints card on the Debug deck:
Select the breakpoint you want to disable or enable.
Click the Disable or Enable button.
-or-
In the Annotation Column in the Source card:
Press the right mouse button when the cursor is over an enabled or disabled breakpoint.
From the menu, select either “Disable Breakpoint” or “Enable Breakpoint.”
Stepping is performed relative to a thread. When a breakpoint is reached, all threads are suspended, and you can then step through the code that a specific thread is executing. Note that if the thread you have designated as the current thread is in a suspended state and a breakpoint is reached in another thread, the context does not automatically switch to the thread where the breakpoint was encountered. The current thread must be running for the context to switch automatically to the thread where the breakpoint was encountered.
In the Source card on the Debug deck:
When execution of a thread is suspended at a breakpoint, use the Step, Next, or Return buttons to step through the code that the thread is executing.
Step Executes a single step in a line of source code. If a statement invokes a method, it is stepped “into.” That is, the next source statement is displayed, even if that statement is encountered in a different method.
Next Executes a single step in a line of source code. If a statement invokes a method, it is stepped “over.” That is, the next source statement in the current method is displayed, although statements in a different method are being executed.
Return Continues execution of the thread until the current method that is being executed returns. If you move up and down the call stack while a thread is suspended, clicking the Return button continues execution and returns from whichever method you are currently examining on the call stack.
To step more than one line at a time, press the right mouse button over the Step or Next button and select the number of lines to jump.
In any card:
Check that your program is running and that the Thread bar is visible at the bottom of the Cosmo Code window.
Click the thread you want to suspend from the Thread bar.
Click the Suspend button to suspend the thread.
You can choose to suspend all threads by pressing the right mouse button with the cursor over the Suspend button and choosing “All Threads” from the menu. If your code has reached a breakpoint, the default behavior is to suspend all threads.
Perform operations on the suspended thread as needed.
Click the Continue button to resume execution of the thread.
You can choose to continue all suspended threads by pressing the right mouse button with the cursor over the Continue button and choosing “All Threads” from the menu. If you are continuing from a breakpoint, the default behavior is to continue all suspended threads.
In the Source card on the Debug deck:
Select “Create Breakpoint...” from the Breakpoints menu.
Select “Exception Breakpoint” from the menu in the Breakpoint dialog.
Enter the name of the class provided as an argument to the throw statement in your source code.
Click the OK button.
In the Command-Line Debugging area:
Identify the exception object on which you want to set an exception. You can type exceptions in the command-line interface to get a list of handled exceptions.
Type stop exception exception_object to set a breakpoint which stops execution when exception_object is thrown.
In the Command-Line Debugging area:
Type exceptions at the prompt to get a list of all handled exceptions in your program.
In the Callstack card on the Debug deck:
Make sure your program is running and the Thread bar is visible.
In the Thread bar, click the thread for which you want to view the call stack.
Click the Suspend button.
The call stack is displayed in the Callstack display area.
To view the source code for a call on the stack, double-click the call you want to examine.
The source code for the call is displayed in the Source card.
Note: You can view only user code and files not marked <stripped> in the call stack.
In any card:
In the Source card on the Debug deck:
Make sure your program was compiled using javac -g. You must use the -g flag to get symbol information.
Make sure the file containing the symbol you want to evaluate is displayed.
If the file containing the symbol you want to evaluate is not displayed, use the File Finder below the source display area to open the file.
Find the symbol in the file by scrolling or choosing “Search...” from the Source menu.
Move the cursor over the symbol.
The value of the symbol appears under the cursor.
-or-
In the Command-line Debugging area:
-or-
In the Source card on the Debug deck:
Select the symbol to evaluate in the source file.
Select “Examine” from the right mouse button menu, or use the Examine button below the source code display area.
This opens the Data card, displaying the symbol and its value.
To view the value of the same expression each time a breakpoint is reached or a thread is explicitly suspended, add the expression to the Expression View table by clicking Keep when the expression is displayed in the Data card.
In the Source card on the Debug deck:
Select the object (an array or instance) in the Source Display area.
Click the Examine button.
The object's handle is displayed in the Data card.
Double-click the handle to view the contents of the object in the Expression Details area.
-or
In the Data card on the Debug deck:
Type an asterisk (*) followed by the name of the object into the Target field. The contents of the object are displayed in a table in the Data card. You can also double-click any item that is a handle to view its contents.
In the Overview card on the Query deck:
Select “Class List” from the View menu to display all classes in the fileset in the List Display area. This list also includes JavaTM interface types.
In the Class card on the Query deck:
In the text entry field at the top of the Class card, type ? to display the Browsing choices window.
The Browsing Choices window lists all classes and interface types in the fileset and provides information about class type: JavaTM class, Java interface, Java Abstract Class, and Java Final Class.
In the Overview card on the Query deck:
Display all classes by selecting “Class List” from the View menu.
Double-click a class to display the class in the Class card.
-or-
In the Class card on the Query deck:
Display a class in one of the following ways:
Type the class name in the text entry field at the top of the window and press <Enter>.
Type ? to display the Browsing Choices window, then double-click the name of the class you want to browse.
Use the List areas in the Class card to view the class or click on the Class Graph button.
In the Overview or Query cards on the Query deck:
Make sure the class you want to edit is displayed in the card.
Select the class.
Press the right mouse button and choose “Show Definition” from the menu.
The file containing the class definition is displayed in the Source card on the Query deck.
Make sure the file is editable by opening the Source menu and checking that the Make Read Only/Make Editable toggle is set correctly.
Edit the file.
Save the file.
-or-
In the Class Card on the Query deck:
Make sure the class you want to edit is displayed in the Class Relations List.
Select the class.
Press the right mouse button and choose “Show Source” from the menu.
The file containing the class definition is displayed in the Source card on the Query deck.
Make sure the file is editable by opening the Source menu and checking that the Make Read Only/Make Editable toggle is set correctly.
Edit the file.
Save the file.
In the Query card on the Query deck:
Type the name of the class into the Query Target field.
Select “Find Matching Classes” from the Query menu.
Click the Do Query button.
Select the class in the display area and press the right mouse button.
From the Class Actions popup menu, choose “List Classes Using.”
The Query display area shows each use of the class with file and line number information.
-or-
In the Class card on the Query deck:
Display the class in one of the following ways:
Type the class name in the text entry field at the top of the window and press <Enter>.
Type ? to display the Browsing Choices window, then double-click the name of the class you want to browse.
Examine the “Used By” section of the Class Relations List on the right-hand side of the Class Card.
In the Overview card on the Query deck:
Double-click the class for which you want to display a graph.
In the Class card, click the button for the type of graph you want to display: Class Graph or Call Graph.
The graph is displayed in either the Class Graph or the Call Graph window.
In the Class Graph window, you can switch graphs using the option menu at the bottom of the window, or you can switch the class you are viewing by double-clicking the class name in the graph.
In the Overview card on the Query deck:
Select “Method List” from the View menu.
All methods in the fileset are displayed in the Overview card.
In the Overview card on the Query deck:
Select “Method List” from the View menu.
Select the method in the display area.
Press the right mouse button to view the Method Actions menu.
Select “List Methods Using” from the menu.
The results are displayed in the Query card. You can make additional queries by selecting methods in the Query card and using the right mouse button menu.
-or-
In the Class card on the Query deck:
Display the class containing the method you want to trace.
Select the method and press the right mouse button to view the Queries on Methods menu.
Select “What Uses” from the menu.
All methods and classes that use the selected method are highlighted.
In the Overview, Query, and Class cards on the Query deck:
Double-click the method name to display the source code for the method in the Source card on the Query deck.
In the Cosmo Code window:
When you run Cosmo Code, a Thread bar that displays all threads including threads for standard class libraries appears at the bottom of the Cosmo Code window. The thread bar is empty if there are no threads running.
-or-
In the command-line interface:
Type the command threads at the jdev prompt in the command-line area at the bottom of the Cosmo code window.
This displays status information on all threads in the program.
In the Thread bar, select the thread for which you want to view the status.
Thread information is displayed in the Status area below the Card deck, as in the following example:
Thread 10, Thread-7:running Thread 3, Screen Updater: cond. waiting |
The following states are possible for a thread: zombie, running, sleeping, waiting in a monitor, cond. waiting, suspended, and at breakpoint.
In the Cosmo Code window:
Make sure your program is running.
In the Thread bar, click a thread button to make it the current thread.
The control buttons and Debug deck are now active for the thread you have selected.
In the Overview card on the Query deck:
Display a list containing the element you want to query by selecting “Class List”, “Method List”, or “File List” from the View menu.
Select the element you want to query.
Press the right mouse button and select the appropriate query from the popup menu.
In the Query card on the Query deck:
Select the item to query in the display area, or type an item name into the Query Target text field.
Note: If you do not see the item you want to query, use the Overview card to list the item you want to query and perform the query from the Overview card. Click the Do Query button.
In the Class card on the Query deck:
Make sure the class you want to perform the query on is displayed in the Class card.
Select the element you want to query.
Press the right mouse button in the List Areas and select the appropriate query from the popup menu.
The query results are shown in the Class card by highlighting items that match the query. A query description is displayed above the list areas.
When you first perform a query from the Overview card or the Results card, or when you specifically regenerate the query database files, files with a .jsuds extension are placed in a .jsuds subdirectory in the same directory as the .class files. In the case of classes where you do not have write permission to the directory, you can use the Preferences dialog to set up a directory for the .jsuds files. The default directory is a .jsuds subdirectory in your home directory (~/.jsuds).
In any card on the Query deck:
From the Admin menu, select “Preferences...”
In the Cosmo Code Preferences dialog, select “Overview” from the Preference Category menu.
In the Generated Files Directory field, specify the directory you want to contain database-related files.
Click the OK button to close the Cosmo Code Preferences dialog.
In any card:
In the “Fileset” field of the Attach Program Dialog, type the pathname of the directory that contains an existing fileset or type the name of the directory in which you want to create a new fileset, followed by the filename jdev.fileset.
Click OK.
In the Fileset Editor, check that the directory you specified appears in the Current Fileset field.