Return-Path: 
 <dev-return-47902-apmail-cocoon-dev-archive=cocoon.apache.org@cocoon.apache.org>
Delivered-To: apmail-cocoon-dev-archive@www.apache.org
Received: (qmail 97101 invoked from network); 20 Sep 2003 12:33:53 -0000
Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12)
  by minotaur-2.apache.org with SMTP; 20 Sep 2003 12:33:53 -0000
Received: (qmail 1332 invoked by uid 500); 20 Sep 2003 12:33:46 -0000
Delivered-To: apmail-cocoon-dev-archive@cocoon.apache.org
Received: (qmail 1287 invoked by uid 500); 20 Sep 2003 12:33:46 -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 1274 invoked from network); 20 Sep 2003 12:33:45 -0000
Received: from unknown (HELO pulse.betaversion.org) (217.158.110.65)
  by daedalus.apache.org with SMTP; 20 Sep 2003 12:33:45 -0000
Received: (qmail 27597 invoked from network); 20 Sep 2003 12:33:44 -0000
Received: from unknown (HELO apache.org) (stefano@80.105.91.155)
  by pulse.betaversion.org with SMTP; 20 Sep 2003 12:33:44 -0000
Date: Sat, 20 Sep 2003 14:33:42 +0200
Subject: Re: [RT] Implementing Cocoon Blocks
Content-Type: text/plain; charset=US-ASCII; format=flowed
Mime-Version: 1.0 (Apple Message framework v552)
From: Stefano Mazzocchi <stefano@apache.org>
To: dev@cocoon.apache.org
Content-Transfer-Encoding: 7bit
In-Reply-To: <3F6BBCA5.70302@leverageweb.com>
Message-Id: <AB1451EA-EB66-11D7-B98A-000393D2CB02@apache.org>
X-Mailer: Apple Mail (2.552)
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


On Saturday, Sep 20, 2003, at 04:34 Europe/Rome, Geoff Howard wrote:

> Stefano Mazzocchi wrote:
>
>> On Thursday, Sep 18, 2003, at 04:51 Europe/Rome, Geoff Howard wrote:
>>> Stefano Mazzocchi wrote:
>
>>> I wasn't sure what "uses component" meant functionally.
>> the blocks declares what component is going to use from that block 
>> and will name it. This is the inverse of the cocoon.xroles file but 
>> does the same thing, providing a shorthand version of the role 
>> identifier in the context of that block.
>
> So, what does a block use from another block if not a component?

pipelines and virtual pipeline components

>  I've
> been thinking that neither file resources or classes would be 
> accessible
> directly.

yep

> So all that's left is components (either sitemap components
> or no)? (ah, source resolving through block: protocol?)

the blocks carry three things:

  1) pipelines (called via the block: protocol)
  2) avalon components (accessed via the component manager)
  3) pipeline virtual components (declared in your sitemap)

> In the example
> what does the first block (@id="cob:mycompany.com/webmail/1.3.43") use
> from cob:mycompany.com/skin aka "external-skin"?  I'd guess all that's
> left is resolving sources through the block: protocol?

yep

>   So this would
> mean there's a block:external-skin which will probably be some xsl 
> file?

no.

block:external-skin identifies the root of the URI space addressed by 
that block. You could do things like

  block:external-skin:/stylesheets/news2html.xslt

that would return a stylesheet. And so on.

>  If it's a virtual component, would this need to be declared on both
> the provider and requirer as a component?

Yes, because the virtual component doesn't have a java classname that 
can be used to uniquely identify it.

>>> For the record, I hate <dependencies> and <depends-on> and I left 
>>> them that way in the hope that they are so offensively bad that 
>>> someone will think of a better one. :)
>> Ok, let me try again:
>> <block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
>>        id="cob:mycompany.com/webmail/1.3.43">
>>   <sitemap src="/webmail.xmap"/>
>>   <requirements>
>>    <requires
>>        block="cob:mycompany.com/skin"
>>        name="external-skin"
>>    />
>>    <requires
>>        block="cob:mycompany.com/skin/2.0"
>>        name="internal-skin"
>>    />
>>    <requires
>>        block="cob.anothercompany.com/MailRepository/2.0"
>>        name="repository">
>>      <uses
>>          component="com.anothercompany.repository.Repository"
>>          name="repository"
>>      />
>>    </requires>
>>   <requirements>
>>   <parameters>
>>    <param name="user" type="string"/>
>>    <param name="password" type="hidden-string"/>
>>   </parameters>
>>  </block>
>
> Sounds good.  You snuck in type="hidden-string" by the way which 
> raises the question: what are the allowable values of type?  string, 
> integer,
> hidden-string, (basic "primitive" values) or complex values like
> "phone-number" or "ip address"?

KISS

> No need to enumerate specifics now, but
> the general concept might be good to address.  And is it extensible?

