commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hus...@apache.org
Subject cvs commit: jakarta-commons-sandbox/chain PROPOSAL.html
Date Wed, 17 Sep 2003 15:06:04 GMT
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>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>
   
  +    <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>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>
  +
  +    <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>
  
  
  

Mime
View raw message