Link Handlers

Definition

A link handler defines how your application deals with hyperlinks, or simply links.

Plug-ins can contribute link handlers for custom URL schemes using the extension point org.eclipse.urischeme.uriSchemeHandlers.

Use

You can add link handlers only by installing software into your application.

Link handlers can be enabled or disabled in the preference dialog. To do this, open the General > Link Handlers preference page and select the relevant option.

The workbench will automatically try to enable link handlers at startup. If you do not want a link handler to be enabled you can manually disable it afterwards. In this case the workbench will no longer automatically registered this link handler again (for the same workspace).

Introduction

Links are best known from the web where clicking on a links navigates the user to another web page. But the concept of links is also usefull for other use-case, for example file sharing. Here, a user uploads a file to a file hosting service and grants access to others by sending a link to that shared document through e-mail. When choosing such a link, the web browser, or another locally installed application will open this link.

Sample

The URL of each link consists of a scheme, host, and path: https://www.eclipse.org/downloads

In this URL, the scheme is "https", the host name is "www.eclipse.org", and the path is "downloads". This URL addresses a hypertext document using the "https" URL scheme.

Choosing such a link, typically a web browser is opened. The web browser then downloads and displays the relevant document.

URL Schemes

Link handlers incorporate the concept of custom URL schemes into this application. Different URL schemes have different meanings and need different handling. A link handler can handle specific URL schemes.

When a user clicks a link containing an URL scheme, which is enabled, the operating system will start the corresponding application or set the corresponding window to the foreground - if the application is already running. Link handling is specific to the URL scheme - it may open a file in an editor, open a dialog, install new software, clone a repository, or result in something else.

The Link Handlers preference page provides a list of URL schemes which the applicaiton can handle. For each scheme, a description further explains the URL scheme. A checkbox shows if handling of this URL scheme is enabled or disabled. If handling is disabled, the list will also display if this URL scheme is handled by another application or not.

Examples of Eclipse-related URL Schemes and How They Are Handled

• eclipse+command:// URL scheme handler makes the application start a command.
  Such URLs have the form eclipse+command://commandId?param1Id=value&param2Id=value.
  For example, to open a preference page: eclipse+command://org.eclipse.ui.window.preferences?preferencePageId=org.eclipse.ui.browser.preferencePage.
• eclipse+mpc:// URL scheme handler makes the application which has Marketplace Client plugin installed start the installation dialog for the given marketplace entry.
  Such URLs have the form eclipse+mpc://marketplaceCatalogPath/marketplaceEntryId.
  For example, eclipse+mpc://marketplace.eclipse.org/install/1640500.

Note

• The internal Web browser automatically checks available Link Handlers when processing links and use suitable one to open referenced URL inside the current application.
• The enabled state of each URL scheme is not persisted in the preference store, but it is directly registered in the operating system. Therefore, this page does not take part in the export and import of preferences and does not provide a "Restore Defaults" button.
• For the "macOS" and "Linux" operating system: If an URL scheme is handled by another application (Eclipse-based or not), it cannot be enabled directly. Handling of this URL scheme must first be disabled in the other application, before it can be enabled in the current application.
• For the "macOS" operating system: If the current application is a signed application it's not possible to register / unregister URL schemes. Registering / unregistering would modify the application's info.plist file. This would break the applications signature and lead to the situation that "macOS Gatekeeper" would no longer allow running the application. URL schemes must be added to the info.plist file already at build-time of the application becore it's signed. For unsigned applications this restriction does not apply.
• When multiple Eclipse-based applications are running at the same time, the operating system may set a window to the foreground, which cannot handle the link. In such cases, ensure that only the expected Eclipse-based application is running.
• In rare cases (e.g. PDE development) the path to the application launcher can not be determined from the eclipse.launcher or eclipse.home.location system properties. The preference page will then show an error message and will not allow any interaction.