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:
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 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.
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:
Notes:
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 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 severity level for discouraged references can be set on
the
Java > Compiler > Errors/Warnings >
Deprecated and restricted API preference page.
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.
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:
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.
