forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [RT] plugin infrastructure
Date Wed, 03 Nov 2004 14:00:55 GMT
Nicola Ken Barozzi wrote:
> 
> We have now a basic plugin system, but as Ross has shown, it's not 
> enough in practice. We have to define the points where the plugins can 
> hook into the existing system and extend it.
> 
> Before going wild into defining possible scenarios, I have to understand 
> better the reason why the current system is not enough and where we will 
> need to extend the system.
> 
> Do we need plugin dependencies?

To date I have not found a compelling reason to allow such things. So 
far I have managed to do everything I need to with the values available 
from core (i.e. {forrest:*} and {project:*}). My guts tell me that it 
will be a necessity one day - but if we can avoid it all the better.

> How are they resolved?

Assuming that we will need them then I would propose using a similar 
extension mechanism to that used in Eclipse. Each plugin can define 
"extension points" which allow values to be retrieved or functionality 
hooks to be added, I have not fully considered how to do this...

> Where do we need to plug in?

To date I have identified the need for three types of plugin:

- infrastructure format (i.e. generation of tabs.xml and site.xml from 
IMSManifest.xml or the auto site-building features in Issue tracker)

- source format (i.e. generation of internal XML format from external 
format, e.g. OpenOffice.org, docbook etc.)

- output format (i.e. generation of slides from our intermediate format)

Thorsten's recent RT about Skin plugins may have identified a fourth 
type of plugin, part of this RT is covered by the output plugins above, 
but other parts are not.

Other use cases may identify more plugin types.

> Do we have to enhance existing transformations or replace them?

No problems to date it is simply a case of finding the right mount point 
for each type of plugin. I believe I have now found this points for the 
above plugin types, see http://issues.cocoondev.org/browse/FOR-344 of 
course, more testing with a wider range of plugins is required.

> Why is the current system not working?

It is, but with hack solutions, see FOR-344 - linked above, and my 
proposal below this explanation.

The problem with the original implementation was that the plugin sitemap 
was being mounted before any matches were made by Forrest, as a result 
if a plugin wanted to match all **.xml files it prevented forrest 
specialist matchers for things like faq.xml or site.xml.

The solution was to move the plugin sitemap mount so that it came after 
these specialist matcher but before Forrests default **.xml matcher. 
This worked fine for the source format plugins, but prevented the 
IMSManifest plugin from working since it needs to match the site.xml and 
tabs.xml requests. This plugin is an example of an "infrastructure" plugin.

The solution to this was to mount the IMSManifest plugins sitemap before 
the forrest matchers for site.xml and tabs.xml. As a result the 
IMSManifest plugin has to copy the replaced matchers from Forrest (i.e. 
site.xml and tabs.xml behaviour). However, this latter requirement can 
be removed once we remove the permanent mount of this plugins sitemap 
since the plugin system no builds the plugin mounts dynamically on each 
run, that is if a site indicates it does not use the IMSManifest plugin, 
  it will not be mounted and therefore will not override the default 
Forrest behaviour.

The next plugin I implemented was the s5 slideshow plugin. This 
generates a new output format (XHTML slide presentation). This cannot be 
mounted in the same location as the source formats since those plugins 
are mounted in forrest.xmap, which, in turn, is mounted on a **.xml 
match. Since output formats will be **.html, **.pdf, **.pod etc. they 
need to be mounted from sitemap.xmap, before any Forrest specific matches.

My Proposal
===========

Each plugin should be able to provide three sitemaps rather than the 
current 1.

- sitemap.xmap - this provides the infrastructure matchers (i.e. 
site.xml, faq.xml, issues.xml), as such it will be mounted before *any* 
of the Forrest matches. This sitemap can override any behaviour within 
Forrest)

- source.xmap - this provides the source matchers (i.e. **.xml), it is 
mounted in forrest.xmap before the default forrest **.xml behaviour and 
therefore can override that default behaviour but it will not interfere 
with any internal Forrest infrastructure matches, or any other plugins 
infrastructure matches.

- output.xmap - this provides (surprise!) the output matchers (i.e. 
**.html, **.pdf, **.slides), it is mounted before any of the default 
matchers for Forrest and so can override this default behaviour

Ideally, each plugin should only provide one of these three sitemaps. I 
believe this will help us to define a sensible granularity for the 
plugins. However, further exploration of use cases may show otherwise 
and therefore we should make it legal (but not encouraged) to implement 
more than one of them.


Avoiding Plugin Conflicts
-------------------------

Clashes between plugins can occur. For example, the simplified-docbook 
and full docbook plugins may try and process the same files. In this 
instance the one that is mounted first will take precedence. Plugins are 
mounted in the order they appear in the project.required.plugins 
property, therefore the mounting order and therefore processing 
precedence is under user control.

Remaining problems
------------------

The mount point of the "infrastructure" plugins means that plugins of 
this type can prevent Forrest from behaving correctly. These types of 
plugins should be considered "advanced" and authors must be very careful 
when building them - note the same is true for the existing mount point 
of the project sitemap - perhaps we should consider using the same 
design for project extensions as we use for plugin extensions (a whole 
new RT I think)

http://issues.cocoondev.org/browse/FOR-341 - Plugin resources are not 
copied to site - in order to fix this problem I believe each plugin 
should implement a site-build.xml file that provides a target for 
copying any required resources into the built site. This is not 
necessary when running dynamically.

Thoughts?

Mime
View raw message