hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Date Tue, 25 Feb 2014 16:25:24 GMT
On 25 February 2014 14:51, Oleg Kalnichevski <olegk@apache.org> wrote:
> 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.

That should fix the Javadoc issue.

Perhaps I'm missing something, but I'm not sure how external code can
invoke the schedule() method?
There does not seem to be a way to create an instance of the required
AsynchronousValidationRequest parameter except from the same package.

Or perhaps the schedule() method is not supposed to be called externally?

In which case, why not just document that the method is only public
because it implements the interface, and is only intended for internal
use?
The changes to AsynchronousValidationRequest could then be reverted,
as there would be no need to reference the package-private class in
the Javadoc.

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

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


Mime
View raw message