Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 234947

Summary:	Specifying packages as true-api, provisional, for-friends-only, internal etc
Product:	[Eclipse Project] PDE	Reporter:	Thomas Watson <tjwatson>
Component:	UI	Assignee:	PDE-UI-Inbox <pde-ui-inbox>
Status:	RESOLVED WONTFIX	QA Contact:
Severity:	normal
Priority:	P3	CC:	david_williams, deboer, jdmiles, jeffmcaffer, john.arthorne, nigelipse, robin, slewis
Version:	3.4
Target Milestone:	---
Hardware:	PC
OS:	Windows XP
Whiteboard:	stalebug

Description Thomas Watson

2008-05-30 17:56:12 EDT

Today in Eclipse we have x-internal and x-friends directives that are useful for declaring the intended clients of our packages.  The problem with the current directives is they are boolean in nature and do not allow for future evolution.

One example is the infamous "provisional" API.  In Eclipse we have not official notion of "provisional" API.  Your packages are either real API or internal.  We have no way of saying a package is "provisional" and likely will change before it becomes true API.  Today these types of packages must be marked as x-internal:=true and therefore giving all clients error/warning messages.  What we usually do is then add x-friends directive and place a list of bundles for which the package is not considered "internal" any more.  But this is not very nice for others which may want to play around and even use the provisional packages, they must live with the internal access warnings or disable the internal access warnings for the whole project.

Perhaps we should consider a new directive (that is not boolean) to describe the access rules to the package.  Maybe x-api or x-access-rules with values like public|friends|provisional|internal.  There are some details to work out in the syntax if we want to combine the friends list with public/provisional/internal access rules.

For example, imagine package foo which you want to be considered provisional api except to a particular list of bundles.  You would need to specify something like this:

Export-Package: foo; x-access-rules:="provisional|friends=a,b,c"

This would mean the package should be considered provisional to all bundles except bundles a, b, and c.  A bit goofy, but you get the idea.

Another thought is to enhance PDE so that you can disable the internal access warning/errors for a project based on particular exporters.  For example, I want warnings for all internal packages I access from all bundles except bundles X, Y and Z or packages a, b and c.  I think we should consider if this solution solves the issues before spending a lot of time defining new directives.

Comment 1 Nigel Westbury

2008-05-30 19:24:47 EDT

We must be aware of complexity creep here. Even if the added complexity is not that much, it all adds up and it all deters newcomers from Eclipse.

Having said that, it seems to me that there is a better solution. The only way to be safe when using a provisional API in production is if the bundle dependency restricts the version to the latest tested version. This suggests a possible solution to this bug. If the version of the exporting bundle is equal to the last possible version in the version range specified in the consuming bundle's manifest then there is no need to show the warnings. The warnings should not be shown because there is no possibility of a later version breaking the API because there is no later version that can satisfy the requirements.

This does mean every time you upgrade the exporting bundle, you must update the version in the manifests of the consuming bundles, but this is good practice. The process is: upgrade the bundle that has the provisional API, check the API is not broken. If not, increase the upper version limit. If it is, fix your bundle and set both lower and upper versions.

Of course, if you are not near production status then you can choose to simply ignore all such warnings. Just be sure that before going into production you turn on the warnings and then set the version ranges correctly in order to fix the warnings.

To summarize: Rather than have a yet more complex syntax to allow developers to ignore legitimate warnings, we would be solving the problem with no extra syntax. We would simply be removing warnings which are not legitimate, thus encouraging developers to set the version ranges correctly.

Comment 2 Thomas Watson

2008-06-02 09:28:01 EDT

(In reply to comment #1)
> Having said that, it seems to me that there is a better solution.  The only way
> to be safe when using a provisional API in production is if the bundle
> dependency restricts the version to the latest tested version.  This suggests a
> possible solution to this bug.  If the version of the exporting bundle is equal
> to the last possible version in the version range specified in the consuming
> bundle's manifest then there is no need to show the warnings.  The warnings
> should not be shown because there is no possibility of a later version breaking
> the API because there is no later version that can satisfy the requirements.
> 

I think there are some versioning issues with your suggestion.  I don't think we can get rid of the warnings if the version of the exporting bundle is equal to the last possible version of the version range specified.  This will still allow the bundle to be installed and run on older versions of the bundle that may not have the provisional API.  Also, we need to consider what to do for Import-Package as well as Require-Bundle.

I agree that new syntax may not be the correct answer.  We should also consider allowing more fine grained control in PDE to all exceptions per package on the project.

Comment 3 James D. Miles

2008-06-02 11:49:18 EDT

I would suggest that it should never be turned off. However it would be adequate to be able to filter to 1 warning for the whole bundle. That way the developer is still warned but it will be much easier to wade though the warnings.

Comment 4 Eclipse Genie

2018-11-05 14:32:53 EST

This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet.

If you have further information on the current state of the bug, please add it. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant.

--
The automated Eclipse Genie.

Comment 5 Thomas Watson

2018-11-05 16:34:55 EST

Closing as wontfix.  I think doing anything more advanced that x-friends and x-internal is likely a bad idea at this point.  Especially given that Java Modules seems to have gone the simple x-friends route.

Comment 6 Lars Vogel

2018-12-03 09:30:49 EST

*** Bug 274514 has been marked as a duplicate of this bug. ***