Coding Standards: API, IMPL and reuse

["Noel J. Bergman" <no...@devtech.com>]

Alex Karasulu wrote:

> Ok looks like a plan then.  I'll add this to the JIRA as a task.

What plan?

> Take commons-logging and make it disappear.
> but you need to log stuff.  So just throw together
> a console logger of your own design [inside] a class
> called ConsoleMonitor or whatever.

Logging is just an instance of reuse.  Stephen said, his "point was not
specific to commons logging - it was specific to consequences related to
non-separation of services from implementation concerns at the packaging
level [...]."  Stephen concluded that "achieving good isolation requires
that the entire api chain is composed of clean apis.  An api exposing [any]
implementation artifact) is not a clean api."

There are relatively few packages that have a complete separation of API and
implementation.  Almost nothing in J2SE and J2EE.

Stephen's commentary, taken to the ludicrous extreme, could suggest that we
would create our own API and adapter IMPL for all things, becoming in effect
our own commons.  So I'd like to see a cogent explanation of the
project-wide plan to reuse common external packages.  What is acceptable to
expose in an API?  And where?  Java lacks a means to express it, but not all
packages are intended for public consumption.

Trustin asked about coding standards.  Forget about braces, tabs, end of
line and other mechanical things.  THIS is a coding standards issue.

Lastly, please separate packages from PACKAGING.  How you package things in
JAR files is not isomorphic with package layout.  Yes, packagING can have
effects, but it can also be transparently changed when and if necessary.

	--- Noel

RE: Coding Standards: API, IMPL and reuse

["Noel J. Bergman" <no...@devtech.com>]

Niclas Hedhman wrote:
> Noel J. Bergman wrote:
> > This issue came up in terms of exposing other people's
> > packages in our API.  So are you suggesting that since
> > J2SE APIs are not clean, where clean is defined as a
> > total API/impl separation, that we not expose them in
> > our public API?

> The JDK classes are not an issue, whether they are clean or
> not is irrelevant, they sit in the bootstrap classloader and
> can't be exchanged during the life-time of the JVM.

OK, so there we have a guideline.  JDK classes are fine to use in the API.
:-)

> Since you don't care about classloading and/or think that it
> is not an issue and/or an issue for someone else, then isn't
> this discussion meaningless.

Whomever said that?  I can't find any recollection of such a silly comment
anywhere in this thread.  Certainly not from me, and Alex specifically
talked about classloading issues.

We are going to want to be mindful of classloader behavior for such things
as stored procedures, class and state factories, etc., not to mention
re-deployment of service components.

Alex is also mentioned MAXINE as a possibly minimal micro-kernel, which
would also require proper redeploy support.

> What is API vs Impl?

I don't believe that we're arguing over that question.  :-)

	--- Noel

Re: Coding Standards: API, IMPL and reuse

[Niclas Hedhman <ni...@hedhman.org>]

On Wednesday 22 September 2004 02:32, Noel J. Bergman wrote:

> This issue came up in terms of exposing other people's packages in our API.
> So are you suggesting that since J2SE APIs are not clean, where clean is
> defined as a total API/impl separation, that we not expose them in our
> public API?

The JDK classes are not an issue, whether they are clean or not is irrelevant, 
they sit in the bootstrap classloader and can't be exchanged during the 
life-time of the JVM. 

Since you don't care about classloading and/or think that it is not an issue 
and/or an issue for someone else, then isn't this discussion meaningless. If 
no reloading or hot-deploy is ever going to occur, just throw everything into 
the system classloader and ignore dynamicity, which is what most people think 
is appropriate.

Conclusion (the point where think stops) is that a lot of this debate is 
around terminology. What is API vs Impl? After discussing the same issue with 
Log4J, it seems that API for most people is a "blob" that does something 
according to a set of documentation. If that is the definition, then you are 
not designing for hot-swap and dynamic systems, and a system that do 
understand the difference will treat your "API" as an implementation "blob", 
together with all the code that links to it.
Whether or not the packaging can be changed later to deal with what I am 
talking about, depends a lot on how the API is designed and what is exposed 
in the methods. Furthermore, people are people and makes mistakes. It is not 
uncommon that dependencies from API to Impl classes are introduced by mistake 
or "couldn't figure it out", which is not the case when they are separated in 
the build system, since a cyclic dependency will result.

Cheers
Niclas
-- 
   +------//-------------------+
  / http://www.bali.ac        /
 / http://niclas.hedhman.org / 
+------//-------------------+

RE: Coding Standards: API, IMPL and reuse

["Noel J. Bergman" <no...@devtech.com>]

Niclas Hedhman wrote:

> Noel J. Bergman wrote:
> > There are relatively few packages that have a complete
> > separation of API and implementation.  Almost nothing
> > in J2SE and J2EE.

> Others shit is a bad excuse to intentionally keep making
> your own shit.

You missed my point.  As I asked:

> > What is acceptable to expose in an API?  And where?

And you responded:

> Your own API should be sleek and clean.

This issue came up in terms of exposing other people's packages in our API.
So are you suggesting that since J2SE APIs are not clean, where clean is
defined as a total API/impl separation, that we not expose them in our
public API?

