Separate API and Implementation?

El vie, 07-04-2006 a las 13:30 +0200, Andreas Hartmann
escribió:
> Thorsten Scherler wrote:
> > El jue, 06-04-2006 a las 17:40 +0200, Andreas
Hartmann escribió:
> >> Hi Lenya devs,
> >>
> >> currently, it's not clear which
classes+interfaces form
> >> the Lenya API (i.e., have to stay backwards
compatible
> >> and therefore may be used by client code).
> >>
> >> Examples are AbstractUsecase and
DocumentUsecase:
> >> Can you extend these classes without the
danger of
> >> incompatible changes in future 1.4.x versions?
> > 
> > I am unsure what to tell you. We have a couple of
usecases that extend
> > this classes. IMO this default implementations
should reflect the least
> > common denominator
> 
> +1
> 
> > and as soon as 1.4.x is in the release cycle they
> > *should* be backwards compatible.
> 
> IMO AbstractUsecase and DocumentUsecase are general
enough
> to put them into the API.
> 

agreed, but we still would need an implementation right?

> 
> >> I like the approach taken by Avalon/Excalibur:
> >>
> >> - framework/api/src/java
> >> - framework/api/src/test
> >> - framework/impl/src/java
> >> - framework/impl/src/test
> >>
> >> For example: AbstractLogEnabled is part of the
API,
> >> AbstractConfiguration is not. A disadvantage
of this
> >> approach is that you can't tell whether a
class is
> >> part of the API without knowing where it is
located
> >> in the source tree. Maybe we can solve this
using
> >> package names which contain
"impl":
> >>
> >> o.a.lenya.cms.usecase.*
> >> o.a.lenya.cms.usecase.impl.*
> >>
> >>
> >> Modules are another story, but maybe the same
concept
> >> can be applied there.
> >>
> >>
> >> WDYT?
> > 
> > Yeah, with this move we as well should harmonize
the naming for the
> > implementation classes.
> > 
> > We have now:
> > - Default.java
> > - Impl.java
> 
> I'm using Default{*} if I want to point out
explicitely
> that the class is just an example implementation, and
> {*}Impl if it is meant to be (more or less) the only
> implementation. But the differences are subtle, and
> it's fine with me to use only one naming convention.
> 

Thanks for the explaning this, I always wondered. ;)

> 
> > - .java
> > 
> > IMO if we agree on 
> >> o.a.lenya.cms.usecase.*
> >> o.a.lenya.cms.usecase.impl.*
> > 
> > Then we should have
> > - o.a.lenya.cms.usecase.*
> >   * .java
> > - o.a.lenya.cms.usecase.impl.*
> >   * .java
> 
> IMO this is not very convenient, because you have to
use
> explicit package declarations (which is quite verbose),
> and the class name references are ambiguous.
> 
> For example:
> 
>    package org.apache.lenya.cms.impl.Document;
> 
>    class Document implements
org.apache.lenya.cms.Document {
> 
>        public org.apache.lenya.cms.Document getParent()
{
>            ....
>            org.apache.lenya.cms.Document doc = ...
>            return doc;
>        }
> 
>    }
> 
> In other classes in the *.impl package you might want
to
> access *.impl.Document instances directly (not via the
> interface), which is perfectly valid. IMO this makes
the
> code hard to understand, because you always have to
check
> the imports to know if it's an *.Document or
*.impl.Document.
> 
> 
> I'd prefer
> 
>   - o.a.lenya.cms.usecase.*
>     * .java
>   - o.a.lenya.cms.usecase.impl.*
>     * Impl.java
> 

Makes perfect sense to me.

+1

> 
> Thanks for your comments!

Thanks for bringing this up.

salu2
-- 
Thorsten Scherler
COO Spain
Wyona Inc.  -  Open Source Content Management  -  Apache
Lenya
http://www.wyona.com     
             http://lenya.apache.org
thorsten.scherlerwyona.com                thorstenapache.org


------------------------------------------------------------
---------
To unsubscribe, e-mail: dev-unsubscribelenya.apache.org
For additional commands, e-mail: dev-helplenya.apache.org

Thorsten Scherler wrote:
> El vie, 07-04-2006 a las 13:30 +0200, Andreas Hartmann
escribió:
>> Thorsten Scherler wrote:
>>> El jue, 06-04-2006 a las 17:40 +0200, Andreas
Hartmann escribió:
>>>> Hi Lenya devs,
>>>>
>>>> currently, it's not clear which
classes+interfaces form
>>>> the Lenya API (i.e., have to stay backwards
compatible
>>>> and therefore may be used by client code).
>>>>
>>>> Examples are AbstractUsecase and
DocumentUsecase:
>>>> Can you extend these classes without the
danger of
>>>> incompatible changes in future 1.4.x
versions?
>>> I am unsure what to tell you. We have a couple
of usecases that extend
>>> this classes. IMO this default implementations
should reflect the least
>>> common denominator
>> +1
>>
>>> and as soon as 1.4.x is in the release cycle
they
>>> *should* be backwards compatible.
>> IMO AbstractUsecase and DocumentUsecase are general
enough
>> to put them into the API.
>>
> 
> agreed, but we still would need an implementation
right?

Hmmm, what do you mean? They are abstract implementations
of the Usecase interface ...

The question is really where to draw the line.

IMO some requirements for classes/interfaces in the API are

- it is generic, i.e. it fits all usage patterns
   (nothing like "This only works in certain
circumstances ...")

- it can be guaranteed to work in future versions (e.g.,
   it doesn't use internal classes of other products in
   its signature)

- it doesn't reference any classes/interfaces which are
   not part of the API (completeness of the API is required)


Indicators when to put an implementation in the API are:

- it reflects a best practise
- there's no other (sensible) way to do it
- it would be very hard to implement it in the client code
- it's a mere utility to simplify the usage of components

WDYT? What other criteria do apply?

-- Andreas


-- 
Andreas Hartmann
Wyona Inc.  -   Open Source Content Management   -   Apache
Lenya
http://www.wyona.com     
                http://lenya.apache.org
andreas.hartmannwyona.com                     andreasapache.org


------------------------------------------------------------
---------
To unsubscribe, e-mail: dev-unsubscribelenya.apache.org
For additional commands, e-mail: dev-helplenya.apache.org