cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Giacomo Pati <giac...@apache.org>
Subject Re: [C2] Actions Purpose and Use
Date Sun, 11 Feb 2001 14:16:21 GMT
Berin Loritsch wrote:
> I am at a point where I need to create some actions for
> a working prototype, unfortunately the documentation on
> Actions is virtually non-existent.
>
> If the folks who are familiar with it can help me sort
> through the details, I can create some documentation for
> using Actions in Cocoon.

Thats a deal :)

I'll supply all information you'll need (because I'm the one
who had impemented the action stuff into the sietmap).

>
> JavaDoc Discrepancies
> ---------------------
>
> There are discrepancies in the the JavaDocs, so I need
> to sort them out.
>
> Action.act returns a Map, However the JavaDocs state:
>
> "Returns:
>   "List  The returned List object with sitemap substitution
>    values which can be used in subsequent elements attributes
>    like src= using an xpath expression: src='mydir/{1}/foo'
>    If the return value is null the processing inside the
>    element will be skipped."

This one got forgotten when we switched from List to Map as the
return type for Actions and Matchers. 

> An example in the JavaDocs Comment (needs to be moved)
> in LangSelect states you can do the following:
>
> <map:actions>
>   <map:action name="lang_select"
>    src="org.apache.cocoon.acting.LangSelect"/>
> </map:actions>
>
> <map:match pattern="file">
>   <map:act type="lang_select">
>     <map:generate src="file_{1}.xml"/>
>   </map:act>
>   <map:serialize/>
> </map:match>
>
> In the LangSelect class, we return a Map with one
> value: Map.put("lang", {result});
>
> Issue: Maps do not preserve order, so if you have more
>        than one parameter then you cannot be assured
>        that the proper one is first.

Absolutetly correct.

> Assumption: The JavaDocs are wrong, and the action works
>             like this:
>
> <map:actions>
>   <map:action name="lang_select"
>    src="org.apache.cocoon.acting.LangSelect"/>
> </map:actions>
>
> <map:match pattern="file">
>   <map:act type="lang_select">
>     <map:generate src="file_{lang}.xml"/>
>   </map:act>
>   <map:serialize/>
> </map:match>
>
> (Please note that instead of src="file_{1}" it is
>  src="file_{lang}").

Your assumption is correct. When the move from List to Map was taken all
values in the {} are names now and not positions.

> Also, The xxxEmployeeAction objects do not return
> Maps, so anything internal gets skipped.

Yes, because they don't have anything to tell to the sitemap :)

> Configurations
> --------------
>
> I know that Actions can be configured like:
>
> <map:actions>
>   <map:action name="foo" src="com.infoplanning.customer.MyAction">
>     <my-conf name="Foo"/>
>     <use-connection name="akbar"/>
>   </map:action>
> </map:action>
>
> However, sometimes I want to specify runtime configurations,
> effectively using the same object for multiple cases.  I noticed
> that the Action gets passed a Parameters object.  Does that mean
> if I wanted runtime configurations I would be able to do this?:
>
> <map:match>
>   <map:act type="foo">
>     <parameter name="override" value="myval"/>
>
>     <map:generate src="file_{bar}.xml"/>
>   </map:act>
> </map:match>

I hope I've written the sitemap.xsl to achieve this. It should be
parametrizable as you assumed. 

> Last configuration question: Assuming the above is true, would
> I be able to do the following?:
>
> <map:match>
>   <map:act type="foo">
>     <map:act type="{baz}">

No. Values of type attributes are not replaced that way (so far).

>       <parameter name="override" value="demo"/>
>
>       <map:generate src="file_{bar}.xml"/>
>     </map:act>
>   </map:act>
> </map:match>
>
> Lastly, Action Sets
> -------------------
> In the demonstration webapp that comes with Cocoon, we use an
> Action Set.
>
> How do these work?  How does the Action Set know whether to
> Add, Update, or Delete employees?

