I’ve been pensive as of late since we shipped the Eclipse Galileo release. One of the things I personally have been thinking about is how we can improve our documentation process. Currently, the Eclipse platform team has its documentation in Eclipse Help format (mostly HTML)… all this is kept in source control. In its current shape, the documentation isn’t conducive for people to contribute. There’s a lot of hoops a potential contributor needs to jump through in order to contribute documentation. Even more hoops if our documentation contributor isn’t really a developer. I also know a few committers who dread doing documentation because they have to hack away at HTML documents.

Can we do better? I think we can.

I’m interested in crowdsourcing the documentation at Eclipse.

What do I mean here? Well, I luckily have one example in the Eclipse ecosystem that is crowdsourcing its documentation already. The Mylyn project has its User Guide on the wiki.

The Mylyn project then uses WikiText to parse this wiki markup via a script and generate relevant Eclipse help artifacts.

In the end, there’s one source for the documentation (the wiki) where a multitude of people can easily contribute to. If we look at the Mylyn User Guide, we can see there was a decent amount of edits involving people who weren’t committers.

I’ve been experimenting with this documentation process for PDE and am pretty happy with it. There were only a couple of roadblocks I hit, but that was mostly around making it easier to use some of the WikiText ant tasks within Eclipse. I also experimented with some html2wiki transformers to help convert some of the existing PDE documentation.

One of the reasons I was inspired to look at crowdsourcing documentation for PDE was an excellent series of articles by Ekkehard Gentz on PDE’s new target platform provisioning story. I thought to myself, how could get Ekke to easily contribute that documentation (or even future docs) to PDE where it could be beneficial to everyone?

One point to bring up is that a lot of the Eclipse documentation is on the Eclipse wiki (Eclipsepedia) already. The Eclipse user community has most likely come across Eclipsepedia already. We can also assume that most people are comfortable with wiki syntax or at least the editor that comes with MediaWiki by default. If this isn’t the case, we can try to install something like the FCKEditor extension for MediaWiki to make it easier.

Another point to bring up is that having the documentation sourced from the wiki may have an interesting benefit due to early adopters. For a real world example, I’ll talk about the Equinox p2 project. There have been some complaints that the p2 documentation wasn’t robust enough for early adopters. Well, what happens if those early adopters would be willing to be part of the documentation process? As users adopt the technology, they can document their experiences along with the p2 committer team. If this was set as an expectation, I don’t think people mind sharing their experiences and being part of a team trying to build a cool technology.

What do people think? Is this good for other Eclipse projects?

Would you be enticed more to contribute to official project documentation if it was easier?

Tags: documentation, eclipse, syndicate, wikitext

There is an interesting op-ed in today’s NY Times from the venerable Robert Cringley:

Chrome vs. Bing vs. You and Me

Cringley implicitly asserts that neither Google nor Microsoft are going to innovate in the interest of You and Me and sadly, I think this is all-to-often true in ‘big-time, big-money’ corporate software.

First and formost, companies are interested to achieve ever higher ROI for their shareholders. This does not necessarily mean that they will build anything of value for You and Me.   They may innovate and that’s terrific when it happens. However, if they can make more money by attacking each other and protecting their existing turf… I think it’s pretty clear they will frequently do so.

In my view, this points directly at a long-term sustainable role for open source and startup ecosystems:  end-user-focused innovation.  Of course, as Bjorn Freeman-Benson points out, end-user focus can be a challenge for open source communities.

What’s your opinion?

Tags: eclipse, eclipse foundation, innovation, Open Source

e4 0.9M5 is now available for download.  One of the things that excites me about this work is the web based form editors that Boris Bokowski has been working on.  The form editors have always tried to mimic a web look and feel, but now they are using real web technology.

The e4 team has even integrated these editors with the workbench.

For a complete list of features, checkout the e4 New and Noteworthy.

Tags: e4

If you are into unit testing, you may find EasyMock quite useful. It is very valuable for making hard-to-test-code testable.

For example I recently was adding tab-switching via keyboard to Riena. The state of each tab is kept in an interface named INavigationNode which has about 40 methods (!). Creating a mock by hand for such a big interface would not be fun at all. With EasyMock it just takes is a call to:

