Skip to content
Permalink
Browse files
Initial revision
  • Loading branch information
Craig R. McClanahan committed Aug 11, 2003
1 parent 4134765 commit d1dce747950bd3f79fd8fa1fdaeadc37ecfab373
Show file tree
Hide file tree
Showing 83 changed files with 13,548 additions and 0 deletions.
@@ -0,0 +1,2 @@
dist
target
@@ -0,0 +1,60 @@
/*
* $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//chain/LICENSE.txt,v 1.1 2003/08/11 04:44:16 craigmcc Exp $
* $Revision: 1.1 $
* $Date: 2003/08/11 04:44:16 $
*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 1999-2003 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
@@ -0,0 +1,195 @@
<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>
@@ -0,0 +1,30 @@
$Id: RELEASE-NOTES.txt,v 1.1 2003/08/11 04:44:16 craigmcc Exp $

Commons Chain Package
Version 1.0
Release Notes


INTRODUCTION:
============

This document contains the release notes for this version of the Commons
Chain package, and highlights changes since the previous version.


NEW FEATURES:
============

Initial release, so all features are new.


CHANGES:
========

Initial release, so no changes to existing features.


BUG REPORTS ADDRESSED:
=====================

Initial release, so no bug reports addressed since the previous release.
@@ -0,0 +1,66 @@
<html>
<head>
<title>Status File for Jakarta Commons "Chain of Responsibility" Component</title>
<head>
<body bgcolor="white">


<div align="center">
<h1>The Jakarta Commons <em>Chain of Responsibility</em> Component</h1>
$Id: STATUS.html,v 1.1 2003/08/11 04:44:16 craigmcc Exp $<br>
<a href="#Introduction">[Introduction]</a>
<a href="#Dependencies">[Dependencies]</a>
<a href="#Release Info">[Release Info]</a>
<a href="#Committers">[Committers]</a>
<br><br>
</div>


<a name="Introduction"></a>
<h3>1. INTRODUCTION</h3>

<p>This scope of the <em>Chain of Responsibility</em> component is
to support modelling of complex computations as composition of individual
commands that operate on a context.</p>


<a name="Dependencies"></a>
<h3>2. DEPENDENCIES</h3>

<p>The <em>Chain of Responsibility</em> component is dependent upon the
following external components for development and use:</p>
<ul>
<li><a href="http://java.sun.com/j2se">Java Development Kit</a>
(Version 1.2 or later)</li>
<li><a href="http://jakarta.apache.org/jakarta-commons/beanutils"/>Jakarta Commons Beanutils</a> (OPTIONAL)</li>
<li><a href="http://jakarta.apache.org/jakarta-commons/collections"/>Jakarta Commons Collections</a> (OPTIONAL)</li>
<li><a href="http://jakarta.apache.org/jakarta-commons/digester"/>Jakarta Commons Digester</a> (OPTIONAL)</li>
<li><a href="http://jakarta.apache.org/jakarta-commons/logging"/>Jakarta Commons Logging</a> (OPTIONAL)</li>
<li>JavaServer Faces API (Version 1.0 or later) (OPTIONAL)</li>
<li>Portlet API (Version 1.0 or later) (OPTIONAL)</li>
<li>Servlet API (Version 2.2 or later) (OPTIONAL)</li>
<li>JUnit Testing Framework (OPTIONAL, unit tests only)</li>
</ul>


<a name="Release Info"></a>
<h3>3. RELEASE INFO</h3>

<p>Current Release: <strong>Unreleased, CVS Repository Only</strong></p>
<p>Planned Next Release: N/A</p>


<a name="Committers"></a>
<h3>4. COMMITTERS</h3>

<p>The following individuals are the primary developers and maintainers of this
component. Developers who plan to use <em>Chain</em> in their own
projects are encouraged to collaborate on the future development of this
component to ensure that it continues to meet a variety of needs.</p>
<ul>
<li><a href="mailto:craigmcc@apache.org">Craig McClanahan</a></li>
<li>TBD</li>
</ul>

</body>
</html>
@@ -0,0 +1,22 @@
# The directory containing your binary distribution of JUnit,
# version 3.8.1 or later
junit.home = /usr/local/junit3.8.1

# The pathname of the "junit.jar" JAR file
junit.jar = ${junit.home}/junit.jar

# (OPTIONAL) The pathname of the "faces-api.jar" file
jsf-api.jar=${user.home}/jwsdp-1.2/jsf/lib/jsf-api.jar

# (OPTIONAL) The pathname of the "portlet-api.jar" file
portlet-api.jar=../../jakarta-jetspeed-2/portlet-api/target/portlet-api-0.6.6.jar

# (OPTIONAL) The pathname of the "servlet-api.jar" file
# Version 2.2 or later required, version 2.4 is supported
servlet-api.jar = /usr/local/jwsdp-1.2/common/lib/servlet-api.jar

# (OPTIONAL) The pathname of the "commons-digester.jar" file
# required only if you are using the org.apache.commons.chain.config package
commons-digester.jar = ../../jakarta-commons/digester/dist/commons-digester.jar


0 comments on commit d1dce74

Please sign in to comment.