cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Fagerstrom <dani...@nada.kth.se>
Subject [Ann/RFC] Virtual Sitemap Components
Date Sun, 10 Apr 2005 21:06:28 GMT
I have continued Vadim's and Sylvain's work and added a first, hopefully 
working version of virtual sitemap components (VPCs) to the trunk.

Use
===

To use VPCs one define them in the components section in the sitemap, e.g.:

   <map:components>
     <map:readers>
       <map:reader name="virtual1" 
src="org.apache.cocoon.reading.VirtualPipelineReader">
         <map:generate type="file" src="vpc-test.xml"/>
         <map:serialize type="xml"/>
       </map:reader>
     </map:readers>

     <map:transformers default="xslt">
       <map:transformer name="virtual2" 
src="org.apache.cocoon.transformation.VirtualPipelineTransformer">
         <map:source param="src2"/>
         <map:transform src="vpc-include.xsl">
            <map:parameter name="file" value="{src}"/>
         </map:transform>
         <map:transform src="vpc-include.xsl">
            <map:parameter name="file" value="{src2}"/>
         </map:transform>
       </map:transformer>
     </map:transformers>
   </map:components>

then they can be used as any component:

   <map:read type="virtual1"/>

   <map:transform type="virtual2" src="vpc-test.xml">
     <map:parameter name="src2" value="vpc-test2.xml"/>
   </map:transform>

in the sitemap where they are defined and in all its subsitemaps.

One of the complicated things with VPCs was how and where to resolve 
sources that are given to VPCs. I followed Sylvain's aproach in 
http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=110064557022481&w=2 
modified with my ideas 
(http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=110539791029866&w=2) 
about how to increase the level of isolation between the caller and the 
callee. This will be needed when we use them from "real" blocks.

To use a source as a parameter one have to declare it with

   <map:source param="src2"/>

in the definition. The "src" is always supposed to be a source. Sources 
are alwas resolved in the calling sitemap.

                 --- o0o ---

More examples of use can be found in the sitemaps for the test cases in 
src/test/org/apache/cocoon/[generation|transformation|serialization|reading].

I didn't research old mails about VPCs about what things are supposed to 
be called. So suggestions about better names and syntax are welcome.

VPCs are not cacheable yet. Its probably not that hard to add caching, 
but it requires that we extend the ProcessingPipeline interface with 
some methods that are needed for VPCs. It also requires that we find 
some syntax for declaring what pipeline type that should be used for a 
specific VPC.

Implementation
==============

In the rest of the mail I will give an overview of the implementation. 
The VPCs is rather complicated, so I would appriciate if people could 
spend some thought and testing on them so we can be sure that they are 
correct.

TreeProcessor
-------------

In the TreeProcessor the VPCs are handled by: ComponentsNodeBuilder, 
VPCsNodeBuilder, VPCNodeBuilder, VPCNode and some definitions in 
sitemap-language.xml.

In the TreeProcessor the VPC definitions are recognized in the 
components section in the sitemap, the source parameters are parsed and 
a partial pipeline node is constructed and put in the Avalon context so 
that it can be found by sitemap components during setup (see Sylvain's 
mail for details).

VPCs
----

All sitemap components have 
o.a.c.sitemap.impl.AbstractVirtualSitemapComponent as base class. Its 
main tasks are to find and setup its partial pipeline from the Avalon 
context and taking care of parameters. It also extends AbstractXMLPipe 
which only is used for the transformer and serializer, but I didn't feel 
like creating several versions (its a fun exercise for one of those who 
think that single inheritance is a feature rather than a nuisance ;) ).

The parameters that are declared as sources are resolved in the 
environment of the calling sitemap the they are put in a map in the 
environment that the VPC pipeline will be executed in (which is based on 
the pipeline where it was defined). The source URI in the caller is 
substituted with an xmodule or module URI that fetches the resolved 
source from the environment (more details can be found in my post cited 
above).

The AbstractVirtualSitemapComponent also sets up two environments, 
mappedSourceEnvironment that is an extension of the callers environment 
with the map with resolved sources and vpcEnvironment which is an 
extension of the previous environment with context URI and prefix from 
the sitemap where the VPC is defined.

The vpcEnvironment is used during creation of the partial pipeline from 
the pipeline node and during preparation of the pipeline. The 
mappedSourceEnvironment is used during execution of the pipeline.

Environment
-----------

One of the main tasks in the respective VPCs: VirtualPipelineGenerator, 
VirtualPipelineTransformer, VirtualPipelineSerializer and 
VirtualPipelineReader, is to execute things in the right environment. To 
achieve this I have added methods to the internal class 
EnvironmentHelper for entering and leaving an environment and also two 
XMLConsumer adapters PushEnvironmentChanger and PopEnvironmentChanger. 
The PushEnvironmentChanger is needed to add the right environment before 
calling an event in a VirtualPipelineTransformer or 
VirtualPipelineSerializer. The PopEnvironmentChanger is used to take 
away the current environment before calling an event in the successor of 
a VirtualPipelineGenerator or VirtualPipelineTransformer, the 
environment is added after returning from the event. See 
VirtualPipelineTransformer for an example.

Pipeline
--------

Vadim added VirtualProcessingPipeline to be able to start working on 
VPCs whithout needing to touch the current pipelines. It is a scaled 
down version of AbstractProcessingPipeline i.e. a non caching pipeline. 
To be able to use it with VPCs I had to (rather obviously) make it more 
tollerant on what types of components that need to be in a pipeline.

I added the methods:

   XMLConsumer getXMLConsumer(Environment, XMLConsumer);

which is needed for VirtualPipelineTransformer,

   XMLConsumer getXMLConsumer(Environment);

which is needed for VirtualPipelineSerializer,

   String getMimeType();
   boolean shouldSetContentLength();

which are needed for VirtualPipelineSerializer and VirtualPipelineReader 
for delegating the corresponding methods in them selves.

Caching
-------

To be able to have caching in VPCs we must extend ProcessingPipeline (or 
  introduce some new interface), with the four methods above (or 
something similar). And update our pipelines so that they support VPCs 
as well.

                 --- o0o ---

Comments?

/Daniel

Mime
View raw message