hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Oleg Kalnichevski <ol...@apache.org>
Subject SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Date Tue, 25 Feb 2014 13:09:30 GMT
On Tue, 2014-02-25 at 12:04 +0000, sebb wrote:
> On 25 February 2014 09:52, Oleg Kalnichevski <olegk@apache.org> wrote:
> > On Tue, 2014-02-25 at 01:08 +0000, sebb wrote:
> >> On 24 February 2014 16:33, Gary Gregory <garydgregory@gmail.com> wrote:
> >> > +1
> >> >
> >> > If we have a public subclass of a package private class, I should be able
> >> > to see all of the methods I can call on that class (and super class).
> >>
> >> That's not the case here. It's a public class using a package class.
> >>
> >> http://hc.apache.org/httpcomponents-client-4.3.x/httpclient-cache/apidocs/org/apache/http/impl/client/cache/ExponentialBackOffSchedulingStrategy.html#schedule%28org.apache.http.impl.client.cache.AsynchronousValidationRequest%29
> >>
> >> Which begs the question - how is it used externally?
> >>
> >> The schedule method implements an interface so has to be public, but
> >> perhaps it is only intended for use internally.
> >> In which case the Javadoc should probably make this clear.
> >>
> >
> > In this package private classes ought not be referenced by public
> > javadocs.
> 
> Is that "package, private" or "package-private" ?
>
> However, a public method - schedule() - uses a package-private class -
> AsynchronousValidationRequest - as a parameter.
> Normally one should be able to provide links to public method parameter types.
> 

Then we have a problem here. Public interfaces are not supposed to
depend on package-private classes or interfaces. This is just plain
wrong.

We have several options how to fix it

(1) Make AsynchronousValidationRequest (and consequently
AsynchronousValidator) public though they clearly were never meant to be
a part of public APIs.

(2) Fix the #schedule method and break API compatibility in the process.
This is unlikely to have any impact on ordinary users given the
interface is clearly unusable in its current form but it going to be the
first deliberate API breakage (I am aware of) in the 4.x GA line.  

(3) Deprecate SchedulingStrategy in favor of a newer interface.

Oleg



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org


Mime
View raw message