Upgrading to Apache Forrest 0.9-dev

This page describes some changes to Apache Forrest that affect people who are upgrading to the 0.9 version. If you have other issues, then please discuss on either the dev or user mailing lists. As more experience is gained, this document will be updated.

(If you are upgrading from a version prior to 0.8 then you will need to see the notes for the previous upgrade.)

The following list shows some of the key new features. For the full list of changes, see the main change log and also for each plugin.

• Our packaged Apache Cocoon is upgraded, along with various other important supporting products such as Apache Xerces and Apache Xalan, etc.
• [Placeholder]

Some new initial plugins are in the "whiteboard". See the entries in the change log and see each plugin's documentation and changes log. This includes the new Dispatcher. See Status of Themes: Skins and Dispatcher.

Our packaged version of Apache Cocoon has been upgraded to use the latest version of their stable 2.1 branch. This is a major step forward for Forrest. It enables us to use a reliable and up-to-date Cocoon. Forrest developers can again participate at Cocoon to fix issues or develop new blocks. A number of major performance issues are already fixed in this version.

In previous versions of Forrest we were using a development version of Cocoon trunk (i.e. 2.2). A number of things happened which caused us to fall out of synchronisation with Cocoon. They started using Maven as a build system, which took a long time to settle down. In turn that meant that Apache Gump could not perform continuous integration, which shut Forrest off. At the same time Cocoon trunk was making technical advances which changed some of the ways that Forrest interacts with Cocoon. In particular the command-line interface which Forrest uses to build a complete static site. See other notes via FOR-1017.

Cocoon-2.1 is closer to our stalled version of Cocoon-2.2 than the current head of Cocoon-2.2 trunk.

Note that this move does not preclude us from future updates to other versions of Cocoon or even to another xml processing framework.

If you want to use your own version of Cocoon-2.1, for example to add another Cocoon Block or to enhance a particular existing block, then see the notes in the $FORREST_HOME/etc/cocoon_upgrade directory.

Cocoon upgrade issues

There are only two minor issues for those upgrading from the previous version of Forrest:

When you first use this in your existing projects, there will probably be a message about a certain cache item. On the second run all is well. A way to avoid that would be to do 'forrest clean-work' in each of your projects to remove the old Cocoon cache.

The configuration file is now at main/webapp/WEB-INF/cocoon.xconf

Our previous version of Cocoon had a facility called "Running modes" which enabled one set of a minimal group of properties for development and a different set for production. This is not available in Cocoon-2.1 version. If you were using this feature, then simply move your defined properties into the main/webapp/WEB-INF/properties/core.properties file.

Users of 0.8, and developers with older 0.9-dev, who based their sites on 'forrest seed-basic' rather than 'forrest seed-sample' will be affected by FOR-1075. There was a partially implemented xml catalog with missing symbols file.

You would get the message:

Failed to create InputSource (java.io.FileNotFoundException:
.../src/documentation/resources/schema/symbols-project-v10.ent
(No such file or directory)...

This is just a warning message from the misconfigured xml entity catalog. To silence it, simply copy the file from a new "seed-basic" site, or more directly by cp $FORREST_HOME/main/fresh-site/src/documentation/resources/schema/symbols-project-v10.ent $PROJECT/src/documentation/resources/schema/symbols-project-v10.ent

This "project symbols" ability using xml entities is useful in two ways. To provide common symbols, words, and phrases, in your source documents (added in v0.8 - FAQ). To configure some Cocoon sitemap components (added in v0.9 - FAQ).

After each release, the "Versioned Docs" are copied to form the new "dev" set. Ideally the docs are then upgraded in readiness for the new release. This has not been completed for recent releases. In particular there are example snippets of sitemaps which have not yet been upgraded to reflect the changes to the sitemaps and the separation of some core stuff into plugins. See issues FOR-546 and FOR-922 and others.

Synchronise your project's skinconf.xml and forrest.properties files.

Take advantage of the separation of concerns. In a new workspace, create a fresh 'forrest seed' site, then tweak its forrest.properties and skinconf.xml until it reflects your old site. When it is ready, replace your project's skinconf.xml and forrest.properties files. Any remaining issues would concern other aspects of your configuration, such as site.xml and your actual content.

It has come to our attention that some people have a project sitemap even though they are not using it. Such un-necessary sitemaps should be removed to avoid maintenance issues.

If you do use a project sitemap, then pay attention to the 0.8 upgrade instructions "Forrest configuration simplification".

...as more issues are discovered/remembered :) Please send feedback to the mailing list.