Boldly Open

ApacheCon just started with a great keynote about computer history, I chaired my first session and I’m now sitting in a crowded room to hear all the best and latest from Apache Geronimo, while trying to catch up with e-mail and office-related issues (sometimes being able to check e-mail sucks badly). These have been incredibly packed days, full of geek fun hacking on Cocoon and its possible migration path to OSGi and with some wonderful moments spent with my wife. Some random bits of what happened during the past few days follow:

• driving to Stuttgart went smooth, despite Switzerland doing its best to piss me off. I always hated having to pay a yearly fee to get to Swiss highways even if it’s just for a day: even though the total amount is probably less of what I’d pay in tolls for a corresponding mileage on italian highways, still I don’t like the idea, so finding out that a good deal of the road was on ordinary single-lane roads going across villages and cities provided a good chance to refresh my curse and swear words vocabulary.
• the hotel is great, offering one of the best breakfasts I could experience in a long time (people who know me are aware of how much of a difference that can make). Beds are incredibly soft and fluffy, and I had a few sleeps to remember (well, driving 500kms surely helps in sleeping well).
• Stuttgart is having an important tennis event, and a good deal of players share our hotel: it’s somewhat funny, in the evening, to see the hotel reception packed with tanned athletes on one side, and over/underweight pale geeks with funny shirts on the other.
• food (well, apart from breakfast, that is) hasn’t been that great so far. We’ve been unable to find a decent place in Stuttgart: when I’m abroad I costantly refuse to eat italian food, and my wife doesn’t like oriental. Given that here you basically have to choose between italian and chinese restaurants, you can imagine us walking frantically downtown to find some local place, with no real luck (bad suabian food really sucks, believe me). Suggestions are welcome, of course.
• A notable exception to the bad food experience happened yesterday. I left the Hackathon early, to drive around Stuttgart with my wife and do some sightseeing. Eventually, we had quite a trip: we were able to get on a scenic road crossing the Black Forest, where we had some breathtaking views of the impressive landscape, with our final destination being Baden-Baden. Well, actually Baden-Bades was just so-so, which made us consider having dinner in Karlsruhe, just to be able to see a different place. On the highway, we found out that Heidelberg wasn’t that far away, and we decided to go the extra (20) miles. Well, it was definitely worth the fuss: Heidelberg was really nice, and after a short walk I had one of the best “Schweinaxe” (spelling?) I can remember. It took us a while to get back to Stuttgart, and eventually I got lost trying to find the hotel, but it has been a great day to remember overall.

It’s now time to get back to the conference with the usual setup going on: enjoy conference, use the wi-fi network, hunt power plugs to recharge your batteries, meet great people and so on. More on this later…

A few notes to self to learn from my own mistakes and avoid spending endless hours next time trying to clean things up when you’re close to production. Some of these rules are of course already part of our internal Cocoon development process, but I thought I could share them online and see if someone has better approaches to suggest to a few simple but cumbersome issues when starting a Cocoon-based project:

