Difference between revisions of "DTP Ganymede Resolving Discouraged Access Warnings"

From Eclipsepedia

Jump to: navigation, search
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
←[[Data Tools Platform Project | Back to DTP Main Page]]
+
{{Back To|name=DTP Main Page|href=Data Tools Platform Project}}
==Document Status==
+
 
+
[8/24/07]: This document is a '''draft''' and '''should not''' be taken as offical until reviewed and approved by the DTP PMC and project leads.
+
 
+
 
==Overview==
 
==Overview==
  
Line 16: Line 12:
  
 
==Resolution of Warnings==
 
==Resolution of Warnings==
While there are a large number of ''Discouraged Access'' warnings, fortunately the vast majority of these are internal. Since we have decided that DTP components can freely use code among themselves, this means that most of the ''Discouraged Access'' warnings are really not a problem. Hence, we only need to find a way of indicating, in project and/or plug-in meta-data, that no ''Discouraged Access'' warning should be registered for ''org.eclipse.datatools.*'' classes using ''org.eclipse.datatools.*'' code.
+
While there are a large number of ''Discouraged Access'' warnings, fortunately the vast majority of these are internal. Since we have decided that DTP components can freely use code among themselves, this means that most of the ''Discouraged Access'' warnings are really not a problem. Hence, we only need to find a way of indicating, in project and/or plug-in meta-data, that no ''Discouraged Access'' warnings should be registered for ''org.eclipse.datatools.*'' classes using ''org.eclipse.datatools.*'' code.
  
 
====Resolving Internal ''Discouraged Access'' Warnings====
 
====Resolving Internal ''Discouraged Access'' Warnings====
Line 32: Line 28:
 
External ''Discouraged Access'' warnings are seen as more serious that internal ones, since they represent DTP usage of Eclipse project code external to DTP that has not been exposed as API. As with any usage of non-API, DTP assumes [http://en.wikipedia.org/wiki/Technical_debt technical debt] and risk with each case. Simply stated, use of non-API exposes DTP, and all DTP adopters/users, to the risk of sudden (potentially serious) breakage at any time, since internal code is allowed to vary freely without public notification and review of changes.
 
External ''Discouraged Access'' warnings are seen as more serious that internal ones, since they represent DTP usage of Eclipse project code external to DTP that has not been exposed as API. As with any usage of non-API, DTP assumes [http://en.wikipedia.org/wiki/Technical_debt technical debt] and risk with each case. Simply stated, use of non-API exposes DTP, and all DTP adopters/users, to the risk of sudden (potentially serious) breakage at any time, since internal code is allowed to vary freely without public notification and review of changes.
  
As part of providing the most stable components to the Eclipse community, DTP must make an effort to resolve as many as possible external ''Discouraged Access'' warnings for the DTP Ganymede release. Since there are a number of factors, sometimes quite complex, that are involved in the motivation to use internal code and the process of removing its usage, we do not expect that every external ''Discouraged Access'' warning will be resolved before release. The procedure described below takes this practicality into account.
+
As part of providing the most stable components possible to the Eclipse community, DTP must make an effort to resolve as many as possible external ''Discouraged Access'' warnings for the DTP Ganymede release. Since there are a number of factors, sometimes quite complex, that are involved in the motivation to use internal code and the process of removing its usage, we do not expect that every external ''Discouraged Access'' warning will be resolved before release. The procedure described below takes this practicality into account.
  
 
For '''all''' external ''Discouraged Access'' warnings in DTP, the plug-in owner responsible must:
 
For '''all''' external ''Discouraged Access'' warnings in DTP, the plug-in owner responsible must:
  
 
* Attempt to refactor the code to use API if possible.
 
* Attempt to refactor the code to use API if possible.
* If no equivalent API are found, then the plug-in owner should contact the relevant team (using whatever channel is appropriate: newsgroups, mailing lists, personal contacts, etc.) and seek advice.
+
* If no equivalent API are found, then the plug-in owner must contact the relevant team (using whatever channel is appropriate: newsgroups, mailing lists, personal contacts, etc.) and seek advice.
* If an alternative is suggested by the target plug-in team, the plug-in owner should (of course) make every attempt to apply the change.
+
* If an alternative is suggested by the target plug-in team, the plug-in owner must (of course) make every attempt to apply the change.
* If there is no alternative, or the suggested change is not acceptable, then the plug-in owner should:
+
* If there is no alternative, or the suggested change is not acceptable, then the plug-in owner must:
 
**Open a bug for the target plug-in seeking (a better) API resolution
 
**Open a bug for the target plug-in seeking (a better) API resolution
**Open a bug for the DTP plug-in involved, detailing the usage and setting a dependency on the bug opened for the target plug-in. The keyword "api" should be applied to the bug for the DTP plug-in.
+
**Open a bug for the DTP plug-in involved, detailing the usage and setting a dependency on the bug opened for the target plug-in. The keyword "api" must be applied to the bug for the DTP plug-in.
  
 
All remaining cases (as documented in bug entries) will be reported to the community as part of the DTP release review presentation. This will give transparency to DTP adopters/users with respect to the API technical debt present in DTP.
 
All remaining cases (as documented in bug entries) will be reported to the community as part of the DTP release review presentation. This will give transparency to DTP adopters/users with respect to the API technical debt present in DTP.
Line 49: Line 45:
 
==Related Bugs==
 
==Related Bugs==
  
The following bugs have been opened to track resolution of ''Discouraged Access'' warnings:
+
The following bugs have been opened to track resolution of ''Discouraged Access'' warnings.
 +
 
 +
*External: All have been marked with the "api" keyword
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201125 201125]: o.e.d.connectivity.ui
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201126 201126]: o.e.d.enablement.jdt.classpath
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201127 201127]: o.e.d.enablement.jdt.dbunit
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201129 201129]: o.e.d.sqltools.common.ui
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201132 201132]: o.e.d.sqltools.editor.core
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201133 201133]: o.e.d.sqltools.routineeditor
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201134 201134]: o.e.d.sqltools.sqleditor
 +
