Access Restrictions

The Eclipse 3.1 runtime gives the plug-in developer the option to control on a per-package basis the visibility of the plug-in code to downstream plug-ins.

A package may be classified as one of the following:

1. Accessible
2. Forbidden
3. Internal
4. Internal with friends

PDE translates these runtime visibility rules into compiler access restriction rules at compile time. As a result, a violation of a visibility rule is flagged by the compiler as a warning or an error, depending on the severity of that violation.

With the availability of this support at compile time, one is never get caught by surprise by classloading errors at runtime, and is always aware when referencing internal types.

Accessible Packages

Accessible packages are visible to downstream plug-ins unconditionally. While API packages must clearly fall in this category, it is completely up to the developer to decide what other packages exported by the plug-in ought to be given this level of visibility.

In order to declare a package as accessible, you must list it in the Exported Packages section on the Runtime of the plug-in manifest editor and leave the default visibility setting as-is.

Forbidden Packages

You can hide a package from downstream plug-ins at all times by excluding it from the list in the Exported Packages section on the Runtime page of the plug-in manifest editor.

References to types from a forbidden package result in classloading errors at runtime.

To avoid such unpleasant situations:

1. The compiler will flag references to forbidden packages with an ERROR.
2. Types from forbidden packages are NOT available as proposals in the content assist.

Notes:

1. All plug-ins in the Eclipse SDK enumerate all their packages in the Exported Packages section. Therefore, none of the packages in the SDK have forbidden access.
2. The severity level for forbidden references is set on the Java > Compiler > Errors/Warnings > Deprecated and restricted API preference page.

   It is strongly recommended that the severity of a forbidden reference is kept at ERROR.

Internal Packages

Internal packages are packages that are not intended for use by downstream plug-ins. These packages are visible to downstream plug-ins by default.

Internal packages are hidden from downstream plug-ins only when Eclipse is launched in strict mode (i.e. when you launch with the -Dosgi.resolverMode=strict VM argument).

Internal packages must be listed in the Exported Packages section on the Runtime page of the plug-in manifest editor with the hidden option selected.

Two measures are taken to discourage downstream plug-ins from referencing internal packages:

- The compiler flags references to such packages with a WARNING.

- Types from discouraged packages are available as proposals in the content assist but with a LOWER PRIORITY.

The severity level for discouraged references can be set on the Java > Compiler > Errors/Warnings > Deprecated and restricted API preference page.

Internal packages with friends

It is important for a plug-in to be able to grant full access to its internal packages to designated "friend" plug-ins. For instance, the PDE code is split across multiple plug-ins, and the org.eclipse.pde.ui plug-in should have full access to org.eclipse.pde.core's internal packages.

In the example below, the friends (the org.eclipse.pde and org.eclipse.pde.ui plug-ins) have full access to the org.eclipse.pde.internal.core.bundle package from the org.eclipse.pde.core plug-in.

The friends are free to reference any type from the org.eclipse.pde.internal.core.bundle package with the compiler's blessing.

If, on the other hand, any other plug-in references a type from the org.eclipse.pde.internal.core.bundle package, the compiler flags the reference as a discouraged reference as described in the previous section.

How to enable access restrictions

To take advantage of the PDE access restriction support, the only requirement is that the plug-ins in question contain an OSGi bundle manifest.mf. PDE, which manages the plug-in classpath, then takes care of the rest.

If the plug-in does not contain a manifest.mf file, that file can be created as follows:

1. Open the plugin.xml in the plug-in manifest editor.
2. In the Plug-in Content section of the Overview page, click on the 'create an OSGi bundle manifest' link.

Inspecting access rules

You can inspect the access restriction rules imposed on each classpath entry by PDE on the Java Build Path property page of your plug-in project.