On Fri, 2018-12-07 at 15:48 -0800, Ryan Schmitt wrote: > Point of clarification: what exactly does @Internal mean? Does it > mean that > customers should not invoke methods on that type, or does it mean > that they > should not import it at all? (In the latter case, we have more > control, > since we can remove or merge types.) >
At the moment it is merely 'there be dragons' warning. It is up to us to decide what that effectively implies. One option is to allow API breakage of internal methods between minor releases (5.x.0). Oleg > On Wed, Dec 5, 2018 at 4:58 AM Oleg Kalnichevski <[email protected]> > wrote: > > > On Tue, 2018-12-04 at 14:36 -0700, Gary Gregory wrote: > > > On Tue, Dec 4, 2018 at 12:54 PM Ryan Schmitt <[email protected] > > > > > > > wrote: > > > > > > > My concern with the core/client split is that I think it > > > > exposes > > > > tons of > > > > additional API surface area which will become a liability post- > > > > release. My > > > > recent changes for TLS handshake timeouts are a good example of > > > > this: in > > > > order to use the `connectTimeout` as the TLS handshake timeout > > > > (which is > > > > basically a bugfix), I had to make breaking API changes to over > > > > a > > > > dozen > > > > public classes, and two interfaces as well (TlsStrategy > > > > and TransportSecurityLayer). > > > > > > > > The interface changes are particularly worrisome, because after > > > > release > > > > they'll be more or less impossible; we won't even have Java 8 > > > > default > > > > methods to fall back on. Core defines over 130 public > > > > interfaces, > > > > about > > > > half of which are new in 5.0, and only four of which are marked > > > > @Internal, > > > > so our compatibility obligations are clearly daunting. > > > > > > > > Merging core into client is obviously an extreme suggestion, > > > > but > > > > I'm not > > > > sure how else to attack the root of this problem. > > > > > > > > > > No silver bullet here I am afraid. > > > > > > > I agree to that. This is a valid concern but I do not think we have > > many options. By our charter the project is intended to build re- > > usable > > components, not a single HTTP client. > > > > Besides, we have somehow managed to keep HttpCore 4.x and > > HttpClient > > 4.x fully backward compatible for over 10 years, though it was not > > easy. > > > > Post 5.0 we should be able to upgrade to Java 1.8 or Java 9. > > > > We can also decide that we can break API of classes / interfaces > > marked > > @Internal. I believe this is what Apache Lucene does. > > > > In the meantime feel free to propose what classes / interfaces > > should > > be made package private or marked internal. > > > > Oleg > > > > > > > > > > ----------------------------------------------------------------- > > ---- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
