Recently, a few people have come to me ask how Eclipse maintains its API and versions. The intent of this question was to see what lessons there are to be learned for other OSGi-based applications. If we step back a bit, in essence, Eclipse is a large OSG application. On top of that, Eclipse is a platform where people build their own OSGi applications on… it’s an OSGi party. As a result, there are many people dependent on the API Eclipse produces so the management of this API is important. If breaking API changes were common, people would have less desire to build on the platform. To help with this problem, Eclipse developed PDE API Tools.

I’ll discuss four main areas around API management that API Tools can help you with.

API Comparisons

I have seen some discussion of people wanting to know what new APIs were part of the Eclipse Galileo release. While it’s pretty easy to see the new and noteworthy items for the latest Eclipse release, it’s difficult to dive into and see what actual classes and methods were modified. To help alleviate this problem, PDE API Tools has the ability to produce API comparison reports to show exactly what has changed. I have mentioned the API Tooling view in a past blog entry for those who are interested.

API Compatibility

One thing that’s important is being able to see binary compatibility issues between a build and a baseline. This is currently possible within the Eclipse IDE if you use PDE API Tools in the workspace, however, if you wanted to generate a report via an Ant task you can do that. As a sample, I generated a report against Eclipse 3.4.2 and Eclipse 3.5:

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_analysis_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.4.2/eclipse" />
	<property name="profile" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.5/eclipse" />
	<property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.analysis
	      	baseline="${baseline}"
	    	profile="${profile}"
	      	report="${report_location}"
	      	debug="true"
	     />
	    <apitooling.analysis_reportconversion
	      	htmlfiles="${html_report_location}"
	      	xmlfiles="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

API Freeze

Another aspect that’s important to Eclipse is the concept of an API Freeze.

Towards the end of the Eclipse release, we implement an API Freeze which means that no new API can be added or modified after this point. Why have an API Freeze? Well, it helps ensure stable APIs for consumers looking to adopt a new version of Eclipse. From a producer point of view, how do you ensure that the API Freeze is actually enforced? Developers are human and make mistakes. Developers can be also be sneaky by modifying API.

To help enforce an API Freeze, PDE API Tools has the ability to produce freeze reports:

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_freeze_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.4.2/eclipse" />
	<property name="profile" value="/Users/chrisaniszczyk/eclipses/eclipse-SDK-3.5/eclipse" />
	<property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.apifreeze
	      	baseline="${baseline}"
	    	profile="${profile}"
	      	report="${report_location}"
	      	debug="true"
	     />
	    <apitooling.apifreeze_reportconversion
	      	htmlfile="${html_report_location}"
	      	xmlfile="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

As part of the Galileo release, we used freeze reports as a way to ensure API stability as we converged.

API Usage

From the consumer point of view, it’s interesting to see how people are consuming your APIs. To help with this, API Tools has the ability to run usage reports against a set of bundles. Awhile ago, I blogged about this topic and produced a report against most of the bundles included in the Galileo release:

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_use_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-galileo" />
    <property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.apiuse
	      	baseline="${baseline}"
	    	proceedonerror="true"
	      	report="${report_location}"
	      	considerinternal="true"
	      	considerapi="true"
	      	debug="true"
	     />
	    <apitooling.apiuse_reportconversion
	      	htmlfiles="${html_report_location}"
	      	xmlfiles="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

I hope this helps and allows you to understand and adopt PDE API Tools.

Also, the PDE team is currently in the planning stages for the next release.

Please file any bugs if you have issues or suggestions so the PDE team can act on them.

Tags: api, galileo, OSGi, pde

As readers of my blog are no doubt aware, I have been counting down the Top 10 Galileo features that I’m most excited about. Galileo is the name of this years “Eclipse Release Train”, the simultaneous release of 33 Eclipse projects. Galileo will available for download on June 24th, but “Friends of Eclipse” get it sooner. Friends of Eclipse is a donation program setup by the Eclipse foundation.

Support the tools that support you. The best $35.00 you will ever spend.

Number 6 on my Top 10 list is the new Install Into Self option. While many people view the Eclipse SDK as an excellent Java development environment; it’s the extensible nature of this environment that makes it so powerful. Eclipse is assembled from 100′s of plug-ins, and while you may commonly use other peoples plug-ins, the true power of Eclipse comes when you start to develop your own. Before Galileo, the steps for building / testing / deploying / installing your own plug-in were quite cumbersome. This has all changed in Eclipse 3.5.

