In my previous post, I referenced a plugin which provides API code. The term API "code" is a bit of a misnomer. Depending on your degree of semantics, API is actually not code at all. API is your contract with external developers. It's surprising how much - rather little - thought goes into what constitutes API code. Code which leaks from a plugin through OSGI exports can create errors in design during the development process. It takes one sufficiently large software project to learn this lesson the hard way. A great podcast that explains the API concept is Episode 143: API Design with Jim des Rivieres on Software Engineering Radio.
The developerWorks Connections platform will be sunset on December 31, 2019. On January 1, 2020, this blog will no longer be available. More details available on our FAQ.
Coding IBM Collaboration Solutions
From archive: October 2010 X
Kind of an odd title, but good for search engines. After searching the web and Eclipse bug reports, I failed to find what seemed like an obvious issue. I found one thread that matched the problem, but it looked as though the respondents misunderstood the question. So here it goes.
When you deploy API plugins to a platform, developers are expected to target the platform, and reference the exported API. You do this all the time during the course of plugin development. Within the Eclipse IDE, you begin by targeting an Expeditor or Notes platform. Then you to develop new plugins which reference the exported Java types or contribute extensions to those plugins.
But the developer has decided that his plugin should be unpacked (unjared) during installation.
Now let's assume that the com.ibm.rcp.support.unpack.provider plugin is deployed into the field either via an update site or bundled product. An eager developer intends to use the Provider type. He targets the platform containing the com.ibm.rcp.support.unpack.provider plugin, adds it to his dependency list, and adds the Provider type into his code. What happens? Interestingly, he receives a compile error stating that the Java type can not be resolved. This is odd because the plugin dependency is satisfied and the original plugin exports the necessary packages. What gives?
It turns out this is a known issue in Eclipse 3.4.2. Because the com.ibm.rcp.support.unpack.provider plugin unpacks itself, it is not added to the classpath appropriately. While not a run-of-the-mill developer issue, it is a bit counter intuitive. But then again, many bugs are exactly that.
How much importance do you give to a plugin's name? After all, it matters what the plugin does rather than its name, right?
Most developers new to RCP generally name their projects not realizing the importance of the project name. For example, you start a new software feature with the project name MyRemoteWebServiceClient. The "problem" is that Eclipse's plugin development environment, PDE, inherits the bundle symbolic name from the project name. So both the project name and plugin name are MyRemoteWebServiceClient. So, what? If you look at Lotus Notes, Sametime, or Expeditor, the naming is seemingly cryptic or even verbose. After all, a plugin named com.ibm.rcp.support.ws.remote.client.jaxws seems much more mysterious than MyRemoteWebServiceClient. The naming convention becomes much more meaningful after deployment or when scaling development.
Generally, plugin naming convention mimics the Java package naming within the source code. For any plugin, I'd expect the top level package in the plugin to be named the same. For example, com.ibm.rcp.support.ws.remote.client.jaxws should have a top level package called com.ibm.rcp.support.ws.remote.client.jaxws. How is this useful? Let's assume that a product fails with the exception:
Once you get beyond the sun packages, we're in the plugin developer's code (com.ibm.rcp.support.ws.remote.client.jaxws). Given the package name or class, how do we know to which bundle this code applies? In other words, who just threw that exception? Since there are no rules, we rely on convention. To inspect the Lotus RCP platform, we can use some OSGI commands from a previous post. To find the bundle, you might issue the command:
which in turn might output:
Now you know there are actually two bundles sharing the com.ibm.rcp.support.ws identifier. I bet they're related, but more importantly bundle 24329 matches the Activator's package com.ibm.rcp.support.ws.remote.client.jaxws. Aha, there's the offending plugin!
This may seem a bit contrived, but given an error at runtime:
Similarly if you're a developer working on a sufficiently large cross-team development project, knowing that the package name matches the bundle ID is helpful. How would you ever know com.ibm.rcp.support.ws.remote.client.jaxws.Activator belongs to MyRemoteWebServiceClient? This is especially true when the source is owned by another development team.
So no more non-package project names in CVS ... unless it's HelloWorld ;)