Access Rules

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

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 this type of support at compile time, one is never caught by surprise by runtime class loading errors and is always aware of internal type references.

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.

Accessible Packages

 

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 class loading 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 Open problem severities preference page 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.

Forbidden preferences

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.

discouraged access

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

discouraged access

discouraged content assist

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

Discouraged preferences

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 the org.eclipse.pde.ui friend plug-in has full access to the org.eclipse.pde.internal.core.bundle package from the org.eclipse.pde.core plug-in.

Friends

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

On the other hand, if 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 will take care of the rest including the management of the plug-in classpath.

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.

convert to manifest.mf

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.

Java Build Path Properties

Plug-in Editor
Overview Page
Dependencies Page
Runtime Page
Extensions Page
Extension Points Page
Build Page