• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Tim Cooke
  • paul wheaton
  • Jeanne Boyarsky
  • Ron McLeod
Sheriffs:
  • Paul Clapham
  • Liutauras Vilda
  • Devaka Cooray
Saloon Keepers:
  • Tim Holloway
  • Roland Mueller
Bartenders:

Internal / External API

 
Greenhorn
Posts: 14
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hello Eclipse contributors
I'm quite new to writing Eclipse plugins thus my question might be quite ridiculous.
When writing a plugin for Eclipse should I also use internal and external packages?
For example, should I use packages in the form com.mycompany.myplugin.internal.whatever? Or only if I provide extension points to my plugin for other developers to enhance my plugin?
Thanks for clarifying this.
Christian
 
author
Posts: 45
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
There is chapter in Contributing to Eclipse on precisely this topic. The Eclipse style is only to publicize explicit API and place other classes in packages named "internal". You can see many examples in the code for Eclipse (see the chapter on setting up for plug-in development to see how you can easily view the Eclipse source code).
Kent
 
Dastardly Dan the Author
Posts: 120
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
First of all, welcome and congratulations! I've not yet finished your book but I like what I've read so far. It covers considerable ground in an approachable fashion.
Returning to the question above... in that chapter, the section entitled "Exporting Classes" seems to advocate specifying <export name="*"> as a matter of practice. Later in "Separating Published from Internal Packages" there are several rules for managing APIs. Do you believe it is too restrictive to list only those non-internal packages in the <export> clause? Is it overly draconian to only list interfaces?
I'm sort of on the fence. Some of the Ready for WebSphere applications are replete with internal package references. Some applicants argue (and rightfully so) that there was no alternative. Many, however, simply picked what was "most evident," not knowing that an equivalent public interface existed. If Eclipse had scoped its exports, that trap would be eliminated, at the risk of limiting "fortuitous" extensibility / reuse. Then again, moving from version to version has been painful for some vendors because they exploited internal packages that were later eliminated or refactored...
Your thoughts?
-- Dan
 
Author
Posts: 16
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Dan,
(glad you like the book)


Do you believe it is too restrictive to list only those non-internal packages in the <export> clause? Is it overly draconian to only list interfaces?


Selective export is problematic since you only get informed about the problem at run-time and not at build-time. I therefore consider selective export to be "draconian". The naming convention for packages makes the intent explicit enough. Not exporting any classes at all is OK - if you want to express that a plug-in isn't meant to be extended.
--erich
 
Dan Kehn
Dastardly Dan the Author
Posts: 120
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Erich Gamma:
Selective export is problematic since you only get informed about the problem at run-time and not at build-time.


Wha-haaaat's this, a JDT limitation? I think that I know just the person to correct it.
-- Dan
 
Erich Gamma
Author
Posts: 16
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Nope - JDT doesn't know about plug-ins - complain one layer above in PDE
 
Dan Kehn
Dastardly Dan the Author
Posts: 120
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
PDE? No, the JDT doesn't get away that easily! The PDE has the information, but I don't know that the JDT has the APIs to enable it. It wouldn't be simple, since the notion of "visible but not public" is foreign to Java. Kind of a pity that the Eclipse architecture allows something that the tools don't support.
I may have to join the "all or nothing" crowd...
-- Dan
 
Erich Gamma
Author
Posts: 16
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I see Dan - you are not giving-up that easily This is fair since you and the other authors wrote over 800 pages on Eclipse (and I have a high respect of your book).
Let me give you another example for why I'm not convinced that you need to enforce an API with selective exports. Not exporting a class is a similar decision as declaring a class final. The decision has the same impact for the client. They have to accept it and there is no way to work around this decision.
Here is the example, in an earlier version SWT declared most of its widget classes as final. This has turned out to be too harsh, there are cases when you would like to subclass even if the original implementor didn't see a need for it. Therefore this was changed to "intent final". This means the class is not declared as final, but in the Javadoc/API it is expressed that the class is not intended to be subclassed (we have a sidebar on this in the book). This makes the intent clear, but clients still have an option to work around your decision. This was a lesson to me that declaring the intent is more important than enforcing it. Declaring a class in an "internal" package makes the API intent clear enough.
BTW, I fully agree, that a checker tool for finding internal class uses would be really useful. I'd use it to validate a plug-in, but I wouldn't use it to enforce which classes are visible to clients.
--erich
 
Thanks tiny ad, for helping me escape the terrible comfort of this chair.
Smokeless wood heat with a rocket mass heater
https://woodheat.net
reply
    Bookmark Topic Watch Topic
  • New Topic