Jump to: navigation, search

Difference between revisions of "Dali Discouraged Access Warnings"

Line 16: Line 16:
 
In theory the EclipseLink plug-ins, <code>o.e.jpt.eclipselink.*</code>, should ''not'' add any access rule exceptions to their projects' Java build paths, since these plug-ins, as exemplary extensions, ''should'' be using only Dali's public API. But, in practice, when extending Dali it is much easier (though riskier) to use and/or subclass the Dali internal classes etc.
 
In theory the EclipseLink plug-ins, <code>o.e.jpt.eclipselink.*</code>, should ''not'' add any access rule exceptions to their projects' Java build paths, since these plug-ins, as exemplary extensions, ''should'' be using only Dali's public API. But, in practice, when extending Dali it is much easier (though riskier) to use and/or subclass the Dali internal classes etc.
  
'''NB:''' The "base" Dali plug-ins do ''not'' list the EclipseLink plug-ins as ''x-friend''s.
+
'''NB:''' The "base" Dali plug-ins do ''not'' list the EclipseLink plug-ins as ''x-friend''s; so we add the appropriate access rule exceptions to the EclipseLink plug-ins.
  
 
*'''WTP ''Discouraged Access'' Warnings'''
 
*'''WTP ''Discouraged Access'' Warnings'''
Line 23: Line 23:
 
*'''External ''Discouraged Access'' Warnings'''
 
*'''External ''Discouraged Access'' Warnings'''
 
Because Dali is so tightly integrated with the Eclipse Java IDE, it references the internals of a number of other Eclipse plug-ins, particularly JDT plug-ins. A bug should be filed for each such warning, requesting the appropriate API be made public. Although these warnings could be suppressed (e.g. using the access rule exceptions described above or a Java annotation <code>@SuppressWarnings("restriction")</code>), it is more helpful to leave them visible and commented with a bug number. See [[Dali Access Warning Documentation]].
 
Because Dali is so tightly integrated with the Eclipse Java IDE, it references the internals of a number of other Eclipse plug-ins, particularly JDT plug-ins. A bug should be filed for each such warning, requesting the appropriate API be made public. Although these warnings could be suppressed (e.g. using the access rule exceptions described above or a Java annotation <code>@SuppressWarnings("restriction")</code>), it is more helpful to leave them visible and commented with a bug number. See [[Dali Access Warning Documentation]].
 +
 +
*'''Notes'''
 +
The Dali UI plug-ins should be using the Core plug-ins ''public'' API; but we still have a number of places where the UI plug-ins are using internal Core API. In most of these situations the code in the Core plug-in should be moved to the UI plug-in.

Revision as of 14:46, 7 March 2011

DRAFT

For background, see

Currently, Dali has four levels of Discouraged Access warnings to deal with:

  • Internal Discouraged Access Warnings
    • Non-Test Plug-ins
      We add non-test plug-ins as "friends" of other non-test plug-ins, as appropriate (e.g. all the non-test plug-ins are friends of o.e.jpt.utility; while none of the plug-ins are friends of o.e.jpt.ui).
    • Test Plug-ins
      Because test plug-ins are not loaded at run-time, there is no need to make them friends of the non-test plug-ins. To suppress the Discouraged Access warnings in a test plug-in, we add the appropriate build-time access rule exceptions to the project's Java build path (e.g. o.e.jpt.core.tests suppresses any access warnings caused by references to o.e.jpt.core). See the DTP description of this Eclipse feature.
      • NB: The test "extension" plug-in, o.e.jpt.core.test.extension.resource, should be using the Dali public API; but see the EclipseLink plug-ins discussion below.
  • EclipseLink plug-ins Discouraged Access Warnings

In theory the EclipseLink plug-ins, o.e.jpt.eclipselink.*, should not add any access rule exceptions to their projects' Java build paths, since these plug-ins, as exemplary extensions, should be using only Dali's public API. But, in practice, when extending Dali it is much easier (though riskier) to use and/or subclass the Dali internal classes etc.

NB: The "base" Dali plug-ins do not list the EclipseLink plug-ins as x-friends; so we add the appropriate access rule exceptions to the EclipseLink plug-ins.

  • WTP Discouraged Access Warnings

As a sub-project of WTP, Dali, ostensibly, is allowed access to the internals of any other WTP sub-project. This requires the appropriate WTP plug-ins to add various Dali plug-ins to their lists of "friends". Since this does not always happen in a timely fashion, we add access rule exceptions as necessary. Currently, only o.e.jpt.core and o.e.jpt.ui require these exceptions.

  • External Discouraged Access Warnings

Because Dali is so tightly integrated with the Eclipse Java IDE, it references the internals of a number of other Eclipse plug-ins, particularly JDT plug-ins. A bug should be filed for each such warning, requesting the appropriate API be made public. Although these warnings could be suppressed (e.g. using the access rule exceptions described above or a Java annotation @SuppressWarnings("restriction")), it is more helpful to leave them visible and commented with a bug number. See Dali Access Warning Documentation.

  • Notes

The Dali UI plug-ins should be using the Core plug-ins public API; but we still have a number of places where the UI plug-ins are using internal Core API. In most of these situations the code in the Core plug-in should be moved to the UI plug-in.