On Sep 2, 2010, at 3:01 PM, Oleksiy Stashok wrote:
>> It's a big ask, but it would be really nice if your team could
>> spend some time going through the Grizzly sources and deciding
>> which APIs are public and which are not. There seem to be a very
>> large number of classes and methods which are probably not
>> intended for public consumption. It would be really nice verify
>> that they have the appropriate access rights (i.e. public/package/
>> protected/private) and update where necessary. This would have two
>> benefits: 1) user-friendliness since a Grizzly with less classes
>> and interfaces will be easier to learn and navigate, and 2)
>> compatibility since only public classes/interfaces will need to
>> remain stable.
>>
>> Of course this is not always possible to do - sometimes an
>> implementation class must be made public because another class in a
>> different package needs to access it. Something that we have done
>> in our LDAP SDK is to split the source tree in two parts: a
>> com.sun.opends.sdk.* package hierarchy containing private
>> implementation classes and a public org.opends.sdk.* package
>> hierarchy containing the public interfaces and classes. Our Javadoc
>> and src.zip only includes the public org.opends.sdk.* package
>> hierarchy, effectively hiding the private package hierarchy. This
>> is how they've managed the problem for J2SE AFAIK.
> Very good point. We've discussed this during our yesterday's
> meeting, and we will make a refactoring nearest time.
>
FWIW Jersey has an impl package where it dumps all the implementation
stuff and that is filtered when generating the JavaDoc. So we don't
change the base package name and anything not in "impl" is part of the
public API.
Guice does something even better and has an impl package where nearly
all stuff in there is package private, which makes it impossible for a
developer to hack Guice and depend on implementation artifacts.
Paul.