You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by sebb <se...@gmail.com> on 2014/02/24 17:18:16 UTC
Change Javadoc show level?
The class ExponentialBackOffSchedulingStrategy references the package
class AsynchronousValidationRequest in Javadoc.
However, because the default is to not show package-protected classes,
the generated Javadoc has a broken link:
http://hc.apache.org/httpcomponents-client-4.3.x/httpclient-cache/apidocs/org/apache/http/impl/client/cache/ExponentialBackOffSchedulingStrategy.html
Just wondering whether we should change the default level?
This can be done on the command-line with -Dshow=package
[The above was found in the 4.3 branch, but is probably relevant in trunk]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Posted by sebb <se...@gmail.com>.
On 25 February 2014 16:53, Oleg Kalnichevski <ol...@ok2consulting.com> wrote:
>
>>>
>>> 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.
>
> Users are expected to implement this method. Without it the interface is pointless.
OK, I see now.
Sorry, was looking at it backwards.
There perhaps should be a test case in a different package to confirm this.
> Oleg
> --
> Sent from my Android device with K-9 Mail. Please excuse my brevity.
>
> ---------------------------------------------------------------------
> 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
Re: SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Posted by Oleg Kalnichevski <ol...@ok2consulting.com>.
>>
>> 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.
Users are expected to implement this method. Without it the interface is pointless.
Oleg
--
Sent from my Android device with K-9 Mail. Please excuse my brevity.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Posted by sebb <se...@gmail.com>.
On 25 February 2014 14:51, Oleg Kalnichevski <ol...@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 <ol...@apache.org> wrote:
>> > > On Tue, 2014-02-25 at 01:08 +0000, sebb wrote:
>> > >> On 24 February 2014 16:33, Gary Gregory <ga...@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
Re: SchedulingStrategy API breakage; was Re: Change Javadoc show
level?
Posted by Oleg Kalnichevski <ol...@apache.org>.
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 <ol...@apache.org> wrote:
> > > On Tue, 2014-02-25 at 01:08 +0000, sebb wrote:
> > >> On 24 February 2014 16:33, Gary Gregory <ga...@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
SchedulingStrategy API breakage; was Re: Change Javadoc show level?
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2014-02-25 at 12:04 +0000, sebb wrote:
> On 25 February 2014 09:52, Oleg Kalnichevski <ol...@apache.org> wrote:
> > On Tue, 2014-02-25 at 01:08 +0000, sebb wrote:
> >> On 24 February 2014 16:33, Gary Gregory <ga...@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
Re: Change Javadoc show level?
Posted by sebb <se...@gmail.com>.
On 25 February 2014 09:52, Oleg Kalnichevski <ol...@apache.org> wrote:
> On Tue, 2014-02-25 at 01:08 +0000, sebb wrote:
>> On 24 February 2014 16:33, Gary Gregory <ga...@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.
> 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
Re: Change Javadoc show level?
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Tue, 2014-02-25 at 01:08 +0000, sebb wrote:
> On 24 February 2014 16:33, Gary Gregory <ga...@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.
Oleg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Change Javadoc show level?
Posted by sebb <se...@gmail.com>.
On 24 February 2014 16:33, Gary Gregory <ga...@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.
> Gary
>
>
> On Mon, Feb 24, 2014 at 11:18 AM, sebb <se...@gmail.com> wrote:
>
>> The class ExponentialBackOffSchedulingStrategy references the package
>> class AsynchronousValidationRequest in Javadoc.
>>
>> However, because the default is to not show package-protected classes,
>> the generated Javadoc has a broken link:
>>
>>
>> http://hc.apache.org/httpcomponents-client-4.3.x/httpclient-cache/apidocs/org/apache/http/impl/client/cache/ExponentialBackOffSchedulingStrategy.html
>>
>> Just wondering whether we should change the default level?
>>
>> This can be done on the command-line with -Dshow=package
>>
>> [The above was found in the 4.3 branch, but is probably relevant in trunk]
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
>> For additional commands, e-mail: dev-help@hc.apache.org
>>
>>
>
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
> Spring Batch in Action <http://www.manning.com/templier/>
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
For additional commands, e-mail: dev-help@hc.apache.org
Re: Change Javadoc show level?
Posted by Gary Gregory <ga...@gmail.com>.
+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).
Gary
On Mon, Feb 24, 2014 at 11:18 AM, sebb <se...@gmail.com> wrote:
> The class ExponentialBackOffSchedulingStrategy references the package
> class AsynchronousValidationRequest in Javadoc.
>
> However, because the default is to not show package-protected classes,
> the generated Javadoc has a broken link:
>
>
> http://hc.apache.org/httpcomponents-client-4.3.x/httpclient-cache/apidocs/org/apache/http/impl/client/cache/ExponentialBackOffSchedulingStrategy.html
>
> Just wondering whether we should change the default level?
>
> This can be done on the command-line with -Dshow=package
>
> [The above was found in the 4.3 branch, but is probably relevant in trunk]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/>
JUnit in Action, Second Edition <http://www.manning.com/tahchiev/>
Spring Batch in Action <http://www.manning.com/templier/>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory