cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Fagerstrom <dani...@nada.kth.se>
Subject Re: Public/Private classification (was Re: javadocs navigation)
Date Thu, 13 Oct 2005 09:42:04 GMT
Upayavira wrote:

> So, I have created a wiki page:
>
> http://wiki.apache.org/cocoon/PublicAPIClasses
>
> Please go there and mark classes public/private as necessary. As it 
> says at the top of that page, if you disagree with someone, change it 
> to "dispute" or D for short. Then it becomes an opportunity for some 
> healthy argument!

Wow! that's a lot of classes. While I aplaud the initiative, 673 classes 
are huge amount to classify. I would suggest that we start discussing 
principles first a bit.

IMO we need to find two set of interfaces/classes: the API of Cocoon, 
and the set of classes (components) that an application programmer need 
JavaDoc for.

I guess this thread is mainly about the second set, but I find it hard 
to adress whoyhout discussing the first one.

Cocoon API
==========

These are the interfaces that we intend an application programmer to 
implement while building Cocoon applications. Our "contract" with the 
user is that we do our best to keep these interfaces. And when that 
would be a to large hinder for further development of Cocoon, we follow 
standard practices for deprecation or interface modification.

We should IMO put the Cocoon API in one or possibly several pure 
interface jars (bundles).

So what is the Cocoon API? All interfaces used in 
cocoon-core-sitemap.xconf are part of the Cocoon API: Generator, 
Transformer, Serializer, Reader, Matcher, Selector, Action, 
ProcessingPipeline. Then the interfaces refered to in the Cocoon API 
must be part of the API as well by transitive closure. So here we get 
various exceptions, SitemapModelComponent, XMLPipe, XMLProducer and much 
more. The ObjectModelHelper with dependencies is also part of the API.

Then we can continue to take a look at cocoon-core.xconf. Most of the 
interfaces used here are probably part of the Cocoon API: InputModule, 
OutputModule, Source (with extending interfaces: WritableSource and 
maybe some more), to mention some obvious. For some of the interfaces 
here it is less clear if they are part of the Cocoon API, as an example 
are we going to support the use of Processor? To connect to a current 
discussion.

Maybe there are part of the Cocoon API that not is used for components 
and "sitemap components"? We obviously support Servlet e.g.

"Public API Classes"
====================

This is what a user needs to build own components, use components from 
flowscript or using Cocoon from other applications or environments.

Here we have all (or most) components defined in 
cocoon-core-sitemap.xconf and cocoon-core.xconf. The CocoonBean and 
CocoonServlet would also be part of this. Some utility classes from util 
and xml and abstract classes that helps implementing different component 
classes could also be part of the public API classes.

             --- o0o ---

So if you think that the above is a good idea, we could work 
incrementally: Start with defining the Cocoon API: one list of sitemap 
component interfaces, one with component interfaces and one where people 
could add other intefaces that should be part of the Cocoon API. Then we 
could mark what should be public and private in these lists.

We also need to have a list with the transitive closure of all 
interfaces and classes that the previous lists depends on (hopefully 
some IDE or other tool can generate that list). As the dependencies also 
need to be part of the Cocoon API. This will also give as an indication 
if there are parts of Cocoon that would need to be refactored to give 
cleaner and more focused interfaces.

When we have agreed about what is the Cocoon API, I would be happy if we 
could move it to an own jar.

After or in parallell with finding the Cocoon API, we could work on the 
"public API classes", following similar principles. Listing all 
components from our configuration for marking them public or private and 
also utility classes. And then a list of the transitive closure of the 
dependencies. Also the public API classes should go to one or several 
"component" bundles.

WDYT?

/Daniel


Mime
View raw message