husted 2003/09/17 08:06:04 Modified: chain PROPOSAL.html Log: Apply Tidy to markup. No content changes. Revision Changes Path 1.4 +231 -187 jakarta-commons-sandbox/chain/PROPOSAL.html Index: PROPOSAL.html =================================================================== RCS file: /home/cvs/jakarta-commons-sandbox/chain/PROPOSAL.html,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- PROPOSAL.html 17 Sep 2003 15:03:47 -0000 1.3 +++ PROPOSAL.html 17 Sep 2003 15:06:04 -0000 1.4 @@ -1,195 +1,239 @@ -<html> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";> + +<html xmlns="http://www.w3.org/1999/xhtml";> <head> -<title>Proposal for "Chain of Responsibility" Package</title> + <meta name="generator" content= + "HTML Tidy for Windows (vers 1st July 2003), see www.w3.org" /> + + <title>Proposal for "Chain of Responsibility" Package</title> </head> -<body bgcolor="white"> -<div align="center"> -<h1>Proposal for <em>Chain of Responsibility</em> Package</h1> -</div> - -<h3>(0) Rationale</h3> - -<p>A popular technique for organizing the execution of complex processing -flows is the "Chain of Responsibility" pattern, as described (among many -other places) in the classic "Gang of Four" design patterns book. Although -the fundamental API contracts required to implement this design patten are -extremely simple, it is useful to have a base API that facilitates using -the pattern, and (more importantly) encouraging composition of command -implementations from multiple diverse sources.</p> - -<p>Towards that end, the proposed API models a computation as a series of -"commands" that can be combined into a "chain". The API for a command -consists of a single method (<code>execute()</code>), which is passed a -"context" parameter containing the dynamic state of the computation, and -whose return value is a boolean that determines whether or not processing -for the current chain has been completed (true), or whether processing -should be delegated to the next command in the chain (false).</p> - -<p>The "context" abstraction is designed to isolate command implementations -from the environment in which they are run (such as a command that can be -used in either a Servlet or Portlet, without being tied directly to the API -contracts of either of these environments). For commands that need to allocate -resources prior to delegation, and then release them upon return (even if a -delegated-to command throws an exception), the "filter" extension to "command" -provides a <code>postprocess()</code> method for this cleanup. Finally, -commands can be stored and looked up in a "catalog" to allow deferral of the -decision on which command (or chain) is actually executed.</p> - -<p>To maximize the usefulness of the Chain of Responsibility pattern APIs, -the fundamental interface contracts are defined in a manner with zero -dependencies other than an appropriate JDK. Convenience base class -implementations of these APIs are provided, as well as more specialized (but -optional) implementations for the web environment (i.e. servlets and portlets). -However, conditional compilation in the build script allows graceful creation -of the underlying API JAR file even in the absence of the optional dependencies. -</p> - -<p>Given that command implementations are designed to conform with these -recommendations, it should be feasible to utilize the Chain of Responsibility -APIs in the "front controller" of a web application framework (such as Struts), -but also be able to use it in the business logic and persistence tiers to -model complex computational requirements via composition. In addition, -separation of a computation into discrete commands that operate on a general -purpose context allows easier creation of commands that are unit testable, -because the impact of executing a command can be directly measured by observing -the corresponding state changes in the context that is supplied.</p> - - -<h3>(1) Scope of the Package</h3> - -<p>The fundamental API contracts of the Chain of Responsibility pattern are -encapsulated in the following interfaces in package -<code>org.apache.commons.chain</code>:</p> -<ul> -<li><strong>Command</strong> - An individual unit of work whose - <code>execute()</code> method is called to perform that work.</li> -<li><strong>Chain</strong> - A set of commands to which work will be - delegated, in a well-defined order, until one of the commands indicates - that work on a request has been completed. Note that a <code>Chain</code> - is itself a <code>Command</code>, so arbitrarily complex hierarchies of +<body bgcolor="white"> + <div align="center"> + <h1>Proposal for <em>Chain of Responsibility</em> Package</h1> + </div> + + <h3>(0) Rationale</h3> + + <p>A popular technique for organizing the execution of complex + processing flows is the "Chain of Responsibility" pattern, as + described (among many other places) in the classic "Gang of Four" + design patterns book. Although the fundamental API contracts + required to implement this design patten are extremely simple, it + is useful to have a base API that facilitates using the pattern, + and (more importantly) encouraging composition of command + implementations from multiple diverse sources.</p> + + <p>Towards that end, the proposed API models a computation as a + series of "commands" that can be combined into a "chain". The API + for a command consists of a single method + (<code>execute()</code>), which is passed a "context" parameter + containing the dynamic state of the computation, and whose return + value is a boolean that determines whether or not processing for + the current chain has been completed (true), or whether + processing should be delegated to the next command in the chain + (false).</p> + + <p>The "context" abstraction is designed to isolate command + implementations from the environment in which they are run (such + as a command that can be used in either a Servlet or Portlet, + without being tied directly to the API contracts of either of + these environments). For commands that need to allocate resources + prior to delegation, and then release them upon return (even if a + delegated-to command throws an exception), the "filter" extension + to "command" provides a <code>postprocess()</code> method for + this cleanup. Finally, commands can be stored and looked up in a + "catalog" to allow deferral of the decision on which command (or + chain) is actually executed.</p> + + <p>To maximize the usefulness of the Chain of Responsibility + pattern APIs, the fundamental interface contracts are defined in + a manner with zero dependencies other than an appropriate JDK. + Convenience base class implementations of these APIs are + provided, as well as more specialized (but optional) + implementations for the web environment (i.e. servlets and + portlets). However, conditional compilation in the build script + allows graceful creation of the underlying API JAR file even in + the absence of the optional dependencies.</p> + + <p>Given that command implementations are designed to conform + with these recommendations, it should be feasible to utilize the + Chain of Responsibility APIs in the "front controller" of a web + application framework (such as Struts), but also be able to use + it in the business logic and persistence tiers to model complex + computational requirements via composition. In addition, + separation of a computation into discrete commands that operate + on a general purpose context allows easier creation of commands + that are unit testable, because the impact of executing a command + can be directly measured by observing the corresponding state + changes in the context that is supplied.</p> + + <h3>(1) Scope of the Package</h3> + + <p>The fundamental API contracts of the Chain of Responsibility + pattern are encapsulated in the following interfaces in package + <code>org.apache.commons.chain</code>:</p> + + <ul> + <li><strong>Command</strong> - An individual unit of work whose + <code>execute()</code> method is called to perform that + work.</li> + + <li><strong>Chain</strong> - A set of commands to which work + will be delegated, in a well-defined order, until one of the + commands indicates that work on a request has been completed. + Note that a <code>Chain</code> is itself a + <code>Command</code>, so arbitrarily complex hierarchies of execution may be composed.</li> -<li><strong>Filter</strong> - A specialized <code>Command</code> that requires - any <code>Chain</code> that executes it to promise a later call to the - <code>postprocess()</code> method if its <code>execute()</code> method - was ever called, even in the face of exceptions being thrown by subsequently - called commands.</li> -<li><strong>Context</strong> - A container for attributes and properties that - represent the dynamic state of the computation being performed by a - <code>Command</code> or <code>Chain</code>. A <code>Context</code> - instance is passed to the <code>execute()</code> method of each - <code>Command</code>, which allows <code>Command</code> instances to be - easily shared in a multithread environment.</li> -<li><strong>Catalog</strong> - A collection of named <code>Command</code>s - (or <code>Chain</code>s) that can be used to symbolically identify a - computation to be performed.</li> -</ul> - -<p>In addition to the fundamental API contracts described above, additional -packages are provided (some of them optional based on the availability of -the corresponding APIs at compile time):</p> -<ul> -<li><strong>org.apache.commons.chain.impl</strong> - Convenience base class - implementations of the fundamental API contracts.</li> -<li><strong>org.apache.commons.chain.generic</strong> - Implementations of - <code>Command</code> that are completely generic across any execution + + <li><strong>Filter</strong> - A specialized + <code>Command</code> that requires any <code>Chain</code> that + executes it to promise a later call to the + <code>postprocess()</code> method if its <code>execute()</code> + method was ever called, even in the face of exceptions being + thrown by subsequently called commands.</li> + + <li><strong>Context</strong> - A container for attributes and + properties that represent the dynamic state of the computation + being performed by a <code>Command</code> or + <code>Chain</code>. A <code>Context</code> instance is passed + to the <code>execute()</code> method of each + <code>Command</code>, which allows <code>Command</code> + instances to be easily shared in a multithread environment.</li> -<li><strong>org.apache.commons.chain.config</strong> - Implementation of - XML parsing rules (via the use of Commons Digester) so that a - <code>Catalog</code> instance can be populated with <code>Command</code> - and <code>Chain</code> instances configured from an XML document. - Optional, compiled only if commons-digester.jar is available.</li> -<li><strong>org.apache.commons.web</strong> - Abstract implementation - of <code>Context</code> that represents the fundamental characteristics - of request, session, and application scope objects in a web application - environment, without being tied specificaly to the Servlet or Portlet - APIs. These characteristics are exposed under property names that are - identical to the "implicit variables" of the expression language that is - defined by JSTL 1.0 and JSP 2.0.</li> -<li><strong>org.apache.commons.web.faces</strong> - Concrete implementation - of <code>WebContext</code> for the JavaServer Faces API. Optional, - compiled only if the JavaServer Faces API classes are available.</li> -<li><strong>org.apache.commons.web.portlet</strong> - Concrete implementation - of <code>WebContext</code> for the Portlet API. Optional, compiled only - if the Portlet API classes are available.</li> -<li><strong>org.apache.commons.web.servlet</strong> - Concrete implementation - of <code>WebContext</code> for the Servlet API. Optional, compiled only - if the Servlet API classes are available.</li> -</ul> - -<p>Over time, it is expected that additional generic commands and specialized -contexts will be developed for specific requirements. However, conditional -compilation capabilities in the build script should be maintained so that a -user of commons-chain need only provide the APIs that he or she cares about. -Likewise, for maximum reuse, command implementations should be based on the -<code>org.apache.commons.chain.Context</code> API, rather than a more -specialized implementation class, if at all possible.</li> - - -<h3>(1.5) Interaction With Other Packages</h3> - -<p><em>Chain</em> relies on: -</p> - -<ul> - <li>Java Development Kit (Version 1.2 or later)</li> - <li>Commons BeanUtils (version 1.6 or later). OPTIONAL, required - only to use the <code>org.apache.commons.chain.config</code> - package.</li> - <li>Commons Collections (version 1.0 or later). OPTIONAL, required - only to use the <code>org.apache.commons.chain.config</code> - package.</li> - <li>Commons Digester (version 1.3 or later). OPTIONAL, required - only to use the <code>org.apache.commons.chain.config</code> - package.</li> - <li>Commons Logging (version 1.0.3 or later). OPTIONAL, required - only to use the <code>org.apache.commons.chain.config</code> - package.</li> - <li>JavaServer Faces API (version 1.0 or later). OPTIONAL, required only - to use the <code>org.apache.commons.web.faces</code> - package.</li> - <li>Portlet API (version 1.0 or later). OPTIONAL, required only - to use the <code>org.apache.commons.web.portlet</code> - package.</li> - <li>Servlet API (version 2.2 or later). OPTIONAL, required only - to use the <code>org.apache.commons.web.servlet</code> - package.</li> -</ul> - - -<h3>(2) Initial Source of the Package</h3> - -<p>This package represents a new approach to the Chain of Responsibility -pattern, and the initial source is provided by Craig R. McClanahan. It was -inspired by ideas from many sources -- in particular, the notion of a Chain -being a Command was copied from the way that handlers are described in Axis.</p> - - -<h3>(3) Required Jakarta-Commons Resources</h3> - -<ul> - -<li>CVS Repository - New directory <code>chain</code> in the -<code>jakarta-commons</code> CVS repository.</li> - -<li>Mailing List - Discussions will take place on the general -<em>[EMAIL PROTECTED]</em> mailing list. To help list -subscribers identify messages of interest, it is suggested that the -message subject of messages about this component be prefixed with -[Chain].</li> - -<li>Bugzilla - New component "Chain" under the "Commons" product -category, with appropriate version identifiers as needed.</li> - - -<h3>(4) Initial Committers</h3> - -<p>The initial committers on the Chain component shall be:</p> - -<ul> - <li>Craig R. McClanahan</li> - <li>TBD</li> -</ul> + <li><strong>Catalog</strong> - A collection of named + <code>Command</code>s (or <code>Chain</code>s) that can be used + to symbolically identify a computation to be performed.</li> + </ul> + + <p>In addition to the fundamental API contracts described above, + additional packages are provided (some of them optional based on + the availability of the corresponding APIs at compile time):</p> + + <ul> + <li><strong>org.apache.commons.chain.impl</strong> - + Convenience base class implementations of the fundamental API + contracts.</li> + + <li><strong>org.apache.commons.chain.generic</strong> - + Implementations of <code>Command</code> that are completely + generic across any execution environment.</li> + + <li><strong>org.apache.commons.chain.config</strong> - + Implementation of XML parsing rules (via the use of Commons + Digester) so that a <code>Catalog</code> instance can be + populated with <code>Command</code> and <code>Chain</code> + instances configured from an XML document. Optional, compiled + only if commons-digester.jar is available.</li> + + <li><strong>org.apache.commons.web</strong> - Abstract + implementation of <code>Context</code> that represents the + fundamental characteristics of request, session, and + application scope objects in a web application environment, + without being tied specificaly to the Servlet or Portlet APIs. + These characteristics are exposed under property names that are + identical to the "implicit variables" of the expression + language that is defined by JSTL 1.0 and JSP 2.0.</li> + + <li><strong>org.apache.commons.web.faces</strong> - Concrete + implementation of <code>WebContext</code> for the JavaServer + Faces API. Optional, compiled only if the JavaServer Faces API + classes are available.</li> + + <li><strong>org.apache.commons.web.portlet</strong> - Concrete + implementation of <code>WebContext</code> for the Portlet API. + Optional, compiled only if the Portlet API classes are + available.</li> + + <li><strong>org.apache.commons.web.servlet</strong> - Concrete + implementation of <code>WebContext</code> for the Servlet API. + Optional, compiled only if the Servlet API classes are + available.</li> + </ul> + + <p>Over time, it is expected that additional generic commands and + specialized contexts will be developed for specific requirements. + However, conditional compilation capabilities in the build script + should be maintained so that a user of commons-chain need only + provide the APIs that he or she cares about. Likewise, for + maximum reuse, command implementations should be based on the + <code>org.apache.commons.chain.Context</code> API, rather than a + more specialized implementation class, if at all possible.</p> + + <h3>(1.5) Interaction With Other Packages</h3> + + <p><em>Chain</em> relies on:</p> + + <ul> + <li>Java Development Kit (Version 1.2 or later)</li> + + <li>Commons BeanUtils (version 1.6 or later). OPTIONAL, + required only to use the + <code>org.apache.commons.chain.config</code> package.</li> + + <li>Commons Collections (version 1.0 or later). OPTIONAL, + required only to use the + <code>org.apache.commons.chain.config</code> package.</li> + + <li>Commons Digester (version 1.3 or later). OPTIONAL, required + only to use the <code>org.apache.commons.chain.config</code> + package.</li> + + <li>Commons Logging (version 1.0.3 or later). OPTIONAL, + required only to use the + <code>org.apache.commons.chain.config</code> package.</li> + + <li>JavaServer Faces API (version 1.0 or later). OPTIONAL, + required only to use the + <code>org.apache.commons.web.faces</code> package.</li> + + <li>Portlet API (version 1.0 or later). OPTIONAL, required only + to use the <code>org.apache.commons.web.portlet</code> + package.</li> + + <li>Servlet API (version 2.2 or later). OPTIONAL, required only + to use the <code>org.apache.commons.web.servlet</code> + package.</li> + </ul> + + <h3>(2) Initial Source of the Package</h3> + + <p>This package represents a new approach to the Chain of + Responsibility pattern, and the initial source is provided by + Craig R. McClanahan. It was inspired by ideas from many sources + -- in particular, the notion of a Chain being a Command was + copied from the way that handlers are described in Axis.</p> + + <h3>(3) Required Jakarta-Commons Resources</h3> + + <ul> + <li>CVS Repository - New directory <code>chain</code> in the + <code>jakarta-commons</code> CVS repository.</li> + + <li>Mailing List - Discussions will take place on the general + <em>[EMAIL PROTECTED]</em> mailing list. To help + list subscribers identify messages of interest, it is suggested + that the message subject of messages about this component be + prefixed with [Chain].</li> + + <li>Bugzilla - New component "Chain" under the "Commons" + product category, with appropriate version identifiers as + needed.</li> + + <li style="list-style: none"> + <h3>(4) Initial Committers</h3> + + <p>The initial committers on the Chain component shall + be:</p> + + <ul> + <li>Craig R. McClanahan</li> + + <li>TBD</li> + </ul> + </li> + </ul> </body> </html>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