• Don’t even start any development before customizing the Cocoon environment for the project needs. This boils down to “cut the crap”: be ruthless in excluding blocks, don’t enable any of them “just in case”. Unnecessary stuff will clutter at best and bite you at random times in most cases. Do version-control your local.build.properties and local.blocks.properties.
• Using Cocoon’s xconf tool, have a set of files ready to further edit the Cocoon configurations, cutting even more crap. The block system still has some quirks, and you end up with unnecessary stuff such as JMS or XSP when you don’t need it and really don’t want it around.
• Always take relocability of your Cocoon application into account, from the very beginning of your project. Your application should work from the webapp root (mounted as /), under a context path (/whatever) or as a sub-sitemap (/whatever/the/user/wants). This means that you should always pass a “mount-point” attribute within your rendering pipelines and components, calculating where your application has been mounted, and building paths accordingly. Unfortunately the current Cocoon API will only tell you the full request path and the URI handled by the sitemap, so you need to mangle those data by substracting (string-wise) the sitemap URI from the request URI in order to obtain the path you’re looking for. That is, if your sitemap is mounted on /context/foo and your request is for /context/foo/bar/baz, the sitemap URI will be bar/baz, while the data you need is actually /context/foo to build your links properly: yeah, that gives me headaches as well, and I have an overdue patch to provide this location in an easier way. But please tell me if I’m just missing an obvious solution.
• Don’t ever rely on Cocoon samples for functionality. If you need any feature such as XSLTs, JS files or sitemaps, import it into your project right away. Do it now, or you will regret it in the future. A lot.
• The above note has a special meaning for form handling. The impressive and powerful Cocoon Forms resources are part of the samples. Since you probably want to reuse them, to avoid any temptation, just package everything up in a JAR file and use resource://whatever as your $resources-uri parameter in your forms stylesheets. the following Ant task might come handy:

   <target name="pack-cforms-resources" depends="jar"
      description="package all the CForms resources">
      <jar jarfile="${dist.dir}/cocoon-forms-block-resources.jar"
         basedir="${cocoon.home}/src/blocks/forms/samples">
          <include name="resources/**"/>
          <exclude name="**/.svn"/>
      </jar>
   </target>

and, later on:

      <map:transform type="forms"/>
      <map:transform
          src="resource://resources/forms-samples-styling.xsl">
        <map: parameter name="resources-uri"
          value="resource://resources"/>
      </map:transform>

• Keep a very strict separation between application files and resources that a user might want to customize. This is expecially true for stylesheets and client-side javascripts/images/icons. Consider using the xsl:import feature in your stylesheets, providing an empty user-oriented version of your stylesheets, where templates can be overridden. Might hurt performance a bit, but sure helps tremendously for real life scenarios, where your customer is supposed to customise files and you’re supposed to provide updated versions of your applications. If you don’t, every deployment after the first one becomes an incredibly painful process.
• Ideally, package the whole application as a jar file: remember that Cocoon can easily access jar-packaged resources with the resource: protocol, and this holds true even for that overrideable XSLT who can import from your jar files. You can even package your root sitemap inside a jar and reference it with the resource:// protocol.
• Don’t forget error and logging management. There is nothing worse that the default Cocoon error page popping up in front of your customers, so plan for a sensible handle-errors section right from the beginning of your project. Also, don’t forget to customise your logkit.xconf file. These resources can be easily part of a shared project codebase, so there is no excuse for preparing them in advance.

I’ve been coding again lately. Boy, that feels good for a change, after a lot of time spent doing project management, offerings, backoffice and a LOT of travel. Sure, you earn free miles for vacation flights, but what’s the point when you don’t have any time off?

Anyway, back to coding: I’ve been using Cocoon again and I’m amazed at how far it went, how incredibly powerful CForms + continuations are, and how easy is to build a seemingly complex app with very few lines of code: I have sitting on my hard disk a full-fledged web file manager with inline XHTML editing, with full internationalization and skin support. with this little thingy you can manage almost everything: a local file system or a remote FTP/WebDAV server (we’re using it as a Subversion frontend). All this fits into less than 150K of overall code, and could definitely use more optimization. We’re using it as a poor man’s CMS and fits the job quite nicely. And yes, as soon as I manage to polish it a bit better, it will be Open Sourced. Hey, glad you asked!

There is quite a bit of room for optimization in Cocoon though, especially with regard to ease of configuration and deployment. There are very promising work in progress (Sylvain and Carsten rock!) about better componentization and modular configuration, but this is really, and badly, needed. It’s incredibly and overly painful to come up with a nice setup to integrate, deploy and distribute an application inside Cocoon. At best, there is a royal PITA in managing patch files for configuration, copying resources and libraries all around the place and figuring out the best way to make an application really portable (where “portable” to me means that it can be mounted anywhere inside a Cocoon installation: Application “foo” should work as /, /foo, /bar/foo and so on).

Howerer, no pain no gain, and using Cocoon indeed pays off in the end: big time. And I hope to have some time this year to help in this area.

(now, if only the Slide folks had not badly broken their client library I would be a much happier man…)