Eclipse 4 Plug-in Development by Example : Beginner's Guide

Eclipse needs Java to run, and so the first step involved in installing Eclipse is ensuring that an up-to-date Java installation is available. By default, Eclipse will find a copy of Java installed on the path or from one of the standard locations. It is also possible to specify a different Java version by using the -vm command-line argument.

If the splash screen doesn't show up, the Eclipse version may be incompatible with the JDK (for example, a 64-bit JDK with a 32-bit Eclipse, or vice-versa). Common error messages shown at the launcher may include Unable to find companion launcher or a cryptic message about being unable to find an SWT library.

On Windows, there is an additional eclipsec.exe launcher, which allows log messages printed to the console to be seen. This is sometimes useful if Eclipse fails to load and no other message is displayed. Other operating systems can use the eclipse command. Both eclipse.exe and eclipse support the -consolelog argument, which can display more diagnostic information about problems while launching Eclipse.

The Eclipse workspace is a directory used for two purposes: as the default project location, and to hold the .metadata directory containing Eclipse settings, preferences, and other runtime information. The Eclipse runtime log is stored in the .metadata/.log file.

The workspace chooser dialog has an option to set the chosen value as the default workspace. It can be changed within Eclipse by navigating to File | Switch Workspace. It can also be overridden by specifying a different workspace location with the -data command-line argument.

Finally, the welcome screen is useful for first-time users, but is worth closing (rather than minimizing) once Eclipse has started.

Creating a plug-in project is the first step towards creating a plug-in for Eclipse. The New Plug-in Project wizard was used with one of the sample templates to create a project.

Plug-ins are typically named in reverse domain name format, so these examples will be prefixed with com.packtpub.e4. This helps to distinguish between many plug-ins; the stock Eclipse SDK comes with more than 440 individual plug-ins, for example, the Eclipse-developed ones start with org.eclipse.

The project contains a number of files which are automatically generated, based on the content filled in the wizard. The key files in an Eclipse plug-in are:

This file is an archaic hangover from the days of Ant builds, and is generally useless when using more up-to-date builds such as Maven Tycho, which will be covered in Chapter 10, Automated Builds with Tycho.

Q1. What is an Eclipse workspace?

Q2. What is the naming convention for Eclipse plug-in projects?

Q3. What are the names of the three key files in an Eclipse plug-in?

When clicking Run in the toolbar (or via the Run | Run As | Eclipse Application menu) a launch configuration is created, which includes any plug-ins open in the workspace. A second copy of Eclipse—with its own temporary workspace—will enable the plug-in to be tested and verified so that it works as expected.

The Run operation is intelligent, in that it launches an application based on what is selected in the workspace. If a plug-in is selected, it will offer the opportunity to run as an Eclipse application; if a Java project with a class with a main method, it will run it as a standard Java application; and if it has tests then it will offer to run the test launcher instead.

However, the Run operation can also be counter-intuitive; if clicked a second time, and in a different project context, something other than the expected launch might be run.

A list of the available launch configurations can be seen by going to the Run menu, or by going to the drop-down list to the right of the Run icon. The Run | Run Configurations menu shows all the available types, including any previously run:

By default, the runtime workspace is kept between runs. The launch configuration for an Eclipse application has options that can be customized; in the previous screenshot, the Workspace Data section in the Main tab shows where the runtime workspace is stored, and an option is shown that allows the workspace to be cleared (with or without confirmation) between runs.

Launch configurations can be deleted by clicking on the red Delete icon on the top-left, and new launch configurations can be created by clicking on the New icon . Each launch configuration has a type:

The launch configuration can be thought of as a precanned script, which can launch different types of programs. Additional tabs are used to customize the launch, such as the environment variables, system properties, or command-line arguments. The type of the launch configuration specifies what parameters are required, and how the launch is executed.

When a program is launched with the Run icon, changes to the project's source code do not take effect. However, as we'll see in the next section, if it's launched with the Debug icon, changes can take effect.

If the test Eclipse is hanging or otherwise unresponsive, in the host Eclipse instance the Console view (shown with the Window | View | Show View | Other | General | Console menu) can be used to stop () the test Eclipse instance.

Q1. What are the two ways of terminating a launched Eclipse instance?

Q2. What are launch configurations?

Q3. How do you create and delete launch configurations?

Now that you've got the Eclipse plug-in running, try the following:

The built-in Eclipse debugger was used to launch Eclipse in debug mode. By triggering an action which led to a breakpoint, the debugger was revealed allowing the local variables to be introspected.

When in the debugger, there are several options available for stepping through the code:

By default, Eclipse ships with Project | Build Automatically enabled. Whenever changes are made to Java files, they are recompiled along with their dependencies if necessary.

When a Java program is launched in run mode, it will load classes in on-demand and then keep using that definition until the JVM shuts down. Even if the classes are changed, the JVM won't notice that they have been updated, and so no differences will be seen in the running application.

