Section 4.3.  Running and Debugging

4.3. Running and Debugging By this point, you have set up a development environment and target platform, defined a simple Hyperbola application, and run it at least once. You have also seen how applications, perspectives, and advisors fit together to form a system. You are now ready to start putting some real function into Hyperbola. Before doing that, it is worth spending a bit of time talking about how to run and debug Eclipse applications effectively. In this section, we show you how to: Launch applications in debug mode. Set breakpoints and step through code. Manage targets, launch configurations, and control the set of plug-ins used. If you have been following along, Figure 4-8 matches your system. It shows the relationships between the IDE install you are running, the workspace in which you are developing, and the target plug-ins you are using for Hyperbola. The IDE plug-ins (bottom left) are the ones in c:\ide. They are the full Eclipse SDK. Running them starts the Eclipse IDE (top left of the diagram). Using the IDE, you work on plug-in projects that are in the workspace (center). When you decide to try running Hyperbola, PDE creates and launches a configuration that lists the relevant plug-ins from the target (bottom right) and the workspace. The result is a running Hyperbola (top right). Figure 4-8. Relationships among IDE, target, and workspace By separating the concerns, the IDE install can be replaced without affecting the workspace or the target. Similarly, the target plug-ins can be updated without changing the workspace or IDE. Of course, there can be several workspaces using the same target. 4.3.1. Debugging Previously, you ran Hyperbola using the Launch link in the Testing section on the Overview page of the plug-in editor. You may have noticed that there is also a Debug link. Go ahead and click on that link now. As with launching, debugging spawns a separate JVM to run the application. The difference is that the Debug perspective opens and shows a list of threads in the target application. Exit the application and the threads all terminate. The debugger is useful when things are not going as you expected. Say, for example, you are getting a NullPointerException. To illustrate, set up that scenario by changing ApplicationWorkbenchWindowAdvisor.preWindowOpen() to simulate null coming back from getWindowConfigurer(). org.eclipsercp.hyperbola/ApplicationWorkbenchWindowAdvisor IWorkbenchWindowConfigurer configurer = getWindowConfigurer(); configurer = null; With the code changed, click on the normal Launch link in the plug-in editor. All you see is an exception reported in the console as shown belowHyperbola does not start: Unhandled event loop exception Reason: java.lang.NullPointerException To find out more, add a breakpoint on the exception by using Run > Add Java Exception Breakpoint... and selecting NullPointerException in the type chooser. Tip The filter in the type chooser takes wildcards. So, to get NullPointerException, just open the chooser and type "null". Keep typing until the list of choices is refined enough for you to see the type you want. Now launch using the Debug link in the editor. Click Yes when prompted to open the Debug perspective. When the debugger opens, the "main" thread is paused at the line where the exception occurred, as shown in Figure 4-9. Figure 4-9. Debugging using breakpoints [View full size image] The execution of the main thread has stopped in preWindowOpen() on the line highlighted. The debugger also contains a Variables view. This view shows the values of all known fields and variables for a given Java stack frame. You can navigate around the object structure by expanding the object tree along the reference paths that interest you. Tip Using the Variables view to examine object structures can be extremely informative. Note also that you can typically change the values of the variables and fields you find along the way! Looking at the line of code and the Variables view, it is easy to see that the configurer field is null and to find the cause of the exception. This is the first step. Now you have to figure out why configurer is null (ignoring, of course, the fact that it is set to null on the previous line). One easy way to do this is to set a breakpoint on the first line of this method and then step through the code to find out how the null value is set. To set a breakpoint, position the text cursor on the line you want and use Run > Toggle Line Breakpoint. Alternatively, you can double-click in the margin at the left of the line. Either way, a blue ball should appear at the left of the line, as shown in Figure 4-10. Figure 4-10. Line breakpoint [View full size image] Terminate the current run using either Run > Terminate or by clicking on the red square button over the list of threads. Then, launch again using the debug link. This time, execution stops at your new breakpoint. From here, you can use the stepping functions described in Table 4-1 to go into getWindowConfigurer() and see what is going on. Table 4-1. Debugger Stepping Functions Image Step Function	Step Into (F5)The next method call. If you think that the problem might be near, step into. Note that Java debugging is line-oriented, so if you have multiple method calls on one line, you might have to step into several times. You can step into and then immediately step to return. You can refine this by using
	Step Into Selection (Ctrl+F5) in the editor's context menu.
	Step Over (F6)The next method call. This is useful for quickly getting around in the execution. Use step over until you start seeing things going wrong and then look in more detail.
	Step to Return (F7)Of the current method. As the name implies, use this function when you just want to get to the end of the method.
	Drop to FrameDrop all stack frames above the selected frame. Execution is reset to the beginning of the method in the current frame. This is useful if you've discovered a problem and want to retry the execution. Note, however, that this does not undo side effects such as writing or closing files or setting shared state.

Tip

Stepping through code is sometimes bewildering, but can be an effective way of finding out what the system is doing and discovering API and coding patterns that are useful in your applications.

The editor's context menu has a number of other step functions such as stepping into and running up to a selected line of code, and the debugger supports conditional breakpoints. The functions described here should be enough for you to handle most problems.

4.3.2. Launch Configurations

Launching using the links in the Testing section of the plug-in editor is easy and convenient. Since you are likely to spend a lot of time running and debugging Hyperbola in the next chapters, here we show you some tricks to make things easier.

Whenever you click on a test link, PDE manages a launch configuration describing the configuration to run. You can look at this launch configuration using either Run > Run... or Run > Debug... Either way, you get a launch configuration dialog as shown in Figure 4-11.

Figure 4-11. Launch configuration dialog

[View full size image]

The Main tab is the most interesting at this point. It has the following parts:

• The Name of the launch configuration is currently "Eclipse Application". To eliminate future confusion, you might want to change it to "Hyperbola" and click Apply. Notice that the name in the left column changes as well.

• The Workspace Data section shows where the target Eclipse puts its workspace or instance data. Since we are running Hyperbola, there isn't any data to worry about. In general, you do not need to change this location, but you may need to know where it is. This is where Eclipse stores some preferences and plug-in-specific information. This is also where you can find the log file if something should go wrong. Look in .metadata/.log in the workspace location if you suspect errors are occurring.

• The Program to Run section identifies the Hyperbola application, org.eclipsercp.hyperbola.application, to run. Click on the drop-down arrow and take a look at the other applications known by the system. Since we are targeting the RCP SDK, Hyperbola is the only application.

• The Command Line Settings area allows you to choose a JRE to use as well as set up any command line arguments. There are quite a number of possible command line arguments, all of which are detailed in the online documentation. Perhaps the most interesting one for debug purposes is the -consoleLog program argument. This causes all log output to be echoed to the Console. This helps because often messages are being logged but go unnoticed unless you check the log. Using -consoleLog, these messages are somewhat more "in your face."

Now that you know about launch configurations, you can run and debug your applications directly rather than using the links on the plug-in editor's Overview page. As shown in Figure 4-12, the Run menu has a host of entries to help.

Figure 4-12. Launching entries in the Run menu

The context menu in the Package Explorer also has Run As and Debug As entries. When you pick one of these entries and specify Eclipse Application, it is equivalent to using the run and debug links in the plug-in editor. PDE finds or creates a launch configuration to match your selection and then launches it.

As you can see, there are several more tabs on the dialog. For now, these are not needed. PDE is pretty good at managing things for you in this relatively simple world. As we make Hyperbola more and more sophisticated, there will be opportunities for you to use the other tabs, in particular, the Plug-ins tab.