cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [Ann/RFC] Virtual Sitemap Components
Date Mon, 11 Apr 2005 16:06:44 GMT
Daniel Fagerstrom wrote:
> I have continued Vadim's and Sylvain's work and added a first, hopefully 
> working version of virtual sitemap components (VPCs) to the trunk.

Awesome!!!

You (and Vadim) rock!

I'm a happy camper.

> 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>

virtual readers? hmmmm, never thought of that one. What does that buy 
you? I mean, it's not harmful to have it, but do you see any real use of 
that?

>     <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.

and in the future, they will be accessible from the blocks that are 
wired to them.

> 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.

Ok, makes sense.

>                 --- 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.

I think that having a src="" attribute in a VPC is YAGNI: do you really 
see yourself using different implementations of the internal wiring of a 
virtual component? If so, it's probably a configuration parameter for 
the tree processor than something you want to use there.

So, my proposal is to keep the above semantics, but differentiate 
between 'real' and 'virtual' pipeline components, with the existance of 
the src="" attribute. If missing, the tree processor will consider it a 
virtual one and construct it from there.

> 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?

Can't say much about the implementation details, but well, thanks so 
much for you effort on this, it is a huge step forward!

-- 
Stefano.


Mime
View raw message