Upayavira wrote:

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