ISubApplicationNode nodeA = EasyMock.createMock(ISubApplicationNode.class);

The code for determining the next tab, depends strictly on the isSelected property. Manipulating the return value of this method takes just another EasyMock call:

EasyMock.expect(nodeA.isSelected()).andReturn(true);

This tells EasyMock that nodeA.isSelected() will be called once and should return true.

After everything is set-up I switch from ‘record’ to ‘play-back’ mode:

EasyMock.replay(nodeA);

Here’s a full example of a test case:

  protected void setUp() throws Exception {
    super.setUp();
    handler = new SwitchSubApplication();
    nodeA = EasyMock.createMock(ISubApplicationNode.class);
    nodeB = EasyMock.createMock(ISubApplicationNode.class);
    nodeC = EasyMock.createMock(ISubApplicationNode.class);
  }
 
  public void testFindNextSubApplicationAtoB() {
    EasyMock.expect(nodeA.isSelected()).andReturn(true);
    EasyMock.replay(nodeA);
 
    ISubApplicationNode[] nodes = { nodeA, nodeB, nodeC };
    assertSame(nodeB, handler.findNextNode(nodes));
  }

This post barely scratches the surface. Curious? Read this nice EasyMock introduction.

Image: (c) *Micky/flickr. Licensed under creative commons.

Tags: riena, testing, tips

On Canada’s west coast we have been having an unbelievable summer.

While the sunshine (and the beach) have a tendency to lure me away from my computer, there has been so much Eclipse activity this summer  that it’s challenging to get away.  One of the things I’m most excited about is the Google Summer of Code work going on in Zest.  Zest is my small graph widget toolkit.  Up to now it has been something I’ve worked on in the evenings and weekends.  However, this all changed when not one… but two students signed up to work on Zest.

Mateusz Matela, has ventured into the world of Zest layouts.  I wouldn’t ask my worse enemy to look at the layouts, but Mateusz managed to refactor the entire package, removing much of the dead (and error prone code) and he came out with a much cleaner (and simpler) design.  Mateusz even managed to fix some bugs along the way.  For the rest of the summer, Mateusz will be adding some new widgets to our library, allowing you to expand and explore complex graphs.

Fabian Steeg has be working on a GraphViz to Zest transformation toolkit. Using this toolkit you can write GraphViz and generate Zest diagrams.

This is done by using a GraphViz DSL (thanks to the oAW team for this great work) and set of Java Emitting Templates.  Fabian also has full text editor for GraphViz and custom builder that will generate the equivalent Zest code.

Fabian has also been working on the reverse transformation (Zest to GraphViz).

I’m not sure how Zest ended up with two of the best Summer of Code students, but I’m very excited about the future of the project.

Great work guys!

Tags: gef, soc, zest

Yesterday I spent the day working on examples of how PDE Build can be used to build OSGi bundles.  I was setting up builders, copying files from my workspace to my builder, and running builds.   Early in the morning I was faced with the follow:

The method disposeImageButtonImages(ImageButton) from the type
ScaledWidgetFactory refers to the missing type ImageButton

Ok, a compile error, no big deal… the better part of a day later I finally had this solved.  Just so nobody ever has to deal with this particular error again, I thought I would post a small debugging tip you can use.  But first, some background on my day (after I saw the error):

1. Ensure export from the UI works… yes!
2. PDE/Build defines a variable called pluginPath that you can use to point at additional plugin locations.  Since the missing type  –ImageButton in my case — was in a pre-compiled bundle that exists in my target, I assumed this variable was set wrong.  I tried different separators, bundle ordering and directory locations (with and without spaces in the name). I even tried putting the bundle in my baseLocation.  No dice.
3. You can debug Ant scripts using PDE/Build.  There are a few things that you must setup first, but after I did this I was able to debug the script and ensure that the “so called ‘missing’” bundle was indeed in my classpath.
4. At this point something hit me — the compile errors is on the method call, not the import statement. That means that the compiler found the type on import, but not when the method was called…. strange!
5. In this particular example we are using Import-Package as opposed to Require-Bundle. Maybe I found a bug… I changed all the code to use Require-Bundle… No Dice.
6. Because build can be finicky, and and a typo can cause all sorts of problems, I started again… Same problem.
7. Read a story to my daughter. (Best part of the day, by far)
8. Back to work… This time, I started making small changes in different bundles, copying them over, and trying again… At one point, IT WORKED!
9. Revert the changes… IT WORKS! — Note: That’s not good
10. Start over, .. IT FAILS… make the same changes I did above.. IT FAILS!
11. Curse
12. Notice something.. when I copy the directories over, I am copying a bin/ directory that may (or may not) have fully built .class files.
13. Delete the bin/ directory .. IT WORKS!