*Internal: As of early August 2007, internal ''Discouraged Access'' warnings appear only in Connectivity and SQL Dev, so aggregate bugs for each project have been opened. If internal warnings later appear in other DTP projects, then aggregate bugs for those cases will be opened as well.
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201136 201136]: Connectivity
 +
**[https://bugs.eclipse.org/bugs/show_bug.cgi?id=201139 201139]: SQL Dev Tools

Latest revision as of 12:45, 31 August 2007

Back to DTP Main Page

Contents

[edit] Overview

As described in the DTP Ganymede Project Plan, a main goal of DTP Ganymede is to resolve as many Discouraged Access warnings in the DTP code line as possible. The reasoning and general process for doing this is outlined in the DTP Ganymede Development Guildlines. The purpose of this page is to collect specific information about how these Discouraged Access warnings will be resolved.

[edit] Current Status

A check of DTP HEAD at the beginning of August 2007 reveals a large number of Discouraged Access warnings. We will call a Discouraged Access warning internal if the reference is within DTP itself, and external otherwise. Using this distinction, we find:

  • About 1800 internal warnings
  • About 160 external warnings

[edit] Resolution of Warnings

While there are a large number of Discouraged Access warnings, fortunately the vast majority of these are internal. Since we have decided that DTP components can freely use code among themselves, this means that most of the Discouraged Access warnings are really not a problem. Hence, we only need to find a way of indicating, in project and/or plug-in meta-data, that no Discouraged Access warnings should be registered for org.eclipse.datatools.* classes using org.eclipse.datatools.* code.

[edit] Resolving Internal Discouraged Access Warnings

Ideally we'd like to make use of the x-friend directive for plug-in manifests. Rather than setting certain packages to "internal," we would specify the exceptions ("friends") to default internal visibilty. Since there are a large number of DTP plug-ins, and this number is changing over time, we would like to use a pattern here: something like x-friend=org.eclipse.datatools.* to indicate that any org.eclipse.datatools code can free use other org.eclipse.datatools code. Unfortunately, this is not possible: the x-friend directive requires listing each "friend" bundle, and hence is not a good solution for DTP.

We can, however, at least filter the Discouraged Access warnings at build time, giving us a clearer picture of warnings we should be addressing and allows us (if we wish) to choose error severity when reporting this class of warnings. Eclipse supports this type of build-time filtering, as described here.

  • Action Item (All plug-in owners): Add the access rule exception filter to all plug-ins containing internal Discouraged Access warnings.

Granted, this does not solve the problem at run time: if the OSGI loader is in "strict" mode, then package access restrictions, as expressed in the plug-ins' manifest file, will be enforced. Yet this is the best solution we have at the present time, and at least allows us to control for internal vs. external Discouraged Access warnings at build time.

[edit] Resolving External Discouraged Access Warnings

External Discouraged Access warnings are seen as more serious that internal ones, since they represent DTP usage of Eclipse project code external to DTP that has not been exposed as API. As with any usage of non-API, DTP assumes technical debt and risk with each case. Simply stated, use of non-API exposes DTP, and all DTP adopters/users, to the risk of sudden (potentially serious) breakage at any time, since internal code is allowed to vary freely without public notification and review of changes.

As part of providing the most stable components possible to the Eclipse community, DTP must make an effort to resolve as many as possible external Discouraged Access warnings for the DTP Ganymede release. Since there are a number of factors, sometimes quite complex, that are involved in the motivation to use internal code and the process of removing its usage, we do not expect that every external Discouraged Access warning will be resolved before release. The procedure described below takes this practicality into account.

For all external Discouraged Access warnings in DTP, the plug-in owner responsible must:

  • Attempt to refactor the code to use API if possible.
  • If no equivalent API are found, then the plug-in owner must contact the relevant team (using whatever channel is appropriate: newsgroups, mailing lists, personal contacts, etc.) and seek advice.
  • If an alternative is suggested by the target plug-in team, the plug-in owner must (of course) make every attempt to apply the change.
  • If there is no alternative, or the suggested change is not acceptable, then the plug-in owner must:
    • Open a bug for the target plug-in seeking (a better) API resolution
    • Open a bug for the DTP plug-in involved, detailing the usage and setting a dependency on the bug opened for the target plug-in. The keyword "api" must be applied to the bug for the DTP plug-in.

All remaining cases (as documented in bug entries) will be reported to the community as part of the DTP release review presentation. This will give transparency to DTP adopters/users with respect to the API technical debt present in DTP.

  • Action Item (All plug-in owners): Following the process above, resolve or document all external Discouraged Access warnings in DTP Ganymede.

[edit] Related Bugs

The following bugs have been opened to track resolution of Discouraged Access warnings.

  • External: All have been marked with the "api" keyword
    • 201125: o.e.d.connectivity.ui
    • 201126: o.e.d.enablement.jdt.classpath
    • 201127: o.e.d.enablement.jdt.dbunit
    • 201129: o.e.d.sqltools.common.ui
    • 201132: o.e.d.sqltools.editor.core
    • 201133: o.e.d.sqltools.routineeditor
    • 201134: o.e.d.sqltools.sqleditor
  • Internal: As of early August 2007, internal Discouraged Access warnings appear only in Connectivity and SQL Dev, so aggregate bugs for each project have been opened. If internal warnings later appear in other DTP projects, then aggregate bugs for those cases will be opened as well.