However, when a Java program is launched in debug mode, whenever changes to classes are made, it will update the running JVM with the new code if possible. The limits to what can be replaced are controlled by the JVM through the JVMTI and whether, for example, the virtual machine's canUnrestrictedlyRedefineClasses() call returns true. Generally, updating an existing method and adding a new method or field will work, but changes to interfaces and super classes may not be. (Refer to http://en.wikipedia.org/wiki/Java_Virtual_Machine_Tools_Interface for more information.)

Note that there are some changes which won't be picked up; for example, new extensions added to the plugin.xml file. In order to see these changes, it is possible to start and stop the plug-in through the command-line OSGi console, or restart Eclipse inside or outside the host Eclipse to see the change.

The Step Filters preferences allows uninteresting packages to be skipped, at least from the point of debugging. Typically, JVM internal classes (such as those beginning with sun or sunw) are not helpful when debugging and can easily be ignored. This also avoids debugging through the class loader, as it loads classes on demand.

Typically, it makes sense to enable all the default packages in the Step Filters dialog, as it's pretty rare to need to debug any of the JVM libraries (internal or public interfaces). This means when stepping through the code, if a common method such as List.toString() is called, debugging won't step through the internal implementation.

It also makes sense to filter out simple setters and getters (those that just set a variable, or those that just return a variable). If the method is more complex (like the getVariable() method discussed previously), it will still stop in the debugger.

Constructors and static initializers can also be specifically filtered.

The breakpoint triggers at the time the method enters and subsequently when the method's return statement is reached.

Note that the exit is only triggered if the method returns normally; if an exception is raised which causes the method to return, this is not treated as a normal method exit, and so the breakpoint won't fire.

Other than the breakpoint type, there's not a significant difference between creating a breakpoint on method entry and creating one on the first statement of the method. Both give the ability to introspect the parameters and do further debugging prior to any statements in the method itself are called.

The method exit breakpoint, on the other hand, will only trigger once the return statement is about to leave the method. Thus, any expression in the method's return value will have been evaluated prior to the exit breakpoint firing. Compare and contrast this to the line breakpoint, which will wait to evaluate the argument of the return statement.

Note that Eclipse's Step Return icon has the same effect; this will run until the method's return statement is about to be executed. However, to find when a method returns, using a method exit breakpoint is far faster than stopping at a specific line and then clicking on Step Return.

When a breakpoint is created, it is enabled by default. A breakpoint can be temporarily disabled, which has the effect of removing it from the flow of execution. Disabled breakpoints can be trivially re-enabled on a per-breakpoint basis, or from the Breakpoints view. Quite often it's useful to have a set of breakpoints defined in the codebase, but not necessarily have them all enabled at once.

It is also possible to temporarily disable all breakpoints using the Skip All Breakpoints setting, which can be changed from the corresponding item in the Run menu (when the debug perspective is enabled), or the corresponding icon in the Breakpoints view. When this is toggled, no breakpoints will be fired.

Conditional breakpoints must use a Boolean expression, rather than a statement or a set of statements. Sometimes this is constraining; if that's the case, having a utility class with a static method allows more complex code paths (with the caveat that all interesting data must be passed in as method arguments).

The Java Exception breakpoint stops when an exception is thrown, not when it is caught. The dialog asks for a single exception class to catch and by default, the wizard has been prefilled with any class whose name includes *Exception*. However, any name (or filter) can be typed into the search box, including abbreviations such as FNFE for FileNotFoundException. Wildcard patterns can also be used, which allows searching for Nu*Ex or *Unknown*.

By default, the exception breakpoint corresponds to instances of that specific class. This is useful (and quick) for exceptions such as NullPointerException , but not so useful for ones with an extensive class hierarchy such as IOException. In this case, there is a checkbox visible in the Breakpoint properties window and the bottom of the Breakpoints view, which allows the selection of all subclasses of that exception, not just of the specific class itself.

There are also two other checkboxes, which say whether the debugger should stop when the exception is caught or uncaught. Both of these are selected by default; if both are deselected, the breakpoint effectively becomes disabled. Caught means that the exception is thrown in a corresponding try/catch block, and Uncaught means that the exception is thrown without a try/catch block (thus, bubbles up to the method's caller).

The Eclipse debugger has many powerful features, and the ability to inspect (and change) the state of the program is one of the more important ones.

Watch expressions, when combined with conditional breakpoints, can be used to find out when data becomes corrupted or used to show the state of a particular object's value.

Expressions can also be evaluated based on objects in the Variables view, and the code completion is available to select methods, with the result being shown with Display.

Q1. How can an Eclipse plug-in be launched in debug mode?

Q2. How can certain packages be avoided when debugging?

Q3. What are the different types of breakpoints that can be set?

Q4. How can a loop debugged that only exhibits a bug after 256 iterations?

Q5. How can a breakpoint be set on a method when its argument is null?

Q6. What does inspecting an object do?

Q7. How can the value of an expression be calculated?

Using the conditional breakpoint to stop at a certain method is fine if the data is simple, but sometimes there needs to be more than one expression. To implement additional functionality, the breakpoint can be delegated to a breakpoint() method in a Utility class. The following steps will help you to work with breakpoints: