You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Roland Weber <ht...@dubioso.net> on 2007/02/02 18:44:08 UTC
[HttpCore] API vs. Implementation
Hi folks,
I just noticed that we have dependencies from API classes
to implementation classes. The one I stumbled across is
AbstractHttpMessage, which depends on DefaultHttpParams.
Is there a consensus that the API classes and interfaces
should never depend on any implementation package?
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Roland Weber <ht...@dubioso.net>.
Hi Julius,
thanks for your comments.
> Doesn't this only matter if the "impl" is supposed to be pluggable?
Does your definition of "pluggable" require a plug-in mechanism?
Or does it cover "completely different implementation of the API"?
For me, it's the latter. We don't have a plug-in mechanism now,
and probably never will have one. But application developers may
use other plug-in/dependency injection mechanisms, like Spring.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Julius Davies <ju...@cucbc.com>.
I've never actually done an API vs. IMPL separation in my own work to
date. But my initial (probably naive) thought is this:
Doesn't this only matter if the "impl" is supposed to be pluggable? If
the "impl" is not pluggable, then there are only two advantages of the
api/impl separation:
#1. It's a nice way to communicate to the consumers of the library the
methods that are there explicitly for them! The "official" entry-points
into the library are easier to discern.
#2. (That age-old saw:) Makes for cleaner code that is easier to
maintain.
So to me, if the IMPL isn't pluggable, then a small number of
dependencies is okay if it makes the library easier to use.
yours,
Julius
On Fri, 2007-02-02 at 18:44 +0100, Roland Weber wrote:
> Hi folks,
>
> I just noticed that we have dependencies from API classes
> to implementation classes. The one I stumbled across is
> AbstractHttpMessage, which depends on DefaultHttpParams.
>
> Is there a consensus that the API classes and interfaces
> should never depend on any implementation package?
>
> cheers,
> Roland
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
>
--
Julius Davies, Senior Application Developer, Product Development
T 416-652-0183 | juliusdavies@cucbc.com
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Sat, 2007-02-03 at 17:58 +0100, Roland Weber wrote:
> Hi Oleg,
>
> > I do not think we should try to be holier than the Pope. As far as I
> > know Sun uses non-public Sun specific classes all over the place in
> > JRE.
>
> If Sun's code were good enough, we wouldn't provide an alternative
> HTTP implementation. Why should we sink to their level in other areas?
> ;-)
>
> This morning I realized why I don't like the API<->Impl intermingling.
> The software engineering classes I attended in the early nineties were
> rather dull, but - apart from the "Chinese Principle" - there was one
> golden rule I took with me, which was reenforced in other areas too:
> Cyclic dependencies are bad.
> The implementation necessarily has a dependency on the API, and by
> letting API classes depend on implementation classes, we get a cyclic
> dependency. Well, Sun has a cyclic dependency even between java.lang
> and java.io, but that doesn't mean I have to like it.
> Cyclic dependencies can't be avoided on a class level, since there
> are no header files in Java. I'm used to avoid cyclic dependencies
> on a package level in my code. For HttpComponents, I would be content
> to avoid a cyclic dependency between the API and the impl part of the
> source tree. I don't think that qualifies as "holier than the Pope".
> But if it is unattainable, so be it. I've got so much refactoring
> ahead of me, I don't insist on doing more.
>
> > We could make HeaderGroup and DefaultHttpParams public classes, or make
> > then inner classes instead, but personally do not see a lot of value in
> > doing so. Http service handlers in HttpCore NIO make a heavy use of
> > buffering primitives that I do not think we want to support as a part of
> > public API. Shall we make them all public, package private or inner?
>
> What's the difference between supporting something as part of the API
> or as part of the implementation part? If there's a bug, we'll fix it.
> If the class needs to be used by applications, such as DefaultHttpParams,
> we'll keep the API stable in the implementation part too. In case of a
> choice, I would rather move API classes to the impl part than vice versa.
>
> > We want people to be able to extend HttpCore and inject some application
> > specific implementation of interfaces, but do we ever want anyone to
> > provide a complete alternative implementation of HttpCore API?
>
> I doubt there will be one, whether the API depends on impl or not.
> I just consider it an indication of a good design if API does not
> depend on impl. But I've seen so many bad code, I won't loose sleep
> over this topic if we get it right otherwise.
> At the moment I can't tell how many dependencies we've got from API
> to impl. Maybe I'll have a look at it after I finish the package
> name change, which I'm about to tackle now.
>
Hi Roland
To me 'impl' in HttpCore means one and only thing: there is more than
one way of doing it. We might be a little less picky about changing the
inner working of those classes but I intend to support the interface
compatibility of 'impl' classes exactly the same way as that of non-impl
ones
Let us fix it if we can, but I personally will not lose sleep over it,
either.
Cheers
Oleg
> cheers,
> Roland
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Roland Weber <ht...@dubioso.net>.
Hi Oleg,
> I do not think we should try to be holier than the Pope. As far as I
> know Sun uses non-public Sun specific classes all over the place in
> JRE.
If Sun's code were good enough, we wouldn't provide an alternative
HTTP implementation. Why should we sink to their level in other areas?
;-)
This morning I realized why I don't like the API<->Impl intermingling.
The software engineering classes I attended in the early nineties were
rather dull, but - apart from the "Chinese Principle" - there was one
golden rule I took with me, which was reenforced in other areas too:
Cyclic dependencies are bad.
The implementation necessarily has a dependency on the API, and by
letting API classes depend on implementation classes, we get a cyclic
dependency. Well, Sun has a cyclic dependency even between java.lang
and java.io, but that doesn't mean I have to like it.
Cyclic dependencies can't be avoided on a class level, since there
are no header files in Java. I'm used to avoid cyclic dependencies
on a package level in my code. For HttpComponents, I would be content
to avoid a cyclic dependency between the API and the impl part of the
source tree. I don't think that qualifies as "holier than the Pope".
But if it is unattainable, so be it. I've got so much refactoring
ahead of me, I don't insist on doing more.
> We could make HeaderGroup and DefaultHttpParams public classes, or make
> then inner classes instead, but personally do not see a lot of value in
> doing so. Http service handlers in HttpCore NIO make a heavy use of
> buffering primitives that I do not think we want to support as a part of
> public API. Shall we make them all public, package private or inner?
What's the difference between supporting something as part of the API
or as part of the implementation part? If there's a bug, we'll fix it.
If the class needs to be used by applications, such as DefaultHttpParams,
we'll keep the API stable in the implementation part too. In case of a
choice, I would rather move API classes to the impl part than vice versa.
> We want people to be able to extend HttpCore and inject some application
> specific implementation of interfaces, but do we ever want anyone to
> provide a complete alternative implementation of HttpCore API?
I doubt there will be one, whether the API depends on impl or not.
I just consider it an indication of a good design if API does not
depend on impl. But I've seen so many bad code, I won't loose sleep
over this topic if we get it right otherwise.
At the moment I can't tell how many dependencies we've got from API
to impl. Maybe I'll have a look at it after I finish the package
name change, which I'm about to tackle now.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Fri, 2007-02-02 at 23:18 -0700, Bindul Bhowmik wrote:
> Hi Roland / Oleg,
>
> On 2/2/07, Roland Weber <ht...@dubioso.net> wrote:
> > Oleg Kalnichevski wrote:
> >
> > > Here's my take. No impl classes in public methods (and hence
> > > interfaces). I do not see a problem with using impl class internally if
> > > they never get exposed to the consumer.
> >
> > There goes my idea of compiling the API classes separately
> > to detect dependencies on impl.
>
> It is not required to actually compile the classes separately. Tools
> like Classycle[1] or JDepend[2] could be used.
>
> >
> > Using anything internally does not match with my understanding
> > of an Application Programming _Interface_, but since it seems
> > I'm the only one who doesn't like it, let's leave it as it is.
>
> [Non-binding thought]: I actually like to stick to the idea of having
> API and interfaces should be separate from implementation classes. I
> like to think that if APIs need to depend on implementations, then the
> APIs probably need to be expanded.
>
Hi Roland / Bindul
I do not think we should try to be holier than the Pope. As far as I
know Sun uses non-public Sun specific classes all over the place in
JRE.
We could make HeaderGroup and DefaultHttpParams public classes, or make
then inner classes instead, but personally do not see a lot of value in
doing so. Http service handlers in HttpCore NIO make a heavy use of
buffering primitives that I do not think we want to support as a part of
public API. Shall we make them all public, package private or inner?
We want people to be able to extend HttpCore and inject some application
specific implementation of interfaces, but do we ever want anyone to
provide a complete alternative implementation of HttpCore API?
Oleg
> >
> > cheers,
> > Roland
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> > For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
> >
> >
>
>
> Regards,
> Bindul
>
> [1] http://classycle.sourceforge.net/
> [2] http://www.clarkware.com/software/JDepend.html
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Bindul Bhowmik <bi...@gmail.com>.
Hi Roland / Oleg,
On 2/2/07, Roland Weber <ht...@dubioso.net> wrote:
> Oleg Kalnichevski wrote:
>
> > Here's my take. No impl classes in public methods (and hence
> > interfaces). I do not see a problem with using impl class internally if
> > they never get exposed to the consumer.
>
> There goes my idea of compiling the API classes separately
> to detect dependencies on impl.
It is not required to actually compile the classes separately. Tools
like Classycle[1] or JDepend[2] could be used.
>
> Using anything internally does not match with my understanding
> of an Application Programming _Interface_, but since it seems
> I'm the only one who doesn't like it, let's leave it as it is.
[Non-binding thought]: I actually like to stick to the idea of having
API and interfaces should be separate from implementation classes. I
like to think that if APIs need to depend on implementations, then the
APIs probably need to be expanded.
>
> cheers,
> Roland
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
>
>
Regards,
Bindul
[1] http://classycle.sourceforge.net/
[2] http://www.clarkware.com/software/JDepend.html
--
Bindul Bhowmik
MindTree Consulting Ltd.
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Roland Weber <ht...@dubioso.net>.
Oleg Kalnichevski wrote:
> Here's my take. No impl classes in public methods (and hence
> interfaces). I do not see a problem with using impl class internally if
> they never get exposed to the consumer.
There goes my idea of compiling the API classes separately
to detect dependencies on impl.
Using anything internally does not match with my understanding
of an Application Programming _Interface_, but since it seems
I'm the only one who doesn't like it, let's leave it as it is.
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: [HttpCore] API vs. Implementation
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Fri, 2007-02-02 at 18:44 +0100, Roland Weber wrote:
> Hi folks,
>
> I just noticed that we have dependencies from API classes
> to implementation classes. The one I stumbled across is
> AbstractHttpMessage, which depends on DefaultHttpParams.
>
> Is there a consensus that the API classes and interfaces
> should never depend on any implementation package?
>
> cheers,
> Roland
Here's my take. No impl classes in public methods (and hence
interfaces). I do not see a problem with using impl class internally if
they never get exposed to the consumer.
Oleg
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org