lenya-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andreas Hartmann <andr...@apache.org>
Subject Re: [1.4] Separate API and Implementation?
Date Fri, 07 Apr 2006 11:30:41 GMT
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


> 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.

>> 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{api-class-name}.java
> - {api-class-name}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.

> - {different-name-then-the-api-class-name}.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.*
>   * {api-class-name}.java
> - o.a.lenya.cms.usecase.impl.*
>   * {api-class-name}.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.*
    * {api-class-name}.java
  - o.a.lenya.cms.usecase.impl.*
    * {api-class-name}Impl.java

Thanks for your comments!

-- Andreas

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

To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org

View raw message