You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm@excalibur.apache.org by rd...@apache.org on 2009/06/16 19:55:28 UTC
svn commit: r785324 [14/28] - in /excalibur/site: ./ css/ developing/ event/
fortress/ framework/ images/logos/ instrument/ lifecycle/ sourceresolve/
store/ xmlutil/
Modified: excalibur/site/framework/best-practices.html
URL: http://svn.apache.org/viewvc/excalibur/site/framework/best-practices.html?rev=785324&r1=785323&r2=785324&view=diff
==============================================================================
--- excalibur/site/framework/best-practices.html (original)
+++ excalibur/site/framework/best-practices.html Tue Jun 16 17:55:25 2009
@@ -1,100 +1,558 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Apache Excalibur - OOP best Practices</title><style type="text/css" media="all">
- @import url("../style/maven-base.css");
-
- @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta><meta name="author" content="Leo Simons"></meta><meta name="email" content="leosimons@apache.org"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="The Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://excalibur.apache.org/" id="projectLogo"><img alt="Apache Excalibur" src="http://excalibur.apache.org/logo.gif"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xright">
-
- <a href="../index.html">Home</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../fortress/index.html">Fortress</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../component-list.html">Components</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../containerkit.html">Containerkit</a>
- </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuEssentials"><h5>Essentials</h5><ul><li class="none"><a href="../index.html">Overview</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../svn.html">Subversion</a></li><li class="none"><a href="http://wiki.apache.org/excalibur/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions" class="externalLink" title="External Link">FAQ</a></li><li class="none"><a href="http://excalibur.apache.org/apidocs/" class="externalLink" title="External Link">Javadocs</a></li><li class="none"><a href="http://excalibur.apache.org/download.cgi" class="externalLink" title="External Link">Download</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li><li class="collapsed"><a href="../misc.html">Miscellaneous</a></li></ul></div><div
id="menuFortress"><h5>Fortress</h5><ul><li class="none"><a href="../fortress/index.html">Overview</a></li><li class="none"><a href="../fortress/features.html">Features Oriented</a></li><li class="none"><a href="../fortress/getting-started.html">Getting Started</a></li><li class="none"><a href="../fortress/using-meta-info.html">Using Meta Info</a></li><li class="none"><a href="../fortress/cli.html">CLI</a></li><li class="none"><a href="../fortress/swing.html">Swing</a></li><li class="none"><a href="../fortress/servlet.html">Servlet</a></li><li class="none"><a href="../lifecycle/index.html">Lifecycle Extensions</a></li><li class="none"><a href="../fortress/design-notes.html">Design Notes</a></li></ul></div><div id="menuFramework"><h5>Framework</h5><ul><li class="expanded"><a href="../framework/index.html">Documentation</a><ul><li class="none"><a href="../framework/lifecycle.html">Lifecycle</a></li><li class="none"><a href="../framework/guide-cop-in-avalon.html">COP in Avalon<
/a></li><li class="none"><a href="../framework/guide-patterns-avalon.html">Patterns in Avalon</a></li><li class="none"><a href="../framework/guide-patterns-ioc.html">IOC Patterns</a></li><li class="none"><a href="../framework/guide-patterns-ioc-security.html">IOC Security</a></li><li class="none"><a href="../framework/guide-patterns-soc.html">Seperation of Concerns</a></li><li class="none"><a href="../framework/guide-patterns-soii.html">Interface and Implementation</a></li><li class="none"><a href="../framework/component-design.html">Designing Components</a></li><li class="none"><strong><a href="../framework/best-practices.html">Best Practices</a></strong></li></ul></li><li class="collapsed"><a href="../developing/index.html">Developing</a></li></ul></div><div id="menuComponents"><h5>Components</h5><ul><li class="none"><a href="../component-list.html">Overview</a></li><li class="collapsed"><a href="../sourceresolve/index.html">Sourceresolver</a></li><li class="collapsed"><a
href="../store/index.html">Store</a></li><li class="none"><a href="../thread.html">Thread</a></li><li class="collapsed"><a href="../xmlutil/index.html">XMLUtil</a></li></ul></div><div id="menuContainerkit"><h5>Containerkit</h5><ul><li class="none"><a href="../containerkit.html">Overview</a></li><li class="collapsed"><a href="../instrument/index.html">Instrument</a></li><li class="collapsed"><a href="../lifecycle/index.html">Lifecycle</a></li><li class="none"><a href="../logger.html">Logger</a></li></ul></div><div id="menuDeprecated_Materials"><h5>Deprecated Materials</h5><ul><li class="none"><a href="../deprecation.html">Overview</a></li><li class="expanded"><a href="../deprecation.html">Old Documentation</a><ul><li class="none"><a href="../component.html">ECM</a></li><li class="collapsed"><a href="../event/index.html">Event</a></li><li class="none"><a href="../configuration.html">Configuration</a></li></ul></li></ul></div><div id="menuThanks"><h5>Thanks</h5><ul><li class="n
one"><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="External Link">to our sponsors!</a></li><li class="none"><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="External Link">Sponsor the ASF</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="../index.html">About Apache Excalibur</a></li><li class="collapsed"><a href="../project-info.html">Project Info</a></li><li class="collapsed"><a href="../maven-reports.html">Project Reports</a></li><li class="none"><a href="http://maven.apache.org/development-process.html" class="externalLink" title="External Link">Development Process</a></li></ul></div></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="OOP_best_Practices"></a><h2>OOP best Practices</h2><div class="subsection"><a name="Recursion_Introduction"></a><h3>Recursion Introduction</h3><p>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Excalibur - OOP best Practices</title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+ <meta name="author" content="Leo Simons" />
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <span id="bannerLeft">
+
+ Excalibur
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 2009-06-16
+ </div>
+ <div class="xright"> <a href="../index.html">Home</a>
+ |
+ <a href="../fortress/index.html">Fortress</a>
+ |
+ <a href="../component-list.html">Components</a>
+ |
+ <a href="../containerkit.html">Containerkit</a>
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+
+ <h5>Essentials</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../mail-lists.html">Mailing Lists</a>
+ </li>
+
+ <li class="none">
+ <a href="../svn.html">Subversion</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/excalibur/" class="externalLink">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions" class="externalLink">FAQ</a>
+ </li>
+
+ <li class="none">
+ <a href="http://excalibur.apache.org/apidocs/" class="externalLink">Javadocs</a>
+ </li>
+
+ <li class="none">
+ <a href="http://excalibur.apache.org/download.cgi" class="externalLink">Download</a>
+ </li>
+
+ <li class="none">
+ <a href="../issue-tracking.html">Issue Tracking</a>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../misc.html">Miscellaneous</a>
+ </li>
+ </ul>
+ <h5>Fortress</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../fortress/index.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/features.html">Features Oriented</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/getting-started.html">Getting Started</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/using-meta-info.html">Using Meta Info</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/cli.html">CLI</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/swing.html">Swing</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/servlet.html">Servlet</a>
+ </li>
+
+ <li class="none">
+ <a href="../lifecycle/index.html">Lifecycle Extensions</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/design-notes.html">Design Notes</a>
+ </li>
+ </ul>
+ <h5>Framework</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../framework/index.html">Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="../framework/lifecycle.html">Lifecycle</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-cop-in-avalon.html">COP in Avalon</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-avalon.html">Patterns in Avalon</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-ioc.html">IOC Patterns</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-ioc-security.html">IOC Security</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-soc.html">Seperation of Concerns</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-soii.html">Interface and Implementation</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/component-design.html">Designing Components</a>
+ </li>
+
+ <li class="none">
+ <strong>Best Practices</strong>
+ </li>
+ </ul>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../developing/index.html">Developing</a>
+ </li>
+ </ul>
+ <h5>Components</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../component-list.html">Overview</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../sourceresolve/index.html">Sourceresolver</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../store/index.html">Store</a>
+ </li>
+
+ <li class="none">
+ <a href="../thread.html">Thread</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../xmlutil/index.html">XMLUtil</a>
+ </li>
+ </ul>
+ <h5>Containerkit</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../containerkit.html">Overview</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../instrument/index.html">Instrument</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../lifecycle/index.html">Lifecycle</a>
+ </li>
+
+ <li class="none">
+ <a href="../logger.html">Logger</a>
+ </li>
+ </ul>
+ <h5>Deprecated Materials</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../deprecation.html">Overview</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../deprecation.html">Old Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="../component.html">ECM</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../event/index.html">Event</a>
+ </li>
+
+ <li class="none">
+ <a href="../configuration.html">Configuration</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h5>Thanks</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../../foundation/thanks.html">to our sponsors!</a>
+ </li>
+
+ <li class="none">
+ <a href="../../foundation/sponsorship.html">Sponsor the ASF</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <div class="section"><h2><a name="OOP_best_Practices"></a>OOP best Practices</h2>
+<div class="section"><h3><a name="Recursion_Introduction"></a>Recursion Introduction</h3>
+<p>
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>
+ </p>
+<p>
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
+ (hence the name "Recursion Introduction"). Even if
there is no recursion happening, it appears to operate in the
same manner.
- </p></div><div class="subsection"><a name="Eliminate_Case_Analysis"></a><h3>Eliminate Case Analysis</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Eliminate_Case_Analysis"></a>Eliminate Case Analysis</h3>
+<p>
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></div><div class="subsection"><a name="Reduce_the_Number_of_Arguments"></a><h3>Reduce the Number of Arguments</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Reduce_the_Number_of_Arguments"></a>Reduce the Number of Arguments</h3>
+<p>
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></div><div class="subsection"><a name="Reduce_the_Size_of_Methods"></a><h3>Reduce the Size of Methods</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Reduce_the_Size_of_Methods"></a>Reduce the Size of Methods</h3>
+<p>
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></div><div class="subsection"><a name="The_Top_of_the_Class_Hierarchy_Should_be_Abstract"></a><h3>The Top of the Class Hierarchy Should be Abstract</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="The_Top_of_the_Class_Hierarchy_Should_be_Abstract"></a>The Top of the Class Hierarchy Should be Abstract</h3>
+<p>
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></div><div class="subsection"><a name="Minimize_Accesses_to_Variables"></a><h3>Minimize Accesses to Variables</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Minimize_Accesses_to_Variables"></a>Minimize Accesses to Variables</h3>
+<p>
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></div><div class="subsection"><a name="Subclasses_Should_be_Specializations"></a><h3>Subclasses Should be Specializations</h3><p>
- A [subclass] "is a" [superclass]. If what you
+ </p>
+</div>
+<div class="section"><h3><a name="Subclasses_Should_be_Specializations"></a>Subclasses Should be Specializations</h3>
+<p>
+ 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></div><div class="subsection"><a name="Split_Large_Classes"></a><h3>Split Large Classes</h3><p>
+ "has a" [external class]).
+ </p>
+</div>
+<div class="section"><h3><a name="Split_Large_Classes"></a>Split Large Classes</h3>
+<p>
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></div><div class="subsection"><a name="Factor_Implementation_Differences_Into_Subcomponents"></a><h3>Factor Implementation Differences Into Subcomponents</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Factor_Implementation_Differences_Into_Subcomponents"></a>Factor Implementation Differences Into Subcomponents</h3>
+<p>
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></div><div class="subsection"><a name="Separate_Methods_that_Do_Not_Communicate"></a><h3>Separate Methods that Do Not Communicate</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Separate_Methods_that_Do_Not_Communicate"></a>Separate Methods that Do Not Communicate</h3>
+<p>
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></div><div class="subsection"><a name="Send_Messages_to_Components_instead_of_to_This"></a><h3>Send Messages to Components instead of to This</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Send_Messages_to_Components_instead_of_to_This"></a>Send Messages to Components instead of to This</h3>
+<p>
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>
+ </p>
+<p>
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 class="source"><pre>
+<div class="source"><pre>
abstract class AbstractExampleDocument
{
// skip some code ...
@@ -108,14 +566,15 @@
protected void format(Example structure);
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
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 class="source"><pre>
+<div class="source"><pre>
class DefaultExampleDocument
{
// skip some code ...
@@ -129,17 +588,49 @@
}
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
An inheritance based framework (White Box) can be converted
into a component based framework (Black Box) structure by
replacing overridden methods with method calls (message sends)
to components. Component based architecture is much more
flexible in this regard.
- </p></div><div class="subsection"><a name="Eliminate_Implicit_Parameter_Passing"></a><h3>Eliminate Implicit Parameter Passing</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Eliminate_Implicit_Parameter_Passing"></a>Eliminate Implicit Parameter Passing</h3>
+<p>
Just because two methods share the same information within the
class does not mean that it should be done in that manner.
Many times, the attribute that is shared should be passed
as a parameter of the method instead of directly accessing
the attribute.
- </p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 1997-2007, The Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+ </p>
+</div>
+</div>
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2009
+
+ The Apache Software Foundation
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Modified: excalibur/site/framework/component-design.html
URL: http://svn.apache.org/viewvc/excalibur/site/framework/component-design.html?rev=785324&r1=785323&r2=785324&view=diff
==============================================================================
--- excalibur/site/framework/component-design.html (original)
+++ excalibur/site/framework/component-design.html Tue Jun 16 17:55:25 2009
@@ -1,60 +1,494 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Apache Excalibur - </title><style type="text/css" media="all">
- @import url("../style/maven-base.css");
-
- @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="The Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://excalibur.apache.org/" id="projectLogo"><img alt="Apache Excalibur" src="http://excalibur.apache.org/logo.gif"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xright">
-
- <a href="../index.html">Home</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../fortress/index.html">Fortress</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../component-list.html">Components</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../containerkit.html">Containerkit</a>
- </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuEssentials"><h5>Essentials</h5><ul><li class="none"><a href="../index.html">Overview</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../svn.html">Subversion</a></li><li class="none"><a href="http://wiki.apache.org/excalibur/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions" class="externalLink" title="External Link">FAQ</a></li><li class="none"><a href="http://excalibur.apache.org/apidocs/" class="externalLink" title="External Link">Javadocs</a></li><li class="none"><a href="http://excalibur.apache.org/download.cgi" class="externalLink" title="External Link">Download</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li><li class="collapsed"><a href="../misc.html">Miscellaneous</a></li></ul></div><div
id="menuFortress"><h5>Fortress</h5><ul><li class="none"><a href="../fortress/index.html">Overview</a></li><li class="none"><a href="../fortress/features.html">Features Oriented</a></li><li class="none"><a href="../fortress/getting-started.html">Getting Started</a></li><li class="none"><a href="../fortress/using-meta-info.html">Using Meta Info</a></li><li class="none"><a href="../fortress/cli.html">CLI</a></li><li class="none"><a href="../fortress/swing.html">Swing</a></li><li class="none"><a href="../fortress/servlet.html">Servlet</a></li><li class="none"><a href="../lifecycle/index.html">Lifecycle Extensions</a></li><li class="none"><a href="../fortress/design-notes.html">Design Notes</a></li></ul></div><div id="menuFramework"><h5>Framework</h5><ul><li class="expanded"><a href="../framework/index.html">Documentation</a><ul><li class="none"><a href="../framework/lifecycle.html">Lifecycle</a></li><li class="none"><a href="../framework/guide-cop-in-avalon.html">COP in Avalon<
/a></li><li class="none"><a href="../framework/guide-patterns-avalon.html">Patterns in Avalon</a></li><li class="none"><a href="../framework/guide-patterns-ioc.html">IOC Patterns</a></li><li class="none"><a href="../framework/guide-patterns-ioc-security.html">IOC Security</a></li><li class="none"><a href="../framework/guide-patterns-soc.html">Seperation of Concerns</a></li><li class="none"><a href="../framework/guide-patterns-soii.html">Interface and Implementation</a></li><li class="none"><strong><a href="../framework/component-design.html">Designing Components</a></strong></li><li class="none"><a href="../framework/best-practices.html">Best Practices</a></li></ul></li><li class="collapsed"><a href="../developing/index.html">Developing</a></li></ul></div><div id="menuComponents"><h5>Components</h5><ul><li class="none"><a href="../component-list.html">Overview</a></li><li class="collapsed"><a href="../sourceresolve/index.html">Sourceresolver</a></li><li class="collapsed"><a
href="../store/index.html">Store</a></li><li class="none"><a href="../thread.html">Thread</a></li><li class="collapsed"><a href="../xmlutil/index.html">XMLUtil</a></li></ul></div><div id="menuContainerkit"><h5>Containerkit</h5><ul><li class="none"><a href="../containerkit.html">Overview</a></li><li class="collapsed"><a href="../instrument/index.html">Instrument</a></li><li class="collapsed"><a href="../lifecycle/index.html">Lifecycle</a></li><li class="none"><a href="../logger.html">Logger</a></li></ul></div><div id="menuDeprecated_Materials"><h5>Deprecated Materials</h5><ul><li class="none"><a href="../deprecation.html">Overview</a></li><li class="expanded"><a href="../deprecation.html">Old Documentation</a><ul><li class="none"><a href="../component.html">ECM</a></li><li class="collapsed"><a href="../event/index.html">Event</a></li><li class="none"><a href="../configuration.html">Configuration</a></li></ul></li></ul></div><div id="menuThanks"><h5>Thanks</h5><ul><li class="n
one"><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="External Link">to our sponsors!</a></li><li class="none"><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="External Link">Sponsor the ASF</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="../index.html">About Apache Excalibur</a></li><li class="collapsed"><a href="../project-info.html">Project Info</a></li><li class="collapsed"><a href="../maven-reports.html">Project Reports</a></li><li class="none"><a href="http://maven.apache.org/development-process.html" class="externalLink" title="External Link">Development Process</a></li></ul></div></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Designing_a_Component"></a><h2>Designing a Component</h2><p>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Excalibur - </title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <span id="bannerLeft">
+
+ Excalibur
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 2009-06-16
+ </div>
+ <div class="xright"> <a href="../index.html">Home</a>
+ |
+ <a href="../fortress/index.html">Fortress</a>
+ |
+ <a href="../component-list.html">Components</a>
+ |
+ <a href="../containerkit.html">Containerkit</a>
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+
+ <h5>Essentials</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../mail-lists.html">Mailing Lists</a>
+ </li>
+
+ <li class="none">
+ <a href="../svn.html">Subversion</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/excalibur/" class="externalLink">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions" class="externalLink">FAQ</a>
+ </li>
+
+ <li class="none">
+ <a href="http://excalibur.apache.org/apidocs/" class="externalLink">Javadocs</a>
+ </li>
+
+ <li class="none">
+ <a href="http://excalibur.apache.org/download.cgi" class="externalLink">Download</a>
+ </li>
+
+ <li class="none">
+ <a href="../issue-tracking.html">Issue Tracking</a>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../misc.html">Miscellaneous</a>
+ </li>
+ </ul>
+ <h5>Fortress</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../fortress/index.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/features.html">Features Oriented</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/getting-started.html">Getting Started</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/using-meta-info.html">Using Meta Info</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/cli.html">CLI</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/swing.html">Swing</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/servlet.html">Servlet</a>
+ </li>
+
+ <li class="none">
+ <a href="../lifecycle/index.html">Lifecycle Extensions</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/design-notes.html">Design Notes</a>
+ </li>
+ </ul>
+ <h5>Framework</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../framework/index.html">Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="../framework/lifecycle.html">Lifecycle</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-cop-in-avalon.html">COP in Avalon</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-avalon.html">Patterns in Avalon</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-ioc.html">IOC Patterns</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-ioc-security.html">IOC Security</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-soc.html">Seperation of Concerns</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-soii.html">Interface and Implementation</a>
+ </li>
+
+ <li class="none">
+ <strong>Designing Components</strong>
+ </li>
+
+ <li class="none">
+ <a href="../framework/best-practices.html">Best Practices</a>
+ </li>
+ </ul>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../developing/index.html">Developing</a>
+ </li>
+ </ul>
+ <h5>Components</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../component-list.html">Overview</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../sourceresolve/index.html">Sourceresolver</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../store/index.html">Store</a>
+ </li>
+
+ <li class="none">
+ <a href="../thread.html">Thread</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../xmlutil/index.html">XMLUtil</a>
+ </li>
+ </ul>
+ <h5>Containerkit</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../containerkit.html">Overview</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../instrument/index.html">Instrument</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../lifecycle/index.html">Lifecycle</a>
+ </li>
+
+ <li class="none">
+ <a href="../logger.html">Logger</a>
+ </li>
+ </ul>
+ <h5>Deprecated Materials</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../deprecation.html">Overview</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../deprecation.html">Old Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="../component.html">ECM</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../event/index.html">Event</a>
+ </li>
+
+ <li class="none">
+ <a href="../configuration.html">Configuration</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h5>Thanks</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../../foundation/thanks.html">to our sponsors!</a>
+ </li>
+
+ <li class="none">
+ <a href="../../foundation/sponsorship.html">Sponsor the ASF</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <header>Avalon Framework - Designing a Component<version>1.0</version><authors><person name="Berin Loritsch" email="bloritsch@apache.org"><person name="Leo Simons" email="leosimons@apache.org"></authors></header><div class="section"><h2><a name="Designing_a_Component"></a>Designing a Component</h2>
+<p>
The first step in writing the component is determining how it is going
to be used. There will be a number of times where you have a powerful
component that can be used in many different contexts. Those contexts
may include executing the component from the command line (separate
from Avalon), using it as a part of a sub system, or using it as an
integral part of Avalon.
- </p><div class="subsection"><a name="Part_of_Avalon"></a><h3>Part of Avalon</h3><p>
+ </p>
+<div class="section"><h3><a name="Part_of_Avalon"></a>Part of Avalon</h3>
+<p>
All components are an integral part of Avalon, so there is really
nothing to be done beyond specifying its interface (role). It is
important to identify and document its social contract with the
rest of the system. What I mean by social contract is the order
of dependencies, what it needs to function, and what it supplies
to the rest of the system.
- </p></div><div class="subsection"><a name="Part_of_a_Sub_System"></a><h3>Part of a Sub System</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Part_of_a_Sub_System"></a>Part of a Sub System</h3>
+<p>
A sub system can either be part of Avalon, or live in a separate
context. A perfect example would be a component that can function
within a Servlet or Enterprise Application. Neither of those
contexts are native to Avalon (though they can easily be built
on top of Avalon).
- </p><p>
+ </p>
+<p>
It is important to do even more careful planning than in the
first scenario. The reason is that you want the interface to be
as generic as possible and still accurately represent its role.
- </p><p>
+ </p>
+<p>
Because the contexts may not be an integral part of Avalon,
you must take care to use the component in the same manner as
Avalon would. That means that you follow the order of concerns
that Avalon has specified for those concerns.
- </p></div><div class="subsection"><a name="A_Stand_Alone_Program"></a><h3>A Stand Alone Program</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="A_Stand_Alone_Program"></a>A Stand Alone Program</h3>
+<p>
When you are designing a component to be run from the command
line (or directly by the operating system), try to separate
the main function from the component itself. This is imperative
@@ -62,17 +496,47 @@
your component in the manner stated in the previous section,
you have effectively minimized what the main function has to
do.
- </p><p>
+ </p>
+<p>
Follow the practice of having an object dedicated to the main
function that includes the parsing of the command line parameters
and initialization of the component. When the component is used
the exact same way in every context (including the command line),
you minimize the number of locations to look while debugging.
- </p><p><i>
+ </p>
+<p><i>
A common mistake is to combine the main function in the
implementation of the component. This requires violating the
contracts and principles that Avalon is built upon. This
- violation of the pattern of "Inversion of Control" is
- aptly dubbed "Subversion of Control" (thanks to Steven Coffman
+ violation of the pattern of "Inversion of Control" is
+ aptly dubbed "Subversion of Control" (thanks to Steven Coffman
for the name of the anti-pattern).
- </i></p></div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 1997-2007, The Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+ </i></p>
+</div>
+</div>
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2009
+
+ The Apache Software Foundation
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
Modified: excalibur/site/framework/guide-cop-in-avalon.html
URL: http://svn.apache.org/viewvc/excalibur/site/framework/guide-cop-in-avalon.html?rev=785324&r1=785323&r2=785324&view=diff
==============================================================================
--- excalibur/site/framework/guide-cop-in-avalon.html (original)
+++ excalibur/site/framework/guide-cop-in-avalon.html Tue Jun 16 17:55:25 2009
@@ -1,40 +1,469 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Apache Excalibur - </title><style type="text/css" media="all">
- @import url("../style/maven-base.css");
-
- @import url("../style/maven-theme.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="The Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://excalibur.apache.org/" id="projectLogo"><img alt="Apache Excalibur" src="http://excalibur.apache.org/logo.gif"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xright">
-
- <a href="../index.html">Home</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../fortress/index.html">Fortress</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../component-list.html">Components</a>
-
-
-
- <span class="separator">|</span>
-
-
- <a href="../containerkit.html">Containerkit</a>
- </div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuEssentials"><h5>Essentials</h5><ul><li class="none"><a href="../index.html">Overview</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../svn.html">Subversion</a></li><li class="none"><a href="http://wiki.apache.org/excalibur/" class="externalLink" title="External Link">Wiki</a></li><li class="none"><a href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions" class="externalLink" title="External Link">FAQ</a></li><li class="none"><a href="http://excalibur.apache.org/apidocs/" class="externalLink" title="External Link">Javadocs</a></li><li class="none"><a href="http://excalibur.apache.org/download.cgi" class="externalLink" title="External Link">Download</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li><li class="collapsed"><a href="../misc.html">Miscellaneous</a></li></ul></div><div
id="menuFortress"><h5>Fortress</h5><ul><li class="none"><a href="../fortress/index.html">Overview</a></li><li class="none"><a href="../fortress/features.html">Features Oriented</a></li><li class="none"><a href="../fortress/getting-started.html">Getting Started</a></li><li class="none"><a href="../fortress/using-meta-info.html">Using Meta Info</a></li><li class="none"><a href="../fortress/cli.html">CLI</a></li><li class="none"><a href="../fortress/swing.html">Swing</a></li><li class="none"><a href="../fortress/servlet.html">Servlet</a></li><li class="none"><a href="../lifecycle/index.html">Lifecycle Extensions</a></li><li class="none"><a href="../fortress/design-notes.html">Design Notes</a></li></ul></div><div id="menuFramework"><h5>Framework</h5><ul><li class="expanded"><a href="../framework/index.html">Documentation</a><ul><li class="none"><a href="../framework/lifecycle.html">Lifecycle</a></li><li class="none"><strong><a href="../framework/guide-cop-in-avalon.html">COP in
Avalon</a></strong></li><li class="none"><a href="../framework/guide-patterns-avalon.html">Patterns in Avalon</a></li><li class="none"><a href="../framework/guide-patterns-ioc.html">IOC Patterns</a></li><li class="none"><a href="../framework/guide-patterns-ioc-security.html">IOC Security</a></li><li class="none"><a href="../framework/guide-patterns-soc.html">Seperation of Concerns</a></li><li class="none"><a href="../framework/guide-patterns-soii.html">Interface and Implementation</a></li><li class="none"><a href="../framework/component-design.html">Designing Components</a></li><li class="none"><a href="../framework/best-practices.html">Best Practices</a></li></ul></li><li class="collapsed"><a href="../developing/index.html">Developing</a></li></ul></div><div id="menuComponents"><h5>Components</h5><ul><li class="none"><a href="../component-list.html">Overview</a></li><li class="collapsed"><a href="../sourceresolve/index.html">Sourceresolver</a></li><li class="collapsed"><a
href="../store/index.html">Store</a></li><li class="none"><a href="../thread.html">Thread</a></li><li class="collapsed"><a href="../xmlutil/index.html">XMLUtil</a></li></ul></div><div id="menuContainerkit"><h5>Containerkit</h5><ul><li class="none"><a href="../containerkit.html">Overview</a></li><li class="collapsed"><a href="../instrument/index.html">Instrument</a></li><li class="collapsed"><a href="../lifecycle/index.html">Lifecycle</a></li><li class="none"><a href="../logger.html">Logger</a></li></ul></div><div id="menuDeprecated_Materials"><h5>Deprecated Materials</h5><ul><li class="none"><a href="../deprecation.html">Overview</a></li><li class="expanded"><a href="../deprecation.html">Old Documentation</a><ul><li class="none"><a href="../component.html">ECM</a></li><li class="collapsed"><a href="../event/index.html">Event</a></li><li class="none"><a href="../configuration.html">Configuration</a></li></ul></li></ul></div><div id="menuThanks"><h5>Thanks</h5><ul><li class="n
one"><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="External Link">to our sponsors!</a></li><li class="none"><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="External Link">Sponsor the ASF</a></li></ul></div><div id="menuProject_Documentation"><h5>Project Documentation</h5><ul><li class="none"><a href="../index.html">About Apache Excalibur</a></li><li class="collapsed"><a href="../project-info.html">Project Info</a></li><li class="collapsed"><a href="../maven-reports.html">Project Reports</a></li><li class="none"><a href="http://maven.apache.org/development-process.html" class="externalLink" title="External Link">Development Process</a></li></ul></div></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Components_in_Avalon"></a><h2>Components in Avalon</h2><p>
- 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
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+
+
+
+
+
+
+
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>Excalibur - </title>
+ <style type="text/css" media="all">
+ @import url("../css/maven-base.css");
+ @import url("../css/maven-theme.css");
+ @import url("../css/site.css");
+ </style>
+ <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <span id="bannerLeft">
+
+ Excalibur
+
+ </span>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+
+
+
+
+
+
+
+
+ <div class="xleft">
+ Last Published: 2009-06-16
+ </div>
+ <div class="xright"> <a href="../index.html">Home</a>
+ |
+ <a href="../fortress/index.html">Fortress</a>
+ |
+ <a href="../component-list.html">Components</a>
+ |
+ <a href="../containerkit.html">Containerkit</a>
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+
+
+
+
+
+
+ <h5>Essentials</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../index.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../mail-lists.html">Mailing Lists</a>
+ </li>
+
+ <li class="none">
+ <a href="../svn.html">Subversion</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/excalibur/" class="externalLink">Wiki</a>
+ </li>
+
+ <li class="none">
+ <a href="http://wiki.apache.org/excalibur/FrequentlyAskedQuestions" class="externalLink">FAQ</a>
+ </li>
+
+ <li class="none">
+ <a href="http://excalibur.apache.org/apidocs/" class="externalLink">Javadocs</a>
+ </li>
+
+ <li class="none">
+ <a href="http://excalibur.apache.org/download.cgi" class="externalLink">Download</a>
+ </li>
+
+ <li class="none">
+ <a href="../issue-tracking.html">Issue Tracking</a>
+ </li>
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../misc.html">Miscellaneous</a>
+ </li>
+ </ul>
+ <h5>Fortress</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../fortress/index.html">Overview</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/features.html">Features Oriented</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/getting-started.html">Getting Started</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/using-meta-info.html">Using Meta Info</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/cli.html">CLI</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/swing.html">Swing</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/servlet.html">Servlet</a>
+ </li>
+
+ <li class="none">
+ <a href="../lifecycle/index.html">Lifecycle Extensions</a>
+ </li>
+
+ <li class="none">
+ <a href="../fortress/design-notes.html">Design Notes</a>
+ </li>
+ </ul>
+ <h5>Framework</h5>
+ <ul>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../framework/index.html">Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="../framework/lifecycle.html">Lifecycle</a>
+ </li>
+
+ <li class="none">
+ <strong>COP in Avalon</strong>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-avalon.html">Patterns in Avalon</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-ioc.html">IOC Patterns</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-ioc-security.html">IOC Security</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-soc.html">Seperation of Concerns</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/guide-patterns-soii.html">Interface and Implementation</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/component-design.html">Designing Components</a>
+ </li>
+
+ <li class="none">
+ <a href="../framework/best-practices.html">Best Practices</a>
+ </li>
+ </ul>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../developing/index.html">Developing</a>
+ </li>
+ </ul>
+ <h5>Components</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../component-list.html">Overview</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../sourceresolve/index.html">Sourceresolver</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../store/index.html">Store</a>
+ </li>
+
+ <li class="none">
+ <a href="../thread.html">Thread</a>
+ </li>
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../xmlutil/index.html">XMLUtil</a>
+ </li>
+ </ul>
+ <h5>Containerkit</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../containerkit.html">Overview</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../instrument/index.html">Instrument</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../lifecycle/index.html">Lifecycle</a>
+ </li>
+
+ <li class="none">
+ <a href="../logger.html">Logger</a>
+ </li>
+ </ul>
+ <h5>Deprecated Materials</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../deprecation.html">Overview</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../deprecation.html">Old Documentation</a>
+ <ul>
+
+ <li class="none">
+ <a href="../component.html">ECM</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="collapsed">
+ <a href="../event/index.html">Event</a>
+ </li>
+
+ <li class="none">
+ <a href="../configuration.html">Configuration</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ <h5>Thanks</h5>
+ <ul>
+
+ <li class="none">
+ <a href="../../foundation/thanks.html">to our sponsors!</a>
+ </li>
+
+ <li class="none">
+ <a href="../../foundation/sponsorship.html">Sponsor the ASF</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img alt="Built by Maven" src="../images/logos/maven-feather.png"></img>
+ </a>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <header>Avalon Framework - Guide - COP in Avalon<authors><person name="Berin Loritsch" email="bloritsch@apache.org"><person name="Leo Simons" email="leosimons@apache.org"></authors></header><div class="section"><h2><a name="Components_in_Avalon"></a>Components in Avalon</h2>
+<p>
+ 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 class="subsection"><a name="A_passive_API"></a><h3>A passive API</h3><p>
+ </p>
+<div class="section"><h3><a name="A_passive_API"></a>A passive API</h3>
+<p>
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></div><div class="subsection"><a name="A_specific_Role"></a><h3>A specific Role</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="A_specific_Role"></a>A specific Role</h3>
+<p>
The concept of roles comes 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
@@ -42,12 +471,14 @@
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 its script.
- </p><p>
+ </p>
+<p>
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>
+ "cast" of components so to speak.
+ </p>
+<p>
For each role, you need to specify its 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
@@ -55,64 +486,75 @@
of the component must provide, and what the component produces.
When the interfaces and contracts are defined, you can work on your
implementation.
- </p></div></div><div class="section"><a name="The_Component"></a><h2>The Component</h2><p>
- John Donne wrote, "No man is an island." to communicate that we
+ </p>
+</div>
+</div>
+<div class="section"><h2><a name="The_Component"></a>The Component</h2>
+<p>
+ 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><p><i>
+ </p>
+<p><i>
We used to have a 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.omg.org" class="externalLink" title="External Link">CORBA</a> very cumbersome.
- </i></p><p>
+ <a href="http://www.omg.org" class="externalLink">CORBA</a> very cumbersome.
+ </i></p>
+<p>
As you might have 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>
- <strong>Configurable:</strong> marks an object that can be configured.
+ </p>
+<ol type="1"><li><strong>Configurable:</strong> marks an object that can be configured.
</li>
- <li>
- <strong>Serviceable:</strong> marks an object that uses Components.
+<li><strong>Serviceable:</strong> marks an object that uses Components.
</li>
- <li>
- <strong>Initializable:</strong> marks an object that can be initialized.
+<li><strong>Initializable:</strong> marks an object that can be initialized.
</li>
- <li>
- <strong>Disposable:</strong> marks an object that can be disposed.
+<li><strong>Disposable:</strong> marks an object that can be disposed.
</li>
- <li>
- <strong>Stoppable:</strong> marks an object that can be started and stopped.
+<li><strong>Stoppable:</strong> marks an object that can be started and stopped.
</li>
- </ol><p>
+</ol>
+<p>
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><p><i>
+ </p>
+<p><i>
Notice that each interface is separate from Component, so you can use
them for simple objects.
- </i></p></div><div class="section"><a name="The_Serviceable"></a><h2>The Serviceable</h2><p>
+ </i></p>
+</div>
+<div class="section"><h2><a name="The_Serviceable"></a>The Serviceable</h2>
+<p>
In Avalon, Serviceable is defined as an active entity that controls
or uses components. Its best analogy is that of a musical composer.
The musical composer chooses instruments (components) by their
role in the symphony (system) and tells them which notes to play.
- </p><p>
+ </p>
+<p>
The Avalon Serviceable follows the principles of Inversion of Control,
and is assigned a Service Manager. Within this section we will
discuss how to look up specific components, and then how to prepare
the ServiceManager for the Serviceable.
- </p><note>
+ </p>
+<note>
The Serviceable has a specific contract that must be enforced for security
reasons. The ServiceManager must only be set once. That means that
the <code>compose</code> method must ignore all subsequent
requests to set the ServiceManager after it is successfully set.
- </note></div><div class="section"><a name="Finding_your_Component"></a><h2>Finding your Component</h2><div class="subsection"><a name="The_Service_Manager"></a><h3>The Service Manager</h3><p>
+ </note></div>
+<div class="section"><h2><a name="Finding_your_Component"></a>Finding your Component</h2>
+<div class="section"><h3><a name="The_Service_Manager"></a>The Service Manager</h3>
+<p>
For the majority of all cases, you will need to use the ServiceManager
to get the instance of the component you need. If you recall the discussion
on component roles in the component documentation, you already have
@@ -121,17 +563,19 @@
because it is the interface that defines the component's role. Serviceable
and Component are concern interfaces because they address specific
concerns about the component.
- </p><p>
+ </p>
+<p>
The ServiceManager 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). See the following
example:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
final MyComponent component = (MyComponent)manager.
- lookup( "com.mycompany.myproject.MyComponent" );
- </pre></div>
- <p>
+ lookup( "com.mycompany.myproject.MyComponent" );
+ </pre>
+</div>
+<p>
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
@@ -141,7 +585,10 @@
that the interface name match the key used to lookup component. In this
situation you may need to create a new interface that does nothing
more than extend another interface and add a new role.
- </p></div><div class="subsection"><a name="The_Service_Selector"></a><h3>The Service Selector</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="The_Service_Selector"></a>The Service Selector</h3>
+<p>
Sometimes you will have several components that function in the same role.
For those cases, you will use the ServiceSelector to choose the exact
one you need. The best way to describe its proper use is the scenario
@@ -152,7 +599,8 @@
may reverse the formerly mentioned one. Yet another takes the text file
and formats it for a canvas object. For the Serviceable, it makes no difference
what the implementation does--just that it formats the text.
- </p><p>
+ </p>
+<p>
Using the processing chain example in the previous paragraph, we realize
the unsuitability of the ServiceManager for getting the right component.
The component addresses the concern of one component per role. Fortunately,
@@ -161,63 +609,76 @@
the specific component out of many that perform the <strong>same</strong>
role. The following code will help:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
final ServiceSelector selector = (ServiceSelector)manager.
- lookup( "org.mycompany.myproject.FormatterSelector" );
+ lookup( "org.mycompany.myproject.FormatterSelector" );
final Formatter formatter = (Formatter)selector.select( myURL );
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
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><p><i>
+ </p>
+<p><i>
Discussions are currently taking place about the ServiceSelector interface and
concept. It might be deprecated at some point in the future. There are indications
that usage of the ServiceSelector is only required when an application is
badly designed.
- </i></p></div><div class="subsection"><a name="When_you_are_done_with_the_component"></a><h3>When you are done with the component</h3><p>
+ </i></p>
+</div>
+<div class="section"><h3><a name="When_you_are_done_with_the_component"></a>When you are done with the component</h3>
+<p>
Both the ServiceManager and the ServiceSelector 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
+ 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 class="source"><pre>
+<div class="source"><pre>
MyComponent component = null;
try
{
- component = (MyComponent) manager.lookup("org.mycom.MyComponent");
+ component = (MyComponent) manager.lookup("org.mycom.MyComponent");
component.myMethod();
}
catch (Exception e)
{
- getLogger().debug("Error using MyComponent", e);
+ getLogger().debug("Error using MyComponent", e);
}
finally
{
if (component != null) manager.release(component);
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
The reason for this is so that smart component managers that
select components from a pool can properly manage the resources.
- </p></div></div><div class="section"><a name="Populating_the_ServiceManager"></a><h2>Populating the ServiceManager</h2><p>
+ </p>
+</div>
+</div>
+<div class="section"><h2><a name="Populating_the_ServiceManager"></a>Populating the ServiceManager</h2>
+<p>
It is the responsibility of the entity that creates the Serviceable to give it a
ServiceManager with all of the Roles populated. If you create your own
implementations of the ServiceManager and ServiceSelector 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 class="subsection"><a name="DefaultComponentManager"></a><h3>DefaultComponentManager</h3><p>
+ </p>
+<div class="section"><h3><a name="DefaultComponentManager"></a>DefaultComponentManager</h3>
+<p>
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 ServiceManager. One feature of the DefaultComponentManager is that
it can cascade. In other words, if the role is not found in this ServiceManager,
the default implementation will look in the parent ServiceManager.
- </p><p>
+ </p>
+<p>
For the paranoid developer, the cascading feature of the ServiceManager
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
@@ -226,25 +687,62 @@
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 ServiceManager is set.
- </p></div><div class="subsection"><a name="DefaultComponentSelector"></a><h3>DefaultComponentSelector</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="DefaultComponentSelector"></a>DefaultComponentSelector</h3>
+<p>
The DefaultComponentSelector again is simply a Hashtable selection of components
based on hints. It gives the method <code>put</code> to populate the ServiceSelector.
The ServiceSelector does not have the cascading feature of the ServiceManager,
nor should it. A ServiceSelector simply holds a number of components that
implement the same role--there really is no need to cascade.
- </p><p>
+ </p>
+<p>
After the ServiceSelector is populated, you must put it in the ServiceManager.
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
+ itself. An acceptable convention is to add the "Selector" name to the end of the
role you are looking up. Just be consistent.
- </p></div></div><div class="section"><p>
+ </p>
+</div>
+</div>
+<div class="section"><h2><a></a></h2>
+"The Container">
+ <p>
The container is the entity that manages your components. It handles
things like loading of configuration files, resolution of dependencies,
component management, component isolation, and lifecycle support.
- </p><p>
+ </p>
+<p>
The container is not formalized in the form of an interface or contract
within Avalon Framework, though it might be at some point in the future.
The informal contract for the container is that it has the ability to
host any fully Avalon-Framework compliant component. Most current containers
place additional requirements on the component.
- </p></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 1997-2007, The Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+ </p>
+</div>
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">©
+ 2009
+
+ The Apache Software Foundation
+
+
+
+
+
+
+
+
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: scm-unsubscribe@excalibur.apache.org
For additional commands, e-mail: scm-help@excalibur.apache.org