| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <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.chain2</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.chain2.impl</strong> - |
| Convenience base class implementations of the fundamental API |
| contracts.</li> |
| |
| <li><strong>org.apache.commons.chain2.generic</strong> - |
| Implementations of <code>Command</code> that are completely |
| generic across any execution environment.</li> |
| |
| <li><strong>org.apache.commons.chain2.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.chain2.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.chain2.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.chain2.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.chain2.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.chain2.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.chain2.config</code> package.</li> |
| |
| <li>Commons Collections (version 1.0 or later). OPTIONAL, |
| required only to use the |
| <code>org.apache.commons.chain2.config</code> package.</li> |
| |
| <li>Commons Digester (version 1.3 or later). OPTIONAL, required |
| only to use the <code>org.apache.commons.chain2.config</code> |
| package.</li> |
| |
| <li>Commons Logging (version 1.0.3 or later). OPTIONAL, |
| required only to use the |
| <code>org.apache.commons.chain2.config</code> package and |
| to build and use the |
| <code>org.apache.commons.chain2.web.servlet.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>dev@commons.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> |
| |
| <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>Ted Husted</li> |
| |
| <li>TBD</li> |
| </ul> |
| </li> |
| </ul> |
| </body> |
| </html> |