This chapter describes in detail the function of each window, menu, and display in the Cosmo Code development environment (jdev). In addition, the chapter describes commands available on the command line.
This chapter contains the following sections:
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. The main Cosmo Code window also contains buttons for controlling execution of your program, a program field, a command-line interface pane, and a Thread bar.
 | 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. |
The interface contains the following elements:
You can get help on using the development environment via the Help menu on the main menu bar; a one-line Quick Help bar in the lower-left corner of the window for each area of the interface; and the help command in the command-line interface.
Quick Help is attached to the position of the cursor. Whenever the cursor is over a certain area of the Cosmo Code window (the control buttons, the menu bar, and so on), a line of text giving a brief description of the area appears in the lower-left corner of the window.
The Admin menu performs general management functions dealing with programs, windows, and user preferences. This menu is available on all cards and provides these selections:
| “Attach...” | Displays the “Attach Program Dialog” which allows you to specify a program to run and a fileset for performing queries. | |
| ”Search Path...” |
| |
| “Set Classpath and Flags...” |
| |
| “Edit Fileset...” | Displays the “Fileset Editor” which allows you to select files for inclusion in a fileset and create a fileset. | |
| “Preferences...” | Displays the “Preferences Dialog” which allows you to set configration preferences for the different tools in the environment. | |
| “Save As Text...” |
| |
| “Quit” | Exits Cosmo Code. |
The Attach Program Dialog allows you to load a program into the Cosmo Code environment. If you installed the Query deck (the Static Analysis subsystem), this dialog also allows you to specify a fileset to use in generating a database for performing queries.
The File Search Path dialog allows you to specify paths to use for files during a debugging session. If your program is stopped and you would like to specify an alternative file to use in continuing, type the pathname and filename into this field. It overrides any other path settings.
| File Search Path |
|
The Set Classpath and Flags editor allows you to set flags, or options, for the JavaTM interpreter. The format for entries is
-option value |
For example:
-classpath .:/usr/people/jjones/apps/app1:/usr/people/jjones/apps/app2 |
| Current Flags | List of flags currently set. You can select an item to display and modify it in the Enter Flags text field. | |
| Enter Flags | An editable text field that either displays an item selected in the Current Flags list or allows you to type in a new flag path. | |
| Add | Adds a flag to the Current Flags list. | |
| Replace | Replaces a selected flag in the Current Flags list with a flag in the Enter Flags field. | |
| Remove | Removes a selected flag from the Current Flags list. | |
| Help | Provides a help window with a description of the editor. | |
| Close | Closes the editor. |
To browse classes or perform queries, you need to create a fileset and a database to represent your application. You create or modify a fileset, a text file called jdev.fileset, using the Fileset Editor. The fileset is created in the directory from which you started Cosmo Code and contains the list of .class files that make up your program.
The only valid file type for a fileset is a .class file. If you add any other file types to your fileset, the database will not generate correctly and you will not be able to perform queries.
You should check that the files you include in the fileset were compiled using the -g flag to javac. If you do not use this flag, or if you use the -O flag, only partial information will be displayed in the Query deck.
For more information on filesets and database generation, see “Generating the Database.”
To invoke the Fileset Editor, choose “Edit Fileset...” from the Admin menu.
Directories and files that you can add to the fileset appear in the file list on the left of the window. Fileset contents appear in the the file list on the right of the wndow.
| Browsing Directory |
| |
| File List | Displays the contents of the directory specified in the Browsing Directory field. Files or directories can be selected for inclusion in the fileset. If you include a directory, all the files contained in the directory are automatically included in the fileset. Make sure the files and directories you include in the fileset consist only of .class files. | |
| Display Files Check Button |
| |
| Current Fileset |
| |
| Fileset File List |
| |
| Add | Adds a selected file or directory to the fileset. To add more than one line at a time, drag the cursor over a range of files or hold down the <Control> button while clicking, then click the Add button. | |
| Remove | Removes a selected line from a fileset list. To remove more than one line at a time, drag the cursor over a range of files or hold down the <Control> button while clicking, then click the Remove button. | |
| Save | Creates the fileset or puts all the fileset changes into effect. | |
| Cancel | Closes the window and returns the fileset to the state it was in when you first opened the Fileset Editor. |
Once you have defined a fileset to represent your program using the “Fileset Editor,” you can perform queries from cards in the Query deck, or from the right mouse button menu in the Source card. The first time you switch to the Query deck or perform a query after the fileset has been created, a database is generated to represent the program's contents.
A number of files are created for the database in the following locations:
In generating the database, Cosmo Code searches the paths set in the CLASSPATH environment variable for any packages and classes to be analyzed that have not been specified in the fileset but are included by files in the fileset. The classes found by searching the class path are fully analyzed as though they were explicitly set in the fileset.
The CLASSPATH variable is automatically set when you start Cosmo Code. You can add to the class path using the “Set Classpath and Flags...” option on the Admin menu.
If you later modify either the contents of the source files in the fileset or add or remove files, the database is automatically regenerated when you perform a query from the View menu in the Overview card or from the Query menu in the Query card. The database is not updated automatically when you perform queries from the right mouse button menu in the Overview, Query and Class cards. In this case, you can update the database explicitly by choosing either “Reanalyze Changed Sources” or “Reanalyze All Sources” from the Analysis menu in the cards on the Query deck.
Note that the database contents for system classes is shared across filesets and does not get regenerated when a fileset changes. If you want to rebuild the database for system classes, you must manually remove the .jsuds directory when the information for system classes is kept. (This directory is created in your home directory when you do not have write permission to directories containing system classes.)
The Preferences dialog allows you to set configuration preferences for the different tools in the environment:
Click Apply Defaults to set the displayed preferences back to the system default. Click Apply to apply the preferences you have selected, but leave the dialog open. Click OK to apply the selected preferences and close the window. The preferences you select are preserved from one debugging session to another.
The following preferences can be set in the Global Preferences category:
| “Preferences File” |
| |
| “Restore Window Configurations At Startup” |
| |
| “Restore Window Location At Startup” |
| |
| “Display Quick-Help Bar In Windows” |
| |
| “Display Delayed Popup Help” |
| |
| “Popup Help/Expression Delay” |
|
The following preferences can be set in the Source Preferences category:
The following preference can be set in the Command-Line Preferences category:
| “Maximum History Depth” |
|
Overview preferences are not available until you have either clicked on the Query deck icon or performed a query. The following preference can be set in the Overview Preferences category:
| “Generated Files Directory” |
|
Query preferences are not available until you have either clicked on the Query deck icon or performed a query. The following preference can be set in the Query Preferences category:
| “Generated Files Directory” |
|
The Source(2) preferences affect the Source card on the Query deck. The following preferences can be set in the Source(2) Preferences category:
| “Use Horizontal Scrollbar” |
| |
| “Show Line Numbers” |
| |
| “Number of Spaces Used For Tabs” |
| |
| “Popup Expression Evaluation Mode” |
|
The following preferences can be set in the Class preferences category:
| “Display Inherited Fields” |
| |
| “Display Java Package Names” |
| |
| “Display Names Aligned” |
| |
| “Display Arglist Aligned” |
|
| “Declaration Order” |
| |
| “Sorted on Name” |
| |
| “Sorted on Type” |
|
Field Double Click Action
| “Show Definition” |
| |
| “Show Declaration” |
| |
| “Show Declaration if no Definition” |
|
Class Relations Display Order
| “Sorted on Name” |
| |
| “Declaration Order” |
|
| File list | Lists files in the current directory. | |
| Selection | A text entry field with options to retrieve previous entries (using the Recycle button) or select directories in the same path for viewing (using the buttons along the top of the File Finder). | |
| OK | Saves the contents of the display area to the specified file. | |
| Filter | Displays a Filter dialog that allows you to filter the contents of the file list. | |
| Cancel | Cancels the save operation. |
The Help menu provides a set of help cards that contain steps to complete common tasks in Cosmo Code. Each help card also contains links to related information elsewhere in the documentation.
In addition to the task-based help, the Help menu provides the following help options:
The tabs in the “Card Deck” allow you to quickly switch between the various cards. Each card enables you to view and manipulate different pieces of the code you are debugging: for example, the Source Card allows you to view and modify source code, the Callstack Card allows you to view and modify call stack information.
A card deck consists of a number of tabbed cards that allow you to move easily from one view of your program to another. For example, select the Source card to view or modify source code, or select the Data card to evaluate a symbol. The Cosmo Code development environment provides two decks: the Debug deck, which is displayed at startup, and the Query deck, which is accessible using the deck buttons to the right of the tabs.
| Note: Although the Query deck (the Static Analysis subsystem) is installed by default, installation is optional and the Query deck may not be available in your configuration. |
Each card in the deck can be torn off to create a separate view. You can tear off a card by using the left mouse button to drag the tab for the card to a point on your desktop, then releasing the mouse button. You can also choose “Clone Card” or “Clone Deck” from the right-button menu available on the tab of each card.
Click the Previous Card button to the left of the card tabs to move back to the previous card visited.
The deck buttons allow you to switch between decks. The Cosmo Code development environment provides access to two decks: the Debug deck and the Query deck. However, at installation you may choose to install only the Debug deck, in which case you won't see a button for the Query deck.
You can clone a deck by using the left mouse button to drag the deck icon to a new location, or by choosing “Clone Deck” from the right mouse button menu.
The Program field displays the pathname of the program that you are currently debugging. You can attach a program by typing the pathname to the program or just the program name in this field. If the program is a JavaTM applet, the program name must be an .html file. If the program is a standalone Java application, the program name must be the .class file containing the main class.
The Program text field is active when there is no thread running in a program. When a thread is running, the Status area appears in place of the Program field.
The Status Area is active when a program is running. It displays information about the current thread in the program. You can make a thread the current thread by clicking the thread button in the Thread bar. Status information about the thread is displayed in the Status area 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.
| Note: Java and other Java-based names are trademarks of Sun Microsystems, Inc., and refer to Sun's family of Java-branded technologies. |
The control buttons above the Command-Line Debugging area allow you to perform operations such as running a program, suspending a thread, stepping into or over a method, and so on. The control buttons available include the following:
The Continue button continues execution of all threads when threads were suspended by reaching a breakpoint, and continues a single thread when the thread has been explicitly suspended. If you press the right mouse button with the cursor over the Continue button, you can choose to continue either “This Thread” or “All Threads” from the menu. The Continue command is legal only if the running thread or threads are suspended. If the program has not been run or has been killed, the button is desensitized (grayed out). If the target program has not yet started executing, click the Run button to start execution.
The Suspend button stops the execution of the currently running thread. If you press the right mouse button with the cursor over the Suspend button, you can choose to suspend “This Thread” or “All Threads.” The Suspend command is valid only when a thread is running; otherwise the button is desensitized (grayed out).
The Step button executes a single step in a line of source code. This command is legal only if a thread is suspended; otherwise the button is desensitized (grayed out). 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. If a breakpoint is encountered while executing Step, the command is canceled and the thread is suspended where the breakpoint was fired.
When you press the right mouse button with the cursor over the Step button, a popup menu allows you to choose the number of source lines to be stepped. The step value menu selections consist of “1, 2, 3, 4, 5, 10, 15, 20, N...” If you choose “N...”, a dialog opens allowing you to enter a step value.
The Next button executes a single step in a line of source code. This command is legal only if a thread is suspended; otherwise the command button is desensitized (grayed out). 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. If a breakpoint is encountered while executing Next, the command is canceled and the thread is suspended where the breakpoint was fired.
When you press the right mouse button with the cursor over the Next button, a popup menu allows you to choose the number of source lines to be stepped. The step value menu selections consist of “1, 2, 3, 4, 5, 10, 15, 20, N...” If you choose “N...”, a dialog opens allowing you to enter a step value.
The Return button 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. This command is legal only if a thread is suspended; otherwise the command button is desensitized (grayed out). The thread is suspended immediately upon returning to the calling method. All code within the current method is executed as usual. If a breakpoint is encountered while executing the Return command, the command is canceled and the thread is suspended where the breakpoint was fired.
If you have selected an item to examine or evaluate in the Source card, the Examine button takes you to the Data card and displays the item in the Target field.
From any card, the Frame Down button allows you to step forward through the frames on the stack. This command is legal only if the running thread is suspended; otherwise the button is desensitized (grayed out). The information displayed in the card reflects the state of the thread at that stack frame.
From any card, the Frame Up button allows you to step backward through the frames on the stack. This command is legal only if the running thread is suspended; otherwise the button is desensitized (grayed out). The information displayed in the card reflects the state of the thread at that stack frame.
The Kill button stops, or kills, the currently running thread. This command is legal only if the thread is running; otherwise the button is desensitized (grayed out).
The Command-Line Debugging area allows you to type in debugging commands at the jdev prompt. For a list of commands, see “Command-Line Interface.” Cut and paste features are available in this area, in addition to the following control sequences:
| <Esc> | Completes a command. Beeps if completion is not possible or if there are multiple completions. | |
| <Ctrl-d> | On an empty line, lists all the available debugging commands in the command-line area. Otherwise lists all possible completions. Beeps if no completions are possible. |
| <Ctrl-p> or up arrow |
| |
| <Ctrl-n> or down arrow |
| |
| <Ctrl-a> | Move cursor to beginning of line | |
| <Ctrl-e> | Move cursor to end of line | |
| <Ctrl-b> | Move cursor back one character | |
| <Ctrl-f> | Move cursor forward one character | |
| <Alt-b> | Move cursor back one word | |
| <Alt-f> | Move cursor forward one word |
| <Ctrl-d> | Delete forward one character | |
| <Ctrl-h> | Delete backward one character | |
| <Ctrl-w> or <Alt-Backspace> |
| |
| <Alt-d> | Delete forward one word | |
| <Ctrl-k> | Delete from current position to end of line | |
| <Ctrl-u> | Delete entire line |
| <Ctrl-y> | Retrieve the last deleted lines or words | |
| <Ctrl-s> | Search forward in the history list | |
| <Ctrl-r> | Search backward in the history list | |
| <Ctrl-m> | Insert a carriage return | |
| !! | Repeat the last command |
The command-line interface supports debugging commands similar to dbx commands. For more information, refer to the dbx Reference Manual. The syntax for the Cosmo Code debugging commands is as follows:
The Thread bar is located at the bottom of the Cosmo Code window. For each thread in the program, the Thread bar contains a button that consists of an icon followed by a thread name. The Thread bar displays threads spawned by standard JavaTM class libraries as well as threads you have explicitly created. For example, if you write an applet that does not explicitly create a thread, you will see a number of threads with names like Awt-Motif or Screen Updater-3 created by classes that you use in your applet.
Thread buttons display the following information:
Blue highlight around the button—the thread is the current thread and all control buttons and Debug deck cards apply to the thread.
Green circle icon on the button—the thread is runnable (either running or waiting to run).
Red square icon on the button—the thread is suspended.
Grey X icon on the button—the thread is stopped (killed).
At any point while a program is running, one thread is the current thread. When a thread is the current thread, you can suspend, resume, or stop the thread. The cards and commands in the Debug deck apply to the current thread. With one exception, you control which thread is current by clicking on a thread button to make it the current thread. If an existing current thread is running and a breakpoint is encountered in another thread, that thread automatically becomes the current thread.
When you select a thread by clicking on its button, status information about the thread is displayed in the Status area 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.
Click the right mouse button on a thread icon to view the thread name or ID and to display a menu with the following options:
| “Switch” | Makes the selected thread the current thread. | |
| “Hide Label”/”Show Label” |
| |
| “Set Label..” | Allows you to specify a label name for a thread. The default label shows either the thread name (if a name is specified in the source code) or a system generated thread name such as Thread-7. |
| Note: The Thread bar displays thread names, not thread IDs. If you do not explicitly name a thread when you create it, a system-generated name such as Thread-7 is used (although the thread ID for this thread might be 9). Status messages and command-line output display both the thread name and the thread ID. |
The Debug deck is displayed when you start the Cosmo Code development environment. It contains the following cards for source-code debugging and analysis:
The Source card allows you to display a file's contents, set breakpoints in the file, and evaluate symbols. You can switch between files in the display area using the File Finder located at the bottom of the file display area. If a breakpoint is reached in a file that is not currently displayed, the Source card shows the file in the display area, highlighting the line of source code where the breakpoint is set.
The Source card contains the following elements:
The source display area is a scrollable text area for displaying and editing source code. Use the Source menu or use the File Finder to view a source file.
If a breakpoint has been set in a displayed file
The line of source code is highlighted
The column to the left of the source code contains an arrow icon to indicate the state of the breakpoint. The arrow points down when the breakpoint is set but not reached, and points right when the breakpoint is reached during execution.
The scroll bar contains a colored indicator for each breakpoint. Click the middle mouse button on the indicator to scroll the file to the breakpoint.
When a breakpoint is reached in a current thread, the thread is suspended and the source where the breakpoint is set is displayed in the source display area. If a current thread is suspended using the Suspend button, the source for the code being executed is displayed in the source display area.
In the source display area, select a symbol to get a right mouse button menu with the following options:
The File Finder allows you to locate and open source files. Use the drop-pocket, text-field or Recycle icon to open a file as follows:
Drag and drop a file into the drop pocket to the left of the text field.
Type the pathname and filename into the text field.
Click Recycle to view a file whose contents you have previously displayed.
The Source Annotation column displays line numbers for a file if the “Show Line Numbers“ preference has been set in the Preferences dialog. It can also be used to set, display, and clear breakpoints.
To set a breakpoint, click the left mouse button when the cursor is positioned to the left of the source-code line where you want to set the breakpoint. To delete a breakpoint, click the left mouse button over an active breakpoint.
Press the right mouse button in the Annotation column to view a menu that displays the line number at the position of the cursor and offers the following options:
| “Continue to Line” |
| |
| “Enable Breakpoint” |
| |
| “Disable Breakpoint” |
| |
| “Delete Breakpoint” |
| |
| “Modify Breakpoint...” |
| |
| “Create Breakpoint...” |
|
The Source menu in the Source card provides these selections to deal with source files:
| “Open...” | Displays an “Open Dialog” that allows you to select and display a source file in the source display area. Keyboard shortcut: <Ctrl> o | |
| “Save” | Records changes made during the debugging session to the source file. The file must be editable before you can save it. (Select “Make Editable,” from the Source menu if the file is read only.) | |
| “Save As...” | Displays a “Save File Dialog” that allows you to record changes made during the debugging session by saving the source file under a different filename or to a different location. | |
| “Insert File...” | Displays an “Insert File Dialog” that allows you to insert the text of a file within your current file. This option is available when the source code display area is in editable mode. | |
| “Make Read Only” / “Make Editable” |
| |
| “Search...” | Displays a “Search Dialog” that allows you to search for a Literal Case-Sensitive, Literal Case-Insensitive, or Regular Expression. Keyboard shortcut: <Ctrl> s | |
| “Go To Line...” | Displays a “Go To Line Dialog” that lets you scroll to a position in the source code by specifying a line number. |
The Open dialog allows you to display source-code files as follows:
| File List | A list of files in the current directory. | |
| File Finder | An editable text field with options to retrieve previous entries (using the Recycle button) or select directories in the same path for viewing (using the buttons along the top of the File Finder). | |
| OK | Opens the file you have specified. | |
| Cancel | Cancels the open file operation. | |
| Filter | Displays a Filter dialog that allows you to filter the contents of the file list. |
The Save File dialog allows you to save source-code files as follows:
| File List | A list of files in the current directory. | |
| File Finder | An editable text field with options to retrieve previous entries (using the Recycle button) or select directories in the same path for viewing (using the buttons along the top of the File Finder). | |
| OK | Saves the file to the path you have specified. | |
| Cancel | Cancels the save operation. | |
| Filter | Displays a Filter dialog that allows you to filter the contents of the file list. |
The Insert File dialog allows you to insert a file into a source-code file as follows:
| File List | A list of files in the current directory. | |
| File Finder | An editable text field with options to retrieve previous entries (using the Recycle button) or select directories in the same path for viewing (using the buttons along the top of the File Finder). | |
| OK | Inserts the file you have specified at the insertion point in the source code display area. | |
| Cancel | Cancels the insert file operation. | |
| Filter | Displays a Filter dialog that allows you to filter the contents of the file list. |
The Search dialog allows you to search for specific items in a source file as follows:
| Search Type | A set of radio buttons that allow you to specify how you want the search performed: Literal Case Sensitive, Literal Case Insensitive, Regular Expression. | |
| Next | Scrolls to the next occurrence of an item and highlights it. | |
| Prev | Scrolls to the previous occurrence of an item and highlights it. | |
| Reset | Removes the highlighted matches in the source display area, the search target indicators in the scroll bar, and any text in the Search text entry field. | |
| Search | An editable text field. Type in the item to search for and press <Enter> or click Apply. | |
| Apply | Performs the search and highlights all matches in the source display area. A beep after a few seconds indicates that no match has been found. Click a search target indicator in the scroll bar with the middle mouse button to scroll to that point. | |
| Cancel | Removes the highlighted matches in the source display area and the search target indicators in the scroll bar, then closes the dialog. | |
| Close | Closes the dialog. |
The Breakpoints menu in the Source card provides the “Create Breakpoint...” option which opens the “Breakpoint Dialog.”
The Callstack card displays the methods in the call stack (referred to as frames) when a thread is at a breakpoint or suspended. The most recent call is highlighted and displayed at the bottom of the list of calls in the display area. To view source code for a user code item on the call stack, double-click the item name. The Source card pops to the top with the appropriate location in the source file highlighted.
Each entry in the Callstack Display area appears as follows:
class.method(filename.java:line_number) |
In a multi-threaded application, the current thread determines the information displayed in the call stack. To view the call stack for other threads, click the appropriate thread in the thread bar at the bottom of the window.
The Breakpoints card allows you to set, clear, enable, and disable one or more breakpoints on lines of source code, methods, and exceptions. The main display area of the Breakpoints card shows all the breakpoints set in the program and their status.
The Edit menu provides the following options:
| “Create Breakpoint...” |
| |
| “Delete All Breakpoints | “ | |
| “Enable All Breakpoints” |
| |
| “Disable All Breakpoints” |
|
The Breakpoint dialog allows you to set three types of breakpoints using the option menu at the top of the dialog.
The OK button creates the breakpoint or generates an error message if the breakpoint cannot be created. The Clear button clears the contents of the dialog entry boxes. The Cancel button cancels breakpoint creation.
The display area shows a list of all breakpoints in either enabled or disabled state. The disabled breakpoints are highlighted in red. You can perform the following operations on breakpoints displayed in the card:
Enable, disable, or delete one or more selected breakpoints by selecting the breakpoint(s) and clicking the appropriate button below the display area.
Modify a breakpoint by selecting it from the list and then clicking the Modify button below the display area.
Select one or more breakpoints and press the right mouse button to display a menu that allows you to enable, disable, delete or modify breakpoints.
Double-click a breakpoint to open the Breakpoint dialog and modify the breakpoint.
The Enable button enables a disabled breakpoint that has been selected in the list (highlighted in red).
The Disable button disables a breakpoint that has been selected in the list. The breakpoint is highlighted in red to show its disabled status.
The Modify button allows you to modify a breakpoint selected in the list. The breakpoint you want to modify is displayed in the Breakpoint dialog. When you modify a breakpoint, you are actually deleting a breakpoint and creating another in its place. For example, if you have a breakpoint at line 32 in a file and you modify the line number to 35, this creates a new breakpoint at line 35 and deletes the breakpoint at line 32.
The Data card allows you to examine variables and expressions in detail, to set variable values, and to set up a view of expressions that is updated each time some part of your program reaches a breakpoint. For example, you can select an object in the Source card and click the Examine button to view the object's structure in the Data card. You can store expressions or variables in the Data card while a program is running. Each time a breakpoint is encountered or a thread is suspended, the stored expression or variable values are updated.
The Edit menu offers the “Clear All” option to clear all data displayed in the Data card Target field.
The Target field allows you to type in a symbol for evaluation. The evaluation is performed when you press <Enter>, and the result appears in the Expression Details area. The following are examples of formats that can be evaluated:
| symbol | Displays the value of symbol. | |
| *object | Displays the contents of object as a table. | |
| *array | Displays the contents of array as a table. | |
| array[i] | Displays the value of the specified array position. | |
| object.field | Displays the contents of the specified field in the structure. |
The Keep button allows you to move an item from the display area to the Expression View area where values are updated during the running of the program.
The View option menu allows you to select the type of data to view and the format to view it in. The options are
If you have compiled your program using javac -g, you can type in a symbol to evaluate in the Target field. When you press <Enter>, the result appears in the Expression Details area. The following are examples of formats that can be evaluated:
| symbol | Displays the value of symbol. | |
| *object | Displays the contents of object as a table. | |
| *array | Displays the contents of array as a table. | |
| array[i] | Displays the value of the specified array position. | |
| object.field | Displays the contents of the specified field in the structure. |
If an evaluation result is an object, array, or similar complex structure, its handle is displayed. Double click the handle to view the contents of the structure in the Expression Details area.
You can select either the “Custom” or “Locals” view for the Expression View area using the View option menu. The default view is “Custom.” Both views display a two-column table. The left-hand column contains variables or expressions and the right-hand column contains values.
Press the right mouse button in the right-hand column of the table to display a menu with the following options:
The Custom view allows you to record symbols whose values you want to monitor as you run a program. You can type symbols into the left-hand column of the table, and view their current values in the right-hand column. You can also move an expression or variable from the Target field to the table by clicking the Keep button.
The Execution card displays text output from a JavaTM program in a scrollable display area.
The Query deck allows you to examine the structure of your JavaTM program by providing features to list different elements of the program, such as classes or methods. You can also perform queries on relationships between the different elements of your application; for example, you can determine which methods call each other. The Query deck contains the following elements:
The Analysis menu appears on all cards in the Query deck. It provides options for rebuilding the query database from .class files:
| “Reanalyze Changed Sources” |
| |
| “Reanalyze All Sources” |
|
For more information on when to use these menu items, see “Generating the Database.”
The Overview card displays different views of an application by listing various components that make up the application, such as classes or files. From any view of your application, you can perform more specific queries.
The Overview card contains the following elements:
The View menu provides the following options:
The left and right arrow buttons allow you to cycle through previous query results. The left arrow moves back in history, and the right arrow moves forward. Arrow buttons are desensitized (grayed out) if there is no history in the direction of the arrow. The results from previous queries are displayed in the display area. The center History button displays a history list with the last ten queries. New queries are always added to the bottom of the list.
The Title field describes the contents of the display area in the Overview card. For example, if you have chosen to list all classes in a fileset, the title field would read “Class List.”
The List Display area displays a view selected from the View menu. The options available are:
You can double-click an item in a list to view it in greater detail:
Double-click a class to display the class in the Class card.
Double-click a method to display the class containing the method in the Source card.
Double-click a filename to display the file in the Query deck's Source card.
Double-click a variable to display the class containing the variable in the Source card.
To perform a query on an item in the display area, select the item and press the right mouse button to get a menu appropriate for the selected item. Query results are displayed in the Query card. The right mouse button menus are
If you change the contents of source files in your fileset, or change the contents of the fileset before performing a right mouse button query, you must recompile any changed files and update the database to reflect fileset changes by choosing the appropriate item from the Analysis menu. For more information on modifying filesets and regenerating the database, see “Generating the Database.”
The options available on the File Actions menu are
| “Show in Class Card“ |
| |
| “Show Definition” |
|
The options available on the Class Actions menu are
| “List Fields” | Displays all methods and variables in the class. | |
| “List Methods” |
| |
| “List Variables” |
| |
| “List Classes Using” |
| |
| “Lists Methods Using” |
| |
| “List All Derived Classes” |
| |
| “Show in Class Card” |
| |
| “Show Definition” |
|
The options available on the Variable Actions menu are
| “List Classes Using” |
| |
| “Lists Methods Using” |
| |
| “Show in Class Card” |
| |
| “Show Definition” |
|
The options available on the Method Actions menu are
| “List Classes Used” |
| |
| “List Fields Used” |
| |
| “List Methods Used” |
| |
| “List Variables Used” |
| |
| “List Classes Using” |
| |
| “Lists Methods Using” |
| |
| “Show in Class Card” |
| |
| “Show Definition” |
|
The Class List displays information in the following columns. A horizontal scroll bar appears across the bottom of the display area if columns are not visible.
| Class | Shows class or interface type and package information. | |
| File | Shows the file that contains the class or interface type. | |
| Line | Shows the line number at which the class or interface type is defined. | |
| Text | Shows the first line of the class or interface type declaration or, if this information is not available, one of the following two messages is displayed: <could not open package.class>— Source files for the class could not be found. If the .java files are not in the same directory as the .class files (or in the directory where you compiled the files), add the directory containing the .java files using the “Search Path...” from the Admin menu. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. <invalid line number>—Files were probably not compiled using the -g option to javac. The -g option provides additional information used by both the debugger and the static analysis extension. To get line number and source information, recompile the .java files using javac -g. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. |
The Method List displays information in the following columns. A horizontal scroll bar appears across the bottom of the display area if columns are not visible.
| Method | Shows the method name. | |
| Class | Shows class or interface type and package information. | |
| File | Shows the file that contains the class or interface type. | |
| Line | Shows the line number at which the class or interface type is defined. | |
| Text | Shows the first line of the class or interface declaration or, if this information is not available, one of the following two messages is displayed: <could not open package.class>— Source files for the class could not be found. If the .java files are not in the same directory as the .class files (or in the directory where you compiled the files), add the directory containing the .java files using the “Search Path...” from the Admin menu. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. <invalid line number>—Files were probably not compiled using the -g option to javac. The -g option provides additional information used by both the debugger and the static analysis extension. To get line number and source information, recompile the .java files using javac -g. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. |
The Query card allows you to perform queries and display results for any query you have performed.
The Query card contains the following elements:
The Query Target field allows you to enter a class, method or file to use in performing a query. Note that this field is case sensitive. You can enter either a complete class, method, or file name or you can enter a partial string. If you type a partial string into this field and then perform a query, the Query card displays all elements that match the partial string.
The left and right arrow buttons allow you to cycle through previous query results. The left arrow moves back in history, and the right arrow moves forward. Arrow buttons are desensitized (grayed out) if there is no history in the direction of the arrow. The results from previous queries are displayed in the display area. The center History button displays a history list with the last ten queries. New queries are always added to the bottom of the list.
The Query option menu allows you to perform the queries listed below. Results are displayed in the Query card.
After entering a query target in the Query Target field and selecting a query from the Query menu, click the Do Query button to perform the query. The results are displayed in the Query card.
The Query Results Display area displays the results of queries performed from the Query option menu below the Query Target field, or from the right mouse button menu in the Overview and Query cards.
The queries available from the option menu are:
You can double-click an item displayed in the Query results area to view it in more detail:
To perform a query on an item in the display area, select the item and press the right mouse button to get a menu appropriate for the selected item. The right mouse button menus are
If you change the contents of source files in your fileset, or change the contents of the fileset before performing a right mouse button query, you must recompile any changed files and update the database to reflect fileset changes by choosing the appropriate item from the Analysis menu. For more information on modifying filesets and regenerating the database, see “Generating the Database.”
The Where Defined query displays symbols that match the text entered in the Query Target field in the following columns. A horizontal scroll bar appears across the bottom of the display area if columns are not visible.
| Symbol | Shows the name of the symbol that matches the text entered in the Query Target field. | |
| Scope | Shows the scope within which the symbol is valid. | |
| File | Shows the file that contains the class or interface type. | |
| Line | Shows the line number at which the class or interface type is defined. | |
| Text | Shows the first line of the class or interface declaration or, if this information is not available, one of the following two messages is displayed: <could not open package.class>—Source files for the class could not be found. If the .java files are not in the same directory as the .class files (or in the directory where you compiled the files), add the directory containing the .java files using the “Search Path...” from the Admin menu. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. <invalid line number>—Files were probably not compiled using the -g option to javac. The -g option provides additional information used by both the debugger and the static analysis extension. To get line number and source information, recompile the .java files using javac -g. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. |
The Find Matching Classes query displays classes that match the text entered in the Query Target field in the following columns. A horizontal scroll bar appears across the bottom of the display area if columns are not visible.
| Class | Shows class or interface type and package information. | |
| File | Shows the file that contains the class or interface type. | |
| Line | Shows the line number at which the class or interface type is defined. | |
| Text | Shows the first line of the class or interface declaration or, if this information is not available, one of the following two messages is displayed: <could not open package.class>—Source files for the class could not be found. If the .java files are not in the same directory as the .class files (or in the directory where you compiled the files), add the directory containing the .java files using the “Search Path...” from the Admin menu. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. <invalid line number>—Files were probably not compiled using the -g option to javac. The -g option provides additional information used by both the debugger and the static analysis extension. To get line number and source information, recompile the .java files using javac -g. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. |
The Find Matching Methods query displays methods that match the text entered in the Query Target field in the following columns. A horizontal scroll bar appears across the bottom of the display area if columns are not visible.
| Method | Shows the method name. | |
| Class | Shows class or interface type and package information. | |
| File | Shows the file that contains the class or interface type. | |
| Line | Shows the line number at which the class or interface type is defined. | |
| Text | Shows the first line of the class or interface declaration or, if this information is not available, one of the following two messages is displayed: <could not open package.class>— Source files for the class could not be found. If the .java files are not in the same directory as the .class files (or in the directory where you compiled the files), add the directory containing the .java files using the “Search Path...” from the Admin menu. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. <invalid line number>—Files were probably not compiled using the -g option to javac. The -g option provides additional information used by both the debugger and the static analysis extension. To get line number and source information, recompile the .java files using javac -g. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. |
The Find Matching Variables query displays variables that match the text entered in the Query Target field in the following columns. A horizontal scroll bar appears across the bottom of the display area if columns are not visible.
| Variable | Shows the variable name. | |
| Class | Shows class or interface type and package information. | |
| File | Shows the file that contains the class or interface type. | |
| Line | Shows the line number at which the class or interface type is defined. | |
| Text | Shows the first line of the class or interface declaration or, if this information is not available, one of the following two messages is displayed: <could not open package.class>— Source files for the class could not be found. If the .java files are not in the same directory as the .class files (or in the directory where you compiled the files), add the directory containing the .java files using the “Search Path...” from the Admin menu. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. <invalid line number>—Files were probably not compiled using the -g option to javac. The -g option provides additional information used by both the debugger and the static analysis extension. To get line number and source information, recompile the .java files using javac -g. Then choose “Reanalyze all Sources” from the Analysis menu and try the query again. |
The Class card displays the contents of a class, and the relationships between classes. It also allows you to graph relations between classes. You can switch to the Class card and type in a class name to view, or you can double-click a class listed in the Overview card or the Query card to open the Class card automatically.
The Class card contains the following elements:
The Current Subject field indicates the kind and name of the element to be analyzed. The label on this field is initially Current Subject, but changes to one of the following labels, depending on what is displayed in the Class card: Java Class, Java Abstract Class, Java Final Class, or Java Interface. You can type a class or interface name directly into this field.
If you type a question mark (?) into the Current Subject field, the “Browsing Choices Window” opens. Double-click an item in the Browsing Choices window to display the item in the Class card.
The Recycle button displays a list of classes previously viewed in the Class card. The list is empty if you have not yet displayed a class in the Class card.
The Class Graph button opens a “Class Graph Window” that displays a graph of the classes related to the class currently displayed in the Class card.
The Call Graph button opens a “Call Graph Window” that displays a graph of the calls between classes related to the class currently displayed in the Class card.
The Query Identification area is directly above the list area. This area displays the most recent query as a sentence containing both the query question and the name of the object of the query. The number of elements matching the query is displayed at the right end of the line.
The lower two-thirds of the Class card consists of the Class Contents List and the Class Relations List areas displayed in side-by-side panes. You can change the relative widths of the panes by moving the sash that separates them. The two list areas contain the following information:
“Class Contents List”—Provides a detailed view of the internals of the current subject.
“Class Relations List”—Provides items related to the current subject.
The Class Contents list displays the methods and variables internal to the current class. They are organized according to access category—Restricted, Public, Protected, or Private. Within each access category, contents are sorted into two categories—Instance and Static. Within each category, first variables and then methods are displayed.
Here is a schematic of the outline format for each nested list:
Access (RESTRICTED, PUBLIC, PROTECTED, or PRIVATE)
Scope (INSTANCE or STATIC)
VARIABLES
METHODS
|
| Note: The Restricted category is the category the JavaTM language uses when no access keyword is supplied in the field definition. For more information, see the JavaTM Language Specification available from Sun's web site. |
The outline icon to the left of items in the Class Contents list can be used to collapse (hide) or expand (make visible) the items under that category. The arrow inside the icon indicates whether the category is in expanded or collapsed state. If the arrow points downward, the list is in an expanded state. If the icon points to the right, the category is in a collapsed state.
Double-clicking any item in the Class Contents list displays the Source card containing the source code for the item with the declaration highlighted.
Select a method or variable and press the right mouse button to get a menu of queries appropriate for the item you have selected:
Query results are displayed in the Class Contents list by highlighting items that match the query. The Class Contents list also displays indicator marks in the scroll bars corresponding to the positions of matching items. Click an indicator with the middle mouse button to scroll to the matching item. A filled outline icon also shows a match.
The Queries on Variables menu allows you to perform one of the following queries when a variable is selected in the Class Contents list:
| “What Modifies” |
| |
| “What Reads” | Highlights all methods and classes in which the selected variable is read. | |
| “What Accesses” |
| |
| “What Defines” |
| |
| “Show Source Where Defined” |
| |
| “Show Documentation” |
|
The Queries on Methods menu allows you to perform one of the following queries when a method is selected in the Class Contents list:
| “What Uses” | Highlights all methods and classes that use the currently selected method. | |
| “What Is Used” |
| |
| “Call Graph” | Displays the “Call Graph Submenu.” | |
| “What Declares” |
| |
| “What Currently Defines” |
| |
| “What Else Defines” |
| |
| “What Overloads” |
| |
| “Show Source Where Declared” |
| |
| “Show Source Where Defined” |
| |
| “Show Documentation” |
|
The What Is Used submenu provides the following options:
| “All (method and data access)” |
| |
| “Method Calls” |
| |
| “Variable Access” |
| |
| “Variable Modification” |
| |
| “Variable Read” |
|
The Call Graph submenu provides the following options:
| “Add” | Adds the currently selected method and its calling structure to the Call Graph window, if one is open. If not, “Add” opens a Call Graph window before adding the method. | |
| “Replace” | Replaces all methods in the display with the selected method and its calling structure in the Call Graph window. | |
| “Remove” | Removes the currently selected method and its calling structure from the Call Graph window. |
The Class Relations list displays the current Java class or Java interface type and its related classes or interfaces separated into the following categories:
Current class—displayed as “<- This”
Base classes—contains the current class and its ancestors, as described in the section “Base Classes Hierarchy”
Derived classes—contains descendants of the current class, as described in the section “Derived Classes Hierarchy”
Interfaces—contains JavaTM interface types implemented by the current class, or by parents of the current class
Uses—contains classes that the current class uses (that is, instantiates or interacts with using methods and/or variables)
Used by—contains classes that the current class is used by (that is, methods and/or variables in the current class are used by the classes shown in this category)
Implementation Classes—Contains all the classes that implement the interface. This category appears only when a Java interface type is displayed in the Class card.
Double-clicking any item listed in the Class Relations list makes it the new current class or interface type.
The outline icon to the left of items in the Class Relations list can be used to collapse (hide) or expand (make visible) the items under that category. The arrow inside the icon indicates whether the category is in the expanded or collapsed state. If the arrow points downward, the list is in its expanded state. If the icon points to the right, the category is in its collapsed state.
The Base Classes hierarchy shows the ancestors of the current class. Each indented class is an ancestor of the class listed above it. If a class has ancestors, click the outline icon to view or hide the ancestors.
This schematic gives an example of a Base Classes hierarchy:
BASE CLASSES
<-This
first_parent_of_This (access type)
parent_of_first_parent_class (access type)
second_parent_of_This (access type)
parent_of_second_parent_class (access type)
|
The Derived Classes hierarchy shows the descendants of the current class. Each indented class is a descendant of the class listed above it. If a class has descendants, click the outline icon to view or hide the descendants.
This schematic gives an example of a Derived Classes hierarchy:
DERIVED CLASSES
first_child_of_This
child_of_first_child_class
second_child_of_This
child_of_second_child_class
|
Select a class or interface and press the right mouse button to get a menu of queries appropriate for the item you have selected. Many of the items in the menus are common to more than one menu. All the queries are listed in alphabetical order below, followed by the menus where they can be found.
Query results are displayed in the Class Relations list by highlighting items that match the query. The Class Relations list also displays indicator marks in the scroll bars corresponding to the positions of matching items. Click an indicator with the middle mouse button to scroll to the matching item. A filled outline icon also shows a match.
| “Show Source” (all menus) |
| |
| “Show Documentation” (all menus) |
| |
| “What Instantiates” (Uses and Used By) |
| |
| “What Is Declared” (Base Classes) |
| |
| “What Is Defined” (Base Classes) |
| |
| “What Is Overloaded” (Derived Classes) |
| |
| “What Is Overridden” (Base Classes) |
| |
| “What Is Overridden” (Derived Classes) |
| |
| “What Is Used” (Derived Classes and Used By Classes) |
| |
| “What Uses” (Uses Classes) |
|
The What Is Used submenu provides the following options:
| “by Calling Methods/Using Variables” |
| |
| “by Calling Methods” |
| |
| “by Using Variables” |
| |
| “by Modifying Variables” |
| |
| “by Reading Variables” |
|
The What Uses submenu provides the following options:
| “by Accessing Any Field” |
| |
| “by Calling Methods” |
| |
| “by Using Variables” |
| |
| “by Modifying Variables” |
| |
| “by Reading Variables” |
|
The Class Graph window displays relationships among classes based on the class displayed in the Class card. The window shows an inheritance graph by default, and includes both JavaTM classes and Java interface types. You can control the type of graph displayed (inheritance or interaction) using the menu at the bottom of the window, and you can view smaller portions of the graph by selecting a view from the Views menu. The buttons along the bottom of the graph allow you to zoom and control the appearance of the graph.
You can use the graph to change the class displayed in the Class card by double-clicking a new class in the graph.
The Class Graph window contains the following elements:
The Admin menu provides the following options:
| “Save Graph” | Displays a“Save Graph Dialog” that allows you to select or type in a filename in which to save the displayed graph. The graph is saved as a PostScript® file. | |
| “Close” | Closes the Class Graph window. |
The Save Graph dialog allows you to save a graph as a Postscript file.
| File list | A list of files in the current directory. | |
| File Finder | An editable text field with options to retrieve previous entries (using the Recycle button) or select directories in the same path for viewing (using the buttons along the top of the File Finder). | |
| OK | Saves the graph in the file you have specified. | |
| Cancel | Cancels the save operation. | |
| Filter | Displays a Filter dialog that allows you to filter the contents of the file list. |
The Views menu provides options for selecting the amount of information to display in the graph:
The Graph Display area displays an inheritance graph of the entire fileset when the Class Graph button is clicked in the Class card. You can change the type of graph using the menu below the Graph Display area. The different graphs are
| Inheritance | Displays the inheritance relationship between classes and the JavaTM interface types that each class implements. Both these relationships are displayed using a solid black line between nodes on the graph. | |
| Interaction | Describes the relationship of used classes to the classes that are their users. A class is considered “used” when its methods and/or variables are accessed. A class is considered a user of another class when it accesses the methods or variables of the other class. The graph displays only one link between classes even when the class uses or is used by more than one method or variable in another class. |
You can view a smaller portion of the graph by selecting an option from the “Views Menu”. The “Show All Related” and “Show Butterfly” options display hierarchies based on the current class. In the graph display, the current class node is highlighted.
If you choose to view a smaller portion of the graph, right-facing arrows appear on class nodes to show you that some classes are not displayed in the current view. You can view the hidden classes by double-clicking the node.
You can also change your view of the graph by selecting nodes in the graph and using the right mouse button menu to control the display of nodes.
To select a single node, click the left mouse button with the cursor over the node.
To select multiple, unrelated nodes, click the left mouse button with the cursor over the first node, then hold down the <Ctrl> key and click over additional nodes.
To select a node and all its sub-nodes, hold down the <Shift> key and click the left mouse button with the cursor over the node.
The right mouse button menu contains the following options:
| “Hide Node” | Hides the selected node or nodes in the graph. | |
| “Collapse Subgraph” |
| |
| “Show Immediate Children” |
| |
| “Show Parents” |
|
The Graph Control Elements allows you to control your view of the graph displayed in the Graph display area.
The Zoom option menu allows you to select a percentage granularity at which to view the graph.
The Overview button provides a window with an outline of the entire graph and allows you to select the part of the graph you want to see in detail.
The Multiple Arcs button allows you to toggle between viewing all relationships between nodes and viewing only a single link between nodes. The button displays multiple arcs between nodes if there are multiple instances of the relationship between the displayed nodes.For example, if more than one method in class X calls a method or methods in class Z, multiple links between the nodes for class X and class z appear in the graph.
The Graph option menu allows you to switch between graphs. The menu displays the currently selected graph type. The available options are
Click the Call Graph button in the Class card to display the Call Graph window with the calling relationship among classes in the fileset. You can also access the Call Graph window when you select a method in the Class Contents list, press the right mouse button and choose an item from the Call Graph menu.
The Admin menu provides the following options:
| “Show Arglist” |
| |
| “Clear” | Clears the Call Graph display area. | |
| “Save Graph” | Displays a “Save Graph Dialog” that allows you to select or type in a filename in which to save the displayed graph. The graph is saved as a PostScript® file. | |
| “Close” | Closes the Call Graph window. |
The Save Graph dialog allows you to save a graph as a Postscript file.
| File List | A list of files in the current directory. | |
| File Finder | An editable text field with options to retrieve previous entries (using the Recycle button) or select directories in the same path for viewing (using the buttons along the top of the File Finder). | |
| OK | Saves the graph in the file you have specified. | |
| Cancel | Cancels the save operation. | |
| Filter | Displays a Filter dialog that allows you to filter the contents of the file list. |
The Browsing Choices window appears when you type “?” into the Current Subject field in the Class card. It displays all classes in the fileset and allows you to double-click a class to view it in the Class card. The list displays the class or interface type (JavaTM Class, Java Interface, Java Abstract class, and Java Final Class) and the class name.
The Admin menu consists of the following options:
| “Sort” | Allows you to sort the items alphabetically by column (type of class or class name.) | |
| “Close” | Closes the Browsing Choices window. |