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 [7/28] - in /excalibur/site: ./ css/ developing/ event/
fortress/ framework/ images/logos/ instrument/ lifecycle/ sourceresolve/
store/ xmlutil/
Modified: excalibur/site/developing/implementing.html
URL: http://svn.apache.org/viewvc/excalibur/site/developing/implementing.html?rev=785324&r1=785323&r2=785324&view=diff
==============================================================================
--- excalibur/site/developing/implementing.html (original)
+++ excalibur/site/developing/implementing.html Tue Jun 16 17:55:25 2009
@@ -1,31 +1,453 @@
-<!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 - Using Avalon Frameowork</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"><a href="../developing/framework.html">Avalon Framework</a></li><li class="none"><strong><a href="../developing/implementing.html">Using the framework</a></strong></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="Using_Avalon_Framework"></a><h2>Using Avalon Framework</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 - Using Avalon Frameowork</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">
+ <a href="../developing/framework.html">Avalon Framework</a>
+ </li>
+
+ <li class="none">
+ <strong>Using the framework</strong>
+ </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="Using_Avalon_Framework"></a>Using Avalon Framework</h2>
+<p>
After your analysis is complete, you need to create the Components and
Services that make up your system. Avalon would be of little use if it
only described some idioms for you to use. Even then, the use of those
@@ -37,13 +459,18 @@
discussion about the theoretical Business Server, we identified this
Component as a Service. In practical situations, a Service is a Component
that has a larger scope.
- </p></div><div class="section"><a name="Implementing_the_Component"></a><h2>Implementing the Component</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Implementing_the_Component"></a>Implementing the Component</h2>
+<p>
At this point, we define how to implement our Component. We will go
through the process of implementing the DocumentRepository Component
previously mentioned. The first things we need to figure out are the
concern areas for our Component. Then we have to figure out how our
Component will be created and managed.
- </p><div class="section"><a name="Choosing_the_Concern_Areas"></a><h2>Choosing the Concern Areas</h2><p>
+ </p>
+<div class="section"><h2><a name="Choosing_the_Concern_Areas"></a>Choosing the Concern Areas</h2>
+<p>
We have already defined the Role and the Interface for our
DocumentRepository Component in the last chapter, we are ready to
create the implementation. Because the interface for the
@@ -62,14 +489,16 @@
area addressed, you merely implement the associated interface, and
incorporate the new functionality. To the client of your Component,
there is no difference.
- </p><p>
+ </p>
+<p>
Since it is a design goal to be thread-safe, we already know that we
need to implement the ThreadSafe interface. The DocumentRepository
interface only has one method, so the use of the Component's work
interface is compatible with that requirement. Furthermore, we know
that a Component will not be used before it is fully initialized, nor
will it be used once it is destroyed.
- </p><p>
+ </p>
+<p>
There are a couple of implicit interfaces that we need to implement to
accomplish the design. We want our solution to be as secure as
possible and explicitly track whether the Component is fully
@@ -81,16 +510,18 @@
instances of the required Component is by using a ServiceManager. We
will need to implement the Serviceable interface to get an instance of
the ServiceManager.
- </p><p>
+ </p>
+<p>
Because the DocumentRepository accesses the documents in the database,
we need to make a decision. Do we want to take advantage of the Avalon
Excalibur DataSourceComponent, or do we want to implement our own
Connection management code. For the sake of this paper, we will use
the DataSourceComponent.
- </p><p>
+ </p>
+<p>
At this point, our skeleton class looks like this:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
public class DatabaseDocumentRepository
extends AbstractLogEnabled
@@ -118,13 +549,13 @@
{
if (initialized || disposed)
{
- throw new IllegalStateException ("Illegal call");
+ throw new IllegalStateException ("Illegal call");
}
if (null == this.dbResource)
{
- this.dbResource = conf.getChild("dbpool").getValue();
- getLogger().debug("Using database pool: " + this.dbResource);
+ this.dbResource = conf.getChild("dbpool").getValue();
+ getLogger().debug("Using database pool: " + this.dbResource);
// Notice the getLogger()? This is from AbstractLogEnabled
// which I extend for just about all my components.
}
@@ -140,7 +571,7 @@
{
if (initialized || disposed)
{
- throw new IllegalStateException ("Illegal call");
+ throw new IllegalStateException ("Illegal call");
}
if (null == this.manager)
@@ -154,17 +585,17 @@
{
if (null == this.manager)
{
- throw new IllegalStateException("Not Composed");
+ throw new IllegalStateException("Not Composed");
}
if (null == this.dbResource)
{
- throw new IllegalStateException("Not Configured");
+ throw new IllegalStateException("Not Configured");
}
if (disposed)
{
- throw new IllegalStateException("Already disposed");
+ throw new IllegalStateException("Already disposed");
}
this.initialized = true;
@@ -181,15 +612,16 @@
{
if (!initialized || disposed)
{
- throw new IllegalStateException("Illegal call");
+ throw new IllegalStateException("Illegal call");
}
// TODO: FILL IN LOGIC
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
You will notice some constructs in the above code. When you are
designing with security in mind, you should explicitly enforce every
contract on your Component. Security is only as strong as the weakest
@@ -197,25 +629,29 @@
initialized, and never use it when it is disposed of. I placed the
logic that you would need in this skeleton class because that way you
can adopt the same practices in classes that you write.
- </p></div><div class="section"><a name="Instantiating_and_Managing_Components"></a><h2>Instantiating and Managing Components</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Instantiating_and_Managing_Components"></a>Instantiating and Managing Components</h2>
+<p>
In order for you to understand how the Container/Component relationship
works, we will first discuss the manual method of managing Components.
Next, we will discuss how Avalon's Excalibur Component infrastructure
hides the complexity from you. You will still find times when you
would rather manage components yourself. Most of the time the power
and flexibility of Excalibur is just what you need.
- </p><div class="section"><a name="The_Manual_Method"></a><h2>The Manual Method</h2><p>
+ </p>
+<div class="section"><h2><a name="The_Manual_Method"></a>The Manual Method</h2>
+<p>
All of Avalon's Components are created somewhere. The code that
creates the Component is that Component's Container. The Container
is responsible for managing the Component's lifecycle from
construction through destruction. A Container can be the static
- "main" method called from a command line, or it can be another
+ "main" method called from a command line, or it can be another
Component. Remember the Inversion of Control pattern when you
design your Containers. Information and method calls should only
flow from the Container to the Component.
- </p><warning>
- <title>Subversion of Control</title>
- <p>
+ </p>
+<warning>Subversion of Control<p>
Subversion of Control is the anti-pattern to Inversion of Control.
Subversion of control is done when you pass a reference to a
Component's Container to the Component. It is also done when you
@@ -224,14 +660,14 @@
happen when you confuse the Container/Component relationship make
the system harder to debug and security harder to audit.
</p>
- </warning><p>
+</warning><p>
In order to manage the child Components, you need to keep a reference
to them for their entire lifetime. Before the Container or any other
Component can use the child Component, it must go through the
initialization phase of its lifecycle. For our DocumentRepository,
the code will look something like the following:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
class ContainerComponent implements Initializable, Disposable
{
@@ -243,14 +679,14 @@
throws Exception
{
Logger docLogger = new LogKitLogger( Hierarchy.defaultHierarchy()
- .getLoggerFor( "document" ) );
+ .getLoggerFor( "document" ) );
- this.docs.enableLogging( docLogger.childLogger( "repository" ) );
- this.guard.enableLogging( docLogger.childLogger( "security" ) );
+ this.docs.enableLogging( docLogger.childLogger( "repository" ) );
+ this.guard.enableLogging( docLogger.childLogger( "security" ) );
- DefaultConfiguration pool = new DefaultConfiguration("dbpool");
- pool.setValue("main-pool");
- DefaultConfiguration conf = new DefaultConfiguration("");
+ DefaultConfiguration pool = new DefaultConfiguration("dbpool");
+ pool.setValue("main-pool");
+ DefaultConfiguration conf = new DefaultConfiguration("");
conf.addChild(pool);
this.manager.addComponent( DocumentRepository.ROLE, this.docs );
@@ -271,8 +707,9 @@
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
For the sake of brevity, I removed all the explicit checking from the
above code. You can see that manually creating and managing
Components is very detailed. If you forget to do one step in the
@@ -281,7 +718,10 @@
approach would be to add a couple methods to the above
<code>ContainerComponent</code> that handles the
initialization of the components dynamically.
- </p></div><div class="section"><a name="Automated_Autonomy"></a><h2>Automated Autonomy</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Automated_Autonomy"></a>Automated Autonomy</h2>
+<p>
Developer's are naturally lazy, so they would spend the time to write
a specialized ComponentManager that became the Container for all of
their Components in the system. That way they would not have to be
@@ -290,7 +730,8 @@
have created just such a beast. Avalon Excalibur's Component
architecture includes a ComponentManager that is controlled by
configuration files written in XML.
- </p><p>
+ </p>
+<p>
There is a tradeoff when you relinquish the responsibility of
managing a Component to Excalibur's ComponentManager. You relinquish
the fine control over what Components are included in the
@@ -298,7 +739,8 @@
that manual control is a daunting task. In that case, it is better
for the stability of the system for one entity to centrally manage
all the Components in a system.
- </p><p>
+ </p>
+<p>
Since there are varying levels of integration you want to achieve
with Excalibur's Component Architecture, we will start with the
lowest level. Excalibur has a group of ComponentHandler objects that
@@ -308,91 +750,63 @@
treats a Component. Since the lifestyle of a component has impact on
the running of a system, we need to discuss the implications of the
current lifestyle interfaces:
- </p><ol>
- <li>
- <p>org.apache.avalon.framework.thread.SingleThreaded</p>
- <ol>
- <li>
- <p>
+ </p>
+<ol type="1"><li>org.apache.avalon.framework.thread.SingleThreaded<ol type="1"><li>
Not thread-safe or reusable.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
When no lifestyle interface is supplied, this is assumed.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
A brand new instance is created every time the Component is
requested.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Creation and initialization is delayed until you request the
Component.
- </p>
- </li>
- </ol>
- </li>
- <li>
- <p>org.apache.avalon.framework.thread.Threadsafe</p>
- <ol>
- <li>
- <p>
+ </li>
+</ol>
+</li>
+<li>org.apache.avalon.framework.thread.Threadsafe<ol type="1"><li>
Component is fully reentrant, and complies with all
principles of thread safety.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
One instance is created and shared with all Composables that
request it.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Creation and initialization is done when ComponentHandler is
created.
- </p>
- </li>
- </ol>
- </li>
- <li>
- <p>org.apache.avalon.excalibur.pool.Poolable</p>
- <ol>
- <li>
- <p>
+ </li>
+</ol>
+</li>
+<li>org.apache.avalon.excalibur.pool.Poolable<ol type="1"><li>
Not thread-safe, but is fully reusable.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
A pool of instances is created and the free instances are
returned to Composables that request it.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Creation and initialization is done when ComponentHandler is
created.
- </p>
- </li>
- </ol>
- </li>
- </ol><p>
+ </li>
+</ol>
+</li>
+</ol>
+<p>
The ComponentHandler interface is very simple to deal with. You
initialize the Constructor with the Java class, the Configuration
object, the ComponentManager, a Context object, and a RoleManager.
If you know that your Component will not need any of the
aforementioned items, you can pass a null in its place. After
- that, when you need a reference to the Component, you call the "get"
- method. After you are done with it, you call the "put" method and
+ that, when you need a reference to the Component, you call the "get"
+ method. After you are done with it, you call the "put" method and
pass the Component back to the ComponentHandler. The following code
will make it easier to understand.
</p>
- <div class="source"><pre>
+<div class="source"><pre>
class ContainerComponent implements Initializable, Disposable
{
@@ -403,9 +817,9 @@
public void initialize()
throws Exception
{
- DefaultConfiguration pool = new DefaultConfiguration("dbpool");
- pool.setValue("main-pool");
- DefaultConfiguration conf = new DefaultConfiguration("");
+ DefaultConfiguration pool = new DefaultConfiguration("dbpool");
+ pool.setValue("main-pool");
+ DefaultConfiguration conf = new DefaultConfiguration("");
conf.addChild(pool);
this.docs.configure(conf);
@@ -417,10 +831,10 @@
null, this.manager, null, null);
Logger docLogger = new LogKitLogger( Hierarchy.defaultHierarchy()
- .getLoggerFor( "document" ) );
+ .getLoggerFor( "document" ) );
- this.docs.enableLogging( docLogger.childLogger( "repository" ) );
- this.guard.enableLogging( docLogger.childLogger( "security" ) );
+ this.docs.enableLogging( docLogger.childLogger( "repository" ) );
+ this.guard.enableLogging( docLogger.childLogger( "security" ) );
this.manager.addComponent(DocumentRepository.ROLE, this.docs);
this.manager.addComponent(GuardianComponent.ROLE, this.guard);
@@ -436,8 +850,9 @@
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
At this point, we only saved ourselves a few lines of code. We still
manually created our Configuration object, we still had to set the
Logger, and we still had to initialize and dispose of the
@@ -449,24 +864,24 @@
can read a configuration file in the following format, and build the
Components in a system from it.
</p>
- <div class="source"><pre>
+<div class="source"><pre>
<my-system>
<component
- role="org.apache.avalon.excalibur.datasource.DataSourceComponentSelector"
- class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
- <component-instance name="documents"
- class="org.apache.avalon.excalibur.datasource.JdbcDataSource">
- <pool-controller min="5" max="10"/>
+ role="org.apache.avalon.excalibur.datasource.DataSourceComponentSelector"
+ class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
+ <component-instance name="documents"
+ class="org.apache.avalon.excalibur.datasource.JdbcDataSource">
+ <pool-controller min="5" max="10"/>
<auto-commit>false</auto-commit>
<driver>org.gjt.mm.mysql.Driver</driver>
<dburl>jdbc:mysql:localhost/mydb</dburl>
<user>test</user>
<password>test</password>
</component-instance>
- <component-instance name="security"
- class="org.apache.avalon.excalibur.datasource.JdbcDataSource">
- <pool-controller min="5" max="10"/>
+ <component-instance name="security"
+ class="org.apache.avalon.excalibur.datasource.JdbcDataSource">
+ <pool-controller min="5" max="10"/>
<auto-commit>false</auto-commit>
<driver>org.gjt.mm.mysql.Driver</driver>
<dburl>jdbc:mysql:localhost/myotherdb</dburl>
@@ -475,20 +890,21 @@
</component-instance>
</component>
<component
- role="org.apache.bizserver.docs.DocumentRepository"
- class="org.apache.bizserver.docs.DatabaseDocumentRepository">
+ role="org.apache.bizserver.docs.DocumentRepository"
+ class="org.apache.bizserver.docs.DatabaseDocumentRepository">
<dbpool>documents</dbpool>
</component>
<component
- role="org.apache.bizserver.docs.GuardianComponent"
- class="org.apache.bizserver.docs.DocumentGuardianComponent">
+ role="org.apache.bizserver.docs.GuardianComponent"
+ class="org.apache.bizserver.docs.DocumentGuardianComponent">
<dbpool>security</dbpool>
- <policy file="/home/system/document.policy"/>
+ <policy file="/home/system/document.policy"/>
</component>
</my-system>
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
The root element can be anything you want. You will notice that we
now have several Components defined. We have our familiar
DocumentRepository class and GuardianComponent class, as well as a
@@ -497,13 +913,14 @@
Component. In order to read that information into your system,
Avalon Framework provides some conveniences for you:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
-Configuration systemConf = builder.buildFromFile("/path/to/file.xconf");
+Configuration systemConf = builder.buildFromFile("/path/to/file.xconf");
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
This does simplify all the code we had for hand-building the
Configuration element earlier, and it limits the amount of
information we need to explicitly know right away. We will take one
@@ -512,7 +929,7 @@
ComponentSelector counts as a Component), and configurations for
each of them.
</p>
- <div class="source"><pre>
+<div class="source"><pre>
class ContainerComponent implements Initializable, Disposable {
ExcaliburComponentManager manager = new ExcaliburComponentManager();
@@ -521,10 +938,10 @@
throws Exception
{
DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
- Configuration sysConfig = builder.buildFromFile("./conf/system.xconf");
+ Configuration sysConfig = builder.buildFromFile("./conf/system.xconf");
this.manager.setLogger( Hierarchy.getDefaultHierarchy()
- .getLoggerFor("document") );
+ .getLoggerFor("document") );
this.manager.contextualize( new DefaultContext() );
this.manager.configure( sysConfig );
this.manager.initialize();
@@ -536,23 +953,27 @@
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
Isn't this amazing? We have more than twice the number Components
initialized and ready for use with less than half the code (six lines
of code instead of thirteen lines of code). There is the drawback of
the Configuration file looking somewhat crazy, but it minimizes the
amount of code you have to write.
- </p><p>
+ </p>
+<p>
There is a lot of activity happening under the hood of the
- ExcaliburComponentManager. For each "component" element in the
+ ExcaliburComponentManager. For each "component" element in the
configuration file, Excalibur creates a ComponentHandler for each
- class entry and maps it to the role entry. The "component" element
+ class entry and maps it to the role entry. The "component" element
and all it's child elements are used for the Configuration of the
Component. When the Component is an ExcaliburComponentSelector, the
- Excalibur reads each "component-instance" element and performs the
+ Excalibur reads each "component-instance" element and performs the
same type of operation as before-this time mapping to the hint entry.
- </p><div class="section"><title>Making the Configuration Pretty</title><p>
+ </p>
+<div class="section"><h2><a></a></h2>
+Making the Configuration Pretty<p>
We can manage the configuration file's appearance with the use of
aliases. Excalibur uses a RoleManager to provide aliases for the
configuration system. A RoleManager can either be a dedicated
@@ -563,7 +984,7 @@
going to be altered by developers. Below is the interface for the
RoleManager:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
interface RoleManager
{
@@ -572,95 +993,99 @@
String getDefaultClassNameForHint( String hint, String shorthand );
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
Let's take a look at how Excalibur uses the RoleManager in our
scheme. First, Excalibur will cycle through all the elements that
are direct children of the root element. This includes all
- "component" elements like before, but this time when Excalibur
+ "component" elements like before, but this time when Excalibur
doesn't recognize an element name, it asks the RoleManager which
role we should use for this Component. If the RoleManager returns
null, the element and all it's child elements are ignored. Next,
Excalibur derives the class name from the role name. The last
method is to dynamically map a class name to a ComponentSelector's
child type.
- </p><p>
+ </p>
+<p>
Excalibur provides a default implementation of the RoleManager that
is configured with an XML configuration file. The markup is very
simple, and it hides all the extra information you don't want your
administrator to see.
</p>
- <div class="source"><pre>
+<div class="source"><pre>
<role-list>
<role
- name="org.apache.avalon.excalibur.datasource.DataSourceComponentSelector"
- shorthand="datasources"
- default-class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
- <hint shorthand="jdbc"
- class="org.apache.avalon.excalibur.datasource.JdbcDataSourceComponent"/>
- <hint shorthand="j2ee"
- class="org.apache.avalon.excalibur.datasource.J2eeDataSourceComponent"/>
+ name="org.apache.avalon.excalibur.datasource.DataSourceComponentSelector"
+ shorthand="datasources"
+ default-class="org.apache.avalon.excalibur.component.ExcaliburComponentSelector">
+ <hint shorthand="jdbc"
+ class="org.apache.avalon.excalibur.datasource.JdbcDataSourceComponent"/>
+ <hint shorthand="j2ee"
+ class="org.apache.avalon.excalibur.datasource.J2eeDataSourceComponent"/>
</role>
<role
- name="org.apache.bizserver.docs.DocumentRepository"
- shorthand="repository"
- default-class="org.apache.bizserver.docs.DatabaseDocumentRepository"/>
+ name="org.apache.bizserver.docs.DocumentRepository"
+ shorthand="repository"
+ default-class="org.apache.bizserver.docs.DatabaseDocumentRepository"/>
<role
- name="org.apache.bizserver.docs.GuardianComponent"
- shorthand="guardian"
- default-class="org.apache.bizserver.docs.DocumentGuardianComponent"/>
+ name="org.apache.bizserver.docs.GuardianComponent"
+ shorthand="guardian"
+ default-class="org.apache.bizserver.docs.DocumentGuardianComponent"/>
</role-list>
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
In order to use the RoleManager, you do need to alter the
- "initialize" method of our Container class. You are using the
+ "initialize" method of our Container class. You are using the
configuration builder to build a Configuration tree from this
file. Please remember, if you are going to use a RoleManager, you
- must call the "setRoleManager" method <em>before</em>
- the "configure" method. To demonstrate how you would retrieve this
+ must call the "setRoleManager" method <em>before</em>
+ the "configure" method. To demonstrate how you would retrieve this
XML file from the class loader, I will demonstrate the technique
below:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
DefaultConfigurationBuilder builder = new DefaultConfigurationBuilder();
-Configuration sysConfig = builder.buildFromFile("./conf/system.xconf");
+Configuration sysConfig = builder.buildFromFile("./conf/system.xconf");
Configuration roleConfig = builder.build(
this.getClass().getClassLoader()
- .getResourceAsStream("/org/apache/bizserver/docs/document.roles"));
+ .getResourceAsStream("/org/apache/bizserver/docs/document.roles"));
DefaultRoleManager roles = new DefaultRoleManager();
-roles.enableLogging(Hierarchy.getDefaultHierarchy().getLoggerFor("document.roles"));
+roles.enableLogging(Hierarchy.getDefaultHierarchy().getLoggerFor("document.roles"));
roles.configure(roleConfig);
this.manager.setLogger( Hierarchy.getDefaultHierarchy()
- .getLoggerFor("document") );
+ .getLoggerFor("document") );
this.manager.contextualize( new DefaultContext() );
this.manager.setRoleManager( roles );
this.manager.configure( sysConfig );
this.manager.initialize();
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
Since we added six more lines of code, we need to see what it
bought us. Our final configuration file can be written like this:
</p>
- <div class="source"><pre>
+<div class="source"><pre>
<my-system>
<datasources>
- <jdbc name="documents">
- <pool-controller min="5" max="10"/>
+ <jdbc name="documents">
+ <pool-controller min="5" max="10"/>
<auto-commit>false</auto-commit>
<driver>org.gjt.mm.mysql.Driver</driver>
<dburl>jdbc:mysql:localhost/mydb</dburl>
<user>test</user>
<password>test</password>
</jdbc>
- <jdbc name="security">
- <pool-controller min="5" max="10"/>
+ <jdbc name="security">
+ <pool-controller min="5" max="10"/>
<auto-commit>false</auto-commit>
<driver>org.gjt.mm.mysql.Driver</driver>
<dburl>jdbc:mysql:localhost/myotherdb</dburl>
@@ -673,16 +1098,23 @@
</repository>
<guardian>
<dbpool>security</dbpool>
- <policy file="/home/system/document.policy"/>
+ <policy file="/home/system/document.policy"/>
</guardian>
</my-system>
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
As you can see, this is much more readable than how we started.
Now we can add any number of components to our system, and we won't
have to write any more code to support them.
- </p></div></div></div></div><div class="section"><a name="Using_the_Component"></a><h2>Using the Component</h2><p>
+ </p>
+</div>
+</div>
+</div>
+</div>
+<div class="section"><h2><a name="Using_the_Component"></a>Using the Component</h2>
+<p>
Now that we have created our Components, we will want to use them. You
access Components the same way regardless of how they were instantiated
or managed. You must implement the Composable interface to get a
@@ -691,7 +1123,9 @@
we will assume that the ComponentManager given to us is configured in the
same manner as the final Configuration file in the last section. This
means that we have a Repository, a Guardian, and two DataSources.
- </p><div class="section"><a name="Rules_for_Using_the_Component_Management_Infrastructure"></a><h2>Rules for Using the Component Management Infrastructure</h2><p>
+ </p>
+<div class="section"><h2><a name="Rules_for_Using_the_Component_Management_Infrastructure"></a>Rules for Using the Component Management Infrastructure</h2>
+<p>
The Component management infrastructure requires that you release any
Component for which you have obtained a reference. The reason for this
restriction is so that the Component's resources can be properly
@@ -701,14 +1135,16 @@
with the same role. Another unique aspect of the ComponentSelector is
that it is a Component by design. This enables us to get a
ComponentSelector from a ComponentManager.
- </p><p>
+ </p>
+<p>
There are two valid approaches for handling references to external
Components. You can obtain your references during initialization, and
release them during disposal. You may also encapsulate the Component
handling in a try/catch/finally block. Each has its advantages and
disadvantages.
- </p><div class="section"><a name="Initialization_and_Disposal_Approach"></a><h2>Initialization and Disposal Approach</h2>
- <div class="source"><pre>
+ </p>
+<div class="section"><h2><a name="Initialization_and_Disposal_Approach"></a>Initialization and Disposal Approach</h2>
+<div class="source"><pre>
class MyClass implements Serviceable, Disposable
{
@@ -735,7 +1171,7 @@
public void myMethod()
throws SecurityException
{
- this.myGuard.checkPermission(new BasicPermission("test"));
+ this.myGuard.checkPermission(new BasicPermission("test"));
}
/**
@@ -749,8 +1185,9 @@
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
As you can see by the sample code, this is easy to follow. The
object gets a reference to a Guardian Component when it first
receives the ComponentManager. If you could be guaranteed that the
@@ -759,7 +1196,8 @@
term. To properly manage resources, we must release the Component
when we are done with it. That's why we kept a reference to the
ComponentManager.
- </p><p>
+ </p>
+<p>
The main disadvantage of this approach comes into play when you are
dealing with pooled Components. The reference of the Component is
kept for the life of this object. It might not be a problem if the
@@ -767,11 +1205,13 @@
the Excalibur component management architecture, its life span is as
long as the Component whose reference it has. What this means is
that we are essentially turning the Component's pool into a Factory.
- </p><p>
+ </p>
+<p>
The main advantage of this approach is that the code is very clear on
how a Component is obtained and released. You don't have to have any
understanding of exception handling.
- </p><p>
+ </p>
+<p>
One other nuance is that you are tying the existence of the Guardian
to the ability to initialize this object. Once an Exception is
thrown during the initialization phase of an object, you must assume
@@ -779,8 +1219,10 @@
required Component does not exist so this is not a problem. You do
need to be aware of this implication when you are designing your
Components though.
- </p></div><div class="section"><a name="Exception_Handling_Approach"></a><h2>Exception Handling Approach</h2>
- <div class="source"><pre>
+ </p>
+</div>
+<div class="section"><h2><a name="Exception_Handling_Approach"></a>Exception Handling Approach</h2>
+<div class="source"><pre>
class MyClass implements Serviceable, Disposable
{
@@ -834,25 +1276,28 @@
public void criticalSection(Guardian myGuard)
throws SecurityException
{
- myGuard.checkPermission(new BasicPermission("test"));
+ myGuard.checkPermission(new BasicPermission("test"));
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
As you can see, the code is a bit more complex. In order to
understand it, you have to understand Exception handling. This is
not necessarily a problem, because most Java developers know how to
handle them. You don't have to worry so much about the Component
life style with this approach, because we are releasing it as soon
as we no longer need it.
- </p><p>
+ </p>
+<p>
The main disadvantage of this approach is the added complexity of the
exception handling code. In order to minimize the complexity and
make the code more maintainable, we extracted the working code into
another method. Keep in mind that we can get the reference to as
many Components as we possibly want inside the try block.
- </p><p>
+ </p>
+<p>
The main advantage of this approach is that you are managing your
Component references more efficiently. Again, there is no real
difference if you are using ThreadSafe Components, but it makes a
@@ -860,14 +1305,19 @@
overhead dealing with getting a new reference every time you use a
Component, but the likelihood of being forced to create a new
instance of the Component is minimized.
- </p><p>
+ </p>
+<p>
Just like the Initialization and Disposal Approach, you have to
understand a subtle nuance. The Exception Handling Approach does not
fail on initialization if the Component is missing from the manager.
As mentioned before, this is not entirely bad. Many times, you want
an object to exist, but it is not a failure if a desired Component
is missing.
- </p></div></div><div class="section"><a name="Getting_Components_from_a_ServiceSelector"></a><h2>Getting Components from a ServiceSelector</h2><p>
+ </p>
+</div>
+</div>
+<div class="section"><h2><a name="Getting_Components_from_a_ServiceSelector"></a>Getting Components from a ServiceSelector</h2>
+<p>
For most operations, you will only need the ServiceManager. Since we
decided that we needed multiple instances of the DataSourceComponent,
we need to know how to get the instance we want. ServiceSelectors
@@ -878,7 +1328,8 @@
an arbitrary object for the hint. Most of the time, the object is a
String, although you might want to use a Locale object to get a proper
internationalization Component.
- </p><p>
+ </p>
+<p>
In our system we have set up, we chose to use Strings to select the
correct instance of the DataSourceComponent. We even gave ourselves a
Configuration element that references the exact string we need to get
@@ -886,7 +1337,8 @@
easier on administrators of a system. It is easier for an
administrator to see a reference to another Component than it is for
them to remember magic values for the configuration.
- </p><p>
+ </p>
+<p>
Conceptually, getting a Component from a ServiceSelector is no
different than getting a Component from a ServiceManager. You just
have one more step. Remember that a ServiceSelector is a Component.
@@ -895,7 +1347,7 @@
the selector. To demonstrate, I will extend the code from the
Exception Handling Approach discussed previously.
</p>
- <div class="source"><pre>
+<div class="source"><pre>
public void myMethod()
throws Exception
@@ -905,7 +1357,7 @@
try
{
dbSelector = (ServiceSelector)
- this.manager.lookup(DataSourceComponent.ROLE + "Selector");
+ this.manager.lookup(DataSourceComponent.ROLE + "Selector");
datasource = (DataSourceComponent)
dbSelector.select(this.useDb);
@@ -929,33 +1381,44 @@
}
}
- </pre></div>
- <p>
+ </pre>
+</div>
+<p>
As you can see, we got the reference to the ServiceSelector using the
Role specified for the Component. We followed the Role naming
- guidelines outlined in a previous chapter by adding the "Selector"
+ guidelines outlined in a previous chapter by adding the "Selector"
suffix to the Role name. It is also perfectly acceptable to use a
static interface for all the Role names in your system to minimize the
number of String concatenation in your code.
- </p><p>
+ </p>
+<p>
Next, we obtained the reference to the DataSourceComponent from the
ServiceSelector. Our sample code assumed that we had already pulled
the required information from the Configuration object and placed it in
- a class variable named "useDb".
- </p></div></div><div class="section"><a name="Excalibur_s_Utilities"></a><h2>Excalibur's Utilities</h2><p>
+ a class variable named "useDb".
+ </p>
+</div>
+</div>
+<div class="section"><h2><a name="Excaliburs_Utilities"></a>Excalibur's Utilities</h2>
+<p>
This last section is included to give you an idea of the types of
Components and utilities that are included with Apache Avalon Excalibur.
These utilities are robust, and fully usable in production systems. We
- do have an unofficial staging project called "Scratchpad" where we iron
+ do have an unofficial staging project called "Scratchpad" where we iron
out implementation details for potential new utilities. Scratchpad
utilities are of varying quality, and their use is not guaranteed to
remain the same -- although you may have good experience with them.
- </p><div class="section"><a name="Command_Line_Interface__CLI_"></a><h2>Command Line Interface (CLI)</h2><p>
+ </p>
+<div class="section"><h2><a name="Command_Line_Interface_CLI"></a>Command Line Interface (CLI)</h2>
+<p>
The CLI utilities are used by a number of projects including Avalon
Phoenix and Apache Cocoon to process command line arguments. It
provides facilities to print help responses, and to process options by
either a short name or a long name.
- </p></div><div class="section"><a name="Collection_Utilities"></a><h2>Collection Utilities</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Collection_Utilities"></a>Collection Utilities</h2>
+<p>
The collection utilities provide some enhancements to the
Java Collections API. Among them is the ability
to find the intersections between two lists and a
@@ -963,7 +1426,10 @@
<code>Stack</code> to allow the priority of objects override
the simple first in/last out <code>Stack</code>
implementation.
- </p></div><div class="section"><a name="Component_Management"></a><h2>Component Management</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Component_Management"></a>Component Management</h2>
+<p>
We already discussed the use of this in the previous section. This is
Excalibur's most complex beast, but it provides a lot of functionality
in just a few classes. It will make one distinction more than simple
@@ -975,30 +1441,45 @@
pool of Components and reuse instances. Most of the time this works
great. For those last remaining times where a Component cannot be
reused, use the <code>SingleThreaded</code> interface.
- </p></div><div class="section"><a name="LogKit_Management"></a><h2>LogKit Management</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="LogKit_Management"></a>LogKit Management</h2>
+<p>
The Avalon development team realized that many people wanted a simple
mechanism to build complex Logging target heirarchies. In the same
spirit as the <code>RoleManager</code> the team developed
a <code>LogKitManager</code> that can be given to the
Excalibur Component Management system meantioned above. Based on the
- "logger" attribute it will give the proper <code>Logger</code>
+ "logger" attribute it will give the proper <code>Logger</code>
object to the different Components.
- </p></div><div class="section"><a name="Thread_Utilities"></a><h2>Thread Utilities</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Thread_Utilities"></a>Thread Utilities</h2>
+<p>
The <em>concurrent</em> package contains several classes
to assist in multithreaded programming: <code>Lock</code>
(a mutex implementation), <code>DjikstraSemaphore</code>,
<code>ConditionalEvent</code>, and
<code>ThreadBarrier</code>.
- </p></div><div class="section"><a name="Datasources"></a><h2>Datasources</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Datasources"></a>Datasources</h2>
+<p>
This is modeled after the <code>javax.sql.DataSource</code>
class, but simplified. There are two implementations of the
<code>DataSourceComponent</code>: one that pools JDBC
connections explicitly, and one that uses a J2EE application server's
<code>javax.sql.DataSource</code> class.
- </p></div><div class="section"><a name="Input_Output__IO__Utilities"></a><h2>Input/Output (IO) Utilities</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="InputOutput_IO_Utilities"></a>Input/Output (IO) Utilities</h2>
+<p>
The IO utilties provide a number of <code>FileFilter</code>s
and other <code>File</code> and IO specific utilities.
- </p></div><div class="section"><a name="Pool_Implementations"></a><h2>Pool Implementations</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Pool_Implementations"></a>Pool Implementations</h2>
+<p>
The Pool implementations provide a <code>Pool</code> for
every occasion. You have an implementation that is blazingly fast, but
only usable in one thread -- which should be ok for implementing a
@@ -1009,11 +1490,42 @@
<code>HardResourceManagingPool</code> throws an exception
when you have reached the maximum number of objects. The last three
pools are all <code>ThreadSafe</code>.
- </p></div><div class="section"><a name="Property_Utilities"></a><h2>Property Utilities</h2><p>
+ </p>
+</div>
+<div class="section"><h2><a name="Property_Utilities"></a>Property Utilities</h2>
+<p>
The property utilities are used in conjunction with Context objects.
- They give you the ability to expand "variables" in your
+ They give you the ability to expand "variables" in your
<code>Resolvable</code> object. It works like this:
- <parameter>"${resource}"</parameter> will look for a Context value
- named <parameter>"resource"</parameter> and substitute its value
+ <parameter>"${resource}"</parameter> will look for a Context value
+ named <parameter>"resource"</parameter> and substitute its value
for the symbol.
- </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/developing/index.html
URL: http://svn.apache.org/viewvc/excalibur/site/developing/index.html?rev=785324&r1=785323&r2=785324&view=diff
==============================================================================
--- excalibur/site/developing/index.html (original)
+++ excalibur/site/developing/index.html Tue Jun 16 17:55:25 2009
@@ -1,87 +1,505 @@
-<!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 - Developing With Apache Avalon</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"><strong><a href="../developing/index.html">Developing</a></strong><ul><li class="none"><a href="../developing/authors.html">Autho
rs</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"><a href="../developing/framework.html">Avalon Framework</a></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="Developing_With_Apache_Avalon"></a><h2>Developing With Apache Avalon</h2><p>
- <strong>Developing With Apache Avalon</strong>: Developer's Guide for the Avalon Framework
- </p><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 - Developing With Apache Avalon</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">
+ <strong>Developing</strong>
+ <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">
+ <a href="../developing/framework.html">Avalon Framework</a>
+ </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="Developing_With_Apache_Avalon"></a>Developing With Apache Avalon</h2>
+<p><strong>Developing With Apache Avalon</strong>: Developer's Guide for the Avalon Framework
+ </p>
+<p>
Published 2001. Copyright 2001-2003 Apache Software Foundation.
- </p><div class="subsection"><a name="Dedicatation"></a><h3>Dedicatation</h3><p>
+ </p>
+<div class="section"><h3><a name="Dedicatation"></a>Dedicatation</h3>
+<p>
This developer's guide is dedicated to the three people who's vision
started the Avalon project: Federico Barbieri, Stefano Mazzocchi, and
Pierpaolo Fumagalli. Their concept for the Avalon project has stood
the test of time.
- </p></div><div class="subsection"><a name="Legal_Notice"></a><h3>Legal Notice</h3><p>
+ </p>
+</div>
+<div class="section"><h3><a name="Legal_Notice"></a>Legal Notice</h3>
+<p>
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:
- </p><ul>
- <li>
- <p>
+ </p>
+<ul><li>
Redistributions of source code must retain the above
copyright notice, this list of conditions and the following
disclaimer.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
The end-user documentation included with the redistribution,
if any, must include the following acknowledgment:
- "This product includes software developed by the Apache
- Software Foundation (http://www.apache.org/)." Alternately,
+ "This product includes software developed by the Apache
+ Software Foundation (http://www.apache.org/)." Alternately,
this acknowledgment may appear in the software itself, if
and wherever such third-party acknowledgments normally appear.
- </p>
- </li>
- <li>
- <p>
- The names "Jakarta", "Apache Avalon", "Avalon Excalibur",
- "Avalon Framework" and "Apache Software Foundation" must not
+ </li>
+<li>
+ The names "Jakarta", "Apache Avalon", "Avalon Excalibur",
+ "Avalon Framework" and "Apache Software Foundation" must not
be used to endorse or promote products derived from this
software without prior written permission. For written
permission, please contact apache@apache.org.
- </p>
- </li>
- <li>
- <p>
+ </li>
+<li>
Products derived from this software may not be called
- "Apache", nor may "Apache" appear in their name, without
+ "Apache", nor may "Apache" appear in their name, without
prior written permission of the Apache Software Foundation.
- </p>
- </li>
- </ul><p>
- THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
+ </li>
+</ul>
+<p>
+ THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION
@@ -93,15 +511,45 @@
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- </p><p>
+ </p>
+<p>
This software consists of voluntary contributions made by many
individuals on behalf of the Apache Software Foundation. For more
information on the Apache Software Foundation, please see
<http://www.apache.org/>.
- </p><p>
+ </p>
+<p>
Java and all Java-based
trademarks and logos are trademarks or registered trademarks
of Sun Microsystems, Inc., in the United States and other
countries. The Apache Software Foundation is independant of
Sun Microsystems.
- </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>
---------------------------------------------------------------------
To unsubscribe, e-mail: scm-unsubscribe@excalibur.apache.org
For additional commands, e-mail: scm-help@excalibur.apache.org