xdocs/index.xml - commons-chain - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
    Copyright 2003-2004 The Apache Software Foundation

    Licensed 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.
 -->

 <document>

   <properties>
     <title>Overview</title>
     <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
     <author email="martinc@apache.org">Martin Cooper</author>
     <author email="craigmcc@apache.org">Craig McClanahan</author>
   </properties>

   <body>

   <section name="Commons Chain">

       <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 Chain 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>

   </section>

   <section name="Documentation">
     <p>
       <ul>
         <li>The <a href="apidocs/index.html">Javadoc</a> of the latest CVS.</li>
         <li>The <a href="cookbook.html">Cookbook</a> containing "recipes" for using the chain.</li>
         <li>The <a href="http://cvs.apache.org/viewcvs/jakarta-commons/chain/">CVS repository</a> can be browsed.</li>
       </ul>
     </p>
   </section>

   <section name="Downloading Chain">
     <subsection name='Releases'>
       <p>
         <strong>Chain 1.0</strong> - 9 Dec 2004
         <ul>
           <li>Download the binary distribution from a mirror site
             <a href='http://jakarta.apache.org/site/binindex.cgi'>here</a>
           </li>
           <li>Download the source distribution from a mirror site
             <a href='http://jakarta.apache.org/site/sourceindex.cgi'>here</a>
           </li>
         </ul>
       </p>
     </subsection>
     <subsection name='Nightly Builds'>
       <p>
         Nightly builds are built every day from the current CVS HEAD. This is
         the latest code and so should be treated with caution!
       </p>
       <p>
         Download nightly builds from
         <a href='http://cvs.apache.org/builds/jakarta-commons/nightly/commons-chain/'>here</a>.
       </p>
     </subsection>
   </section>

 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Copyright 2003-2004 The Apache Software Foundation

	Licensed 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.
	-->

	<document>

	<properties>
	<title>Overview</title>
	<author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author>
	<author email="martinc@apache.org">Martin Cooper</author>
	<author email="craigmcc@apache.org">Craig McClanahan</author>
	</properties>

	<body>

	<section name="Commons Chain">

	<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 Chain 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>

	</section>

	<section name="Documentation">
	<p>
	<ul>
	<li>The <a href="apidocs/index.html">Javadoc</a> of the latest CVS.</li>
	<li>The <a href="cookbook.html">Cookbook</a> containing "recipes" for using the chain.</li>
	<li>The <a href="http://cvs.apache.org/viewcvs/jakarta-commons/chain/">CVS repository</a> can be browsed.</li>
	</ul>
	</p>
	</section>

	<section name="Downloading Chain">
	<subsection name='Releases'>
	<p>
	<strong>Chain 1.0</strong> - 9 Dec 2004
	<ul>
	<li>Download the binary distribution from a mirror site
	<a href='http://jakarta.apache.org/site/binindex.cgi'>here</a>
	</li>
	<li>Download the source distribution from a mirror site
	<a href='http://jakarta.apache.org/site/sourceindex.cgi'>here</a>
	</li>
	</ul>
	</p>
	</subsection>
	<subsection name='Nightly Builds'>
	<p>
	Nightly builds are built every day from the current CVS HEAD. This is
	the latest code and so should be treated with caution!
	</p>
	<p>
	Download nightly builds from
	<a href='http://cvs.apache.org/builds/jakarta-commons/nightly/commons-chain/'>here</a>.
	</p>
	</subsection>
	</section>

	</body>
	</document>