Platform scheme URI

Wow... It has been more than six months since the last time I took a few minutes to write something here. Things have been a bit crazy lately. A lot has kept me occupied, like, for example, writing the 2nd version of the EMF book (which is "already" available as a rough cut), working on a few bugzillas, and supporting the EMF community. On a more personal note, in October we moved to our new house right when our son was entering the "terrible twos" days. Actually, since then, my wife and I have been working as maniacs to finish the basement and prepare the kids' rooms for the arrival of the new member of the Paternostro family, who is supposed to be here by the end of April.

But I am sure you are not reading this to hear about what I've been doing ;-) So, let's move on to the subject of this post. Quite frequently people ask me how to "locate" files in Eclipse. In 80% of the cases, the conversation is about things like IFile and IWorkspace. Sometimes it digresses to files available inside bundles and, rarely, it involves the "state location" of a bundle (see the Plugin.getStateLocation() javadoc for more details). Obviously you can use IResources or java.io.File to work with files in these places. There is another way, though: platform URI. Although this scheme has been around since the beginning of time, I decided to ramble about it here because I've never seem its uses described in one single place.

There are a few ways to work with the "platform" scheme:

platform:/resource	It is used to identify a resource located in the workspace. The next path segment after "resource" should be the name of a project, which can be followed by the folder and/or file we want to locate.
platform:/plugin	It is used to locate a resource available in a plug-in (I know, I know, bundle). One really cool thing about this one is that it doesn't really matter if this resource is available in a directory or in a jar file. It also doesn't matter if the bundle is installed in a link folder or in the default directory. The path segment after "plugin" should be the identifier of the bundle, which can be followed by the path of the resource in the bundle.
platform:/fragment	This one is quite similar to "platform:/plugin", being to used to locate fragment resources instead of bundle resources. As you are probably guessing, the segment after "fragment" should be the fragment's identifier.
platform:/meta	We can use this to access a bundle's stage location. The path segment after "meta" should be the bundle's identifier, followed by the path of the resource we want to refer to.
platform:/config	The "config" segment causes the platform URI to refer to the configuration area of the running Eclipse (usually the eclipse/configuration directory). This can be useful to read the config.ini file, for example.
platform:/base	This always refers to the directory of the Eclipse being executed. It is interesting to note that, for example, platform:/base/plugins/org.eclipse.emf/plugin.xml and platform:/plugin/org.eclipse.emf/plugin.xml don't necessarily refer to the same resource. The former is a "pointer" to a plugin.xml file located in a directory plugins/org.eclipse.emf under the directory that Eclipse is installed. The latter points to the plugin.xml of the "org.eclipse.emf.ecore" bundle regardless of where it is installed and whether it is jarred or not.

For the URI-savvy people, you should see "resource", "plugin", "fragment", "meta", "config", and "base" as authorities. Perhaps they could become authorities in e4 (yey! Now this is an e4 related post ;-)

Since we all like actual code...

IProject project = 
ResourcesPlugin.getWorkspace().getRoot().getProject("myproject");
if (!project.exists())
{
  project.create(new NullProgressMonitor());
}

System.out.println("\n==== platform:/resource ====");
{
  URI uri = URI.createPlatformResourceURI("myproject", true);
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));
  
  uri = uri.appendSegments(new String[]{"folder", "file.txt"});
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));
}

System.out.println("\n==== platform:/plugin ====");
{
  // Just for fun, choose a bundle that is not in the default location
  URI uri = URI.createPlatformPluginURI("org.eclipse.emf.ecore", true);
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));
  
  uri = uri.appendSegments(new String[]{"model", "Ecore.ecore"});
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));

  // Choose a bundle that is in the default location (<eclipse-dir>/plugins)
  uri = URI.createPlatformPluginURI("org.eclipse.core.resources", true);
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));

  uri = uri.appendSegments(new String[]{"META-INF", "MANIFEST.MF"});
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));
}

System.out.println("\n==== platform:/fragment ====");
{
  URI uri = URI.createURI("platform:/fragment/org.eclipse.swt");
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));
  
  uri = uri.appendSegments(new String[]{"META-INF", "MANIFEST.MF"});
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));
}    

System.out.println("\n==== platform:/config ====");
{
  URI uri = URI.createURI("platform:/config/");
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));      
}    

System.out.println("\n==== platform:/base ====");
{
  URI uri = URI.createURI("platform:/base/");
  System.out.println(uri);
  System.out.println(CommonPlugin.resolve(uri));      
}

The call to CommonPlugin.resolve(URI) returns a URI that uses a protocol which is native to the Java class library (file, jar, http, etc).

I will leave it to you to run this code and see the results :-P Don't forget that it must be executed in an Eclipse shell. Probably the simplest way to do so is to paste these lines into a JUnit test located in a bundle and execute it as a "JUnit Plug-in Test".

So what can we do with platform URIs? For one, read the contents of the resources pointed by them. We may also be able to write to such resources or even delete or create them. A tip for EMF 2.4 users: URIConverter.INSTANCE allows easy access to methods that are extremely handy when dealing with URIs (createOutputStream(URI), createInputStream(URI), delete(URI), and exists(URI)).

Personally I consider URIs a good fit for APIs that would normally use "plain" paths. Take as an example the icon attribute of the extension point below. Because its value is handled as a URI, we are allowed to refer to an image located in a different bundle.

<extension point="org.eclipse.ui.editorActions">
  <editorContribution ...>
    <action 
      icon="platform:/plugin/com.myplugin/icons/me.gif"
      ...
    />
  </editorContribution>
</extension>

BTW, if I were to implement the code to process such an extension point, I would probably do something like this:

IConfigurationElement configurationElement = ...
URI iconURI = URI.createURI(configurationElement.getAttribute("icon"));
if (iconURI.isRelative())
{
  URI pluginURI = 
    URI.createPlatformPluginURI(
      configurationElement.getContributor().getName() + "/", true);
  iconURI = iconURI.resolve(pluginURI);
}

try
{
  ImageDescriptor imageDescriptor = 
    ImageDescriptor.createFromURL(new URL(iconURI.toString()));
  descriptorImpl.setIcon(imageDescriptor.createImage());
}
catch (Exception e)
{
  e.printStackTrace();
}

This code assumes that when the value of the icon attribute is a relative URI (like icon/me.gif for example), the developer is indicating that the image is contained in the bundle that uses the extension point.

For obvious reasons, I wrote these examples using EMF APIs, including our URI class. It shouldn't be terribly difficult to rewrite the code in this post to use basic Eclipse and Java code (like, java.net.URI).