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:
- Accessible
- Forbidden
- Internal
- 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.
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:
- The compiler will flag references to forbidden packages with an error.
- Types from forbidden packages are NOT available
as proposals in the content assist.
Notes:
- 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.
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 internal packages with a warning.
- Types from discouraged packages are available as content assist proposals; 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 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.
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:
- Open the plugin.xml in the plug-in manifest editor.
- 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.