Return-Path: 
 <dev-return-59726-apmail-cocoon-dev-archive=cocoon.apache.org@cocoon.apache.org>
Delivered-To: apmail-cocoon-dev-archive@www.apache.org
Received: (qmail 26995 invoked from network); 20 Apr 2004 10:17:21 -0000
Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12)
  by minotaur-2.apache.org with SMTP; 20 Apr 2004 10:17:21 -0000
Received: (qmail 55678 invoked by uid 500); 20 Apr 2004 10:16:50 -0000
Delivered-To: apmail-cocoon-dev-archive@cocoon.apache.org
Received: (qmail 55652 invoked by uid 500); 20 Apr 2004 10:16:49 -0000
Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:dev-help@cocoon.apache.org>
list-unsubscribe: <mailto:dev-unsubscribe@cocoon.apache.org>
list-post: <mailto:dev@cocoon.apache.org>
Reply-To: dev@cocoon.apache.org
Delivered-To: mailing list dev@cocoon.apache.org
Received: (qmail 55634 invoked from network); 20 Apr 2004 10:16:49 -0000
Received: from unknown (HELO smtp.nada.kth.se) (130.237.222.202)
  by daedalus.apache.org with SMTP; 20 Apr 2004 10:16:49 -0000
Received: from nada.kth.se (cvap80.nada.kth.se [130.237.218.93])
	(authenticated bits=0)
	by smtp.nada.kth.se (8.12.10/8.12.1) with ESMTP id i3KAH24c011766
	(version=TLSv1/SSLv3 cipher=RC4-MD5 bits=128 verify=NO)
	for <dev@cocoon.apache.org>; Tue, 20 Apr 2004 12:17:02 +0200 (MEST)
Message-ID: <4084F89E.2050305@nada.kth.se>
Date: Tue, 20 Apr 2004 12:17:02 +0200
From: Daniel Fagerstrom <danielf@nada.kth.se>
User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.2.1) Gecko/20030225
X-Accept-Language: sv, en-us
MIME-Version: 1.0
To: dev@cocoon.apache.org
Subject: Re: [RT] Use of flowscript or the pyramid of contracts  (was Re:
 [RT] Checked exceptions considered harmful)
References: 
 <1E0CC447E59C974CA5C7160D2A2854EC097DF1@SJMEMXMB04.stjude.sjcrh.local>
In-Reply-To: 
 <1E0CC447E59C974CA5C7160D2A2854EC097DF1@SJMEMXMB04.stjude.sjcrh.local>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

Hunsberger, Peter wrote:

