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 [6/28] - in /excalibur/site: ./ css/ developing/ event/
fortress/ framework/ images/logos/ instrument/ lifecycle/ sourceresolve/
store/ xmlutil/
Modified: excalibur/site/developing/framework.html
URL: http://svn.apache.org/viewvc/excalibur/site/developing/framework.html?rev=785324&r1=785323&r2=785324&view=diff
==============================================================================
--- excalibur/site/developing/framework.html (original)
+++ excalibur/site/developing/framework.html Tue Jun 16 17:55:25 2009
@@ -1,48 +1,475 @@
-<!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 - Framework and Foundations</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="Paul Hammant"></meta><meta name="email" content="hammant@apache.org"></meta><meta name="author" content="Berin Loritsch"></meta><meta name="email" content="bloritsch@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="collapsed"><a href="../framework/index.html">Documentation</a></li><li class="expanded"><a href="../developing/index.html">Developing</a><ul><li class="none"><a href="../developing/authors.html">Authors</a></li><li cl
ass="none"><a href="../developing/introduction.html">Introduction</a></li><li class="none"><a href="../developing/decomposing.html">Decomposition</a></li><li class="none"><strong><a href="../developing/framework.html">Avalon Framework</a></strong></li><li class="none"><a href="../developing/implementing.html">Using the framework</a></li><li class="none"><a href="../developing/compatiblity.html">Compatibility with Avalon</a></li><li class="none"><a href="../developing/strategies.html">Development Strategies</a></li><li class="none"><a href="../developing/conclusion.html">Conclusion</a></li></ul></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.htm
l">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="none"><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="External Link">to our sponsors!</a></li><li class="none"><a h
ref="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="Framework_and_Foundations"></a><h2>Framework and Foundations</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 - Framework and Foundations</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="Paul Hammant" />
+ <meta name="author" content="Berin Loritsch" />
+ </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="collapsed">
+ <a href="../framework/index.html">Documentation</a>
+ </li>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ <li class="expanded">
+ <a href="../developing/index.html">Developing</a>
+ <ul>
+
+ <li class="none">
+ <a href="../developing/authors.html">Authors</a>
+ </li>
+
+ <li class="none">
+ <a href="../developing/introduction.html">Introduction</a>
+ </li>
+
+ <li class="none">
+ <a href="../developing/decomposing.html">Decomposition</a>
+ </li>
+
+ <li class="none">
+ <strong>Avalon Framework</strong>
+ </li>
+
+ <li class="none">
+ <a href="../developing/implementing.html">Using the framework</a>
+ </li>
+
+ <li class="none">
+ <a href="../developing/compatiblity.html">Compatibility with Avalon</a>
+ </li>
+
+ <li class="none">
+ <a href="../developing/strategies.html">Development Strategies</a>
+ </li>
+
+ <li class="none">
+ <a href="../developing/conclusion.html">Conclusion</a>
+ </li>
+ </ul>
+ </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="Framework_and_Foundations"></a>Framework and Foundations</h2>
+<p>
Avalon Framework is the central piece to the entire Avalon project. If you
understand the contracts and constructs defined in the framework, you can
understand anything that uses it. Remember the principles and patterns we
have already discussed so far. In this section, we will expound on how the
Role concept works practically, the lifecycle of Components, and how the
interfaces work.
- </p></div><div class="section"><a name="Defining_the_Component_s_Role"></a><h2>Defining the Component's Role</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Defining_the_Components_Role"></a>Defining the Component's Role</h2>
+<p>
In Avalon, all Components have a role. The reason is that you retrieve
your Components by role. At this stage, the only concern area we are
using is the signature of the role. If you recall in the second section,
- we defined a Component as "the combination of a work interface and the
- implementation of the interface". That work interface is your role.
- </p><div class="subsection"><a name="Creating_the_Role_s_Interface"></a><h3>Creating the Role's Interface</h3><p>
+ we defined a Component as "the combination of a work interface and the
+ implementation of the interface". That work interface is your role.
+ </p>
+<div class="section"><h3><a name="Creating_the_Roles_Interface"></a>Creating the Role's Interface</h3>
+<p>
Below you will find an example interface, followed by some best
practices along with their reasoning.
</p>
- <div class="source"><pre>
+<div class="source"><pre>
package org.apache.bizserver.docs;
@@ -53,80 +480,70 @@
Document getDocument(Principal requestor, int refId);
}
- </pre></div>
- <div class="subsection"><a name="Best_Practices"></a><h3>Best Practices</h3><ol>
- <li>
- <p>
- Include a String called "ROLE" that has the role's official name.
+ </pre>
+</div>
+<div class="section"><h3><a name="Best_Practices"></a>Best Practices</h3>
+<ol type="1"><li>
+ Include a String called "ROLE" that has the role's official name.
That name is the same as the fully qualified name for the work
interface. This helps later on when we need to get an instance
of the Component later.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Do extend the Component interface if possible. This makes it easier
on you when it is time to release your Component. If you are not
in control of the work interface, then you do not have this option.
It is not the end of the world, as you can recast the instance to
<code>Component</code> when it is time to release it.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Do one thing and do it well. A Component should have the simplest
interface possible, When your work interface extends several other
interfaces, you muddy the contract for this Component. An old
American acronym helps define this pattern: Keep It Simple, Stupid
(KISS). It's not hard to outsmart yourself -- I've done it
a number of times myself.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Only specify the methods you need. The client should have no
knowledge of implementation details, and too many alternative
methods only introduce unneeded complexity. In other words pick
an approach and stick with it.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Don't let your Role's interface extend any lifecycle or lifestyle
interfaces. By implementing any of those classes of interfaces, you
are tying an implementation to the specification. This is a
bad pattern and this will only lead to debugging and implementation
problems later.
- </p>
- </li>
- </ol></div><div class="subsection"><a name="Choosing_the_Role_s_Name"></a><h3>Choosing the Role's Name</h3><p>
+ </li>
+</ol>
+</div>
+<div class="section"><h3><a name="Choosing_the_Roles_Name"></a>Choosing the Role's Name</h3>
+<p>
In Avalon, every Role has a name. It is how you get references to
other Components in the system. The Avalon team has outlined some
idioms to follow for the naming of your role.
- </p><div class="subsection"><a name="Naming_Idioms"></a><h3>Naming Idioms</h3><ol>
- <li>
- <p>
+ </p>
+<div class="section"><h3><a name="Naming_Idioms"></a>Naming Idioms</h3>
+<ol type="1"><li>
The fully qualified name of the work interface is usually the
role name. The exceptions are listed after this general rule.
Using this example, our theoretical Component's name would be
- "org.apache.bizserver.docs.DocumentRepository". This is the
- name that would be included in your interface's "ROLE"
+ "org.apache.bizserver.docs.DocumentRepository". This is the
+ name that would be included in your interface's "ROLE"
property.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
If we obtain the reference to this Component through a
Component Selector, we usually take the role name derived from
- the first rule and append the word "Selector" to the end. The
+ the first rule and append the word "Selector" to the end. The
result of this naming rule would be
- "org.apache.bizserver.docs.DocumentRepositorySelector". You
+ "org.apache.bizserver.docs.DocumentRepositorySelector". You
can use the shorthand
- <parameter>DocumentRepository.ROLE + "Selector"</parameter>.
- </p>
- </li>
- <li>
- <p>
+ <parameter>DocumentRepository.ROLE + "Selector"</parameter>.
+ </li>
+<li>
If we have multiple Components that implement the same work
interface, but are used for different purposes, we have
separate roles. A Role is the Component's purpose in the
@@ -136,12 +553,17 @@
we could have the following purposes for our
DocumentRepository: PurchaseOrder and Bill. Our two roles
would be expressed as
- <parameter>DocumentRepository.ROLE + "/PurchaseOrder"</parameter>
- and <parameter>DocuementRepository.ROLE + "/Bill"</parameter>,
+ <parameter>DocumentRepository.ROLE + "/PurchaseOrder"</parameter>
+ and <parameter>DocuementRepository.ROLE + "/Bill"</parameter>,
respectively.
- </p>
- </li>
- </ol></div></div></div></div><div class="section"><a name="Overview_of_Framework_Interfaces"></a><h2>Overview of Framework Interfaces</h2><p>
+ </li>
+</ol>
+</div>
+</div>
+</div>
+</div>
+<div class="section"><h2><a name="Overview_of_Framework_Interfaces"></a>Overview of Framework Interfaces</h2>
+<p>
The entire Avalon Framework can be divided into seven main categories (as
is the API): Activity, Service, Configuration, Context, Logger,
Parameters, Thread, and Miscellany. Each of those categories (except
@@ -149,7 +571,9 @@
Component to implement several interfaces to identify all the concern
areas that the Component is worried about. This will allow the
Component's container to manage each Component in a consistent manner.
- </p><div class="subsection"><a name="Lifecycle_for_Avalon_Interfaces"></a><h3>Lifecycle for Avalon Interfaces</h3><p>
+ </p>
+<div class="section"><h3><a name="Lifecycle_for_Avalon_Interfaces"></a>Lifecycle for Avalon Interfaces</h3>
+<p>
When a framework implements several interfaces to separate the concerns
of the Component, there is potential for confusion over the order of
method calls. Avalon Framework realizes this, and so we developed the
@@ -158,7 +582,8 @@
that will be called. Because there is a correct way to create and
prepare Components, you can set up your Components as you receive
events.
- </p><p>
+ </p>
+<p>
The Lifecycle of a Component is split into three phases:
Initialization, Active Service, and Destruction. Because these phases
are sequential, we will discuss the events in order. In addition, the
@@ -168,113 +593,85 @@
number of stages identified by method names. Those stages are executed
if your Component extends the associated interface specified in
parenthesis.
- </p><div class="subsection"><a name="Initialization"></a><h3>Initialization</h3><p>
+ </p>
+<div class="section"><h3><a name="Initialization"></a>Initialization</h3>
+<p>
This list of stages occurs in this specific order, and occurs only
once during the life of the Component.
- </p><ul>
- <li>
- <p>
- <code>enableLogging</code>
+ </p>
+<ul><li><code>enableLogging</code>
[<code>LogEnabled</code>]
- </p>
- </li>
- <li>
- <p>
- <code>contextualize</code>
+ </li>
+<li><code>contextualize</code>
[<code>Contextualizable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>compose</code>
+ </li>
+<li><code>compose</code>
[<code>Composeable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>service</code>
+ </li>
+<li><code>service</code>
[<code>Serviceable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>configure</code>
+ </li>
+<li><code>configure</code>
[<code>Configurable</code>]
- <em>or</em>
- <code>parameterize</code>
+ <em>or</em><code>parameterize</code>
[<code>Parameterizable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>initialize</code>
+ </li>
+<li><code>initialize</code>
[<code>Initializable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>start</code>
+ </li>
+<li><code>start</code>
[<code>Startable</code>]
- </p>
- </li>
- </ul></div><div class="subsection"><a name="Active_Service"></a><h3>Active Service</h3><p>
+ </li>
+</ul>
+</div>
+<div class="section"><h3><a name="Active_Service"></a>Active Service</h3>
+<p>
This list of stages occurs in this specific order, but may occur
multiple times during the life of the Component. Please note that
should you choose to not implement the Suspendable interface, it is
up to your Component to ensure proper functionality while executing
any of the Re* stages.
- </p><ul>
- <li>
- <p>
- <code>suspend</code>
+ </p>
+<ul><li><code>suspend</code>
[<code>Suspendable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>recontextualize</code>
+ </li>
+<li><code>recontextualize</code>
[<code>Recontextualizable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>recompose</code>
+ </li>
+<li><code>recompose</code>
[<code>Recomposable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>reconfigure</code>
+ </li>
+<li><code>reconfigure</code>
[<code>Reconfigurable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>resume</code>
+ </li>
+<li><code>resume</code>
[<code>Suspendable</code>]
- </p>
- </li>
- </ul></div><div class="subsection"><a name="Destruction"></a><h3>Destruction</h3><p>
+ </li>
+</ul>
+</div>
+<div class="section"><h3><a name="Destruction"></a>Destruction</h3>
+<p>
This list of stages occurs in the order specified, and occurs only
once during the life of the Component.
- </p><ul>
- <li>
- <p>
- <code>stop</code>
+ </p>
+<ul><li><code>stop</code>
[<code>Startable</code>]
- </p>
- </li>
- <li>
- <p>
- <code>dispose</code>
+ </li>
+<li><code>dispose</code>
[<code>Disposable</code>]
- </p>
- </li>
- </ul></div></div><div class="subsection"><a name="Avalon_Framework_Contracts"></a><h3>Avalon Framework Contracts</h3><p>
+ </li>
+</ul>
+</div>
+</div>
+<div class="section"><h3><a name="Avalon_Framework_Contracts"></a>Avalon Framework Contracts</h3>
+<p>
In this section, we will cover all the sections alphabetically with
the exception of the most important concern area: Component.
- </p><table class="bodyTable"><tr class="b"><th>A Word About Containers</th></tr><tr class="a"><td>
- When I use the word "container" or "contains" when describing
+ </p>
+<table class="bodyTable"><tr class="a"><th>A Word About Containers</th>
+</tr>
+<tr class="b"><td>
+ When I use the word "container" or "contains" when describing
Components, I have a very specific meaning. I am referring to child
Components that the parent Component has instantiated and controls.
I am not referring to Components obtained through a ServiceManager or
@@ -285,65 +682,91 @@
Initializable, Startable, Suspendable, and Disposable. The reasoning
for this contract is that these particular interfaces have specific
execution contracts.
- </td></tr></table><div class="subsection"><a name="Service"></a><h3>Service</h3><p>
+ </td>
+</tr>
+</table>
+<div class="section"><h3><a name="Service"></a>Service</h3>
+<p>
This is the core of Avalon Framework. Any interface defined in this concern
area will throw ServiceException.
- </p><div class="subsection"><title>Serviceable</title><p>
+ </p>
+<div class="section"><h3><a></a></h3>
+Serviceable<p>
A Component that uses other Components needs to implement either this
interface or the old Composable interface. The new interface is the
preferred way of doing things. The interface has only one method
<code>service</code> with a
<code>ServiceManager</code> passed in as the only
parameter.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>service</code> is called once and only once during
the lifetime of this Component.
- </p><p>
+ </p>
+<p>
This interface along with any other interface that has methods
specified uses the Inversion of Control pattern. It is called by
the Component's container, and only the Components that this
Component needs should be present in the
<code>ServiceManager</code>.
- </p></div><div class="subsection"><a name="Reserviceable_"></a><h3>Reserviceable?</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Reserviceable"></a>Reserviceable?</h3>
+<p>
The Recomposable interface has no replacement in the Serviceable
package. Use of Recomposable has been extremely rare, and many
applications that use avalon do not provide support for it.
- </p></div></div><div class="subsection"><a name="Activity"></a><h3>Activity</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Activity"></a>Activity</h3>
+<p>
This group of interfaces refers to contracts for the life cycle of
the Component. If there is an error during any method call with this
group of interfaces, then you can throw a generic Exception.
- </p><div class="subsection"><a name="Disposable"></a><h3>Disposable</h3><p>
+ </p>
+<div class="section"><h3><a name="Disposable"></a>Disposable</h3>
+<p>
The <code>Disposable</code> interface is used by any
Component that wants a structured way of knowing it is no longer
needed. Once a Component is disposed of, it can no longer be used.
In fact, it should be awaiting garbage collection. The interface
only has one method <code>dispose</code> that has no
parameters.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>dispose</code> method is called once and the method
is the last one called during the life of the Component. Further
implications include that the Component will no longer be used,
and all resources held by this Component must be released.
- </p></div><div class="subsection"><a name="Initializable"></a><h3>Initializable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Initializable"></a>Initializable</h3>
+<p>
The <code>Initializable</code> interface is used by any
Component that needs to create Components or perform
initializations that take information from other initialization
steps. The interface only has one method
<code>initialize</code> that has no parameters.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>initialize</code> method is called once and the
method is the last one called during the initialization sequence.
Further implications include that the Component is now live, and it
can be used by other Components in the system.
- </p></div><div class="subsection"><a name="Startable"></a><h3>Startable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Startable"></a>Startable</h3>
+<p>
The <code>Startable</code> interface is used by any
Component that is constantly running for the duration of its life.
The interface defines two methods: <code>start</code> and
<code>stop</code>. Neither method has any parameters.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>start</code> method is called once after the
Component is fully initialized, and the <code>stop</code>
@@ -354,7 +777,10 @@
<code>start</code> and <code>stop</code> methods be
conducted safely (unlike the <code>Thread.stop</code>
method) and not render the system unstable.
- </p></div><div class="subsection"><a name="Suspendable"></a><h3>Suspendable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Suspendable"></a>Suspendable</h3>
+<p>
The <code>Suspendable</code> interface is used by any
Component that is running for the duration of its life that permits
itself to be suspended. While it is most commonly used in
@@ -362,7 +788,8 @@
is not required to do so. The interface defines two methods:
<code>suspend</code> and <code>resume</code>.
Neither method has any parameters.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that
<code>suspend</code> and <code>resume</code> may be
called any number of times, but never before the Component is
@@ -370,24 +797,34 @@
disposed. Calls to <code>suspend</code> when the system is
already suspended should have no effect as well as calls to
<code>resume</code> when the system is already running.
- </p></div></div><div class="subsection"><a name="Configuration"></a><h3>Configuration</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Configuration"></a>Configuration</h3>
+<p>
This group of interfaces describes the concern area of configuration.
If there are any problems, such as required
<code>Configuration</code> elements that are missing, then
you may throw a <code>ConfigurationException</code>.
- </p><div class="subsection"><a name="Configurable"></a><h3>Configurable</h3><p>
+ </p>
+<div class="section"><h3><a name="Configurable"></a>Configurable</h3>
+<p>
Components that modify their exact behavior based on configurations
must implement this interface to obtain an instance of the
<code>Configuration</code> object. There is one method
associated with this interface: <code>configure</code> with
a <code>Configuration</code> object as the only
parameter.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>configure</code> method is called once during the
life of the Component. The <code>Configuration</code>
object passed in <em>must not be null</em>.
- </p></div><div class="subsection"><a name="Configuration"></a><h3>Configuration</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Configuration"></a>Configuration</h3>
+<p>
The <code>Configuration</code> object is a representation
of a tree of configuration elements that have attributes. In a
way, you can view the configuration object as an overly simplified
@@ -399,12 +836,14 @@
<code>boolean</code> -- all with default values. You
can do the same for attribute values. You may also get child
<code>Configuration</code> objects.
- </p><p>
+ </p>
+<p>
There is a contract that says that if a
<code>Configuration</code> object has a value that it
should not have any children, and the corollary is also
true -- if there are any children, there should be no value.
- </p><p>
+ </p>
+<p>
You will notice that you may not get parent
<code>Configuration</code> objects. This is by design.
To reduce the complexity of the <code>Configuration</code>
@@ -413,7 +852,10 @@
any access to parent configuration values. This approach might
provide a little inconvenience, but the Avalon team opted for
security by design in every instance where there was a tradeoff.
- </p></div><div class="subsection"><a name="Reconfigurable"></a><h3>Reconfigurable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Reconfigurable"></a>Reconfigurable</h3>
+<p>
Components that implement this interface behave very similar to
<code>Recomposable</code> Components. It's only method
is named <code>reconfigure</code>. This design decision is
@@ -422,7 +864,11 @@
<code>Configurable</code> as
<code>Recomposable</code> is to
<code>Composable</code>.
- </p></div></div><div class="subsection"><a name="Context"></a><h3>Context</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Context"></a>Context</h3>
+<p>
The concept of the <code>Context</code> in Avalon arose
from the need to provide a mechanism to pass simple objects from a
container to a Component. The exact protocol and binding names are
@@ -430,7 +876,9 @@
developers. The contracts surrounding the use of the
<code>Context</code> object are left for you to define in
your system, however the mechanism is the same.
- </p><div class="subsection"><a name="Context"></a><h3>Context</h3><p>
+ </p>
+<div class="section"><h3><a name="Context"></a>Context</h3>
+<p>
The <code>Context</code> interface defines only the
method <code>get</code>. It has an
<code>Object</code> for a parameter, and it returns an
@@ -438,7 +886,8 @@
populated by the container, and passed to the child Component who
only has access to <em>read</em> the
<code>Context</code>.
- </p><p>
+ </p>
+<p>
There is no set contract with the <code>Context</code>
other than it should always be <em>read-only</em> by
the child Component. If you extend Avalon's
@@ -447,18 +896,25 @@
design. In addition, it is a bad idea to pass a reference to the
container in the Context for the same reason that the Context
should be <em>read-only</em>.
- </p></div><div class="subsection"><a name="Contextualizable"></a><h3>Contextualizable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Contextualizable"></a>Contextualizable</h3>
+<p>
A Component that wishes to receive the container's
<code>Context</code> will implement this interface. It
has one method named <code>contextualize</code> with the
parameter being the container's <code>Context</code>
object.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>contextualize</code> method is called once during the
life of a Component, after <code>LogEnabled</code> but
before any other initialization method.
- </p></div><div class="subsection"><a name="Recontextualizable"></a><h3>Recontextualizable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Recontextualizable"></a>Recontextualizable</h3>
+<p>
Components that implement this interface behave very similar to
<code>Recomposable</code> Components. It's only method
is named <code>recontextualize</code>. This design
@@ -467,7 +923,10 @@
<code>Contextualizable</code> as
<code>Recomposable</code> is to
<code>Composable</code>.
- </p></div><div class="subsection"><a name="Resolvable"></a><h3>Resolvable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Resolvable"></a>Resolvable</h3>
+<p>
The Resolvable interface is used to mark objects that need to be
resolved in some particular context. An example might be an object
that is shared by multiple <code>Context</code> objects,
@@ -475,51 +934,72 @@
<code>Context</code>. The <code>resolve</code>
method is called by the <code>Context</code> before the
object is returned.
- </p></div></div><div class="subsection"><a name="Logger"></a><h3>Logger</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Logger"></a>Logger</h3>
+<p>
Every system needs the ability to log events. Avalon uses its
LogKit project internally. While LogKit does have ways of accessing
a Logger instance statically, the Framework wishes to use the
Inversion of Control pattern.
- </p><div class="subsection"><a name="LogEnabled"></a><h3>LogEnabled</h3><p>
+ </p>
+<div class="section"><h3><a name="LogEnabled"></a>LogEnabled</h3>
+<p>
Every Component that needs a Logger instance implements this
interface. The interface has one method named
<code>enableLogging</code> and passes Avalon Framework's
<code>Logger</code> instance to the Component.
- </p><p>
+ </p>
+<p>
The contract surrounding this method is that it is called only
once during the Component's lifecycle before any other
initialization step.
- </p></div><div class="subsection"><a name="Logger"></a><h3>Logger</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Logger"></a>Logger</h3>
+<p>
The <code>Logger</code> interface is used to abstract
away the differences in logging libraries. It provides only a
client API. Avalon Framework provides three wrapper classes that
implement this interface: <code>LogKitLogger</code> for
LogKit, <code>Log4jLogger</code> for Log4J, and
<code>Jdk14Logger</code> for JDK 1.4 logging.
- </p></div></div><div class="subsection"><a name="Parameters"></a><h3>Parameters</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Parameters"></a>Parameters</h3>
+<p>
Avalon realizes that the Configuration object hierarchy can be
heavy in many circumstances. Therefore, we came up with a
<code>Parameters</code> object that captures the
convenience of <code>Configuration</code> objects with a
simple name and value pair.
- </p><div class="subsection"><a name="Parameterizable"></a><h3>Parameterizable</h3><p>
+ </p>
+<div class="section"><h3><a name="Parameterizable"></a>Parameterizable</h3>
+<p>
Any Component that wants to use <code>Parameters</code>
instead of <code>Configuration</code> objects will
implement this interface. <code>Parameterizable</code>
has one method named <code>parameterize</code> with the
parameter being the <code>Parameters</code> object.
- </p><p>
+ </p>
+<p>
The contract is that this is called once during the lifecycle of
the Component. This interface is not compatible with the
<code>Configurable</code> interface.
- </p></div><div class="subsection"><a name="Parameters"></a><h3>Parameters</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Parameters"></a>Parameters</h3>
+<p>
The <code>Parameters</code> object provides a mechanism
to obtain a value based on a <code>String</code> name.
There are convenience methods that allow you to use defaults if the
value does not exist, as well as obtain the value in any of the
same formats that are in the <code>Configurable</code>
interface.
- </p><p>
+ </p>
+<p>
While there are similarities between the
<code>Parameters</code> object and the
<code>java.util.Property</code> object, there are some
@@ -531,58 +1011,75 @@
<code>Parameters</code> object is derived from XML
fragments that look like this:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
-<parameter name="param-name" value="param-value"/>
+<parameter name="param-name" value="param-value"/>
- </pre></div>
- </div></div><div class="subsection"><a name="Component"></a><h3>Component</h3><p>
+ </pre>
+</div>
+</div>
+</div>
+<div class="section"><h3><a name="Component"></a>Component</h3>
+<p>
This used to be the core of Avalon Framework. The Component interface
and it friends have been deprecated in favor of the Service package,
which is exactly the same, except that the service package uses
java.lang.Object in place of the Component interface.
Any interface defined in this
concern area will throw ComponentException.
- </p><div class="subsection"><a name="Component"></a><h3>Component</h3><p>
+ </p>
+<div class="section"><h3><a name="Component"></a>Component</h3>
+<p>
Before the service package was put in place, every Avalon Component
had to implement the Component interface. We have removed this restriction
in the service package.
The Component Manager and Component Selector only handle Components.
There are no methods associated with this interface. It is only used as
a marker interface.
- </p><p>
+ </p>
+<p>
For maximum backward compatibility with existing applications, it can still
be useful to implement the Component interface as older applications may
depend on it being available.
- </p><p>
+ </p>
+<p>
Any Component must use default no parameter constructors. All
configurations are done with the
<code>Configurable</code> or
<code>Parameterizable</code> interfaces.
- </p></div><div class="subsection"><a name="Composable"></a><h3>Composable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Composable"></a>Composable</h3>
+<p>
A Component that uses other Components needs to implement either this
interface or the new Serviceable interface. The new interface is the
preferred way of doing things. The interface has only one method
<code>compose</code> with a
<code>ComponentManager</code> passed in as the only
parameter.
- </p><p>
+ </p>
+<p>
The contract surrounding this interface is that the
<code>compose</code> is called once and only once during
the lifetime of this Component.
- </p><p>
+ </p>
+<p>
This interface along with any other interface that has methods
specified uses the Inversion of Control pattern. It is called by
the Component's container, and only the Components that this
Component needs should be present in the
<code>ComponentManager</code>.
- </p></div><div class="subsection"><a name="Recomposable"></a><h3>Recomposable</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Recomposable"></a>Recomposable</h3>
+<p>
On rare occasions, a Component will need a new
<code>ComponentManager</code> with new Component role
mappings. For those occasions, implement the recomposable
interface. It has a separate method from Composable called
<code>recompose</code>.
- </p><p>
+ </p>
+<p>
The contract surrounding the interface states that the
<code>recompose</code> method can be called any number of
times, but never before the Component is fully initialized. When
@@ -590,7 +1087,11 @@
and consistent manner. Usually this means all processing that the
Component is performing must stop before the update and resume
after the update.
- </p></div></div><div class="subsection"><a name="Thread"></a><h3>Thread</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Thread"></a>Thread</h3>
+<p>
The thread marker interfaces are used to signal to the container
essential semantic information regarding the Component use. They
mark a component implementation in regards to thread safety. It is
@@ -604,7 +1105,9 @@
Excalibur package -- so it is an extension to this core
set -- <code>Poolable</code> that is defined in
Excalibur's pool implementations.
- </p><div class="subsection"><a name="Single_Threaded"></a><h3>Single Threaded</h3><p>
+ </p>
+<div class="section"><h3><a name="Single_Threaded"></a>Single Threaded</h3>
+<p>
is that the interface or the implementation precludes this
Component being accessed by several threads simultaneously. Each
thread needs its own instance of the Component. Alternatively, you
@@ -612,7 +1115,10 @@
every request for the Component. In order to use pooling, you will
need to implement Avalon Excalibur's <code>Poolable</code>
interface instead of this one.
- </p></div><div class="subsection"><a name="ThreadSafe"></a><h3>ThreadSafe</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="ThreadSafe"></a>ThreadSafe</h3>
+<p>
The contract with <code>ThreadSafe</code> Components is
that both their interface and their implementation function
correctly no matter how many threads access the Component
@@ -621,21 +1127,58 @@
using. A Component that implements this interface will generally
only have one instance available in the system, and other
Components will use that one instance.
- </p></div></div><div class="subsection"><a name="Miscellany"></a><h3>Miscellany</h3><p>
+ </p>
+</div>
+</div>
+<div class="section"><h3><a name="Miscellany"></a>Miscellany</h3>
+<p>
The classes and interfaces in the root package for Avalon Framework
incorporates Cascading Exceptions, and a couple of generic utilities.
However, one class deserves mention beyond the others.
- </p><div class="subsection"><a name="Version"></a><h3>Version</h3><p>
+ </p>
+<div class="section"><h3><a name="Version"></a>Version</h3>
+<p>
Java versioning techniques are entries in
the manifest file in a jar. The problem is, when the jar is
unpacked you lose the versioning information, and the versioning
is in an easily modified text file. When you couple this with a
higher learning curve, detecting Component or Interface versions
is difficult.
- </p><p>
+ </p>
+<p>
The Avalon team came up with the Version object to allow you to
have easily determined versions, and to compare versions. You may
implement the <code>Version</code> object in your
Components and your tests for the proper Component or minimum
version level will be much easier.
- </p></div></div></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>
+ </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