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