Using Eclipse 3.5 you can quickly develop your own plug-in (maybe it’s a new static code analysis view or an awesome new twitter client – All the cool kids are building twitter clients these day), and deploy it directly into your running instance. This makes development / testing / deploying much easier and enables all developers to “eat their own dog food”.

I consider this feature a “game changer” as it completely changes the way I work with Eclipse. Kudos for this feature go to Curtis Windatt with help from John Arthorne for p2 side of things. Thanks guys!

Tags: galileo, pde

Awhile ago, I blogged about PDE API Tools and the usage scans feature. In honor of the Eclipse Galileo release, I decided to run the usage scan tool and generate a report against a good portion of the release to see if anything interesting came up. I was particularly looking at what bundles were accessing internal code. I decided to look at the org.eclipse.compare bundle and noticed that PDT had some internal references:

If we dig deeper and look at a particular set of internal references, we notice org.eclipse.php.ui using various classes:

As an API provider (in this case, org.eclipse.compare) you have a couple questions you can ask yourself based on a report like this. Why are my consumers accessing these particular internal classes? Is there API I can point my consumers too that they can use instead of the internal classes? Should I make these classes API or craft API? And so on…

Does anyone else see interesting internal usage?

Do people want to see this type of report run against Galileo and future release trains?

For those who are interested, here’s the build script that I used to generate the report.

<?xml version="1.0" encoding="UTF-8"?>
<project name="api_use_reporting" default="run" basedir=".">
    <property name="baseline" value="/Users/chrisaniszczyk/eclipses/eclipse-galileo" />
    <property name="report_location" value="${baseline}/api" />
	<property name="html_report_location" value="${baseline}/api-html"/>
 
	<target name="run">
	    <apitooling.apiuse
	      	baseline="${baseline}"
	    	proceedonerror="true"
	      	report="${report_location}"
	      	considerinternal="true"
	      	considerapi="true"
	      	debug="true"
	     />
	    <apitooling.apiuse_reportconversion
	      	htmlfiles="${html_report_location}"
	      	xmlfiles="${report_location}"
	      	debug="true"
	    />
	  </target>
</project>

Enjoy.

Tags: galileo, pde

I have been working with the upcoming Equinox OSGi book authors quite a bit as of late. They are a demanding bunch, but they have helped me improve PDE’s OSGi tooling while they write and exercise parts of PDE that not many people know about. In particular, the book uses something in PDE called Automated Management of Dependencies (AMD). What’s that? Well, have you ever noticed this collapsed section in the PDE editor:

Let’s take a peak!

This section of the manifest editor was built for people who have different bundle development workflow. At Eclipse, we have traditionally done a manifest-first workflow where users are responsible for crafting their whole manifest. I personally believe this is the best workflow for advanced users. However, for new users, it’s very cumbersome to specify your dependencies. For example, if I want to use some JFace Databinding code, how do I know what bundles or packages I need to specify? Well, AMD was built to address this concern. The first step to using AMD, is to add the bundles that PDE will consider to when generating your dependencies (we call this the secondary classpath). The easiest thing you can do is add all the bundles as part of your target (although this isn’t always optimal):

Ok, now that we have added all the bundles that PDE will consider when generating the dependencies, we need to select what type of dependencies PDE should generate. In this case, we choose Import-Package, but you can as easily choose Require-Bundle if that was your preference. To test the AMD functionality out, we will remove all of our current dependency statements, which will result in a bunch of compile errors in our project:

So now, we can either click the analyze dependencies button in the AMD section of the editor… or we can simply launch our application and the dependencies will be automatically calculated. To verify, let’s look at our manifest:

Wow, magic! PDE analyzed the code and calculated the dependencies so you didn’t have to think about it.

This works great, however, not everything is perfect yet… there are a couple bits missing. If you noticed, the version ranges weren’t properly calculated on the dependencies. This is a hard problem and we are currently exploring it in the PDE API Tools project. It is also a bit cumbersome to add things to your secondary classpath… should the default be that we look at everything in your target? Should PDE look at using something like BND to do the dependency calculation? Should we allow people to somehow scope the bundles in advanced… while creating a new project? If you’re interested in this functionality, please let me know. The PDE team plans to explore and improve AMD in the next release cycle, so please comment if you have ideas. You can also file bugs and feature requests against PDE.

I’ve also created a quick video which shows AMD usage with the RCP mail example.

Enjoy.

Tags: OSGi, pde

