Community
Participate
Working Groups
I configured the DSF and DSF-GDB plugins to use API tooling. A quick "how to" can be found at http://wiki.eclipse.org/PDE/API_Tools/User_Guide. I used DD 1.0 release features as a base line for the APIs. I had to do three main changes to eliminate the API errors (plus some minor stuff): 1) I had to mark our provisional APIs as "internal" in MANIFEST.MF files. This in itself was considered an API change by the tooling, so I had to add a whole bunch of filters for those errors. 2) I added a ton of @since 1.1 tags. 3) I had to add duplicate constructors and methods which now refer to ICommandControlDMContext type (changed from MIControlDMContext), because changing method argument type breaks api compatibility). I already committed the changes, but they were so wide-spread that I didn't think it would make sense to create a patch. Please take the time to configure API tooling (it is really quick) for further work with DSF and DSF-GDB.
Marc, since the only code changes were in DSF-GDB, please have a quick look through the changes.
(In reply to comment #0) > I configured the DSF and DSF-GDB plugins to use API tooling. I was thinking we really needed something like that. Thanks for setting it up! > I used DD 1.0 release features as a base line for the APIs. I assume you mean that you checked-out the DSF plugins with version 1.0-RC4, right to create your baseline? > I had to add a whole bunch of filters for those errors. Do you know of something special we need to do to get those filters? I was hoping they would be part of the plugin, but currently, I'm getting 293 errors from the API tooling. Maybe the filters are stored as preferences in your workspace? If that is the case, Can you export that part of your preferences and attach it to this bug? Thanks
(In reply to comment #2) I noticed that the filters are part of the plugins. So, I must be doing something wrong with my baseline because I'm still getting a bunch of errors. For instance, the org.eclipse.dd.dsf plugin gives me a bunch of missing @since, such as for the class ConfinedToDsfExecutor.
To create the base line I downloaded the 1.0 version three features: DSF, DSF-GDB and DSF-GDB-Launch and extracted them into the same directory. Then I created the base line with just these plugins. Are you still having issues with it?
(In reply to comment #4) > To create the base line I downloaded the 1.0 version three features: DSF, > DSF-GDB and DSF-GDB-Launch and extracted them into the same directory. Then I > created the base line with just these plugins. > > Are you still having issues with it? Ok, now it works. I didn't think the API tooling would work with just jar files, but it is smarter than I thought. Thanks
(In reply to comment #0) > 3) I had to add duplicate constructors and methods which now refer to > ICommandControlDMContext type (changed from MIControlDMContext), because > changing method argument type breaks api compatibility). I noticed that yes, the API tooling does not accept such a change, however, I was wondering why. When I made the change, I was under the impression it was ok. I figured that changing the type of a -constructor- argument to a less specific type would not break anything. Is there a case where it would break the compilation?
I was actually under the same impression as you. The question is whether it breaks binary API compatibility. After noticing that the API tooling marked it as an error I read up on the http://wiki.eclipse.org/Evolving_Java-based_APIs_2 page which describes what is and isn't a breaking change. Apparently changing the constructor and method argument types is a breaking change.
(In reply to comment #7) > I was actually under the same impression as you. The question is whether it > breaks binary API compatibility. After noticing that the API tooling marked it > as an error I read up on the http://wiki.eclipse.org/Evolving_Java-based_APIs_2 > page which describes what is and isn't a breaking change. Apparently changing > the constructor and method argument types is a breaking change. It does say there that changing the type of a formal parameter of a constructor or method is not compatible. But that seems to be a more generic case than what we are dealing with by making the type less specialized. They might be overly careful in their rule... But this is not a question for this bug anymore as we have to follow the rule of the API tooling tool. So, we'll just have an extra constructor. I would like to mark those as @Deprecated so that they can easily be removed when we go to 2.0 I'll continue to review the changes.
(In reply to comment #8) > ...They might be overly careful in their rule... That could very well be and someone with more knowledge of the java bytecode and run-time linking may know better. A quick experiment may solve the mystery too... > But this is not a question for this bug anymore as we have to follow the rule > of the API tooling tool. So, we'll just have an extra constructor. I would > like to mark those as @Deprecated so that they can easily be removed when we go > to 2.0 Agreed.
(In reply to comment #9) > A quick experiment may solve the mystery too... That is the tricky part. Not finding an example where it breaks could simply mean we haven't looked far enough :-)
Created attachment 112908 [details] Minor cleanup (In reply to comment #9) > > I would like to mark those as @Deprecated so that they can easily be > > removed when we go to 2.0 > Agreed. This patch makes some old constructors deprecated, and removes a couple of @since 1.1 that I happened to notice were not needed. Committed this patch and verified the bug. I'm really glad you set this up, it will prove extremely useful. Wish I had known about it sooner :-)
Yes, I'm glad I set it up too... and that the JDT team created it in the first place :-)
DD 1.1 reelased!
