| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> |
| <HTML> |
| <HEAD> |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <title>Access Restrictions</title> |
| </HEAD> |
| |
| <BODY> |
| <p align="center"><font size="5"><b>Access Restrictions</b></font></p> |
| <p align="left">The Eclipse 3.1 runtime gives the plug-in developer the <em><strong>option</strong></em> |
| to control on a per-package basis the visibility of the plug-in code to downstream |
| plug-ins. </p> |
| <p align="left">A package may be classified as one of the following:</p> |
| <ol> |
| <li>Accessible</li> |
| <li>Forbidden</li> |
| <li>Internal</li> |
| <li>Internal with friends</li> |
| </ol> |
| <p align="left">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. </p> |
| <p align="left">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.</p> |
| <p align="left"> </p> |
| <p align="left"><b><font size="4">Accessible Packages</font></b></p> |
| <p align="left">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.</p> |
| <p align="left">In order to declare a package as accessible, you must list it in |
| the <b>Exported Packages</b> section on the <b>Runtime</b> of the plug-in |
| manifest editor and leave the default visibility setting as-is.</p> |
| <p align="center"><img src="images/accessible.PNG" alt="Accessible Packages"></p> |
| <p align="center"> </p> |
| <p align="left"><b><font size="4">Forbidden Packages</font></b></p> |
| <p align="left">You can hide a package from downstream plug-ins at all times by |
| <b>excluding</b> it from the list in the <b> Exported Packages</b> section on |
| the <b>Runtime</b> page of the plug-in manifest editor.</p> |
| <p align="left">References to types from a forbidden package result in classloading |
| errors at runtime.</p> |
| <p align="left"> To avoid such unpleasant situations:</p> |
| <ol> |
| <li>The compiler will flag references to forbidden packages with an <font color="#000000">ERROR</font><font color="#FF0000">.</font></li> |
| <li>Types from forbidden packages are <font color="#000000"> NOT</font> available |
| as proposals in the content assist.</li> |
| </ol> |
| <p align="left"><u>Notes:</u></p> |
| <ol> |
| <li> 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.</li> |
| <li> The severity level for forbidden references is set on the <b>Java > |
| Compiler > Errors/Warnings > Deprecated and restricted API</b> preference |
| page. |
| <p> It is strongly recommended that the severity of a forbidden reference |
| is kept at ERROR.</p> |
| </li> |
| </ol> |
| <p align="center"> <img src="images/forbidden_pref.PNG" alt="Forbidden preferences" border="0"></p> |
| <p align="left"><font size="4"><b>Internal Packages</b></font></p> |
| <p align="left">Internal packages are packages that are not intended for use by |
| downstream plug-ins. <em><strong>These packages are visible to downstream plug-ins |
| by</strong> <strong>default</strong></em>. </p> |
| <p align="left">Internal packages are hidden from downstream plug-ins only when |
| Eclipse is launched in <em><strong>strict</strong></em> mode (i.e. when you |
| launch with the <em>-Dosgi.resolverMode=strict</em> VM argument).</p> |
| <p align="left">Internal packages must be listed in the <b>Exported Packages</b> |
| section on the <b>Runtime</b> page of the plug-in manifest editor with the <i> |
| <b>hidden</b></i> option selected.</p> |
| <p align="center"> <img src="images/discouraged.PNG" alt="discouraged access"></p> |
| <p align="left">Two measures are taken to discourage downstream plug-ins from |
| referencing internal packages:</p> |
| <ul> |
| <li>The compiler flags references to such packages with a <font color="#000000">WARNING</font>.</li> |
| </ul> |
| <p align="center"><img src="images/compiler_discouraged.PNG" alt="discouraged access"></p> |
| <ul> |
| <li>Types from discouraged packages are available as proposals in the content |
| assist but with a <font color="#000000">LOWER PRIORITY</font>.</li> |
| </ul> |
| <p align="center"><img src="images/content_assist_discouraged.PNG" alt="discouraged content assist"></p> |
| <p align="left">The severity level for discouraged references can be set on the |
| <b>Java > Compiler > Errors/Warnings > Deprecated and restricted API</b> |
| preference page.</p> |
| <p align="center"> <img src="images/discourage_pref.PNG" alt="Discouraged preferences" border="0"></p> |
| <p align="left"> </p> |
| <p align="left"><b><font size="4">Internal packages with friends</font></b></p> |
| <p align="left">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 <em>org.eclipse.pde.ui</em> |
| plug-in should have full access to <em>org.eclipse.pde.core</em>'s internal |
| packages.</p> |
| <p align="left">In the example below, the friends (the <em>org.eclipse.pde</em> |
| and <em>org.eclipse.pde.ui</em> plug-ins) have full access to the <em>org.eclipse.pde.internal.core.bundle</em> |
| package from the <em>org.eclipse.pde.core </em>plug-in.</p> |
| <p align="center"><img src="images/friends.PNG" alt="Friends"></p> |
| <p align="left">The friends are free to reference any type from the <em>org.eclipse.pde.internal.core.bundle</em> |
| package with the compiler's blessing. </p> |
| <p align="left">If, on the other hand, any other plug-in references a type from |
| the <em>org.eclipse.pde.internal.core.bundle</em> package, the compiler flags |
| the reference as a discouraged reference as described in the previous section.</p> |
| <p align="left"> </p> |
| <p align="left"><strong><font size="4">How to enable access restrictions</font></strong></p> |
| <p align="left">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.</p> |
| <p align="left">If the plug-in does not contain a manifest.mf file, that file |
| can be created as follows:</p> |
| <ol> |
| <li>Open the plugin.xml in the plug-in manifest editor.</li> |
| <li>In the <strong>Plug-in Content</strong> section of the <strong>Overview</strong> |
| page, click on the '<strong>create an OSGi bundle manifest</strong>' link.</li> |
| </ol> |
| <div align="center"> |
| <p><img src="images/convert.PNG" alt="convert to manifest.mf"></p> |
| <p align="left"> </p> |
| <p align="left"><strong><font size="4">Inspecting access rules</font></strong></p> |
| <p align="left">You can inspect the access restriction rules imposed on each |
| classpath entry by PDE on the <strong>Java Build Path</strong> property page |
| of your plug-in project. </p> |
| <p align="center"><img src="images/properties.PNG" alt="Java Build Path Properties"></p> |
| </div> |
| </BODY> |
| </HTML> |
