As Java developers, we are lucky to have a wide selection of open source tools to help us more efficiently and effectively write applications.  Tools, frameworks, and libraries take care of common functionality such as security, logging, database transactions, component instantiation, application builds, and much more.  This allows us to spend more time writing the core business logic.  While this is certainly a blessing, it can be frustrating when you notice odd behavior or cryptic exceptions coming from this third-party code.  When online message boards don’t provide immediate insight, how can we effectively debug the logic that we didn’t write?  Having access to the source code and being able to step through it in debug mode can be invaluable.  In this post, we’ll investigate the various methods that can be used in Eclipse to attach source code to the third-party components used in our Java projects.

Note: Eclipse Mars Release 4.5.1 is used in the following examples.

Source Code Navigation

First, let’s review the most common ways to navigate into Java files.

  • Control-clicking on a type or method.
  • Opening a type through the Open Type dialog (Ctrl-Shift-T).
  • Clicking on the line number link in a stack trace that was printed to the console.
  • Stepping through code in the debugger.

The catch is that Eclipse needs to know where the source code is located.  If you aren’t navigating into Java files that are defined in your workspace, you need to give Eclipse some hints on where to find them.  This post will help you do just that.  Furthermore, you will be able to set breakpoints in the attached source code and step through each line when running in debug mode.

Maven-Managed Library Source Code

If you are developing a Maven-managed project and use the Eclipse Maven plugin (M2E), make sure that you have the Download Artifact Sources option checked in your Eclipse Preferences (Window-Preferences-Maven).  With this option selected, Eclipse will automatically download the source code for libraries managed by Maven.  This will happen on-demand as you navigate into types defined in these libraries.

DownloadSourceMaven

Manually-Added Libraries

If you are manually adding libraries to your Eclipse project, you will need to manually add the source code.  There are a few ways to achieve this.

In either your Package or Project Explorer view, right-click on the JAR to which you would like to attach source code and select Properties.  You will be presented with a dialog that allows you to specify a location for the corresponding source code.

JavaSourceAttachmentDialog

Alternatively, right-click on your Java project and select Properties.  In the dialog that appears, select Java Build Path and click on the Libraries tab.  The libraries that you manually added should be included in the list that is displayed.  Expand the entry for the library for which you want to add source code, and edit the source attachment location.

ManuallyAttachJARSource

Another option is to simply navigate into a type that is defined in the library.  If source code is not yet attached, you may see a panel with a Change Attached Source… button.  Click on this button to attach the corresponding source code.

ClassFileEditor

Java Source Code

What if you want to navigate into the Java source code?  For instance, maybe you want to see how ArrayList is implemented.  Simply set your project’s JRE System Library to point to a JDK distribution rather than a JRE distribution.  JDK distributions come with the Java Source code bundled.

If you need to use a JRE distribution as your JRE System Library for some reason, you aren’t out of luck.  You can still attach the source code manually.  First, get the source code from the corresponding JDK distribution.  It’s in the top-level folder as two zip files, src.zip and javafx-src.zip.

Go to Window-Preferences-Java-Installed JREs.  Select the JRE that you are using and click the Edit button.  The edit window will list all of the jars that comprise the JRE.  Set src.zip as the source attachment for: resources.jar, rt.jar, jsse.jar, jce.jar, charsets.jar, and jfr.jar.  If you are using Java FX, set javafx-src.zip as the source attachment to jfxrt.jar.

AttachJavaSource

Server Source Code

If you need to inspect the source code for the server in which you are running, then you will need to attach it manually.  If you use an open source application server, its source code should be available online.  Once you have the source code saved to your system, perform the following steps:

After launching your server in debug mode at least once, right-click on the server debug target in your Debug view and select Edit Source Lookup…

AddToSourceDebugTarget

Click the Add button to add the server’s source code to the source lookup path.  If the source code is in a zip file, select the External Archive option (or Archive if the source is saved within your workspace) and navigate to the location of the file.

AddToSourceLookup

Source Code For Other Tools/Containers

There are times when you may need the source code for other tools that interact with your project.  For example, you may want to troubleshoot an exception that is getting thrown from the Maven M2E plugin during a Maven build.

The process for attaching source code to these other types of debug targets is identical to the process for attaching server source code.  In this case, you would select the Maven build debug target from the Debug view and follow the steps from the previous section.

AttachMavenSource

Summary

With a bit of configuration, Eclipse’s source lookup functionality can provide a powerful way to troubleshoot the issues that will inevitably be encountered when integrating with third-party software.  I hope you found these tips helpful!