leosimons 02/05/10 14:52:40
Modified: docs/framework index.html
Added: docs/framework features.html for-developers-changes.html
for-developers-project-structure.html
getting-started.html guide-cop-in-avalon.html
guide-cop-what-is.html
guide-oop-best-practices.html
guide-patterns-in-avalon.html
guide-patterns-ioc.html
guide-patterns-ioc-security.html
guide-patterns-soc.html guide-patterns-soii.html
guide-patterns-what-are.html
guide-where-to-go-from-here.html
reference-the-lifecycle.html
Removed: docs/framework changes.html designing-a-component.html
inversion-of-control.html lifecycle.html
patterns.html reuse-standards.html security.html
separation-of-concerns.html
separation-of-interface-and-implementation.html
what-is-a-component.html what-is-a-composer.html
Log:
major overhaul of framework documentation.
Revision Changes Path
1.15 +114 -86 jakarta-avalon-site/docs/framework/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-avalon-site/docs/framework/index.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- index.html 2 Apr 2002 17:21:17 -0000 1.14
+++ index.html 10 May 2002 21:52:40 -0000 1.15
@@ -21,13 +21,13 @@
<font face="arial,helvetica,sanserif">
<br>
<br>
-<a href="../"><font size="+1" color="#778899">Jakarta main</font></a>
+<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
-<a href="../index.html"><font size="+1" color="#778899">Avalon
main</font></a>
+<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
-<font size="+1" color="#000000">About</font>
+<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
@@ -35,62 +35,79 @@
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
-<a href="changes.html"><font size="-1">Changes</font></a>
+<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
-<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
-</li>
-<li>
-<a href="http://jakarta.apache.org/avalon/api/index.html";><font
size="-1">API Docs</font></a>
+<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
-<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
+<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
-<font size="+1" color="#000000">Patterns and Design</font>
+<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
-<a href="patterns.html"><font size="-1">Patterns</font></a>
+<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
-<a href="reuse-standards.html"><font size="-1">Reuse Standards</font></a>
+<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
-<a href="inversion-of-control.html"><font size="-1">Inversion of
Control</font></a>
+<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
-<a href="separation-of-concerns.html"><font size="-1">Separation of
Concerns</font></a>
+<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
-<a href="separation-of-interface-and-implementation.html"><font
size="-1">Separation of interface & impl</font></a>
+<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
-<a href="security.html"><font size="-1">Security</font></a>
+<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
-<font size="+1" color="#000000">The API</font>
+<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
-<a href="what-is-a-component.html"><font size="-1">What is a
Component?</font></a>
+<a href="http://jakarta.apache.org/avalon/api/index.html";><font
size="-1">API Docs</font></a>
</li>
<li>
-<a href="what-is-a-composer.html"><font size="-1">What is a
Composer?</font></a>
+<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
-<a href="lifecycle.html"><font size="-1">The Component Lifecycle</font></a>
+<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
+</li>
+</ul>
+</font>
+<br>
+<br>
+<font size="+1" color="#000000">For Developers</font>
+<br>
+<font size="-1">
+<ul>
+<li>
+<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
+</li>
+<li>
+<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
+</li>
+<li>
+<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
-<a href="designing-a-component.html"><font size="-1">Designing a
Component</font></a>
+<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
+</li>
+<li>
+<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
@@ -111,7 +128,7 @@
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
-<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
+<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Peter Donald</a>, <a href="mailto:[EMAIL
PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
@@ -131,6 +148,44 @@
lightweight convenience implementations of the generic components.
</p>
+<p align="justify">
+ If that sounds a bit abstract to you, we suggest you start by reading
+ the guide (see below). If you want to see the code first, either
+ <a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";>Download</a>
+ it or
+ <a href="http://jakarta.apache.org/site/cvsindex.html";>get it from
CVS</a>.
+ The <a href="getting-started.html">Getting started</a> document
+ provides more pointers.
+ </p>
+
+</font></td>
+</tr>
+</table>
+</div>
+<br>
+<div align="right">
+<table cellspacing="0" cellpadding="2" border="0" width="100%">
+<tr>
+<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Guide to Avalon Framework</b></font></td>
+</tr>
+<tr>
+<td><font face="arial,helvetica,sanserif" color="#000000">
+<br>
+
+<p align="justify">
+ The Avalon Framework is based on several important programming
+ concepts (design patterns and COP) which are applied throughout
+ Avalon. This documentation first introduces each of these,
providing
+ links to external sources for more elaborate documentation. Then,
+ we look at how these concepts are used within Avalon.
+ </p>
+
+<p align="justify">
+ This is more a theoretical introduction than a hands-on guide. If
you
+ prefer looking at code while learning, try our
+ <a href="http://jakarta.apache.org/avalon/developing";>Developing
with Avalon</a> paper.
+ </p>
+
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
@@ -139,118 +194,91 @@
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
-
+
<p align="justify">
- This documentation is aimed towards developers who:
- <ul>
-
+ This documentation is aimed towards developers who:
+ <ul>
+
<li>are interested in the design principles of Avalon</li>
-
+
<li>wish to develop code that will be incorporated into Avalon</li>
-
+
<li>wish to reuse Avalon concepts in their own application</li>
-
+
</ul>
-
+
</p>
-
+
</font></td>
</tr>
</table>
</div>
<br>
-
+
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
-<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Theoretical Aspects of Component Development</b></font></td>
+<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Contents</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
-
-<p align="justify">
- The following documents provide basic theoretical concepts that
are applied
- through-out Avalon's framework. It would be good for a prospective
developer to
- be at least passingly familiar with the concepts outlined in this
document.
- The documentation also provides links to outside sources which can
be consulted
- for further information.
- </p>
-
-<ol>
+<ol>
+
<li>
-<a href="patterns.html">Patterns</a>
+<a href="guide-oop-best-practices.html">OOP best practices</a>
</li>
-
+
<li>
-<a href="reuse-standards.html">Reuse Standards</a>
+<a href="guide-patterns-what-are.html">What are design patterns?</a>
</li>
-
+
<li>
-<a href="inversion-of-control.html">Inversion of Control</a>
+<a href="guide-patterns-in-avalon.html">Design patterns in Avalon</a>
</li>
-
+
<li>
-<a href="separation-of-concerns.html">Separation of Concerns</a>
+<a href="guide-cop-what-is.html">What is Component-Oriented Programming?</a>
</li>
-
+
<li>
-<a href="separation-of-interface-and-implementation.html">Separation of
Interface and Implementation</a>
+<a href="guide-cop-in-avalon.html">COP in Avalon</a>
</li>
-
+
<li>
-<a href="security.html">Security</a>
+<a href="guide-where-to-go-from-here.html">Where to go next</a>
</li>
-
+
</ol>
-
+
</font></td>
</tr>
</table>
</div>
<br>
+</font></td>
+</tr>
+</table>
+</div>
+<br>
<div align="right">
-<table cellspacing="0" cellpadding="2" border="0" width="99%">
+<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
-<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Concrete Descriptions of the Avalon Component model</b></font></td>
+<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Avalon Framework Reference Documentation</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
- This section describes concrete examples of how the theoretical
ideas
- are applied within the context of Avalon.
+ Besides the
+ <a
href="http://jakarta.apache.org/avalon/api/index.html";>Javadocs</a>, we have
+ <a href="diagrams/index.html">Class diagrams</a> and the
+ <a href="reference-the-lifecycle">The Lifecycle specification</a>.
</p>
-
-<ol>
-
-<li>
-<a href="what-is-a-component.html">What is a Component?</a>
-</li>
-
-<li>
-<a href="what-is-a-composer.html">What is a Composer?</a>
-</li>
-
-<li>
-<a href="lifecycle.html">The Component Lifecycle</a>
-</li>
-
-<li>
-<a href="designing-a-component.html">Designing a Component</a>
-</li>
-
-</ol>
-</font></td>
-</tr>
-</table>
-</div>
-<br>
-
</font></td>
</tr>
</table>
1.3 +175 -45 jakarta-avalon-site/docs/framework/features.html
1.1
jakarta-avalon-site/docs/framework/for-developers-changes.html
Index: for-developers-changes.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Revision History</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Revision History</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Revision
History</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<div align="right">
<table width="100%" cellspacing="0" cellpadding="2" border="0">
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.1.2
(January 31, 2002)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Updated the build jars.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add EMPTY_PARAMETERS constant object to the Parameters object.
(CZ)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Made it configurable whether you print nested exceptions or not,
and specify the depth that the AvalonFormatter will go with nested
exceptions (defaults to 8).
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Update build to have a "compress.jars" property (defaults to
true by default).
(LM)</li>
</ul>
</font></td>
</tr>
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.1.1
(December 21, 2001)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/fix.jpg" border="0" alt="off" align="absmiddle">
Force build process to produce JDK 1.2 compliant class files.
The last release had JDK 1.4 compliant class files, causing
some classloaders to not work with the Framework.
(BL)</li>
</ul>
</font></td>
</tr>
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.1
(December 12, 2001)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Improve and update the configuration javadocs to reflect the new
namespace support.
(JT)</li>
<li>
<img src="images/remove.jpg" border="0" alt="deleted" align="absmiddle">
Deprecate the Loggable and AbstractLoggable classes, and replace
them with LogEnabled and AbstractLogEnabled.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add an abstraction layer to the Logging implementation. Thanks
to Peter Donald for supplying the interface.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add Namespace support to Configuration files.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add AvalonFormatter that was in LogKit's heirarchy. This way, we
avoid circular dependancies.
(BL)</li>
<li>
<img src="images/fix.jpg" border="0" alt="off" align="absmiddle">
Previously resolve did not throw a ContextException. This made it
difficult to indicate errors resolving objects. It now throws an
exception thus allowing errors to be propogated and recorded.
(PD)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
New ConfigurationSerializer to have your configuration objects persist.
(BL)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Upgrade DefaultConfigurationBuilder to be JAXP compliant,
with the option to pass in your own XMLReader.
(BL)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Configuration objects are now Serializable.
(PD)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add new support to ask a component manager if it has a component.
(BL)</li>
<li>
<img src="images/fix.jpg" border="0" alt="off" align="absmiddle">
Bug fixes for documentation
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Update developers docs to support new configuration methods.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Improved "Hello World" documentation.
(PH)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add UML diagrams supplied by Dieter Wimberger
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Add new author bios.
(BL)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Update build process to proposed standard.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Added a method to Version to parse a Version from a string. Added
accessor
methods to Version to allow access to major/minor/micro components of
version.
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Updated Version class to refer to micro version rather than revision.
This
is to match the terminology for JDK versioning. This is just
documentation
changes.
(PD)</li>
<li>
<img src="images/fix.jpg" border="0" alt="off" align="absmiddle">
Changed access of Enum and ValuedEnum constructors from public to
protected, to prevent Enum users from breaking type-safety by adding new
Enum items. This breaks backwards-compatibility in cases where Enum
and ValuedEnum were being incorrectly used.
(JT)</li>
</ul>
</font></td>
</tr>
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.0
(July 30, 2001)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Added new method to Component Manager and Selector for discovering
if a Component exists inside or not. Also augmented the default
versions with the basic implementation to discover them.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Added stylesheet to convert Stylebook markup to DocBook markup.
(BL)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Changed the documentation build process to use Cocoon to build
the site.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Added new "Developing with Avalon" book in DocBook format.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Added Executable interface to activity package.
(PD)</li>
<li>
<img src="images/fix.jpg" border="0" alt="off" align="absmiddle">
Updated Resolvable interface to allow a ContextException to be thrown
on failure.
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Add a makeReadOnly() method to the default implementations of
Configuration,
Context and ComponentManager. Calling this method after the respective
object has been filled will make the object read-only. This is a safety
precaution to stop code performing unwanted operations.
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Updated the javadocs of many of the classes.
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Update documentation so that it is more accurate and descriptive.
(BL)</li>
</ul>
</font></td>
</tr>
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.0b3
(June 6, 2001)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Release 4.0b3
(BL)</li>
<li>
<img src="images/fix.jpg" border="0" alt="off" align="absmiddle">
Made DefaultComponentManager/Selector, DefaultContext, and
DefaultConfiguration read-only to avoid bad programming
practices by clients.
(PD)</li>
</ul>
</font></td>
</tr>
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.0b2
(June 4, 2001)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Release 4.0b2
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Add makeReadOnly() method to default implementations to prevent
alteration after they are set up.
(PD)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Removed the "throws Exception" from Disposable interface. That was
inadvertently left in the previous release.
(BL)</li>
<li>
<img src="images/add.jpg" border="0" alt="added" align="absmiddle">
Added extra methods to Parameters to throw exceptions if the value
does not exist. They are the "no default value" methods.
(BL)</li>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Updated javadocs for Framework.
(PD)</li>
</ul>
</font></td>
</tr>
<tr>
<td bgcolor="#525D76"><font face="arial,helvetica,sanserif"
color="#ffffff"><b>Revision 4.0b1
(May 11, 2001)
</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<ul>
<li>
<img src="images/update.jpg" border="0" alt="changed" align="absmiddle">
Official release
(BL)</li>
</ul>
</font></td>
</tr>
</table>
</div>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/for-developers-project-structure.html
Index: for-developers-project-structure.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Project Structure</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Project Structure</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Project Structure</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">Avalon Framework is not very big, codewise. It is usually
quite easy to find
what you need. This document provides an overview of the project structure. It
is still under construction.</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Package structure</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
org.apache.avalon.framework
|
|- activity
|- component
|- configuration
|- context
|- logger
|- parameters
|- service
|- thread
</pre>
</td>
</tr>
</table>
</div>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>CVS Directory structure</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
jakarta-avalon
|
|- lib : for third party libraries
|
|- src
| |
| |- compat : deprecated stuff
| |- conf : jar manifest
| |- documentation : cocoon configuration
| |- java : java sources
| |- logos : avalon logo sources
| |- make : no idea
| |- proposal : place for ideas to nurture
| |- scratchpad : place for nonsupported, unstable code
| |- skins : cocoon configuration
| |- test : unit tests
| |- xdocs : site documentation in xml format
|
|- tools
| |
| |- bin : scripts to run our personal ant and cocoon copies
| |- documentation : cocoon configuration
| |- etc : misc stuff
| |- ext : optional libraries used in the build process
| |- lib : libraries used in the build process
|
|- build.xml
|
|- BUILDING.txt
|- LICENSE.txt
|- README.txt
|- TODO.txt
</pre>
</td>
</tr>
</table>
</div>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1 jakarta-avalon-site/docs/framework/getting-started.html
Index: getting-started.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Getting Started</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Getting Started</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Getting Started</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">If you are completely new to Avalon, the Framework
subproject is not
the easiest place to start. We suggest you take a look at the
<a
href="http://jakarta.apache.org/avalon/phoenix/getting-started.html";>Avalon
Phoenix getting started document</a>
first, as it will take you through downloading, installing and then
running something (a very simple server program) much more concrete.</p>
<p align="justify">Probably the next smart step is to learn by example. Take
a look at
one or two of the <a
href="http://jakarta.apache.org/avalon/apps";>applications</a>
that use avalon and at how well these are set up, and at some of the
available <a
href="http://jakarta.apache.org/avalon/excalibur";>components (in Excalibur)</a>
and <a href="http://jakarta.apache.org/avalon/cornerstone";>services (in
Cornerstone)</a>
Avalon offers.</p>
<p align="justify">You will find that the Framework has an important role in
each and
every one of these. To learn what that role is and how it fulfills this
role, you should read our guide, which starts with a summary of
<a href="guide-oop-best-practices.html">OOP best practices</a>.</p>
<p align="justify">When you get stuck in sources, documentation, and the
mailing list archive,
post your questions to the mailing list (information on it is
<a href="http://jakarta.apache.org/site/mail.html";>here</a>). For
many, Avalon poses a steep learning curve, and we'll try and help you
flatten it as much as we can.</p>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-cop-in-avalon.html
Index: guide-cop-in-avalon.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - COP in Avalon</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - COP in Avalon</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - COP in Avalon</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Components in Avalon</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
At the core of the Avalon framework is the Component. We define it as
"a
passive entity that performs a specific role". This is important to
grasp
because it requires a specific way of thinking.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>A passive API</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
A passive entity must employ a passive API. A passive API is one
that is
acted upon, versus one that acts itself. See the
<a href="guide-patterns-ioc.html">Inversion of Control</a> pattern
for an explanation.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>A specific Role</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The concept of roles come from the theater. A play, musical,
or movie will have a certain number of roles that actors play.
Although there never seems to be a shortage of actors, there
are a finite number of roles. I am not going to make reference
to different types of roles at this point, but simply bring
the concept to light. The function or action of a role is
defined by it's script.
</p>
<p align="justify">
We are introducing this concept now because you need to have it
in mind when you are designing your system architecture. Think
of the different roles in your system, and you will have your
"cast" of components so to speak.
</p>
<p align="justify">
For each role, you need to specify it's script, or interface to
the rest of the system. To be honest the interface is not enough.
There are specific contracts that you must define and keep in mind
when you specify your interfaces. In other words, what users
of the Component must provide, and what the Component produces.
When the interface and contract are defined, you can work on your
implementation.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>The Component</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
John Donne wrote, "No man is an island." to communicate that we
are all interdependent. The same is true for the Component. That
is why there are different concerns regarding the Component. In
the section on roles we specified one of the concerns: the role.
The concerns directly supported by the Avalon Framework are:
configuration, external component use, management, and execution.
</p>
<note>
We used to have an marker interface Component. This has been
deprecated
because requiring all components extend this interface makes
integrating Avalon with other component systems like
<a href="http://www.corba.org";>CORBA</a> very cumbersome.
</note>
<p align="justify">
As you might of guessed, each one of these concerns has a separate
interface that describes that concern. We will delve deeper into
the interfaces and the reasoning behind them in other sections. It
is important to know the order of precedence for the concerns so
that you know the overall contracts of how they are put together.
</p>
<ol>
<li>
<em>Configurable:</em> marks an object that can be configured.
</li>
<li>
<em>Composable:</em> marks an object that uses Components.
</li>
<li>
<em>Initializable:</em> marks an object that can be initialized.
</li>
<li>
<em>Disposable:</em> marks an object that can be disposed.
</li>
<li>
<em>Stoppable:</em> marks an object that can be started and stopped.
</li>
</ol>
<p align="justify">
The contract surrounding this order means that the methods defined
by each of those interfaces are called in a specific order by the
object
that created the Component. Each interface represents a narrow view
of the Component or object being controlled.
</p>
<note>
Notice that each interface is separate from Component, so you can use
them for simple objects.
</note>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>The Composable</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
In Avalon, Composable is defined as an active entity that controls
or uses Components. Its best analogy is that of a musical composer.
The musical composer chooses what instruments (Components) by their
role in the symphony (system) and tells them which notes to play.
</p>
<p align="justify">
The Avalon Composable follows the principles of Inversion of Control,
and is assigned a Component Manager. Within this section we will
discuss how to look up specific Components, and then how to prepare
the ComponentManager for the Composable.
</p>
<note>
The Composable has a specific contract that must be enforced for
security
reasons. The ComponentManager must only be set once. That means that
the <code>compose</code> method must ignore all subsequent
requests to set the ComponentManager after it is successfully set.
</note>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Finding your Component</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>The Component Manager</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
For the majority of all cases, you will need to use the
ComponentManager
get the instance of the Component you need. If you recall the
discussion
on Component Roles in the Component documentation, you already have
a head start. In Avalon, Roles are defined by the work interface a
Component has. A work interface is different from any other
interface
because it is the interface that defines the Component's Role.
Composable
and Component are concern interfaces because they address specific
concerns about the Component.
</p>
<p align="justify">
The ComponentManager has one method to retrieve all of your
Components.
The <code>lookup</code> method will look up the Component based on
the
fully qualified name (FQN) of the work interface (Role). It is
important
to realize that the ComponentManager returns Components, and
therefore
you must recast the Component to the Role you need. See the
following
example:
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
final MyComponent component = (MyComponent)manager.
lookup( "com.mycompany.myproject.MyComponent" );
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
It is important to note that Role is not the same thing as
functional
equivalence. In other words, if you have a MailSpooler that is
functionally
equivalent to a FileStore (they do the same thing), it does not
mean that
they perform the same Role. The FileStore is used to store objects
to
files, and the MailSpooler is used to temporarily store messages
until
they are sent. Thus they are separate roles. Sometimes you need to
create a new interface name that does nothing more than allow
access to
alternate roles who have the same role.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>The Component Selector</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Sometimes you will have several Components that function in the
same role.
For those cases, you will use the ComponentSelector to choose the
exact
one you need. The best way to describe its proper use is the
scenario
described here. You have several formatters that have the same
Role:
to take an input document and format it according to the rules in
the
individual Component implementations. One formatter may take a
text file
and remove all tabs and replace them with four spaces. Another
formatter
may reverse the formerly mentioned one. Yet another takes the text
file
and formats it for a canvas object. For the Composable, it makes
no difference
what the implementation does--just that it formats the text.
</p>
<p align="justify">
Using the processing chain example in the previous paragraph, we
realize
the unsuitability of the ComponentManager for getting the right
Component.
The Component addresses the concern of one Component per role.
Fortunately,
the ComponentSelector is a Component. That means we use the
ComponentManager
to lookup the ComponentSelector. The ComponentSelector is designed
to choose
the specific Component out of many that perform the <em>same</em>
Role. The following code will help:
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
final ComponentSelector selector = (ComponentSelector)manager.
lookup( "org.mycompany.myproject.FormatterSelector" );
final Formatter formatter = (Formatter)selector.select( myURL );
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
The selector does not discriminate against lookup keys. In that
respect it
acts much like a hashtable lookup. Keep in mind that the
implementation of the
selector does not limit you to a hashtable lookup--you can
dynamically
instantiate objects as well. It takes an object (a hint), and
returns the
specific Component based on that hint.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>When you are done with the Component</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Both the ComponentManager and the ComponentSelector require you to
release your Component when you are done with it. The method used
to do this is "release". One way of handling this is to use the
try/catch/finally construct. For your convenience, the following
code can help:
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
MyComponent component = null;
try
{
component = (MyComponent) manager.lookup("org.mycom.MyComponent");
component.myMethod();
}
catch (Exception e)
{
getLogger().debug("Error using MyComponent", e);
}
finally
{
if (component != null) manager.release(component);
}
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
The reason for this is so that smart Component Managers that
select Components from a pool can properly manage the resources.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Populating the ComponentManager</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
It is the responsibility of the entity that creates the Composable to
give it a
ComponentManager with all of the Roles populated. If you create your
own
implementations of the ComponentManager and ComponentSelector then
you have
the liberty of deciding how to populate them. Keep in mind that
there are
default implementations included, and you should model their behavior
as
much as possible.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>DefaultComponentManager</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The DefaultComponentManager is nothing more than a Hashtable lookup
of roles
and Components. It even gives you the method <code>put</code> to
populate
the ComponentManager. One feature of the DefaultComponentManager
is that
it can cascade. In other words, if the role is not found in this
ComponentManager,
the default implementation will look in the parent ComponentManager.
</p>
<p align="justify">
For the paranoid developer, the Cascading feature of the
ComponentManager
can be seen as a security hole as opposed to a usability
enhancement. You
are free to create your own implementation that does not use the
Cascading
feature--but you have to manually populate it with anything that
would
have been in the parent ComponentManager that your child Composable
needs.
Truth be told, there is very little risk due to the set-once
contract for
ComponentManagers. The method is never exposed to hostile agents
before
the ComponentManager is set.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>DefaultComponentSelector</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The DefaultComponentSelector again is simply a Hashtable selection
of Components
based on hints. It gives the method <code>put</code> to populate
the ComponentSelector.
The ComponentSelector does not have the cascading feature of the
ComponentManager,
nor should it. A ComponentSelector simply holds a number of
Components that
implement the same role--there really is no need to cascade.
</p>
<p align="justify">
After the ComponentSelector is populated, you must put it in the
ComponentManager.
Please use the role of the Component you are selecting, not the
role of the selector
itself. An acceptable convention is to add the "Selector" name to
the end of the
Role you are looking up. Just be consistent.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1 jakarta-avalon-site/docs/framework/guide-cop-what-is.html
Index: guide-cop-what-is.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - What is COP?</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - What is COP?</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - What is COP?</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Component Oriented Programming, or COP for short, takes Object
Oriented
Programming one step further. Regular OOP organizes data object into
entities that take care of themselves. There are many advantages to
this
approach. I'll assume that you, being a java programmer, are familiar
with those.
</p>
<p align="justify">
It also has a big limitation: that of object co-dependency. To remove
that
limitation, a more rigid idea had to be formalized: the Component.
The key
difference between a regular object and a component is that a
component is
completely replaceable.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>COP is not just a buzzword</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
There is a lot of buzz in the industry touting Component Based Design
(CBD). You will find, that the definition of a Component in Avalon
is more formal than most companies' definition of a Component. Any
system developed with the principles of Avalon can claim CBD. In
fact the Avalon Framework formalizes CBD more rigidly than the marketing
definition. Do not be fooled though, CBD and COP aren't necessarily
the same thing. Component Based Design refers to how a system is
designed and not how it is implemented. Component Oriented Programming,
on the other hand, refers to how a system is implemented and not how
it is designed. In practice, you can't implement COP without first
designing with Components in mind.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-oop-best-practices.html
Index: guide-oop-best-practices.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - OOP best practices</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - OOP best practices</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - OOP best practices</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
While Avalon is not really about Object-Oriented Programming (OOP)
(we go much further), some of its concepts are important in
any programming project, so we summarise the 12 rules for code reuse
as given in
<a href="http://www.laputan.org/drc/drc.html";>
"Designing Reusable Classes"
</a> by Ralph E. Johnson and Brian Foote (an excellent book).
</p>
<p align="justify">
Note that a good knowledge of the basic OOP concepts is a requirment
for
understanding any of this. Many books deal with this, one that is
freely
available online is
<a href="http://www.mindview.net/Books/TIJ/";>
"Thinking in Java"
</a> by Bruce Eckel (also a recommended read).
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Recursion Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Use the same interface for communication with components of
the same type. It allows the swapping of those components
for other components of the same type without breaking existing
code.
</p>
<p align="justify">
If you need additional functionality, either create proxy
objects that implement the interface, or add it by subclassing
(hence the name "Recursion Introduction". Even if
there is no recursion happening, it appears to operate in the
same manner.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Eliminate Case Analysis</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Avoid testing to see if an object is an instance of a particular
class. Usually, if you think you need that approach then a
redesign will help immensely.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Reduce the Number of Arguments</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Methods with a half-dozen arguments are hard to read, and can
usually be accomplished with an object that represents that
set of arguments. It also makes it easier to track down the
problems.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Reduce the Size of Methods</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Most of your methods should only need to be a few lines long.
Methods that are very long (like 50 lines or so) are too complex,
and should be considered guilty of bad design until proven
innocent.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>The Top of the Class Heirarchy Should be Abstract</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
In many cases it is beneficial to provide an abstract base class
to extend for your specializations. The majority of the
functionality and behavior is well defined. This makes it easier
to decipher what the intents of the interface designer were.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Minimize Accesses to Variables</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
This point formalizes the principles of data hiding. Try not
to expose class attributes to other classes, but protect them
by methods. If an attribute changes name, then you only have
one place to update the code instead of hundreds.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Subclasses Should be Specializations</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
A [subclass] "is a" [superclass]. If what you
are trying to do is make a Component into a ComponentManager,
then you are violating the spirit of the framework. A better
approach is to use containment in that case (i.e. a [class]
"has a" [external class]).
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Split Large Classes</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
If a class has 50+ methods, then it is most likely trying to
do too much. Look at separating the functionality into
separate components. Like methods that are too long, classes
that violate this rule should be considered guilty of wrong
design until proven innocent.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Factor Implementation Differences Into
Subcomponents</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
If a subclass implements a method completely different from
the superclass, then it is not really a specialization. It
should be split off from that class hierarchy tree.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Separate Methods that Do Not Communicate</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Sometimes in building a framework you run into a case where
you have different views of the same data. In these cases,
you can have some attributes that describe how to generate
the data, and some attributes that describe the data itself.
It is better to separate these two views into separate classes.
The semantics are different enough to justify this solution.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Send Messages to Components instead of to This</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The point of this point is that you want to build your framework
based on Components, and not inheritance. Avalon takes this
point to heart. In order to illustrate, I will give two examples
of the same thing. The scenario is that we have a data structure
that we want to output to an arbitrary format.
</p>
<p align="justify">
In the following example, we will use the java <code>this</code>
object and an inheritance based framework. As you can see, this
would be a bear to maintain, and it won't easily be extended.
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
abstract class AbstractExampleDocument
{
// skip some code ...
public void output(Example structure)
{
if( null != structure )
{
this.format( structure );
}
}
protected void format(Example structure);
}
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
In the next example, we will use the Avalon Component based
architecture. There is a clean separation between the purpose
of the objects, and you can exchange and extend formatting
without worrying about any other concerns.
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
class DefaultExampleDocument
{
// skip some code ...
public void output(Example structure)
{
ExampleFormatter formatter =
(ExampleFormatter) manager.lookup(Roles.FORMATTER);
if( null != structure )
{
formatter.format(structure);
}
}
}
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
An inheritance based framework (White Box) can be converted
into a component based framework (Black Box) structure by
replacing overridden methods by method calls (message sends)
to components. Component based architecture is much more
flexible in this regard.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Eliminate Implicit Parameter Passing</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Just because two methods share the same information within the
class does not mean that it should be done in that manner.
Many times, that attribute that is shared should be passed
as a parameter of the method instead of directly accessing
the attribute.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-patterns-in-avalon.html
Index: guide-patterns-in-avalon.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - Patterns in Avalon</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - Patterns in Avalon</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - Patterns in Avalon</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Leo simons</a>, <a href="mailto:[EMAIL
PROTECTED]">Paul Hammant</a>, <a href="mailto:[EMAIL PROTECTED]">Peter
Donald</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Getting Started with Patterns</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Avalon takes many design patterns and architectural mindsets, and
implements the best ones for Servers. There are different kinds of
patterns that represent different aspects of Avalon. Avalon uses four
main conceptual patterns called Separation of Interface and
Implementation, Inversion of Control, Multi-Dimensional Separation
of Concerns, and Aspect Oriented Programming. Avalon also uses
several
architectural patterns like the Singleton and the Factory.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>The Avalon Patterns in short</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
We provide you with a short description of the patterns first, with a
detailed description of each pattern on a separate page.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Separation of Interface and Implementation</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
<b>Summary:</b> The Separation of Interface and Implementation is
a core feature of the Java language. However, it is misused so that we
list it as one of the Avalon patterns, as our use of it is extensive.
</p>
<p align="justify">
<a href="guide-patterns-soii.html">
More Information...
</a>
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Inversion of Control</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
<b>Summary:</b> Avalon not only has an inheritance hierarchy, but also a
Component hierarchy. In this hierarchy, the control of program flow is
completely in the hands of the parent component(s), as soldiers in the
military take orders from their officers.
</p>
<p align="justify">
<a href="guide-patterns-ioc.html">
More Information...
</a>
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Multi-Dimensional Separation of Concerns</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
<b>Summary:</b> You just read the introduction about patterns before
reading about Avalon's patterns because that enables you to reuse the
knowledge you gained about patterns in context other than that of
Avalon. We do this with software as well.
</p>
<p align="justify">
<a href="guide-patterns-soc.html">
More Information...
</a>
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Aspect-Oriented Programming</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
<b>Summary:</b> this is the next logical step ofter Separation of
Concerns. Many concerns cannot be centrally addressed using the
standard
OOP mechanisms. Using AOP (which is an extension to OOP), we would be
able to do so in a simple fashion. As there is no good AOP facility
in java, we use "aspect marker interfaces" and COP instead.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Component-Oriented Programming</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
<b>Summary:</b> The Avalon framework promotes black-box reuse at
every level. Doing so is commonly known as COP. This is so important
in Avalon we devote an
<a href="guide-cop-what-is.html">
entire section
</a>
to it.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-patterns-ioc.html
Index: guide-patterns-ioc.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - Inversion of Control</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - Inversion of Control</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - Inversion of Control</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
One of the key design principles behind Avalon is the principle
of <em>Inversion of Control</em>. <em>Inversion of Control</em> is
a concept promoted by one of the founders of the Avalon project,
<a href="mailto:[EMAIL PROTECTED]">Stefano Mazzocchi</a>. The
principle enforces security by design.
</p>
<p align="justify">
It is difficult to track down one paper that defines this pattern
at length, so here are a couple of different definitions of
<em>Inversion of Control</em>.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>What it Means</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The Framework plays the role of the main program in coordinating
and sequencing events and application activity.
</p>
<p align="justify">
A designer sets up a chain among objects that can all react
to certain messages in a delegation hierarchy. There is one
major semantic detail: Inversion of Control refers to a parent
object <em>controlling</em> a child object. With this distinction,
the SAX API is not considered Inversion of Control because its
purpose is to send <em>information</em> from a source to a handler.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Definition by Analogy</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
There are a couple of different analogies that make
understanding <em>Inversion of Control</em> easier. We
experience this in many different ways in regular life,
so we are borrowing the form in code. One analogy is called
the "Chain of Command" in the military.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="98%">
<tr>
<td bgcolor="e8f8ff"><font face="arial,helvetica,sanserif" color="#000000"
size="-1"><b>Chain of Command</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
This is probably the clearest parallel to <em>Inversion
of Control</em>. The military provides each new recruit
with the basic things they need to operate at their rank,
and issues commands that recruit must obey. The same
principle applies in code. Each Component is given the
provisions they need to operate by the instantiating
entity (i.e. Commanding Officer in this analogy). The
instantiating entity then acts on that Component how it
needs to act.
</p>
<p align="justify">
There are some deficiencies in this analogy as some military
or ex-military people have explained to me. In the military,
<em>any</em> Commanding Officer can issue commands to
anyone under his or her rank. In the development world, to
ensure proper security, this is not a pattern you want in your
software. In Avalon, Inversion of Control (IoC) is from one
parent (controlling) object to a child (controlled) component.
A parent may have many children, but children only have one
parent.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>How to Apply It</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
<em>Inversion of Control</em> is applied in a very simple
manner. Basically, it means that the Component architecture
employs a <em>passive</em> structure. See the following code:
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
class MyComponent
implements Component, LogEnabled
{
Logger logger;
public enableLogging(Logger newLogger)
{
this.logger = newLogger;
}
myMethod()
{
logger.info("Hello World!");
}
}
</pre>
</td>
</tr>
</table>
</div>
<p align="justify">
The parent of MyComponent instantiates MyComponent, sets the
Logger, and calls myMethod. The Component is not autonomous,
and is given a Logger that has been configured by the parent.
</p>
<p align="justify">
The MyComponent class has no state apart from the parent, and
has no way of obtaining a reference to the Logger implementation
without the parent giving it the implementation it needs.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>IOC promotes Security</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">A big advantage of IOC for server applications is that it
promotes
security. You can read an analysis about this
<a href="guide-patterns-ioc-security.html">
here
</a>.</p>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-patterns-ioc-security.html
Index: guide-patterns-ioc-security.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - Security Concerns</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - Security Concerns</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - Security Concerns</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
One major concern for many companies is the security of a system.
In this context security is defined as protection of data, and
quality of service (QOS). Both of these fall under security because
a system must protect itself from these two forms of attack. When
a company loses a system, they lose business, and the money they
lose can reach scary amounts.
</p>
<p align="justify">
For the purpose of this discussion, we will address the first
aspect (protection from crackers and system infiltration). Many
times, the same fixes for this type of protection inherently fix
the other (QOS). System security has three distinct concerns
that have been well defined: authentication, authorization, and
architecture. Why didn't I say encryption? It is because
encryption does not equal security. It is only part of the whole
system.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Authentication</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Authentication is the process of identifying parties. In a
completely
trusted system, authentication is as simple as grabbing a reference
to the object or entity you want to manipulate. However, sometimes
you have trusted systems running in hostile environments (e.g. the
internet). In those cases you have to make sure that the entity
is the correct one.
</p>
<p align="justify">
There are two sides of authentication. On one side, you are
authenticating an entity you want to do business with. On the other
side, there is an entity wanting to do business with you. This is
best understood when you bring it into a financial realm. Let's say
you want to get a loan from XYZ bank. If you initiate the exchange
at their facility, you have already authenticated them--although you
will have to jump through hoops to authenticate yourself. If a
telemarketer calls from ACME Loan Machine, Inc., they know who you
are--although if you are smart, you will make them jump through
hoops to authenticate themselves.
</p>
<p align="justify">
Currently, Avalon identifies Blocks as trusted parties. In other
words, the fact that they are installed correctly in the proper
directory is enough to mark them as authenticated. Much like a
good friend--you know them by their voice. Because of the
architecture
of Avalon, Blocks define their own authentication system. That
means that whether the Block assumes all Components are trusted
or it forces the blocks to authenticate themselves is up to the
block.
</p>
<p align="justify">
For systems that deal with sensitive information, authentication
becomes more of an issue. You must validate that the Components
in use are the ones you have authorized for use. The more open a
system is, the more authentication and authorization play an
important
role. If you have Components that are transmitted over some form
of communications system (wire, air, etc.) you must verify that
they are who they say they are.
</p>
<p align="justify">
For this purpose, protocols like Kerberos and Leighton-Micali have
been defined. It is beyond the scope of this page to discuss the
pros and cons of each system.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Authorization</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Once a Component has been authenticated (in other words it's
identity
has been authoritatively validated), then you must decide what
access
it has to your systems. A fully trusted Component can do what it
likes.
An untrusted Component must be denied functions it is not allowed.
</p>
<p align="justify">
Authorization is part of the architecture, but is significant enough
to warrant it's own concern. The best rule of thumb is to hide
access
to everything unless the Component is trusted. When hiding is not
an option, then you have to resort to denying access. For the
security
conscious, all denied accesses should be logged along with the
Component's
identifier.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Architecture</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Avalon already has the framework for the proper secure architecture.
With proper planning, security can be added without recoding the
Components.
However there are some rules of thumb for paranoid programming.
</p>
<ol>
<li>
Never expose anything that does not need to be exposed.
Information
hiding is as important in security as it is in Component
Oriented Programming (COP).
</li>
<li>
Any Component that originates from your own jar should be
trusted--you
provided it after all.
</li>
<li>
Any Component that originates from another source, and especially
over
a wire, should be treated with suspicion. Authenticate it, and
if it
checks out, trust it. Otherwise, don't give it access--you don't
know
where it's been or who created it.
</li>
<li>
Encrypt <em>all</em> communications. Period.
</li>
</ol>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>From the Sublime to the Ridiculous</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Throughout my short career I have been exposed to a wide range of
security
implementations. Having worked for a DoD contractor, I learned about
physical
security requirements (how to manage paper files, and the rules and
regulations
regarding secure information). However in a recent attempt to
install a
solution at our customer's site, I learned more about computer
security
than I have at any other time.
</p>
<p align="justify">
Our customer, a well known corporation whom I will call ACME for
anonymity, is in custody of sensitive information. Product movement
data,
financial data, and demographic data are all stored in one of a couple
huge server farms. Our application was to reside in the De-Militarize
Zone (DMZ), and talk to a database behind the firewall. When they
discovered
that the application server we chose required Remote Procedure Calls
(the
subject of many CERT advisories in the Unix world), we hit a brick
wall. Our
application was no longer trusted, and was not to be installed.
Luckily
the next version of the application server fixed that problem.
</p>
<p align="justify">
In the midst of this, I decided to learn as much as I could about
operating
in a hardened environment. Hardening involves turning off access to
anything
that is not needed, and only allowing what is needed. All mail
servers, ftp
servers, rpc services, telnet, and any other clear text
communications ports need
to be removed. All communication into and out of the box needs to be
encrypted, with the exception of HTTP (although we were using HTTPS).
</p>
<p align="justify">
All of this was necessary. I understand the principles behind it.
However,
I decided to ask their security analyst how to learn more--so we
don't run
into this problem again. He gave me a link to
<a href="http://www.sans.org";>SANS institute</a> and a word of
advice: "Be paranoid. Don't trust anything."
</p>
<p align="justify">
There is a point where the aforementioned philosophy goes a bit too
far. The
case in point relates to a story I heard working with the DoD.
During the
height of the "Cold War" between the US and Russia, a US commanding
officer required that all the computers be placed on these huge power
conditioners to reduce the Electro-Magnetic Interference (EMI) coming
from the
power line feedback of the computers. His rationalization was that
he was
positive KGB agents had the technology that they could read the EMI
interference
on the power lines and read the bits on the computers. In hind sight
this is
improbable; no one can identify the bits travelling on a computer from
EMI in the
power lines due to the level of noise (clocks, addressing lines,
<em>encrypted data</em>, and other computers on the network).
</p>
<p align="justify">
The security industry have a general rule of thumb to ensure that you
don't spend
too much time in this area: The cost of cracking the server should
be more than
the information that is protected is worth. Basically it boils down to
this:
sites like Slashdot and SourceForge do not require as much security as
a Bank.
Protecting free information is not as critical as protecting peoples
bank accounts.
I am not minimizing the contributions of the aforementioned sites to
the world
as a whole, but people become much more agitated if their bank account
is wiped
clean than if their news article is defaced. This is not to say that
if you are
protecting free information then you can safely ignore security. While
the information
is monetarily free to customers, it has value that can be measured in
pride, respect,
and accountability.
</p>
<p align="justify">
The moral of the story is be paranoid to a point. Avalon is designed
to be
a trusted system, and will be improved to work in an untrusted
network.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-patterns-soc.html
Index: guide-patterns-soc.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - Multi Dimensional Separation of
Concerns</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - Multi Dimensional Separation of
Concerns</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - Multi Dimensional Separation of Concerns</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The concept of using different points of view within the the system
goes a long way in the overall comprehension of the system.
</p>
<p align="justify">You can get more formal information in this paper:
<a
href="http://www.research.ibm.com/hyperspace/MDSOC.htm";>Multi-Dimensional
Separation of Concerns</a>.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>What it Means</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
"Separation of Concerns" in its simplest form is separating
a problem into different points of view. For instance, the
documentation
uses the "Separation of Concerns" pattern to make the documents
comprehensible (we have separate documents for Developers,
Administrators,
and Block Implementers). The documents also use the pattern with
XML and
XSL so that the look is separated from the content. Either can
change
without breaking the other.
</p>
<p align="justify">
This pattern is less clear to point out in the code, however the
concept
is evident. There are several interfaces included in Avalon that
identify
an object's role within the system. For instance, all Components
have certain
contracts -- therefore any object that implements the Component
interface
must comply with those Contracts. This allows developers to
manipulate
Components using a standard interface, without worrying about the
semantics
of the implementation. They are separate concerns.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>How to Use It</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
There are many ways to separate concern areas, but in Avalon
we use interfaces to define the concern areas addressed in
code.
</p>
<p align="justify">
Every time you use interfaces within Object Oriented Programming
(OOP),
you are using the "Separation of Concerns" Pattern. The interface
separates the concern of the implementation from the concern of the
user
of the interface. For example, every Object that can be configured
implements the Configurable interface. The contract surrounding the
Configurable interface is that the instantiator of the object
passes a
Configuration object to the Configurable object (see "Inversion
of Control"). Just what the Configurable object does with the
passed Configuration object is irrelevant to the instantiator.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-patterns-soii.html
Index: guide-patterns-soii.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - Separation of Interface and
Implementation</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - Separation of Interface and
Implementation</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - Separation of Interface and Implementation</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Paul Hammant</a>, <a
href="mailto:[EMAIL PROTECTED]">Peter Donald</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The core concept of interface and implementation separation is built
into
Java itself in that it has interfaces and classes. Many toolkits have
been developed along the lines of an API / implementation separation.
One such toolkit is the SAX API and the multiple XML parsers that
implement
it. Developers are quite happy using Apache's Xerces via the SAX API
and
understand that SAX represents the interface and Xerces an
implementation.
We notice that a lot of developers are happy to use interface/impl
separated tools, but not to make them. We will try to justify in this
document why we think people making applications should define
interface/impl boundaries early in the design cycle.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Justification</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The main reason we do it is because:
<ol>
<li>it forces you to decouple different modules/components/objects</li>
<li>if specified correctly allows you to easily change the implementation of
the interface/contract in the future</li>
<li>makes it possible for a user to read documentation about interface
without having the implementation details clutter up their
perception</li>
<li>increases the possibility of reuse in a larger application</li>
</ol>
</p>
<p align="justify">
If you are building objects with the aim of reuse then [2] is
important but
most people don't build for reuse (and most XP advocates say you
should just
plan to use not reuse) and thus [1] and [2] are more important. If
you feel
like documenting that and expanding this then feel free to.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Example</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Let us hope this is not necessary:
</p>
<div align="center">
<table cellspacing="2" cellpadding="2" border="1">
<tr>
<td>
<pre>
package helloworld;
public interface HelloWorld {
void sayHello(String greeting);
}
package helloworld.impl.default;
public class DefaultHelloWorld implements HelloWorld {
void sayHello(String greeting) {
System.out.println("HelloWorld Greeting: " + greeting);
}
}
package helloworld.impl.remote;
public class RemoteHelloWorld implements HelloWorld {
private RemoteMessager mRemoteMessager;
public RemoteHelloWorld(RemoteMessager rm) {
RemoteMessager = rm;
}
void sayHello(String greeting) {
rm.sendMessage("HelloWorld Greeting: " + greeting);
}
}
</pre>
</td>
</tr>
</table>
</div>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>History</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
We are referring to this pattern at <em>interface/impl
separation</em>.
Wiley's Patterns in Java book refers to it simply as 'Interface',
but we feel
that the word interface is overloaded enough in English and
computing.
</p>
<p align="justify">
It might be true to say that this is 'API/implementation
separation', but
this too could be confusing as the aforementioned SAX is not quite a
pure set of interfaces. It has a static factory that thunks in an
implementation that all subsequent calls to the factory method will
be
forced to use. See Anti-patterns below.
</p>
<p align="justify">
Better might be 'separation of implementation and the
interface/contract' as
that is quite correct, but a tad unwieldy.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Related topics</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Implementation hiding</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Once a tool is split into interface and impl, it is possible for a
container
to hide the implementation. Most containers already use dynamic
proxys
(Available in the JDK since 1.3), but we are talking about having
the classes
of the implementation hidden from classes using the interface.
</p>
<p align="justify">
To do this, it is easiest to mount the impl classes in a separate
classloader
to the classloader that the interface-using classes are mounted in.
The
interfaces being mounted in a classloader that is visible to both.
</p>
<p align="justify">
This is not a new proposition. Sun defined the servlet spec, and
included
rules about implementation hiding for hosted servlets. Essentially,
instantiated servlets are only allowed to 'see' classes from the
JDK, their
own WAR file and those of the Servlet API itself. Tomcat correctly
hides
the implementation of the Servlet API from the hosted servlets.
</p>
<p align="justify">
To actually achieve this separation, many containers (including
those from
the Avalon project) require that the interface and impl are in
separate jars.
Or to put it another way, there is no point separating your
interface and impl
classes if you are going to distribute them in the same jar.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Kernel, Client API, Hosted Components</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
This is building the previous section, and in short is referred to
as K/CAPI/HC.
Basically the Kernel mounts hosted components and satisfies their
need for a
client API. However the kernel wants to hide its implementation
from the hosted
components.
</p>
<p align="justify">
An EJB container is another good example of this. EntityBean,
SessionBean etc is
the client API. The hosted components are the beans, and the
container has a
kernel. It builds a complex tree of classloaders to separate its
implementation,
the client API, the JDK's runtime jar (that always being in the
system or
primordial classloader), and the hosted components.
</p>
<p align="justify">
The central message of this is that it you have interface/impl
separated your
tool, and are doing tricky things with more classloaders in the
implementation,
please make sure you do not assume that the parent classloader of
any classloader
is the system classloader. If your reusable tool has been taken by
another team
and at some non root place in a classloader tree, then the tools
will fail if
you have made such assumptions.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Anti-patterns</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
SAX, mentioned in multiple contexts in this document, is also an
example of
where the design can go wrong. The Factory is static (that in
itself is an
anti-pattern to IoC). Despite giving the appearance of having the
ability
to generate a parser based on the implementation's class name, only
the first
caller of that method will register a parser for the whole
environment to use.
</p>
<p align="justify">
Given that the SAX API is now in the JDK, the environment we allude
to above
is the whole JVM. This is a problem because in a very complex
application
with differing concurrent needs for implementation of parsers, not
all can be
met if the SAX API is used for making parsers.
</p>
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-patterns-what-are.html
Index: guide-patterns-what-are.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - What are Design Patterns?</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - What are Design Patterns?</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - What are Design Patterns?</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Getting Started with Patterns</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
I highly recommend reading the
<a
href="http://www6.software.ibm.com/developerworks/education/j-patterns/index.html";>
"Java Design patterns 101"
</a> tutorial, and its follow-up
<a
href="http://www6.software.ibm.com/developerworks/education/j-patterns201/index.html";>
"Java Design patterns 201"
</a>, if you are unfamiliar with the concept of Design Patterns (and
see below for more information). Note that you have to register at the
IBM DeveloperWorks site in order to read these, but that's a good idea
anyway.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Where to learn more</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
You can find more information about patterns from the following links:
</p>
<ol>
<li>Brian Foote's <a href="http://www.laputan.org/foote/papers.html";>Pattern
documents</a>
</li>
<li>
<a
href="http://www6.software.ibm.com/developerworks/education/j-patterns/index.html";>
"Java Design patterns 101"
</a> at DeveloperWorks</li>
<li>
<a
href="http://www6.software.ibm.com/developerworks/education/j-patterns201/index.html";>
"Java Design patterns 201"
</a> at DeveloperWorks</li>
<li>
<a href="http://cseng.aw.com/book/0,3828,0201633612,00.html";>
"Java Design patterns: Elements of Reusable Object-Oriented
Software"
</a> by the GoF (printed book)</li>
</ol>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/guide-where-to-go-from-here.html
Index: guide-where-to-go-from-here.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - Guide - Where to go next</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - Guide - Where to go next</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - Guide - Where to go next</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>There's a lot more to study</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
Each of the pages in this short guide deserves an entire book, and
indeed, most of them have a lot of documentation devoted to them.
Here we provide you with pointers where else to look for more
information, within and outside of Avalon.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Creating components</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
After all the information in this guide has sunk in, you're probably
itching to write an Avalon Component. Our
<a href="http://jakarta.apache.org/avalon/developing";>
Developing with Avalon guide
</a> takes you through doing just that. You can download it as a PDF
and read at your leisure (it comes down to 56 printed pages). If
that's
too much for you, we suggest you get the latest
<a href="http://jakarta.apache.org/avalon/excalibur";>excalibur</a>
release and
take those components as an example. One application that uses a lot
of
those components and is in widespread daily use is
<a href="http://xml.apache.org/cocoon";>Cocoon</a>.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>More on Avalon's design concepts</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">A collection of links to interesting projects elsewhere on
the web.</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Design patterns</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
TODO
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Aspect-Oriented Programming</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
TODO
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Component-Oriented Programming</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
TODO
</font></td>
</tr>
</table>
</div>
<br>
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
1.1
jakarta-avalon-site/docs/framework/reference-the-lifecycle.html
Index: reference-the-lifecycle.html
===================================================================
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Avalon Framework - The Component Lifecycle</title>
</head>
<body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4"
topmargin="4" alink="#023264" vlink="#023264" link="#525D76" text="#000000">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top"><a
href="http://jakarta.apache.org/index.html";><img src="images/jakarta-logo.gif"
border="0" vspace="0" hspace="0"></a></td><td bgcolor="#ffffff" align="left"
valign="top" width="100%"><img src="images/header.gif" align="right" border="0"
vspace="0" hspace="0"></td>
</tr>
<tr>
<td colspan="2" height="2" width="100%">
<hr size="1" noshade="">
</td>
</tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td valign="top" width="1%"></td><td nowrap="1" valign="top" width="14%">
<br>
<font face="arial,helvetica,sanserif">
<br>
<br>
<a href="http://jakarta.apache.org/";><font size="+1" color="#778899">Jakarta
main</font></a>
<br>
<br>
<a href="http://jakarta.apache.org/avalon";><font size="+1"
color="#778899">Avalon main</font></a>
<br>
<br>
<font size="+1" color="#000000">Essentials</font>
<br>
<font size="-1">
<ul>
<li>
<a href="index.html"><font size="-1">Overview</font></a>
</li>
<li>
<a href="features.html"><font size="-1">Features</font></a>
</li>
<li>
<a href="getting-started.html"><font size="-1">Getting started</font></a>
</li>
<li>
<a
href="http://jakarta.apache.org/builds/jakarta-avalon/release/framework";><font
size="-1">Download</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Guide</font>
<br>
<font size="-1">
<ul>
<li>
<a href="guide-oop-best-practices.html"><font size="-1">OOP best
practices</font></a>
</li>
<li>
<a href="guide-patterns-what-are.html"><font size="-1">What are
patterns?</font></a>
</li>
<li>
<a href="guide-patterns-in-avalon.html"><font size="-1">Patterns in
Avalon</font></a>
</li>
<li>
<a href="guide-cop-what-is.html"><font size="-1">What is COP?</font></a>
</li>
<li>
<a href="guide-cop-in-avalon.html"><font size="-1">COP in Avalon</font></a>
</li>
<li>
<a href="guide-where-to-go-from-here.html"><font size="-1">Where to go from
here</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">Reference</font>
<br>
<font size="-1">
<ul>
<li>
<a href="http://jakarta.apache.org/avalon/api/index.html";><font size="-1">API
Docs</font></a>
</li>
<li>
<a href="diagrams/index.html"><font size="-1">Diagrams Docs</font></a>
</li>
<li>
<a href="reference-the-lifecycle.html"><font size="-1">The
Lifecycle</font></a>
</li>
</ul>
</font>
<br>
<br>
<font size="+1" color="#000000">For Developers</font>
<br>
<font size="-1">
<ul>
<li>
<a href="for-developers-changes.html"><font size="-1">Changes</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/avalon/code-standards.html";><font
size="-1">Coding standards</font></a>
</li>
<li>
<a href="for-developers-project-structure.html"><font size="-1">Project
Structure</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/cvsindex.html";><font
size="-1">CVS</font></a>
</li>
<li>
<a href="http://jakarta.apache.org/site/mail.html";><font size="-1">Mailing
Lists</font></a>
</li>
</ul>
</font>
<br>
<br>
</font></td><td align="left" valign="top" width="*">
<title>Avalon Framework - The Component Lifecycle</title>
<center>
<table width="100%">
<tr>
<td bgcolor="#99aabb">
<center>
<b><font face="arial,helvetica,sanserif" color="#000000" size="+2">Avalon
Framework - The Component Lifecycle</font></b>
</center>
</td>
</tr>
</table>
</center>
<br>
<font size="-2" face="arial,helvetica,sanserif" color="#000000">
<p>by <a href="mailto:[EMAIL PROTECTED]">Berin Loritsch</a>, <a
href="mailto:[EMAIL PROTECTED]">Peter Donald</a>, <a href="mailto:[EMAIL
PROTECTED]">Leo Simons</a>
</p>
</font><font face="arial,helvetica,sanserif" color="#000000"></font>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Introduction</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
A Component lives within something called a container. Avalon
provides an
application that functions as a container for Applications (which are
Components) called <a
href="http://jakarta.apache.org/avalon/phoenix/index.html";>Phoenix</a>.
You can also create your own Components that function as a container.
</p>
<p align="justify">
The contract between a container and a contained Component is simple:
the
container is required to take a Component through what is called its
<em>lifecycle</em>.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>The Lifecycle</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The lifecycle of a Component specifies the methods that can be called
on it,
and the order in which this may happen. Some methods can be called
only once
in a specific <code>Phase</code> of a Component its lifecycle, others
may
be called multiple times. These methods are called the lifecycle
methods.
</p>
<p align="justify">
It is up to each container to indicate which lifecycle methods it
will honor.
This should be clearly documented together with the description of the
container. Phoenix supports all of the lifecycle methods defined in
the
Avalon Framework API.
</p>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>The Lifecycle interfaces</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
A Component exposes its lifecycle methods by implementing the
lifecycle
interfaces. Each of these defines one or more methods that represent a
specific Phase in a Component's lifecycle. The defined interfaces are:
</p>
<ol>
<li>LogEnabled</li>
<li>Contextualizable</li>
<li>Composable</li>
<li>Configurable</li>
<li>Parameterizable</li>
<li>Initializable</li>
<li>Startable</li>
<li>Suspendable</li>
<li>Recontextualizable</li>
<li>Recomposable</li>
<li>Reconfigurable</li>
<li>Reparameterizable</li>
<li>Stoppable</li>
<li>Disposable</li>
</ol>
<note>
<em>Note:</em>java.lang.Runnable has also been in use as a lifecycle
interface. This is not recommended and is not supported by Avalon.
Instead,
the run() method is the responsibility of the Component itself. If
you wish
to use it, call it from within start() or another method.
</note>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="100%">
<tr>
<td bgcolor="bbccdd"><font face="arial,helvetica,sanserif" color="#000000"
size="+1"><b>Phase order</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The order in which the various lifecycle methods are called is very
specific.
While none are required (it is possible to have a Component
implementing
none of the lifecycle methods, although the use of that would be
limited),
some can only be used when others are as well. This is best explained
using
a few examples.
</p>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>simple examples</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">The lifecycle of a <code>Component</code> implementing
only Configurable for
example will be:</p>
<ol>
<li>constructor</li>
<li>configure</li>
<li>finalize</li>
</ol>
<p align="justify">The lifecycle of a <code>Component</code> implementing
only Composable will be:</p>
<ol>
<li>constructor</li>
<li>compose</li>
<li>finalize</li>
</ol>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>complete</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
If a <code>Component</code> implements more than one interface the
order of
the events (compose, configure etc.) follow a specific order. A
Component
implementing all above interfaces (including Runnable) will follow
this
specific path:
</p>
<ol>
<li>constructor</li>
<li>contextualize</li>
<li>compose</li>
<li>configure</li>
<li>parameterize</li>
<li>initialize</li>
<li>start</li>
<li>
<ol>
<li>suspend</li>
<li>recontextualize</li>
<li>recompose</li>
<li>reconfigure</li>
<li>reparameterize</li>
<li>resume</li>
</ol>
</li>
<li>stop</li>
<li>dispose</li>
<li>finalize</li>
</ol>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Phases executed once</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
These lifecycle methods are only called once in the entire life of a
Component:
</p>
<ul>
<li>contextualize</li>
<li>compose</li>
<li>configure</li>
<li>parameterize</li>
<li>initialize</li>
<li>dispose</li>
</ul>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>Phases executed once or more</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
These lifecycle methods are called at least once and possibly more,
depending
on the container:
</p>
<ul>
<li>start</li>
<li>stop</li>
</ul>
</font></td>
</tr>
</table>
</div>
<br>
<div align="right">
<table cellspacing="0" cellpadding="2" border="0" width="99%">
<tr>
<td bgcolor="ddeeff"><font face="arial,helvetica,sanserif" color="#000000"
size="+0"><b>The Suspendable Interface</b></font></td>
</tr>
<tr>
<td><font face="arial,helvetica,sanserif" color="#000000">
<br>
<p align="justify">
The methods suspend() and resume() are not guaranteed to be called
at all,
even when implemented. They can be called more than once, but only
after
one another and between start() and stop(). The reason they exist
is so
the container can notify the Component it needs to come to
temporary stop
any operations. The container may need to perform some synchronized
operation
on one of the Components used by this Component, or it may wish to
call any
of the following methods, which can also be called zero or more
times, and
only between a suspend() and a resume().
</p>
<ul>
<li>recontextualize()</li>
<li>recompose()</li>
<li>reconfigure()</li>
<li>reparameterize()</li>
</ul>
</font></td>
</tr>
</table>
</div>
<br>
<!--
<s2 title="The Command Pattern">
<p>
The most advanced, most complicated and most flexible option is to
use
the Command pattern by having your Component implement the
Commandable
interface. This is experimental; you'll find the Commandable and its
related classes in the excalibur package.
</p>
<p>
It is recommended that if your Component implements Commandable, it
should
not implement Executable or Interruptable. When you do choose to
combine the
two, the order in which the different steps must happen is very
specific:
<code>
// inside container...<br />
// ...<br />
myComponent.initialize();<br />
myComponent.start();<br />
Iterator commands = myComponent.getCommands();<br />
runAll(commands);<br />
myComponent.suspend();<br />
myComponent.resume();<br />
myComponent.suspend();<br />
myComponent.resume();<br />
myComponent.stop();<br />
myComponent.dispose();<br />
// ...<br />
// on shutdown...<br />
stopAll(commands);<br />
commands = null;<br />
myComponent = null;<br />
System.gc(); // finalize() is called on myComponent, which allows it to
perform some<br />
// final operation on its Commands.<br />
</code>
</p>
<p>
The advantage of using Commands is that you can have multiple
processes running
outside your Component that can manipulate it. These will run until
completion
even if you Component has already been disposed of.
</p>
<p>
You should note that the Command interface we use extends Runnable,
which means
Commands can be (and usually are) run() using standard pooling
utilities for
threads.
</p>
</s2>
-->
</font></td>
</tr>
</table>
</div>
<br>
</td>
</tr>
</table>
<br>
<table cellpadding="0" cellspacing="0" border="0" width="100%">
<tr>
<td>
<hr size="1" noshade="">
</td>
</tr>
<tr>
<td align="center"><font color="#525D76" size="-1"
face="arial,helvetica,sanserif"><i>
Copyright ©1999-2002 by the Apache Software Foundation.
All Rights Reserved.
</i></font></td>
</tr>
</table>
</body>
</html>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