>Daniel Fagerstrom <danielf@nada.kth.se> writes:
>
><snip/>
>
>  
>
>>I believe OTH that some of the "simpler" input modules, 
>>especially the 
>>request module, the request attribute module and the flow attribute 
>>module, makes it possible to have a *cleaner* SOC, than it is 
>>possible 
>>without them. Let me give a simple example:
>>
>><match pattern="table.html">
>>   <generate src="table.xml"/>
>>   <transform src="table2html.xsl">
>>     <parameter name="sortOrder" value="{request-param:sortOrder}"/>
>>   </transform>
>>   <serialize>
>></match>
>>
>>    
>>
>
><snip/>
>  
>
>>I fail to see that:
>>
>><flow language="javascript">
>>   <script src="sortOrder.js"/>
>></flow>
>>
>><match pattern="table.html">
>>   <call function="getSortOrder"/>
>></match>
>>
>><match pattern="table-view">
>>   <generate src="table.xml"/>
>>   <transform src="table2html.xsl">
>>     <parameter name="sortOrder" value="{flow-attribute:sortOrder}"/>
>>   </transform>
>>   <serialize>
>></match>
>>
>>sortOrder.js:
>>
>>function getSortOrder() {
>>   sendPage("table-view",
>>            {"sortOrder": cocoon.request.attibute.sortOrder}
>>}
>>
>>would be an improvement in clearity compared to using input modules, 
>>    
>>
>
>Ok, but what I think you are partly missing is the level of generic
>sitemap that flow can allows.  Instead it becomes something more like:
>
> <flow language="javascript">
>    <script src="controller.js"/>
> </flow>
> 
> <map:match pattern="*.html">
>    <map:call function="main">
>	<map:parameter name="p1" value="{1}"/>
>    </map:call>
> </map:match>
> 
> <match pattern="_page.*">
>    <generate src="{1}.xml"/>
>    <transform src="page2html.xsl"/>
>    <serialize>
> </match>
>
>controller.js:
>
> function main( page ){
>	var func = this[ page ];
>      var args = new Array( page );
>      if ( func != undefined )
>      {
>          func.apply( this, args );
>      }
>      else
>	    sendPage( "_page.+page );
> }
>
> function table( page ) {
>    sendPage("_page."+ page,
>             {"sortOrder": cocoon.request.attibute.sortOrder}
> }
>
So, lets see, I started with a 7 line sitemap snippet, where most Cocoon 
users should be able to understand at a course level what is going on 
after short look at it. Then I proposed that the flowscript version 
where you have to look at two files at once for seeing what is going on 
is more complicated to grasp. And now you propose that it would have 
been better to write something that abstracts away about everything that 
was concrete and easy to grasp about the first example.

Let me discuss a little bit about abstractions. First I also have a CS 
background and I love abstractions. But some of my coworkers whithout 
such background are less than happy when they try to support apps that I 
have written, where I excess in abstractions. And to be honest, 
sometimes when I go back to old apps that I have written I am less happy 
whith the use of abstractions my self, it often takes much longer to 
understand whats going on. So my coding style has become less abstract 
when it once was.

Some rule of thumb that I use is: don't abstract anything before you 
have at least three examples of it. Here refactoring style programming 
has helped me a lot. Start simple and _if_ common concepts appears 
factor out them, don't try to do that upfront. When writing sitemaps I 
try to make them be a map of the site rather than a collection of 
abstracted access patterns.

I think you have to do some kind of cost/benefit analysis before you 
introduce an abstraction. How long time will it take to develop, how 
long time will it take to understand for your coworkers, and for 
yourself when you return to the code after a year. And how much time 
will it save. I would guess that the "cost" for your sitemap and 
flowcript snippet would be at least a order of magnitude higher than for 
the first one, (this is of course highly dependent on what design 
patterns that you currently use, background and so on). So you would 
need a lot of regularity in your app before it is worthwhile.

There is one kind of abstraction that we can call "leaky abstraction" 
that IMO is especially expensive, and unfortionlly the easisest ones to 
come upp with. Leaky abstractions are such abstractions where the 
deatils from the layer beneath, leaks through so that you have to 
understand booth levels at once. While good abstractions are so well 
thought out concepts so that you don't need to now anything about the 
layer underneath.

>(I believe making the generic XSLT processor handle the flow generated
>parameters directly wouldn't be that hard?
>

Not hard at all, before the arive of input modules we maintained an own 
fork of the xslt transformer that got some extra stuff as input to the 
xslt params.
 

>  In our case, we just have a
>whole patch of common parameters we always pass in the sitemap, subbing
>them in via an action, but that's more-or-less the same thing as using a
>module to get at them...)
>
Sure, you can do that, but you either have to turn of caching or make 
the cache key depend on a lot of stuff that it shouldn't depend on. Also 
after having started to feed my xslt with params explicitly through 
input-modules in the sitemap to get better cache control I also, as a 
side effect, find it easier to understand what my apps do from looking 
at the sitemap.

Request attributes are often parts of the urls and because of that a 
part of the sitemaps concern area. Also flow attributes are part of the 
contract between the sitemap and flow scripts, so in many cases it, 
IMHO, increase readability if you are explicit about what flowscript 
attributes a sitemap rule depends on.

>If you're site map shrinks down to almost nothing, and all the logic on
>what page is being called is in the flow script, doesn't that add
>clarity?  In your example, you're still using the sitemap to determine
>page flow...
>  
>
IMO, the sitemap contains excelent abstractions for describing one page 
"page flows", as long as you don't require to much input handling, (and 
as some readers might remember, I have some ideas about how to improve 
the sitemap abilities in that area as well ;) ).

And flowscrips are a good abstraction of multipage flow. IMO it does not 
increase readability to put absttractions of one page access patterns, 
this is of course a matter of taste.

/Daniel