This document attempts to answer the common questins asked by people familiar with Forrest 1 and trying to understand Forrest 2.

Where are the *.xmap files?

There aren't any.

Forrest 2 does not use Cocoon as its underlying framework and so we have been able to do away with our sitemaps.

So where is the processing pipeline define?

In Forrest 1 the processing pipeline was defined in the cocoon sitemap files. The sitemap language is very powerful, but it is also very confusing for newcomers. Forrest 2 recognises that since Forrest is an XML publishing framework all it needs to do is read an input (or set of inputs), convert them to the Forrest internal format and then process them using relevant output documents. To do this we do not need the complexities of the sitemap.

The processing pipeline of Forrest 2 is defined in forrestContext.xml. Briefly:

All pipelines are, essentially, a Reader -> an Input Plugin -> an Output Plugin. This is anologous to Generator -> Transformaer -> Serliazer in Cocoon sitemaps.

The reader provides the source document, the input plugin converts it into a document Forrest can work with internally, and the output Plugin produces the required output document.

A client makes a query, such as "http://foo.org/bar.html". This is mapped to a source document URI using the locationmap (this process is almost identical to that in Forrest 1). This URI will look something like "file:foo/bar.xml" or "http://remote.foo.org/bar.xml".

Once we have this source URI we can select a reader to retrieve the document. Readers are selected based on the protocol in the source URI. The protocol corresponds to the bean id in forrestContext.xml.

So a source of "file://foo/bar.xml" will use the reader identified by <bean id="file"...> in forrestcontext.xml. Similarly, "http://remote.foo.org/bar.xml" will use the reader identified by <bean id="http"...>.

The reader produces a document encapsulated in a class that exposes a getType() method. The return value of this method is used to select the input plugin to use. Again selected on the bean id in forrestContext.xml

Now we have the input plugin we need to get the output plugin. This is selected slightly differently, because each output plugin may be used for many request URI's. For example, both "html" and "htm" extensions may indicate that an HTML document is required.

In order to select the output plugin each plugin bean defines a "pattern" property. This property is a Regular Expresion that is used to match against the original client request URI. The first output plugin that is discovered is the one that is used.

So now we have all of our pipeline compoenents and processing can proceed.