You can arrage actions in an action set. The sitemap calls the
act method of those actions in the sequence they are defined in the 
action set. It is possible to signal to the sitemap to
call an antion only if the Environments getAction method returns
a String identical to the value supplied with an action attribute.
In the current implementation of the HttpEnvironment the value 
returned by the getAction methos is determined by a http parameter 
called "cocoon-action". So far let's have a look at at possible 
action set definition:

 <map:action-sets>
  <map:action-set name="shop-actions">
   <map:act type="session-invalidator"  action="logoff"/>
   <map:act type="session-validator"/>
   <map:act type="cart-add"             action="addItem"/>
   <map:act type="cart-remove"          action="removeItem"/>
   <map:act type="cart-remove-all"      action="removeAll"/>
   <map:act type="cart-update"          action="updateQty"/>
   <map:act type="order-add"            action="addOrder"/>
   <map:act type="order-verify"         action="verifyOrder"/>
   <map:act type="screen-navigator"     src="{1}"/>
  </map:action-set>
 </map:action-sets>

And this is a possible pipeline snipped which uses this action set:

   <map:match pattern="*">
    <map:act set="my-actions">     <--- HERE
     <map:generate  type="serverpages" src="docs/xsp/{nextpage}.xsp"/>
     <map:transform src="stylesheets/page2html.xsl"/>
     <map:serialize type="html"/>
    </map:act>
   </map:match>

Let me explain some of those actions in the set first. 

The "session-invalidator" action gets called when an action of logoff is
requested (ie. a html submit button named "cocoon-action" with the 
value "logoff" was pressed). 

The "session-validator" action is called on every request. It assures that
an http session is created and available to the other sitemap components
(other actions and xsp pages selected for resource production).

The other actions in the set with an action attribute do specific things
like adding an item to the cart, removing one or all items from the cart
etc. They are called depending on the value returned by the getAction method
of the HttpEnvironment object passed to the sitemap engine as described 
above ( see "session-invalidator" action).

The screen-navigation action is always called because it has knowledge 
about the flow/sequence of pages and it knows how/where the preceding actions
stores their execution status (ie. as an request attribute). Depending on those
stati the screen-navigation action sets up a Map with an element called 
"nextpage" with the value of the page that produces the next "view".

However, one is not limited to specify distinct values at the action attribute.
It is possible and I think usefull to mark several actions with the same
action attribute value which will then be called in sequence. This allows you
to choose a granularity of your actions at will.

Let me know if you could follow my explanations. If not, please don't hesitate
to ask again.

I think there are still some flaws in the concept of actions which I haven't
solved so far because it would pollute the sitemap with additional semantics
that I'd like to keep at the minimum and thus have to be well designed. 

First there was a question if one can parametrize the hole action-set like:

   <map:act set="my-set">
     <parameter name="foo" value="bar"/>
     ...
   </map:act>

I have no idea so far how this should work. Logically all actions should get
the parameters expressed above but given the fact that you can do the 
following:
 
   <map:action-set name="my-set">
     <map:act type="action1">
       <parameter name="foobar" value="baz"/>
     </map:act>
     <map:act type="action1">
       <parameter name="color" value="white"/>
     </map:act>
     <map:act type="action2"/>
   </map:action-set>

doesn't makees it easy how to define preceedin one over the othe methos of
parametrizing actions.

Also, there is no way to use Exceptions to communicate with the sitemap 
engine and thus you have to specify your own "protocol" how your actions
communicate to each other if they need (we solved this by using the http 
request, session and context object passed to the action in the objectModel 
Map.

Also, the granularity of actions is much lower than those of normal sitemap 
components and their degree of reusability is *much* lower across resource 
generation.... almost non. I've also thought that we have *one* 
"sitemap extender" (it could well be a Matcher) which has a richer 
syntax to define how to use and call those lower level actions would be a 
better approach thn the one we have today with the actions.

Every idea is still welcome but keep in mind that extending the sitemaps
semantic is a thing I'll not be very happy about. You have to convince me 
it is *absolutely* necessary :)

Cheers

Giacomo


Mime
View raw message