> > Trustin asked about coding standards.  Forget about braces,
> > tabs, end of line and other mechanical things.  THIS is a
> > coding standards issue.

> Maybe I have missed it, but I haven't seen Trustin asking
> about coding standards. The only one I can think of is
> his query about "code convention".

Same issue.  My point is simply that this issue is a lot more important than
whitespace.

	--- Noel

Re: Coding Standards: API, IMPL and reuse

[Niclas Hedhman <ni...@hedhman.org>]

On Wednesday 22 September 2004 00:01, Noel J. Bergman wrote:

> There are relatively few packages that have a complete separation of API
> and implementation.  Almost nothing in J2SE and J2EE.

Others shit is a bad excuse to intentionally keep making your own shit.

> What is acceptable to expose in an API?  And where?  

Your own API should be sleek and clean.

> Java lacks a means to express it, but not
> all packages are intended for public consumption.

That is another reason to drop it into the implementation classloader, and 
have that classloader in a separate branch. 

> Trustin asked about coding standards.  Forget about braces, tabs, end of
> line and other mechanical things.  THIS is a coding standards issue.

Not sure what you are on about here. Maybe I have missed it, but I haven't 
seen Trustin asking about coding standards. The only one I can think of is 
his query about "code convention". Maybe you are referring to something else.

> Lastly, please separate packages from PACKAGING.  How you package things in
> JAR files is not isomorphic with package layout.  Yes, packagING can have
> effects, but it can also be transparently changed when and if necessary.

Agree. What you can't change is what constitutes the API to a smaller set. So 
bundling to much crap into the API from the beginning is a sure way to dig an 
early grave. (You mentioned the J2SE as an example)

-- 
   +------//-------------------+
  / http://www.bali.ac        /
 / http://niclas.hedhman.org / 
+------//-------------------+

RE: Coding Standards: API, IMPL and reuse

[Stephen McConnell <mc...@apache.org>]

> -----Original Message-----
> From: Trustin Lee [mailto:trustin@gmail.com]
> Sent: 24 September 2004 02:19
> To: Apache Directory Developers List
> Subject: Re: Coding Standards: API, IMPL and reuse
> 
> >   1. service interfaces
> >   2. exceptions
> >   3. other immutable datatypes
> 
> Nice!  But I have a question:  Does 'service interface' mean literally
> Java 'interface' construct?  If so, I'm slightly negative on this.
> How about abstract classes or very well defined APIs such JDOM?  If
> what the service does is very concrete and needs only small extension
> point , abstract classes or concrete classes which provides some
> extension points using the patterns such as Observer or Strategy.

In the above 'service interface' means literally a Java interface
construct.  However, I share your concerns/opinions as the subject of
abstract classes.  My own experience is that the issue is much more
related to tools and enabling technologies.  If you have good tools and
the supporting infrastructure - you stop caring about the number of jar
files - instead you think more in terms of classloader composition,
hierarchies, and code-base identification.

This is something that has to be taken into consideration.  Within
Avalon we have over 140 different version projects - but we never play
around with jar files directly.  We do play around with plugin
definitions, blocks, and other constructs that at of the day represent
cloassloader chains, api, spi and implementation hierarchies.

Cheers, Steve.


> Trustin
> --
> what we call human nature in actually is human habit
> --
> http://gleamynode.net/

Re: Coding Standards: API, IMPL and reuse

[Trustin Lee <tr...@gmail.com>]

>   1. service interfaces
>   2. exceptions
>   3. other immutable datatypes

Nice!  But I have a question:  Does 'service interface' mean literally
Java 'interface' construct?  If so, I'm slightly negative on this. 
How about abstract classes or very well defined APIs such JDOM?  If
what the service does is very concrete and needs only small extension
point , abstract classes or concrete classes which provides some
extension points using the patterns such as Observer or Strategy.

Trustin
-- 
what we call human nature in actually is human habit
--
http://gleamynode.net/

RE: Coding Standards: API, IMPL and reuse

[Stephen McConnell <mc...@apache.org>]

> -----Original Message-----
> From: Noel J. Bergman [mailto:noel@devtech.com]
> What is acceptable to expose in an API?  And where?  Java
> lacks a means to express it, but not all packages are intended 
> for public consumption.

Just a quick overview of the sort of things I consider as acceptable
content in an API:

  1. service interfaces
  2. exceptions
  3. other immutable datatypes

With respect to service interfaces - these should not expose aspects
related to object instantiation, deployment or implementation strategy.
Exceptions and other immutable datatypes exposed in an API should only
include those classes exposed by and documented under service
interfaces.  

Furthermore, the quality of the interface can be impacted by the
references it contains to external APIs and Java classes. Reference to
external APIs should in general be handled with caution as this
represents exposure of your own API to an external development cycle.
Specifically - major version changes within an external API while
manageable at build time - are not necessarily under your control at
runtime. Lastly, reference to Java classes should not include
implementation classes.

Above and beyond the content of the api is the subject of identification
of the purpose of the api. In particular - is the api for a client, for
management, or some other aspect?  Identifying the role of the user will
often result in the identification of different apis (e.g. client api,
management api, plugin service provider (SPI), etc.).  Lastly,
separation of these different concerns under identifiable codebases
enables better integration within the java security framework. 

Cheers, Steve.