/
PROPOSAL.html
259 lines (212 loc) · 10.9 KB
/
PROPOSAL.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
<!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>