In fact, the problem will happen very infrequently.  It only happened because I was copying bundles from my workspace (not fetching them from CVS), and in some cases, the bundles were not fully built.

So, the lesson: If you get strange compile errors using PDE Build, try deleting the bundles bin/ directory.

Thanks goes out to Andrew Niefer who once again came through with a much better way off structuring my build.

Tags: pde, pde build, tips

Previously, I blogged about the current state of the Eclipse Packaging Project (EPP) Wizard. I have good news, the EPP wizard is now officially available.

The wizard has been embedded in our own company download site under the Customize Download button. If you start on the Eclipse Foundation download site and chose to download your packages from EclipseSource, you have the option to download an unmodified package from the Cloud but also the possibility to use the EPP Wizard to create your own download. If you select the latter option, the wizard will be opened with the package content you already selected on the Eclipse download site. If you are satisfied with your selection just go to the finish page of the wizard and select the packages you want to install.

Can you spot the difference in the screenshots bellow?

Install new Software Dialog with Update Site Management

Install new Software Dialog without Update Site Management

We found out that some installations created with the EPP Wizard don’t have the p2 UI for management of repositories (update sites). The available update sites are shown under Preferences > Install/Update > Available Software Sites and under Help > Install New Software… but you don’t have the possibility to edit them. This issue was fixed last week but if you have an older installation and the update sites management functionalty is missing you have to change the start options of the bundle org.eclipse.equinox.ds to get it. The start options associated with bundles are saved into the bundles.info located under eclipse/configuration/org.eclipse.equinox.simpleconfigurator/bundles.info (in this case eclipse is the directory of your eclipse installation). Just change the start options of the bundle org.eclipse.equinox.ds from “4, false” to “2, true” and restart your eclipse.

The EPP Download Wizard integrates Yoxos OnDemand as external service provider. Yoxos OnDemand is a free Eclipse download and update service we provide. Yoxos OnDemand provides access to additional third party content which is not available from the EPP Wizard. However, from the EPP Wizard, you can continue your download with Yoxos without losing time because your selection will be sent to Yoxos.

If you encounter other problems or have ideas how to improve the wizard please send us feedback through our feedback form on our download site.

Tags: epp, galileo, p2

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

When adding keybindings to an existing Eclipse RCP application, it is extremelly helpful to get realtime information about which keybinding registered and to what command handlers it is mapped to. Why is that?  Because sometimes the operating system or another widget will consume the keyboard event before it gets to the command framework. Other times there are several handlers bound to the same key causing a conflict.

Enabling Tracing for Keybindigs

Fortunatelly, this information is easy to get, if you enable the right tracing options:

org.eclipse.ui/debug = true
org.eclipse.ui/trace/keyBindings = true
org.eclipse.ui/trace/keyBindings.verbose = true

After that each keystroke will produce some output on the console:

KEYS --- WorkbenchKeyboard.press(potentialKeyStrokes = [CTRL+PAGE_UP, CTRL+])
KEYS --- WorkbenchKeyboard.executeCommand(commandId = 'org.eclipse.riena.navigation.ui.previousSubApplication', parameters = {})

In the above you can see that Ctrl+PageUp is mapped to the ‘previousSubApplication’ command.

Some times there is a conflict – i.e. one keybinding is mapped to two or more ‘active’ command handlers. This looks like this:

BINDINGS --- A conflict occurred for CTRL+SHIFT+W
BINDINGS ---     [Binding(CTRL+SHIFT+W,
	ParameterizedCommand(Command(org.eclipse.ui.file.closeAll,Close All,
		Close all editors,
		Category(org.eclipse.ui.category.file,File,null,true),
		org.eclipse.ui.internal.CloseAllHandler,
		,,true),null),
	org.eclipse.ui.defaultAcceleratorConfiguration,
	org.eclipse.ui.contexts.window,,,system), Binding(CTRL+SHIFT+W,
	ParameterizedCommand(Command(org.eclipse.riena.navigation.ui.closeModuleGroup,Close module group,
		,
		Category(org.eclipse.riena.navigation.ui.swt,Riena Navigation Commands,null,true),
		org.eclipse.riena.internal.navigation.ui.swt.handlers.CloseModuleGroup@39880a,
		,,true),null),
	org.eclipse.ui.defaultAcceleratorConfiguration,
	org.eclipse.ui.contexts.window,,,system)]

What happened here is that Ctrl+Shift+W was already bound to the CloseAllHandler via the ‘file.closeAll’ command. I was not aware of this initially, because it is defined in the org.eclipse.ui plugin. So I accidentally bound another command and handler to Ctrl+Shift+W. With the output I quickly realized what was going on. I ditched my own command and instead made ‘CloseModuleGroup’ a handler for the ‘file.closeAll’ command.

Tags: bindings, eclipse ui, jface, rcp, tips

With all excitement for the Galileo release, we totally missed to mention that the RAP Incubator project was approved. This is a great way to accept, distribute and mature community contributions. I look forward to some new widgets and improved tooling. For starters the project contains:

• chart support via the Google Visualization Widgets
• the GCCanvas widget
• an editor for RAP themes

Read on for more details on these goodies.

Google Visualization Widgets

This project contains over 10 new RAP widgets:

• AnnotatedTimeLine
• AreaChart
• BarChart
• ColumnChart
• Gauge
• Geomap
• IntensityMap
• LineChart
• MotionChart and ScatterChart
• PieChart
• Table

Note that the widgets are interactive – they are not just static images. The widgets have an SWT-like java interface and are build around Google’s Visualization APIs. They have been contributed by David Donohue and were originally developed for the inqle project.

Here’s some example code:

JSONGoogleDataTable dataTable = new JSONGoogleDataTable();
dataTable.addColumn("Activity", "Activity", "string", null);
dataTable.addColumn("Hours", "Hours per Week", "number", null);
dataTable.addRow(new Object[] {"Design", 12});
dataTable.addRow(new Object[] {"Development", 16});
dataTable.addRow(new Object[] {"Testing", 8});
dataTable.addRow(new Object[] {"Documentation", 4});
String widgetData = dataTable.toString();
 
PieChart pieChart = new PieChart( parent, SWT.NONE );
pieChart.setWidgetOptions("{width: 300, height: 300, is3D:true, legend:'none'}");
pieChart.setWidgetData(widgetData);
GridDataFactory.fillDefaults().hint(300, 300).applyTo(pieChart);

GCCanvas Widget

On of the most requested features in RAP is the ability to paint directly in the browser using Java. The GCCanvas widget developed by Mirko Solazzi makes this possible. It provides a Java API around  the Explorer Canvas java-script widget. This way one can draw in the browser without having to use flash or an applet.

Here’s some example code:

canvas = new GCCanvas( shell, SWT.NONE);
canvas.setSize(500, 500);
canvas.setForeground(display.getSystemColor(SWT.COLOR_RED));
canvas.setLineWidth(5);
canvas.drawLine(100, 100, 200, 200);
canvas.drawLine(200, 200, 500, 0);

RAP Theme Editor

This editor should make it much easier to customize the css-based themes used by RAP. It provides structured editing for the themeable RAP widgets. It was developed by Matthias Schaeffner during last year’s ‘google summer of code’.  The screenshots on the Eclipse wiki look very promising. Currently the tool has some issues with the recent RAP 1.2 release but we intend to fix that.

Note, please be patient while the project is created and provisioned.

If you need access to the code now follow the links in the project proposal.

Tags: eclipse, rap