For those of you who don’t know, the Eclipse SDK now ships an implementation of OSGi Declarative Services (DS). I love DS when working with OSGi services and recommend it to people over using the brittle ServiceTracker mechanism. I’m a big proponent of having people learn by example. To help people understand DS a bit more, PDE includes a DS template now. To access the template, simply create a new project and select the template:

Since the template is based on a simple dictionary service, you can fill out some sample words to be in the dictionary:

Once you click finish, PDE will generate a sample project for you. Inside that sample project, there will be a DictionaryService that allows you to register dictionaries (Dictionary):

package org.eclipse.equinox.ds.example;
 
public interface Dictionary {
 
    /**
     * Returns the language of the dictionary
     *
     * @return the language of the dictionary
     */
    public String getLanguage();
 
    /**
     * Check for the existence of a word in the dictionary
     * 
     * @param word the word to be checked.
     * @return true if the word is in the dictionary
     */
    public boolean check(String word);
 
}

You will also notice that the MANIFEST.MF has an entry of ‘OSGI-INF/*.xml’ for the Service-Component header that lists the required DS files. If we take a peak at the component that registers a sample dictionary, it looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="Simple Dictionary">
   <implementation class="org.eclipse.equinox.ds.example.DictionaryImpl"/>
   <service>
      <provide interface="org.eclipse.equinox.ds.example.Dictionary"/>
   </service>
</scr:component>

The Java code equivalent of registering the sample dictionary without DS would look something like this:

...
service = new DictionaryImpl();
// register the service
context.registerService(DictionaryService.class.getName(), service, null);
...

Great, less code we have to write! Now let’s look at a more complicated example of declaring a component that both needs and registers a service:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="Command Provider for Dictionary Service">
   <implementation class="org.eclipse.equinox.ds.example.ServiceComponent"/>
   <service>
      <provide interface="org.eclipse.osgi.framework.console.CommandProvider"/>
   </service>
   <reference bind="setDictionary" cardinality="1..1" interface="org.eclipse.equinox.ds.example.DictionaryService" name="Dictionary" policy="static" unbind="unsetDictionary"/>
</scr:component>

If we had to write this in code, it would involve a ServiceTracker to track the dictionary service, registering our component’s CommandProvider service implementation and code to track dictionary implementations. All in all, it would be quite a chunk of code to keep track of everything. It would get more complicated if we allowed for different cardinality types.

As a reminder, you can also use the DS Tooling in PDE to help craft these component definitions:

Let’s test this example now by launching a new self-hosted instance and checking out the console:

Cool, we can now check for the existence of words in our dictionary using the Equinox console.

Here’s the code used in this example. To test, simply use the ‘Dictionary Example’ launch configuration included:

For a bonus tip, there are console commands to help you debug DS:

---Service Component Runtime---
     list/ls [-c] [bundle id] - Lists all components; add -c to display the complete info for each component;
     use [bundle id] to list the components of the specified bundle
     component/comp <component id> - Prints all available information about the specified component;
     enable/en <component id> - Enables the specified component;
     disable/dis <component id> - Disables the specified component;

Also, I highly recommend using ‘-Dequinox.ds.print=true’ for extra debug information while debugging components that aren’t working like you expect them.

Good luck and I hope this helps! If you want more in depth knowledge of DS, I highly recommend checking out the new Equinox book which showcases an in depth chapter on DS.

Tags: equinox, OSGi, pde

Eclipse 3.5 M7 is out! Get it while it’s hot! (new and noteworthy)

Note this is the last major milestone release of Eclipse for Galileo and marks feature freeze. No more new features after this milestone, only bug fixes until the Galileo release in late June. Here are some of my favorite noteworthy items:

SWT.SHEET support

Improved PDE Target Provisioning Support

PDE API Tooling Comparisons

I hope you enjoy the release this year, the Eclipse Platform team put in a lot to close out the year. Thank a committer if you see one

See you for next year’s release (which we have yet to name)!

Tags: eclipse, pde

I’ve been doing bundle development for a very long time so I have a lot of fantasies of how we can improve development workflows. One of my fantasies while working with my target platform has been to have it automatically provisioned to me based on some requirements. Well, I’m happy to report that PDE now supports provisioning your target platform from a repository (as of Eclipse 3.5 M7) which makes my fantasty come true!

What does this mean? Well, let me walk you through a short demo:

The first thing to do is to create a new target definition in PDE (File->New->Target Definition):

For the purposes of this demo, let’s create a empty target to work with the Eclipse Communications Framework (ECF):

Next, let’s add some content to our target definition and choose the ‘Software Site’ source:

Let’s point to the Galileo repository as that’s where the ECF SDK lives:

Once that happens and we set our target platform, PDE will resolve the target definition and download everything that is needed:

Tada! After waiting for the target to resolve and download, we have everything we need to develop against ECF!

What exactly is going under the covers here? Well, PDE now allows you to craft a target definition using p2 IUs from a software site (repository). Just as we selected ECF, we could be building another product that needs Riena and ECF so we simply select the Riena and ECF IUs. All software-site based target definitions now are managed by a p2 profile and share a local bundle pool in the PDE metadata area. These target definitions are now easily shareable with your colleagues. You simply have to craft a target definition with the right information and put it somewhere your colleagues can access it. One of the coolest things about this feature is that since we use p2, you can plug in any repository and things would work transparently. For example, if someone wrote a p2 connector to talk to Maven or OBR repositories, things would work transparently since everything is an IU!

Note that if you aren’t comfortable with people provisioning a target from a software site, you can choose the other sources for content (directory, features, installation) and ship a target locally or in a SCM (this was how things worked before).

In the future, you’ll continue to see closer PDE and p2 integration.

Hope this helps! If you have any bugs or suggestions, please file a bug.

Tags: OSGi, pde

In Eclipse 3.5, the PDE team has been hard at work improving the API Tools component. One of the new exciting features we have planned for Eclipse 3.5 M7 is comparing baselines. To compare an API baseline, simply right click an API Tools enabled project and select the ‘Compare With -> API Baseline’ menu option (I’m using an Eclipse 3.5 build with an Eclipse 3.4.2 baseline):

Once you do that, you should be presented with the ‘API Tooling’ view:

No changes have been found? Oh, that makes sense since the org.eclipse.ui.views.log bundle doesn’t contain any API. Let’s choose the ‘org.eclipse.osgi’ bundle which definitely should have some API changes in it:

Look at that! You get information about methods and types added!

Hope this helps! If you have any ideas on how to improve API Tools, please file bugs.

Tags: OSGi, pde

In the traditional RCP development workflow, you find yourself self-hosting a lot. If you don’t know what self-hosting means, it’s simply the process of launching a new Eclipse instance and executing the bundles you were working on in your workspace. This works well as there’s no real deployment step, but what happens if you want to run what you’re working on inside your current running Eclipse (host)? Well, you could use the classic, “export, copy, paste, delete, restart” technique” but that’s not optimal and takes some time. How do we get around this? Well, in Eclipse 3.5, PDE has new functionality to directly export into your host.  To demonstrate this functionality, let’s create a sample project using the ‘Hello, World Command’ template:

Then let’s export into our host using a new option in the export wizard:

Once we export and apply changes, we should see the sample plug-in installed and running (check the toolbar):

To uninstall, simply go to the ‘Installation Details’ page via the About page:

Hope this helps! I also created a video of this workflow in case anyone is interested.

Tags: pde

At the recent OSGi Tool Summit, one of the biggest discussion items that came up was visualization. This makes perfect sense to me as visualizations can be a powerful tool, whether it’s for reviewing your architecture or sharing information with colleagues. In the OSGi world, I only know of two projects starting to scratch the surface of visualizing OSGi systems: PDE and Knopflerfish. Since I co-lead PDE, let me speak about what I know best. In PDE, I recently published a new build of the PDE Visualization project:

To install, point Eclipse (Help->Install New Software…) to this repository (make sure you have the Galileo or Ganymede repository in your list of repositories so p2 can reason about the dependencies). I recommend using Eclipse 3.4 or later too.

A couple days ago, I spent some time polishing the visualization code and pondering about what functionality is missing. First and foremost, the biggest thing missing is the ability to visualize packages and services. Currently, it’s only possible to visualize bundle-level dependencies and the only reason this is the case is because noone has spent time to add support! Another cool feature that’s missing in my opinion is to measure dependency extent. Imagine for a second if the screenshot above included information on the weight of a dependency… for example the lines could be thicker to signify how “strong” of a dependency org.eclipse.jdt.core has on certain bundles. This type of information would allow us to potentially prune bundles that we didn’t really need or catch mistakes where we bring in one bundle that depends on the “rest of the world.” There’s so many possibilities when you start thinking about it!

What do people out there want to see in their OSGi visualization tools? Any crazy ideas?

If you’re interested in helping the PDE Visualization project move forward, let me know and I’d love to help you contribute. In my opinion, it would be a great opportunity to get invovled with PDE and potentially the Zest project (which powers the visualizations). Don’t be shy and feel free to shoot me an email.

Tags: OSGi, pde