<html>
<head>
<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
    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 subseuqently
    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
    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 appication
    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>commons-dev@jakarta.apache.org</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>

</body>
</html>