Open an Eclipse Rich Client Platform application from a URL

Click a hyperlink to open an RCP application with a business object at the ready

Imagine being able to navigate to the rich function of a Rich Client Platform (RCP) application just as easily as you can navigate to a Web page today. Follow along to enable the opening of specific business objects in your Eclipse RCP application simply by clicking a URL.


Brian Fleming (, Advisory Software Engineer, IBM

Brian Fleming is an architect in IBM Software Services for WebSphere, specializing in IBM's own implementation of WebSphere Commerce Enterprise and IBM Sales Center for WebSphere Commerce.

Aaron Kasman (, Advisory Software Engineer, IBM

Aaron Kasman is an advisory software engineer in the Innovation Engineering team in the IBM CIO Office where he focuses on internal Platform-as-a-Service (PaaS) offerings, with an interest toward supporting innovators and situational application development. Prior to this role, he was part of the IBM Software Services for WebSphere team developing’s e-commerce presence. His interests include WebSphere sMash, Platform and Software-as-a-Service technologies, content and community management with Drupal and CiviCRM, and visual design.

27 May 2008

The Eclipse Rich Client Platform (RCP) provides an extremely flexible, feature-rich framework for thick clients. But one drawback is the ability to easily link to business objects in an RCP application from other sources. It would be helpful if a user were able to click a link in another application and be taken to the RCP application with a business object referred to in the link already open. For example, imagine an RCP application used to process expense claims. Perhaps a report for overdue reimbursements is generated and published as a spreadsheet (or on an intranet, or as a rich-text document, or as an e-mail, or as … well, you get the picture). The report probably has a reference number for each overdue claim. Instead of forcing the consumer of that report to copy and paste the reference number into a search dialog within the RCP application, the report could contain a hyperlink URL that will launch the RCP application, taking the user directly to that expense claim. This article will explain how to accomplish just that.

Readers should have experience writing Eclipse plug-ins, as well as general knowledge of the Windows® registry and the TCP protocol. While this article provides specific examples for a Windows operating system, the same function can be achieved on other operating systems. See Resources for more information.

Solution overview

Let's take a look at the big picture of how the solution works once it's in place. Then we will break it down and discuss how to implement each of the parts.

Follow along with the flow in Figure 1:

  1. Assume that a user already has the RCP application open on his desktop.
  2. Then suppose this user receives an e-mail in his favorite mail client containing the link rcp://claim=25222 — a reference to an overdue claim (1).
  3. The user clicks the link, which launches the user's default browser to handle the request (2).
  4. The browser knows that it cannot natively open this URL, so it consults with the Windows registry to determine how the action should be delegated (3).
  5. The registry looks up the rcp:// protocol and determines that there is a batch file bound to it (4).
  6. This batch file is executed (5), which triggers a stand-alone Java™ client (6), captures the URL's parameters, and makes a local TCP call to a TCP server embedded in the RCP application for this purpose (7).
  7. The TCP server handles parsing the parameters from the URL (i.e., claim=25222) and requests the RCP application to open the corresponding business object (8).
  8. The user is then presented with the requested business object in the RCP application UI (9).
Figure 1. Flow control when opening an RCP application using a URL
Flow control when opening an RCP application using a URL

There are many steps involved in this process, but fortunately, each is relatively straightforward and can be adapted to your environment and applications. Some finishing touches help with details like bringing your RCP application into focus in Windows.

Solution details

Registering your application to a URL protocol in Windows

Windows uses entries in the registry to recognize valid URL protocols and to determine what application a request with a particular protocol should be sent to. To enable our RCP application to respond to URLs, a key must be created under the HKEY_CLASSES_ROOT hive. The key name must match the protocol being created. In this article, we are using an "rcp://" URL protocol, so the key must be named "rcp." The default string value under this key corresponds to the display name of the new protocol. Under the "rcp" key, we must also create a shell\open\command key with a string value containing the path to the application Windows should open when it receives an "rcp://" request.

In this article, we will point Windows to a batch file (see "The batch file"). The string value for this key should also have a %1 appended to the end of it, telling Windows to pass the URL query string to your application. This is how we will pass context information, such as the particular business object to open, to the RCP application.

The following Windows batch file snippet will create the appropriate keys in your registry, with an "rcp://" protocol, which will launch Notepad. To customize the script, replace all instances of rcp with the protocol you wish to use and C:\Windows\Notepad.exe with the full path to the file you want Windows to execute.

Listing 1. Batch file code to register a URL protocol in the Windows registry
   reg add HKCR\rcp /ve /d "URL:RCP Protocol" 
   reg add HKCR\rcp /v "URL Protocol" 
   reg add HKCR\rcp\Shell\Open\Command /ve /d "C:\Windows\Notepad.exe %%1"

Note: If you prefer updating your registry manually with regedit, see Resources for an article describing how to do this.

Once the URL protocol has been registered, you can test it out by typing rcp:// into your browser's address bar and clicking Go. Notepad (or the file you chose to register) should now be open.

Other operating systems, such as Linux®, delegate the job of registering URL protocols to the browser. See Resources for instructions to register a URL protocol in Mozilla Firefox.

The batch file

Once you have tested that the rcp:// protocol we defined opens Notepad as expected, try remapping the rcp:// protocol to a batch file that will launch the TCP client. To do this, change the value for the HKCR\rcp\Shell\Open\Command registry entry. See Listing 2 for an example of how the batch file that launches the TCP client might look.

Listing 2. Batch file code to launch a TCP client
@echo off 
set JAVA_BIN=c:\<insert your java directory here> 
cd <root location of your URIClient application's package.> 
%JAVA_BIN%\java.exe %1 
Table 1. Annotations for Listing 2
Line numberAnnotation
2For example, set JAVA_BIN=C:\Program Files\IBM\Java50\jre\bin
3For example, the directory containing the TCP client's parent package
4URIClient is described below

The TCP client/server pair

As described in the overview, the user's action of clicking on the rcp:// hyperlink ultimately fires off a TCP request that hits a TCP server embedded in the RCP application. This solution involves a bit of network programming, but fortunately, the Java API takes care of the details of the TCP communication for us.

In our example, the TCP server is launched in an RCP plug-in's startup code and waits for a call from the TCP client. The call will be from the client to a server on its localhost, made on a port number known to both the client and the server. The client passes the details of the URL request to the server over a Java socket. The TCP server is then responsible for executing the appropriate RCP actions to open the business object. These actions will be specific to the particular application, but we'll deal with that in "Handling the business object."

For our demonstration, we use four Java classes that live in the package.
A stand-alone TCP client triggered by the URL selection and
Comprise a TCP server embedded in our RCP application
Some constants shared between client and server

These Java files are available for download.

The TCP server —URIServer and URIServerThread

  • URIServer is responsible for listening for requests. As it detects a request, it spawns a thread of URIServerThread that will handle the connection with the TCP client.
  • URIServer can be launched in a plug-in's initialization class. Each RCP plug-in may have an associated startup class that extends org.eclipse.ui.plugin.AbstractUIPlugin. This class's start method can initialize URIServer.
  • Our RCP application spawns URIServer by calling new URIServer().start(), launching the sever in its own thread and preventing the RCP application from blocking with waiting TCP requests.
  • Our URIServerThread handles logic for opening the business application. This will be discussed in detail in "Handling the business object."
  • Note that both URIServer and URIServerThread extend java.lang.Thread.
Listing 3. Sample plug-in start method
 * This method is called upon plug-in activation, starts up URIServer
  public void start(BundleContext context) throws Exception {

    new URIServer().start();

The TCP client application —URIClient

  • The TCP client is deployed as a stand-alone Java file not referenced by the RCP application. URIClient.main() is executed when triggered by the batch file associated with the rcp:// protocol.
  • The constructor passes the URL parameters to the tcpConnect method. This method constructs a socket targeted to the TCP server on the localhost at a host number known both to the client and server through URIConstants.
  • Tip: Consider that while the Java client isn't referenced by an RCP plug-in, deploying it within a plug-in allows the code to be updated through the Eclipse updater framework. If it were to reside outside of a plug-in, deploying code updates becomes more difficult.

Handling TCP requests

  1. How do the TCP client and server communicate? Assume that the RCP application and, therefore, the TCP server, is already running. As we have explained, the registry and batch file handle launching the TCP client. URIClient will strip off the parameters (i.e., claim=25222) and will attempt to make a socket connection to the URIServer at a port number known to the client and server.
  2. Now that the connection's been made, the server will acknowledge the client and request further instruction by sending a literal stored in the constants file, and known to the client and server. In the example, the server sends the literal sendAction. Once the client receives this instruction, it responds by sending the server the name-value pair — in this case, "claim=25222" — containing the information about the desired business object. At this point, the client and server terminate their connections.  Of course, as long as the server knows what to expect, the specific name-value pairs being sent can be customized.
  3. It's now up to the TCP server to parse the arguments and launch the appropriate actions.

Ideally, the TCP client and server that have been described above could both be launched by the RCP application, eliminating the need for a stand-alone Java application and reducing the number of deployed artifacts. Whenever the RCP application is triggered using a URL, conventional application startup would be attempted using the application's .exe or batch-file starter. However, early on in the application's initialization, the application would check whether an instance of it is already running. If the application is already running, a TCP client would be initialized and pass the URL arguments to the embedded TCP server waiting to receive such notification in the running RCP application. The server would handle opening the respective business object, as in the example above. However, if the RCP application is not yet running, it would proceed to be opened at this point, and it would use the URL arguments as RCP program arguments to open the appropriate business object.

Embedding the TCP client in the RCP application may not be possible if you are unable to access your application's early startup code, such as if you are deploying a plug-in on top of an existing application. For this reason, this article has described the more flexible approach of a stand-alone TCP client.

Handling the business object

As noted, our URIServerThread handles opening the business object. In the listing provided here, for simplicity, the code launches a dialog that shows the business object ID provided on the URL. In a real application, we would do something far more interesting, like invoke an Action that will find and open our business object that has the identifier provided.

Eclipse has a single thread for managing the user interface, and some SWT API methods may only be called from that thread. (see Resources for more information). Because our URIServerThread is running as its own thread, we need to consider this limitation. In order for a spawned thread to call back to the Eclipse workbench, it must use methods in the Display object to gain access to the UI thread. If this is not done, an ERROR_THREAD_INVALID_ACCESS error will be thrown at runtime.

Finishing touches

By default, clicking on the rcp:// link will indeed open the business object in an RCP application, but the RCP application may be hidden behind other applications, such as the one that contained the rcp:// link. It is important that we bring the RCP application into focus. In the URIServerThread listing, notice the following statements that are responsible for bringing the RCP application to the user's attention:


We have not mentioned error handling, but this is clearly necessary in several places. First, TCP communication brings along with it try/catch blocks that need to be handled appropriately. Also, one needs to ensure that cases are handled for various malformed URLs, especially to protect against intentional attacks.

You may have noticed that delegating resolution of the rcp:// protocol to the Windows default browser has the unwanted side effect of leaving a browser window open. While not ideal, this is something we have tolerated. We would be eager to hear your suggestions as to how to prevent this, especially in an environment where the RCP application is distributed widely and tweaking the user settings in Firefox might not be feasible.


The process described details a framework for opening a single business object in your RCP application using a URL. However, there are possibilities for extending this idea in interesting ways. For instance, several name-value pairs could be included in the URL to perform more sophisticated operations. Consider an order-entry application, where a URL could be used to pre-populate an order with certain products. Following these steps, any action defined in an RCP application can be accessed from any application simply by clicking a link.


Sample codeos-eclipse-rcpurl.source.zip4KB



Get products and technologies


  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Open source on developerWorks

Zone=Open source
ArticleTitle=Open an Eclipse Rich Client Platform application from a URL