If you had created a startup script for Felix, now it's the time to make it allow remote debugging. The following shows the updated startup script enabling remote debugging of the Felix framework:
java
-Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n
-Xdebug
-jar bin/felix.jar
We tell the JVM to start in the debug mode; the set of options added to the command line will enable debugging and instruct the JVM to listen to the port 8787 for debug clients to connect.
The suspend option controls whether the JVM should halt at start and wait for a client to connect before continuing, or whether it should just start while listening for an eventual client connection. In our case, we've set suspend=n because we're not interested in capturing the startup of the framework. You may need to change it to y if you'd like to debug bundle activation as part of the framework startup procedure.
Launching Felix with remote debugging turned on displays something like:
Listening for transport dt_socket at address: 8787 _______________ Welcome to Apache Felix Gogo
The JVM is now running and waiting, listening to port 8787 for a remote debugger to connect. This won't take too long to happen; we're going to connect our client debugger next.
In Eclipse, we will set up a remote debug profile that is configured to connect to the Felix framework we have started in the previous step.
Once created, the remote debug profile can be used every time we wish to connect to the remote framework. In many cases, we'll be able to connect and disconnect without disturbing the framework.
We will now set up a new remote debug profile in Eclipse. To do that, open the Debug Configurations panel through the Run -> Debug Configurations... menu item. This same configuration panel can also be reached through other means, for example, by right-clicking on the project root.
 |
The Debug Configurations panel that appears holds the debug profiles available. They are organized by profile type. The one we're interested in is the Remote Java Application type.
In the debug configuration panel, find the Remote Java Application debug configuration type, right-click on it, and choose New.
 |
A new remote debug entry is created with default values. Most of the default values that are pre-filled do not need to be changed.
We will update the following items:
The name of the profile. I've set it to Felix (localhost on 8787)
The main targeted project for the debugging
The port to use while connecting to the remote JVM
To update the debug target project, click Browse and select it. Here, we're targeting the bookshelf-inventory-impl-mock project. This debug configuration will be attached to it. Also update the Port to 8787.
 |
When you click on Apply to accept the changes, the profile is ready to be launched. At this point, you can make it connect right away by clicking Debug, or just close this configuration panel and start debugging later.
With the remote debugging configuration in place, we are ready to connect to the Felix application and stop the execution thread at bundle activation.
To prepare for this, if you haven't done so already, complete Chapter 5 and Chapter 6. The result of which is the deployment, installation, and start of the inventory layer on the Felix framework. Then stop the bookshelf-inventory-impl-mock bundle, as we want to capture the call to the bundle activator while the bundle is starting.
Let's set a breakpoint at the first expression of the start() method of BookshelfInventoryMockImplActivator. Do that by double-clicking on the side bar in the class source code editor.
 |
The debugger will now suspend the execution when it is connected to a remote JVM that reaches this point.
If this is the first time you've run it, the debug profile may not be listed in the quick-pick debug drop-down list. In that case, you can start it by going to the Debug configurations panel (see the preceding screenshot). Otherwise, it appears as follows:
 |
Select it to initiate the debugging and launch the connection to the remote server. The debugger is now connected to the remote JVM.
When you start the bookshelf-inventory-impl-mock bundle in Felix, the Eclipse debugger will capture the execution flow when it reaches the breakpoint.
If this is the first time you've run the debugger, you'll get a perspective switch suggestion. In Eclipse, perspectives provide different ways for representing the content and layout of the graphical interface.
The Debug perspective shows panels laid out for debugging, with additional functionality for stepping through the execution, viewing the call stack, inspecting variables, and so on.
Sometimes, to quickly check something out or for quick develop-test cycles, it is useful to embed the target application framework directly in the IDE.
The OSGi Pax Runner, introduced and installed earlier in this appendix, provides a harness for many open source OSGi frameworks including Felix. In this section, we will look at how to use it to embed Felix into Eclipse.
Embedding Felix will consist of launching it in an OSGi Framework container, which is set up as a run configuration in Eclipse. Open the Run Configurations... panel.
 |
In the Run Configurations… panel, find the OSGi Framework configuration type and use it to create a new run profile.
 |
The configuration entry is added with default values pre-filled. Change the configuration name to Embedded Felix and select the target framework in the Framework drop-down menu.
 |
At the point of writing this appendix, the latest version of embedded Felix available is 2.0.1. The example will show snapshots using that entry. However, be sure to check for updates to the Pax Runner plugin that support the later version; the configuration steps should not be very different.
Next, in the following Bundles listing, deselect the root Target Platform (we will install the additional bundles ourselves).
This configuration can now be saved and run.
Let's give our newly embedded Felix a try. Running the Felix (2.0.1) profile that was set up a little earlier will start Felix and display its TUI in the Console window in Eclipse.
The console, as you see it here, is a bit different from the one provided by Felix 3.0. Version 2.0 of the Felix distribution was based on the Apache Felix Shell Service and the Shell TUI. For example, here you type ps for a list of the bundles. You can type help for the few commands available here and to learn how to use it.
From this point onwards, this is the same as with a shell-launched Felix application. The difference is that it's running inside Eclipse.
 |
For the completeness of the example, let's install the bookshelf-inventory-impl-mock bundle.
The bundle repository service on this Felix framework is not yet configured. We will start by adding the OBR repositories we're using, namely, the default Felix repository and our local releases repository.
In this version of the console, OBRs are added using the command obr add-url:
obr add-url//felix.apache.org/obr/releases.xml.obr add-url : /C:/projects/felixbook/releases/repository.xml.
Type those commands on the console in Eclipse.
Now that the OBR service in the embedded Felix instance knows where to find our bundles, we can install the Bookshelf Inventory Impl - Mock bundle.
In this version of the console, bundles are installed and started from the OBR using the following command:
-> obr start "Bookshelf Inventory Impl - Mock" Target resource(s): ------------------- Bookshelf Inventory Impl - Mock (1.5.0) Required resource(s): --------------------- Bookshelf Inventory API (1.4.0) Deploying... Starting Book Inventory Mock Impl done.
We now have our inventory implementation running in the embedded Felix. Let's look at how to use the embedded Felix that we have just set up for debugging bundles.
The embedded Felix framework can be debugged by launching its run configuration in the debug mode. To do that, just select it from the Debug Configurations or from a shortcut in the Debug drop-down menu.
 |
The debugging process from this point on is the same as that described in the previous remote debugging sections.