I thought about postponing the design of Cocoon Blocks after Cocoon 2.1
was released, but since many people seem to expect better user-level
componentization of Cocoon sooner rather than later, I want to write a
short summary describing the status of its design so that we can decide
what to do.
Ok, here is what it was decided so far:
1) Cocoon Blocks are user-level polymorphic components that can contain
resources, classes and libraries. These resources can be either files or
pipelines.
2) Cocoon Blocks are zipped archives that follow the design of WAR
files. They have a /BLOCK-INF/ directory (which is automatically
protected from access for security reasons) where configuration files,
classes and libraries are stored. The internal directory layout of this
/block-inf/ directory follow the WAR model.
3) In order to obtain polymorphic behavior, each Cocoon Block (CB) must
*implement* a Cocoon Block Contract (CBC). This contract explains the
'behavior' of the block (much like a Java interface for an Avalon
Component, or a WSDL file for a web service).
4) Each Cocoon Block has a descriptor file (written using an XML syntax)
that includes:
- information about the block (author, version, etc...)
- description of the CBC the block implements
- dependencies of the block on other CBC
- configurations that are required to be entered at installation time
in order for the block to be functional
This descriptor is used by the CB installation system to understand if
the CB can operate in the existing environment.
- o -
Here are the things that we need to design now:
1) the CB descriptor schema
2) the CB contract schema
- o -
Here is a temptative schema for the CB descriptor (CBD).
Location: /BLOCK-INF/block.cbd
<block xmlns="http://apache.org/cocoon/block/descriptor/1.0";>
<info>
<name>MyBlock</name>
<description>This is my block that does something</description>
<version>3.4.334</version>
<provider>MyCorp Corp.</provider>
<location href="http://mysite.com/fixed/url/to/block"/>
</info>
<contracts>
<implements src="http://apache.org/cocoon/contracts/mycontract/1.0"/>
<implements
src="http://apache.org/cocoon/contracts/myothercontract/2.1"/>
</contracts>
<dependencies>
<requires src="http://mysite.com/contracts/something";
version="2.0+"/>
<requires src="http://yoursite.com/contracts/whatever";
version="2.x"/>
<requires src="http://yoursite.com/contracts/anything"/>
<requires src="http://oldsite.com/contracts/blah"; version="4.0-"/>
</dependencies>
</block>
NOTE:
1) while the contracts are versioned with their URI (since there is
always a one2one link between the two), the dependencies might have
ranged versions. The syntax is as follows:
contract versions are forced to be major.minor:
- major is increased when back compatibility emerges,
- minor is increased when things are added without breaking back
compatibility.
1.0 -> indicates dependency on *exactly* the version 1.0 of the
contract, no other version can fulfill the dependency.
1.0+ -> indicates dependency on everything that is greater than 1.0
(2.0 is included)
1.x -> indicates dependency on the 1.x series, 2.0 is *not* included
2.0- -> indicates dependency on everything below 2.0, 2.0 is *not*
included, but 0.1 is.
- o -
Here is a temptative schema for the CB contract (CBC)
<contract xmlns="http://apache.org/cocoon/block/contract/1.0";>
<info>
<name>MyContract</name>
<description>This contract does this and that</description>
<version>3.2</version>
</info>
<resources catalog="catalogs/mycatalog.catalog">
<pipelines>
<pipeline href="news" type="text/xml" actions="GET"/>
</pipelines>
<views>
<view name="content" actions="GET"/>
<view name="links" actions="GET"/>
<view name="edit" actions="GET,POST"/>
</views>
<files>
<file src="hello.xml" type="text/xml"/>
<file src="stylesheets/whatever2html.xslt" type="text/xml"/>
<file src="images/logo.gif" type="images/gif"/>
<file src="stylesheets/default.css" type="text/css"/>
</resources>
<components>
<role name="org.mysite.mycomponent.DoThisComponent"
shorthand="dothis">
<hint shorthand="white"/>
<hint shorthand="black"/>
</role>
</components>
</resources>
</contract>
- o -
Issues:
1) MIME types are not enough to describe an XML file in full detail. A
better way would be to indicate the namespace of the root element, this
is equivalent of weak typing, but might be enough for a brief validation
check of the contract.
2) pipelines and views are very hard to describe in a meaningful way.
The above is just a wide guess, any comment is very appreciated in this
area.
3) even if contracts are very likely to become verbose, we should not
be using wildcards or the contract will become instantly weaker.
4) components don't need to provide versioning for their interfaces
since that goes along with the contract version.
All right, might not be totally complete, but I'd like to proceed
incrementally and have your feedback before going on.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<[EMAIL PROTECTED]> Friedrich Nietzsche
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