FS for now. Let's have String, Number and HiddenString. That should be 
enough, because the code should do checking at runtime anyway.

>>>>   cob:yetanothercompany.com/skins/fancy/1.2.2
>>>>     implements -> cob:mycompany.com/skin/1.2
>>>
>>> <cob xmlns="http://apache.org/cocoon/blocks/cob/1.0"
>>>      uri="cob:yetanothercompany.com/skins/fancy/1.2.2">
>>>     <implements uri="cob:mycompany.com/skin/1.2"/>
>>> </cob>
>>> do we implement a uri?
>> well, in theory, we implement the block behavior that is identified 
>> by that URI. So I would write it as
>>  <block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
>>         id="cob:yetanothercompany.com/skins/fancy/1.2.2">
>>    <implements behavior="cob:mycompany.com/skin/1.2"/>
>>  </block>
>
> Ok, but we have now at least three different attribute names describing
> the block uri/id: id, behavior, and block which may be harder to
> remember and to identify that these things go together.  I'd propose
> using only two:
> - @id to identify the definition of the unique block element
> - @block to refer to this id elsewhere. (alternatives: @behavior,
> @contract ...)

Good point. +1

> So that becomes
>     <implements block="cob:mycompany.com/skin/1.2"/>

> I'm not convinced of this, but wiki'd it that way just to try it out.
> The distinction of @behavior and @block does kind of make sense to me
> but here's a question:
>
> The implements uri and the requires uri match up based on versioning
> rules but are separate for wiring purposes from the @id.  But in the
> scenario:
>   cob:yetanothercompany.com/skins/fancy/1.2.2
>     implements -> cob:mycompany.com/skin/1.2
>
>   cob:mycompany.com/skins/corporate/34.3.345
>     implements -> cob:mycompany.com/skin/2.3
>     extends -> cob:yetanothercompany.com/skins/fancy/1.2.2
>
> Does cob:mycompany.com/skins/corporate/34.3.345 also implicitly
> implement cob:mycompany.com/skin/1.2 because it extends
> cob:yetanothercompany.com/skins/fancy/1.2.2?

Not necessarely. Since cob:mycompany.com/skin/1.2 and 
cob:mycompany.com/skin/2.3 have different major version numbers, they 
are declared to be back incompatible. It could be that 
cob:mycompany.com/skins/corporate/34.3.345, in order to be implement 
cob:mycompany.com/skin/2.3 had to overload a few URIs from 
cob:yetanothercompany.com/skins/fancy/1.2.2 whose behavior would not be 
compliant to implements -> cob:mycompany.com/skin/1.2.

For example, say cob:mycompany.com/skin/1.2 includes 
/stylesheets/news2html.xslt and /stylesheet/doc2html.xslt.

The first, by default, strips all content that doesn't belong to the 
news markup language. cob:yetanothercompany.com/skins/fancy/1.2.2 
implements this behavior.

Later, a new need is identified (for whatever reason) and the behavior 
of news2html.xslt is changed so that content in different namespaces is 
copied over. Clearly, this is a back-incompatible change and this 
required an increase of the major version number of the URI identifying 
that behavior (cob:mycompany.com/skin/2.3).

The developers of cob:mycompany.com/skins/corporate/34.3.345 decide to 
reuse doc2html.xslt (because they know that behavior is still the same) 
but need to overload news2html.xslt to provide the new behavior that 
conforms to cob:mycompany.com/skin/2.3.

As you see with this simple (yet very likely to happen) example, the 
"implements" property is not, generally, transitive.

> Also, does the fact that no component initially defining
> cob:anothercompany.com/MailRepository/2.0 exists here matter?

What do you mean?

> With this and the above questions I'm trying to get at where the hidden
> contracts are.

Great. This is useful to me as well, as it stress-tests the design. 
keep up the nice thinking.

>>> Is it right to specify the whole version here and let the versioning 
>>> rules specified in the RT work out that this satisfies <depends-on 
>>> uri="cob:mycompany.com/skin" name="external-skin"/> from above?
>> yes. you need to specify *exactly* what behavior you are 
>> implementing. you cannot implement a range of behaviors, that can 
>> potentially lead to inconsistent states.
>
> ok
>
> ...
>
>>>     <provides role="com.anothercompany.repository.Repository"/>
>> change role to component? [role is avalon terminology and might 
>> confuse non-avaloners]
>
> I'm ok either way.  I think "role" is very easy to grasp as the more
> general concept and "component" could get confused between the role and
> the implementation of that role.  Still, I've wiki'd it with component
> for now unless you or others find that argument compelling.
>
>>> Here's the provides which might also be "exposes".
>> both are fine for me.
>
> me too.
>
> Ok, I've wiki'd the latest with my proposal about @id and @block 
> included.

ok, sounds good to me.

anybody else?

--
Stefano.