Date: 2004-07-20T14:08:58 Editor: UgoCei <[EMAIL PROTECTED]> Wiki: Cocoon Wiki Page: ButterflyManifesto URL: http://wiki.apache.org/cocoon/ButterflyManifesto
no comment New Page: = The Butterfly Manifesto (DRAFT) = == Introduction == We all know Cocoon has some problems. I am not referring here to bugs, poor documentation or a steep learning curve for beginners. I am talking about structural deficiencies that make it hard to test it, refactor it, deploy it and manage it. The most distressing fact, for us developers, is that it's hard to '''change it'''. We want to have real blocks for the next major release, but it seems quite improbable that we'll get there with the current Avalon-based architecture. Meanwhile, Avalon continues to be plagued by community problems. This was quite clearly argumented by Stefano on the [http://marc.theaimsgroup.com/?t=108004833700001&r=1&w=2 On building on stone] thread. While Avaloners were fighting and flaming, a new breed of lightweight containers based on a form of Inversion of Control called Dependency Injection saw the light. Among them: [http://www.picocontainer.org/ PicoContainer], [http://jakarta.apache.org/hivemind/ HiveMind] and [http://www.springframework.org/ Spring]. == What is Butterfly == Butterfly is an experiment aiming to implement a (simplified) Cocoon clone but based on Spring instead of Hibernate (hence the name Butterfly: what do cocoons turn into in spring?). '''This is not a fork of Cocoon'''. This is a sandbox where new ideas can be tested without fear of breaking some eggs. If something valid emerges, we can discuss if it can be backported to Cocoon or not. In any case, we won't be reimplementing the whole of Cocoon. Even though Stefano suggested doing our own container, we would like to avoid doing more work than necessary and reuse something existing, if possible. Our initial choice is to use Spring, as it: * has a healthy community * is very well documented * is rapidly growing in acceptance and usage * is being used in real world applications * aims to do one thing and do it well and does not attempt to be everything for everyone * integrates well with other useful technologies (Hibernate, JDO, OJB, EJB, Struts, JMS, AOP ...) instead of trying to replace them * fits perfectly in J2EE environments, where we expect Cocoon to be often deployed. == Design principles == 1. Simplicity 1. Avoid dependencies 1. Testability 1. Use the standards 1. Courage == Practices == Practices embody the above-mentioned design principles in a set of practical guidelines. === Avoid unnecessary dependencies (and excessive coupling) === Following the Spring mantra, components should not depend upon the framework, for instance by implementing interfaces or extending classes provided by the framework, unless this provides real value and is hidden in implementation classes. This allows for greater portability and testability of components in isolation. Importing framework packages in components' source code is a sign of dependency. Doing it in glue code is OK. Remove any possible dependency on Avalon. If you want to reuse some of its functionalities, copy classes over and refactor them as necessary (see org.apache.butterfly.source package). === Limit reuse by implementation inheritance === Case in point: most of Cocoon's sitemap components inherit from Abstract''''''Log''''''Enabled. This must go away: logging is an aspect, not a more general concept. In other words, a File''''''Generator is not an Abstract''''''Log''''''Enabled. Another symptom of this is very deep inheritance hierarchies. We should prefer delegation or composition over inheritance whenever we want to reuse. === Use standard JDK packages whenever possible === Use JAXP and TrAX for processing XML. We can debate whether to use JDK logging or Log4J (or Commons Logging) instead. Since Spring uses the latter and everybody says JDK logging sucks, we should use it too, probably. If necessary, provide a thin wrapper around third-party APIs for adaptation (see org.apache.butterfly.xml.Parser). === Don't be dragged down by backward compatibility === We are exploring new ground, so we should be courageous and not be too limited by considerations of backward compatibility. JDK 1.4 is a minimum requirement. === Strive for 100% unit test coverage === Code that isn't excercised by tests is not there. === Avoid checked exceptions === Checked exceptions do more harm than good, so it would be wise to avoid them altogether. Design instead a hierarchy of runtime exceptions and, whenever you need to catch an exception thrown by a third party library, decide whether you can handle it locally. If you cannot, wrap it in a runtime exception and throw the latter. == Code == There is an Eclipse project in the attached zip file. Volunteers that want to make an Ant build file are welcome. At the moment we have implemented ridiculously simplified versions of: * File''''''Generator * Trax''''''Transformer * XMLSerializer plus some parts of the Source package from Excalibur. This can at least allow us to compose a simple pipeline. Most of the features of the above mentioned components have intentionally been dropped, since our focus is presently on testing how sitemap components can be managed by a Spring bean factory. == References == 1. [http://marc.theaimsgroup.com/?t=108004833700001&r=1&w=2 On building on stone] 1. [http://marc.theaimsgroup.com/?t=108480413200001&r=1&w=2 Serviceable considered harmful] 1. [http://marc.theaimsgroup.com/?t=108188608400002&r=1&w=2 Checked exceptions considered harmful] 1. [http://marc.theaimsgroup.com/?t=108938779700001&r=1&w=2 Spring+JMX == Real Blocks?]
