You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by st...@outerthought.org on 2003/09/20 19:00:08 UTC
[WIKI-UPDATE] BlockIdentification Blocks BlocksCob BlocksDefinition Sat Sep 20 19:00:08 2003
Page: http://wiki.cocoondev.org/Wiki.jsp?page=BlockIdentification , version: 1 on Sat Sep 20 16:35:36 2003 by Stefanomazzocchi
New page created:
+ !!Block URI Scheme
+
+ All blocks (behaviors and implementations) are identified by a URI. The
+ format of the URI is as follows:
+
+ {{{ cob:organization/name/x.y(.z)}}}
+
+ where
+
+ * {{cob:}} is a virtual protocol that is used instead of http:// to avoid the problem of mistaking the URI for a URL
+
+ * {{organization}} is the unique identifier for the organization that is responsible for the maintenance of that identifier. the ICANN domain name should be used (for example, {{apache.org}} for the ASF)
+
+ * {{name}} is the unique name of the identifier. it is suggested that a path delimiter is used to further specialize the name (see belows for examples)
+
+ * {{x.y.z}} is the version identifier, where:
+
+ ** x -> major (>= 1)
+ ** y -> minor (>= 0)
+ ** z -> bugfix (>= 0) (only for implementations)
+
+ NOTE: identifiers are case insensitive.
+
+ Example of good identifiers are
+
+ * cob:apache.org/cocoon/PDF/2.6
+ * cob:apache.org/cocoon/Fop/3.4.34
+ * cob:apache.org/cocoon/iText/1.0.43
+ * cob:mycompany.com/mydepartment/myself/myblock/3.2.23
+
+ example of bad identifiers
+
+ * cob:cocoon.apache.org/whatever/2.3.434
+
+ the use of the virtual host instead of the domain name should be
+ avoided because it mixes location and identification concerns.
+
+ * cob:apache.org/cocoon/block/whatever/2.3.4
+
+ the inclusion of the "block" name should be avoided because redundant
+ (the cob virtual protocol was introduced exactly to specify block
+ specificity and avoid location and identification semantic collisions)
+
+ * cob:apache.org/cocoon/PDF/Fop/2.3.43
+
+ information of what behavior is implemented by a given block
+ implementation should not be included in the identifier.
+
+ * http://mysite.com/blah/3/2
+
+ the use of the HTTP protocol makes it hard to distinguish between URL and a URI
+
+ !!Dependency Ranges
+
+ When a block implementation depends on another block (either
+ implementation or behavior), it should be able to have an 'elastic'
+ dependency which doesn't connect it to the versioned identifier, but to
+ a range of those versions.
+
+ Instead of explicitly indicate the range description language, it is
+ suggested to implicity describe range rules. These implicit range rules
+ are:
+
+ * if the dependency doesn't include the version, all versions are matched
+
+ ex: both "cob:apache.org/blah/1.0" and "cob:apache.org/blah/3.43.342" are matched by "cob:apache.org/blah"
+
+ * if the dependency includes a version, versions are matched with the following rules
+
+ ** if major is equal
+ ** if minor is greater or equal
+ ** in case of implementations and if minor is equal, if bugfix is greater or equal
+
+ ex: depending on "cob:apache.org/blah/2.0.34" will match
+
+ * cob:apache.org/blah/2.0.345
+ * cob:apache.org/blah/2.3.23
+
+ but not
+
+ * cob:apache.org/blah/1.0.0
+ * cob:apache.org/blah/34.323.324534
+
Page: http://wiki.cocoondev.org/Wiki.jsp?page=Blocks , version: 25 on Sat Sep 20 16:21:01 2003 by Stefanomazzocchi
- * [Block Definition|BlocksDefinition] - This document contains the block design
? ^^^^^ ^^ ^ ^^^
+ * [Block Definition|BlocksDefinition] - This document defines what a block is and how it works.
? ^^^ + +++ ^^ +++++ ^^^^^^^^^^^^ ^
+ * [Block Identification|BlockIdentification] - This document defines the URI scheme used for block identification
Page: http://wiki.cocoondev.org/Wiki.jsp?page=BlocksCob , version: 6 on Sat Sep 20 16:58:44 2003 by Stefanomazzocchi
- {{{
+ This page contains examples of the schema used in the block descriptor file.
+
+ The Webmail block:
+
- <block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
+ {{{<block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
? +++
+ <name>Super Webmail</name>
+ <description href="http://www.mycompany.com/products/webmail/">This is a super webmail block with amazing functionalities</description>
+ <license href="http://www.mycompany.com/license/1.3"/>BSD License</license>
+ <author href="http://www.mycompany.com/">MyCompany Inc.</author>
- </block>
+ </block>}}}
? +++
- }}}
- {{{
+
+ The block that implements the "internal-skin":
+
- <block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
+ {{{<block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
? +++
+ <name>Fancy Skin</name>
+ <license href="http://www.yetanothercompany.com/license/1.0"/>Artistic License</license>
+ <author href="http://www.yetanothercompany.com/">YetAnotherCompany Ltd.</author>
- <implements block="cob:mycompany.com/skin/1.2"/>
? -
+ <implements block="cob:mycompany.com/skin/1.2"/>
- </block>
+ </block>}}}
? +++
- }}}
- {{{
+
+ The block that implements the "external-skin":
+
- <block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
+ {{{<block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
? +++
+ <name>Corporate Skin</name>
+ <license href="http://www.mycompany.com/license/1.3"/>BSD License</license>
+ <author href="http://www.mycompany.com/">MyCompany Inc.</author>
- </block>
+ </block>}}}
? +++
- }}}
- {{{
+
+ The block that implements the mail "repository":
+
- <block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
+ {{{<block xmlns="http://apache.org/cocoon/blocks/cob/1.0"
? +++
+ <name>Exchange-based Mail Repository</name>
+ <license href="http://www.mycompany.com/license/1.3"/>BSD License</license>
+ <author href="http://www.mycompany.com/">MyCompany Inc.</author>
- </block>
+ </block>}}}
? +++
- }}}
- {{{
- cob:mycompany.com/webmail/1.3.43
- has a sitemap located on -> /webmail.xmap
- depends on -> cob:mycompany.com/skin
- names this dependency -> external-skin
- depends on -> cob:mycompany.com/skin/2.0
- names this dependency -> internal-skin
- depends on -> cob:anothercompany.com/MailRepository/2.0
- names this dependency -> repository
- uses component -> "com.anothercompany.repository.Repository"
- names this component with role -> repository
- requires the configurations:
- "user" of type string with no default
- "password" of type string with no default
- 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
-
- cob:mycompany.com/repositories/email/exchange/3.2.1
- implements -> cob:anothercompany.com/MailRepository/2.0
- exposes component -> "com.anothercompany.repository.Repository"
- requires the configurations:
- "host" of type string, with default "127.0.0.1"
- }}}
-
Page: http://wiki.cocoondev.org/Wiki.jsp?page=BlocksDefinition , version: 19 on Sat Sep 20 16:45:47 2003 by Stefanomazzocchi
- !Resource dereferencing
+ The main COB configuration file (optional) is found at
+
+ {{{ /BLOCK-INF/block.xconf}}}
+
+ and contains the configurations that are used by the components included in the block.
+
+ !Block configuration at deployment time
+
+ blocks will contain configurations that is written at block-release
+ time but there are information that are deployment dependent. The block
+ deployment descriptor contains a list of those configurations that are
+ required to be entered at deployment time.
+
+ Since these configurations will rather be context-dependent tokens,
+ these can be considered more as properties. An example of a descriptor
+ could be:
+
+ <properties>
+ <property name="username">
+ <default>guest</default>
+ <description>The name of the user</description>
+ </property>
+ ...
+ </properties>
+
+ then, these values will be accessible in the usual block.xconf using
+ {name} style. For example
+
+ ...
+ <datasources>
+ <datasource name="rbdms">
+ <username>{username}</username>
+ ...
+ </datasource>
+ </datasources>
+ ...
+
+ !Exposed Services
+
+ A block exposes two types of services:
+
+ * components
+ * resources
+
+ !Accessing components
+
+ The block.xml descriptor includes the list of components which are exposed and made available by the block.
+
+ Blocks that depend on this block might use the component role (as they normally did with block-less cocoon) and the component manager will load the appropriate component (everthing is done by the component manager and the block manager thru block.xml and wiring information)
+
+ !Accessing resources
+ The above implies that all resources that a block provides are provided by its sitemap. There is no way for a block to access directly the content of another block.
+
+