hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Oleg Kalnichevski <ol...@apache.org>
Subject Re: SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Date Tue, 25 Feb 2014 14:51:05 GMT
On Tue, 2014-02-25 at 14:09 +0100, Oleg Kalnichevski wrote:
> 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
> 

I worked the problem around my making AsynchronousValidationRequest
public while leaving its constructor package private.

Oleg



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


Mime
View raw message