incubator-composer-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hamm...@apache.org
Subject svn commit: r618174 [3/5] - in /incubator/composer/trunk: ./ composer-site/ composer-site/src/ composer-site/src/assembly/ composer-site/src/config/ composer-site/src/resources/ composer-site/src/resources/images/ composer-site/src/resources/style/ com...
Date Mon, 04 Feb 2008 06:33:26 GMT
Added: incubator/composer/trunk/composer-site/src/site/content/inversion-of-control-history.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/inversion-of-control-history.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/inversion-of-control-history.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/inversion-of-control-history.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,115 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html><head>
+<title>Inversion of Control History</title></head>
+
+
+<body>
+<p>Here is some of the history of the pattern or principle known as
+Inversion of Control (IoC). There is some confusion online as to
+whether IoC has been renamed Dependency Injection (DI). This is not the
+case, DI concerns just one aspect of IoC - component assembly. The
+other two are configuration and lifecycle. </p>
+<p>See also the <a href="comparisons.html">comparisons</a> page. </p>
+<h2>Avalon</h2>
+<p>Inversion of Control, as a term, was popularised in 1998 by <a href="http://www.betaversion.org/%7Estefano/">Stefano Mazzocchi</a>
+as consequence of trying to engineer a 'Java Apache Server Framework'
+for the growing set of server side Java components and tools at <a href="http://www.apache.org/">Apache</a>.
+Sun were just starting to protect the word Java when used for
+branding/naming of software and computing functions, so Apache had to
+look for alternative names. Avalon was chosen as a project name (queue
+images of <a href="http://en.wikipedia.org/wiki/Avalon">Arthurian legend</a>).</p>
+<p>To the Avalon team, it was clear that components receiving various aspects of <strong>component assembly</strong>, <strong>configuration</strong> and <strong>lifecycle</strong> was a superior design to those components going at getting the same themselves. </p>
+<p>It is important to point out that The Open Services Gateway (OSGi)
+initiative was also started around the same time as the Avalon
+framework and was similar to a degree. It was born in Europe and
+specified/controlled by a foundation formed around it.&nbsp; </p>
+<p>Latterly this type of IoC has been given a new name - Contextualized Dependency Lookup.</p>
+<p>Avalon was cancelled as an Apache project in 2004, by the Apache Software Foundation.</p>
+<h2>Setter Injection</h2>
+<p><a href="http://joe.truemesh.com/blog/">Joe Walnes</a>, <a href="http://joe.truemesh.com/blog/">Mike Cannon Brookes</a> and others found themselves writing <a href="http://www.opensymphony.com/xwork/">XWork</a> and <a href="http://www.opensymphony.com/webwork/">WebWork2</a> to support their forthcoming book, <a href="http://www.amazon.com/Java-Open-Source-Programming-Hibernate/dp/0471463620">Java Open Source Programming</a>.
+Joe pointed out that the concepts were very much like those from
+IoC/Avalon that Paul had been trying to convince Joe to adopt for a
+couple of years, but that dependencies were passed into the component
+via setters. The need for those dependencies was declared in some
+accompanying XML.</p>
+<p>Paul who worked with Joe at an Energy Trading Company in London,
+suggested this was a different type of Inversion of Control. That, as a
+term, has been obsoleted for "Setter Injection" of course. </p>
+<p><a href="http://blog.interface21.com/main/author/rodj/">Rod Johnson</a>, lead for the <a href="http://www.springframework.org/">Spring Framework</a> wrote a book <a href="http://www.wrox.com/WileyCDA/WroxTitle/productCd-0764543857.html">Expert  One-on-One J2EE Design and Development</a>
+(published Oct 2002) that also discussed the concepts of setter
+injection, and introduced the codeline that ultimately became the <a href="http://sourceforge.net/projects/springframework">Spring Framework</a> at SourceForge in February of 2003. </p>
+<p>Martin Fowler has suggested that it may be better to have such
+dependency resolving methods prefixed with init rather than setter.
+With init or set prefixes to dependency receiving methods, a container
+could automatically assemble SDI components without the manifest. SDI,
+under container control, works best with the manifest though. Without a
+container, SDI Components are very much like simple Java beans to use:</p>
+<p>A downside of direct bean user of an SDI component is that it is
+possible to instantiate a component without setting all the
+dependencies. As mistakes, these should be quite quick to catch
+post-compile with a simple test of that application. Months later
+though, when a jar of components is replaced in an application with a
+latter version of the same, a new dependency may be missed, and a
+non-functioning application may be shipped to live. Again, that could
+be caught with diligent testing.</p>
+<h2>Constructor  Injection </h2>
+<p>Rachel Davies, as one of the enthusiastic reviewers of Joe's book,
+left a margin note for the paragraphs that discussed the elegance of
+type two. The margin-note simply suggested that resolving dependencies
+by constructor was more elegant. Latterly we are inclined to agree. At
+that moment in time (the spring of 2003) there were no implementation
+of the constructor injection idea, so it seemed logical for the initial
+Apache Composer leads (Paul Hammant and Aslak Hellesoy) who liked the
+idea, to kick off the project.</p>
+<p>The added advantage is that CDI Components cannot be instantiated
+with missing dependencies. Thus the compiler or IDE will catch
+mismatches between any constructor and the parameters passed into the
+class on instantiation.</p>
+<p><a href="http://www.atg.com/en/company/dynamo.jhtml">ATG Dynamo</a>
+was a commercial product that was successful in the market place in the
+late 90's. It also used constructors for dependency resolution.
+Dynamo's commercial success yielded a little when Apache made Struts,
+but it should not be forgotten that Dynamo casually used constructors
+for dependencies in web-applications first. </p>
+<h2>Types 1, 2 &amp; 3 renamed </h2>
+<p>In 2003, Paul was refering to the Avalon style of IoC as "type 1",
+setter as "type 2" and constructor as "type 3". He went as far as
+publishing an <a href="http://java.sys-con.com/read/38102.htm">article</a> on it in Java Developer Journal.   </p>
+<p><em>December 2003</em>; Rod Johnson of the Spring Framework team,
+Paul Hammant (former Avaloner, and co-lead of Apache Composer), Mike
+Royle, with Martin Fowler (by email) say down and played with some of
+the language of Martin's forthcoming article. Martin had drafted this
+article entirely independently of this team but had be kind enough to
+show a draft to them. The problem the team had was with the naming of
+the patterns related to Inversion of Control, and the examples of use
+that Martin had shown. Rod had been using the injection phrase before
+so it was felt that the component resolving style being "Dependency
+Injection" would be a good thing. </p>
+
+<p>Thus when Dependency Injection rightly took over:</p>
+
+<blockquote>
+  <p>	Type 1 becomes Contextualized Dependency Lookup<br />
+    <br />
+    Type 2 becomes Setter Dependency Injection<br />
+    <br />
+    Type 3 becomes Constructor Dependency Injection</p>
+  <p>Type 4 was Field Injection or getter injection depending on who you spoke to. </p>
+</blockquote>
+<h2>Timelines</h2>
+<p><img src="images/ioc-timeline.png" alt="timeline picture" height="347" width="691" /></p>
+<h2>Prior Art</h2>
+<p>As a concept, Inversion of Control was not entirely new when
+Steffano popularised it at Apache in 1998. Parts of it been talked
+about before as Dependency Inversion Principle (Bob Martin) and the
+'Hollywood Principle' (don't call us, we'll call you), and the term
+cropped had been cropping up since 1996. </p>
+<p>Gang of Four, <a href="http://en.wikipedia.org/wiki/Design_Patterns">Design Patterns</a>, 1994 "Hollywood Pattern" (don't call us, we'll call you) as discussion point on 'Template' Pattern. </p>
+<p>Robert C. Martin, "Dependency Inversion" in posting on comp.lang.c++, August 1994: <a href="http://groups.google.com/group/comp.lang.c++/msg/b9c929f55c52e4a2?">OO Design Quality Metrics: An Analysis of Dependencies</a> </p>
+<p>Robert C. Martin, : "Principle of Depenency Inversion" in posting on comp.lang.c++, June 1995: <a href="http://groups.google.com/group/comp.lang.c++/msg/30f7c7701209faba?dmode=source">The Principles of OOD</a> with follow up postings through July 1995 </p>
+<p>Robert C. Martin, The Dependency Inversion Principle, In: C++ Report, Vol. 8, May 1996. See more recent <a href="http://www.objectmentor.com/resources/articles/dip.pdf">PDF</a></p>
+<p>Michael Mattesson, 1996, <a href="http://web.archive.org/web/20000815083810/www.ipd.hk-r.se/michaelm/thesis/toc.html">Object-Oriented Frameworks : A survey of methodological issues</a> "inversion of control" used in passing. </p>
+<p>Brian Foote and Joseph Yoder, June 1998. <a href="http://www.laputan.org/mud/">Big Ball of Mud</a>. Not so much on IoC, but setting the scene. </p>
+<p>Ralph E. Johnson and Brian Foote, June 1998, <a href="http://www.laputan.org/drc/drc.html">Designing Reusable Classes</a> "inversion of control" used in passing. </p>
+<p>&nbsp;</p>
+</body></html>
\ No newline at end of file

Added: incubator/composer/trunk/composer-site/src/site/content/inversion-of-control.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/inversion-of-control.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/inversion-of-control.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/inversion-of-control.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,357 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!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" xml:lang="en">
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title>Inversion of Control</title>
+</head>
+<body>
+<h2>Overview</h2>
+
+<p>Inversion of Control (IoC) is a design pattern that addresses a
+component's <a href="injection.html" title="Dependency Injection">dependency
+resolution</a>, <a href="component-configuration.html"
+  title="Component Configuration">configuration</a> and <a
+  href="lifecycle.html" title="Lifecycle">lifecycle</a>. It suggests that the control of those three should not be the concern of the component itself. Thus it is inverted back. Note to confuse
+things slightly, IoC is also relevant to simple classes, not just
+components, but we will refer to components throughout this text. The
+most significant aspect to IoC is dependency resolution and most of the
+discussion surrounding IoC dwells solely on that. Dependency mis-management is acknowledged to be the biggest problem that IoC is trying to solve.<img src="images/ioc-venn.png" width="538" height="336" alt="IoC venn diagram" /></p>
+
+<h3>Types of IoC</h3>
+
+<p>There are many types of IoC, but we'll concentrate on the type of IoC that Apache Composer introduced to the community
+   - <a href="constructor-injection.html" title="Constructor Injection">Constructor Injection</a>. </p>
+
+<h3>IoC History</h3>
+
+<p>Some detail about the history of Inversion of Control - <a href="inversion-of-control-history.html"
+                                                              title="IoC History">IoC History</a></p>
+
+<h2>Component Dependencies</h2>
+
+<p>It generally favors loose coupling between components. Loose coupling in turn favours:</p>
+<ul>
+    <li>More reusable classes</li>
+    <li>Classes that are easier to test</li>
+    <li>Systems that are easier to assemble and configure</li>
+</ul>
+<h3>Explanation</h3>
+
+<p>Simply put, a component designed according to IoC does not go off and get other components that it needs in order to
+   do its job. It instead <em>declares</em> these dependencies, and the container supplies them. Thus the name
+   IoC/DIP/Hollywood Principle. The control of the dependencies for a given component is inverted. It is no longer the
+   component itself that establishes its own dependencies, but something on the outside. That something could be a
+   container like Apache Composer, but could easily be normal code instantiating the component in an embedded sense.</p>
+
+<h3>Examples</h3>
+
+<p>Here is the simplest possible IoC component :</p>
+
+<div class="source">
+              <pre>public interface Orange {
+  // methods
+}
+public class AppleImpl implements Apple {
+  private Orange orange;
+  public AppleImpl(Orange orange) {
+    this.orange = orange;
+  }
+  // other methods
+}</pre>
+</div>
+<p>Here are some common smells that should lead you to refactor to IoC :</p>
+
+<div class="source">
+              <pre>public class AppleImpl implements Apple{
+  private Orange orange;
+  public Apple() {
+    this.orange = new OrangeImpl();
+  }  
+  // other methods
+}</pre>
+</div>
+<p>The problem is that you are tied to the OrangleImpl implementation for provision of Orange services. Simply put, the
+   above apple cannot be a (configurable) component. It's an application. All hard coded. Not reusable. It is going to
+   be very difficult to have multiple instances in the same classloader with different assembly.</p>
+
+<p>Here are some other smells along the same line :</p>
+
+<div class="source">
+              <pre>public class AppleImpl implements Apple {
+  private static Orange orange = OrangeFactory.getOrange();
+  public Apple() {
+  }  
+  // other methods
+}</pre>
+</div>
+
+<h2>Component Configuration</h2>
+
+<p>Sometimes we see configuration like so ...</p>
+
+<div class="source">
+            <pre>public class BigFatComponent {
+  String config01;
+  String config02;
+  public BigFatComponent() {
+    ResourceFactory resources = new ResourceFactory(new File(&quot;mycomp.properties&quot;));
+    config01 = resources.get(&quot;config01&quot;);
+    config02 = resources.get(&quot;config02&quot;);
+  }  
+  // other methods
+}</pre>
+</div>
+<p>In the IoC world, it might be better to see the following for simple component designs :</p>
+
+<div class="source">
+            <pre>public class BigFatComponent {
+  String config01;
+  String config02;
+  public BigFatComponent(String config01, String config02) {
+    this.config01 = config01;
+    this.config02 = config02;
+  }  
+  // other methods
+}</pre>
+</div>
+<p>Or this for more complex ones, or ones designed to be more open to reimplementation ..</p>
+
+<div class="source">
+            <pre>public interface BigFatComponentConfig {
+  String getConfig01();
+  String getConfig02();
+}
+public class BigFatComponent {
+  String config01;
+  String config02;
+  public BigFatComponent(BigFatComponentConfig config) {
+    this.config01 = config.getConfig01();
+    this.config02 = config.getConfig02();
+  }  
+  // other methods
+}</pre>
+</div>
+<p>With the latter design there could be many different implementations of BigFatComponentConfig. Implementations such
+   as:</p>
+<ol>
+    <li>Hard coded (a default impl)</li>
+    <li>Implementations that take config from an XML document (file, URL based or inlined in using class)</li>
+    <li>Properties File.</li>
+</ol>
+<p>It is the deployer's, embeddor's or container maker's choice on which to use.</p>
+
+<h2>Component Lifecycle</h2>
+
+<p>Simply put, the lifecycle of a component is what happens to it in a controlled sense after it has been instantiated.
+   Say a component has to start threads, do some timed activity or listen on a socket. The component, if not IoC, might
+   do its start in its contructor. Better would be to honor some start/stop functionality from an interface, and have
+   the container or embeddor manage the starting and stopping when they feel it is appropriate:</p>
+
+<div class="source">
+            <pre>public class SomeDaemonComponent implements Startable {
+  public void start() {
+    // listen or whatever
+  }
+  public void stop() {
+  }
+  // other methods
+}</pre>
+</div>
+<h3>Notes </h3>
+
+<p>The lifecycle interfaces for Apache Composer are the only characterising API elements for a component. If Startable was
+   in the JDK, there would be no need for this. Sadly, it also menas that every framework team has to write their own
+   Startable interface. </p>
+
+<p>The vast majority of components do not require lifecycle functionality, and thus don't have to implement
+   anything.</p>
+
+<h2>IoC Exceptions</h2>
+
+<p>Of course, in all of these discussions, it is important to point out that logging is a common exception to the IoC
+   rule. Apache has two static logging frameworks that are in common use: Commons-Logging and Log4J. Neither of these is
+   designed along IoC lines. Their typical use is static accessed whenever it is felt appropriate in an application.
+   Whilst static logging is common, the Apache Composer team do not recommend that developers of reusable components
+   mandate a logging choice. We suggest instead that a Monitor component interface is created and default adapters are
+   provided to a number of the logging frameworks are provided.</p>
+
+<h2>Overview</h2>
+
+<h2>IoC Types - Family Tree</h2>
+
+<p>In recent years different approaches have emerged to deliver an IoC vision. Latter types, as part of a 'LightWeight'
+   agenda have concentrated on simplicity and transparency.</p>
+
+<p>Devised in London at the ThoughtWorks office in December of 2003; Present at the &quot;Dependency Injection&quot;
+   meeting were Paul Hammant, Aslak Hellesoy, Jon Tirsen, Rod Johnson (Lead Developer of the Spring Framework), Mike
+   Royle, Stacy Curl, Marcos Tarruela and Martin Fowler (electronically).</p>
+
+<p><strong>Inversion of Control</strong></p>
+<ul>
+    <li>Dependency Injection
+        <ul>
+            <li>Constructor Dependency Injection (CDI) <br />
+                <br />
+                Examples: Apache Composer, Spring Framework, (not in EJB 3.x sadly), Guice with Annotations
+            </li>
+            <li>Setter Dependency Injection<br />
+                <br />
+                Examples: Spring Framework, Apache Composer, EJB 3.0 &amp; Guice with Annotations
+            </li>
+            <li>Interface Driven Setter Dependency Injection<br />
+                <br />
+                Examples: XWork, WebWork 2
+            </li>
+            <li>Field Dependency Injection<br />
+                <br />
+                Examples: Plexus, Apache Composer &amp; Guice with Annotations.
+            </li>
+        </ul>
+    </li>
+    <li>Dependency Lookup
+        <ul>
+            <li>Pull approach (registry concept)<br />
+                <br />
+                Examples: EJB 2.x that leverages JNDI, Servlets that leverage JNDI
+            </li>
+            <li>Contextualized Dependency Lookup - AKA Push approach <br />
+                <br />
+                Examples: Servlets that leverage ServletContext, Apache's Avalon, OSGi, Keel, Loom (they use Avalon)
+            </li>
+        </ul>
+    </li>
+</ul>
+<p>See also <a href="constructor-injection.html" title="Constructor Injection">Constructor Injection</a>, <a
+    href="setter-injection.html" title="Setter Injection">Setter Injection</a> for more information.</p>
+
+<p>Note Field Injection was categorised but there was was really no interest it until the EJB3.0 specification rolled out. Getter
+   Injection flourished for a while, but did not take and was never supported by the Apache Composer team.</p>
+
+<h2>Examples of Common Types</h2>
+
+<h3>Constructor Dependency Injection</h3>
+
+<p>This is where a dependency is handed into a component via its constructor :</p>
+
+<div class="source">
+              <pre>public interface Orange {
+  // methods
+}
+
+public class AppleImpl implements Apple {
+  private Orange orange;
+  public AppleImpl(Orange orange) {
+    this.orange = orange;
+  }
+  // other methods
+}</pre>
+</div>
+<h3>Setter Dependency Injection
+</h3>
+
+<p>This is where dependencies are injected into a component via setters :</p>
+
+<div class="source">
+    <div>
+              <pre>public interface Orange {
+  // methods
+}
+
+public class AppleImpl implements Apple {
+  private Orange orange;
+  public void setOrange(Orange orange) {
+    this.orange = orange;
+  }
+  // other methods
+}</pre>
+    </div>
+</div>
+
+<h3>Contextualized Dependency Lookup (Push Approach)</h3>
+
+<p>This is where dependencies are looked up from a container that is managing the component :</p>
+
+<div class="source">
+              <pre>public interface Orange {
+  // methods
+}
+
+public class AppleImpl implements Apple, DependencyProvision {
+  private Orange orange;
+  public void doDependencyLookup(DependencyProvider dp) throws DependencyLookupExcpetion{
+    this.orange = (Orange) dp.lookup(&quot;Orange&quot;);
+  }
+  // other methods
+}</pre>
+</div>
+
+<h2>Terms: Service, Component &amp; Class</h2>
+
+<p>Component is the correct name for things managed in an IoC sense. However very small ordinary classes are manageable
+   using IoC tricks, though this is for the very brave or extremists <img class="emoticon"
+                                                                          src="http://docs.codehaus.org/images/icons/emoticons/smile.gif"
+                                                                          height="20" width="20" align="absmiddle"
+                                                                          alt="" border="0" /></p>
+
+<p>A component many have dependencies on others. Thus dependency is the term we prefer to describe the needs of a
+   component.</p>
+
+<p>Service as a term is very popular presently. We think 'Service' dictates marshaling and remoteness. Think of Web
+   Service, Database service, Mail service. All of these have a concept of adaptation and transport. Typically a
+   language neutral form for a request is passed over the wire. In the case of the Web Service method requests are
+   marshaled to SOAP XML and forward to a suitable HTTP server for processing. Most of the time an application coder is
+   hidden from the client/server and marshaling ugliness by a toolkit or API.</p>
+
+<h2>Dependency Injection versus Contextualized Lookup</h2>
+
+<p>Dependency Injection is non-invasive. Typically this means that components can be used without a container or a
+   framework. If you ignore life cycle, there is no import requirements from an applicable framework.</p>
+
+<p>Contextualized Dependency Lookup is invasive. Typically this means components must be used inside a container or with
+   a framework, and requires the component coder to import classes from the applicable framework jar.</p>
+
+<p>Note that Apache's Avalon OSGi are not Dependency Injection types of IoC, they are Contextualized Dependency
+   Lookup.</p>
+
+<p>Ultimately, the contextualized lookup designs are not recommended at all. </p>
+
+<h2>What's wrong with JNDI ?</h2>
+
+<p>With plain JNDI, lookup can be done in a classes' static initialiser, in the constuctor or any method including the
+   finaliser. Thus there is no control (refer C of IoC). With JNDI used under EJB control, and concerning only
+   components looked up from that bean's sisters (implicitly under the same container's control), the specification
+   indicates that the JNDI lookup should only happen at a certain moment in the startup of an EJB application, and only
+   from a set of beans declared in ejb-jar.xml. Hence, for EJB containers, the control element should be back. Should,
+   of course, means that many bean containers have no clue as to when lookups are actually being done, and apps work by
+   accident of deployment. Allowing it for static is truly evil. It means that a container could merely be looking at
+   classes with reflection in some early setup state, and the bean could be going off and availing of remote and local
+   services and components. Thus depending whether JNDI is being used in an Enterprise Java Bean or in a POJO, it is
+   either an example of IoC or not.</p>
+
+<h2>Related Pages </h2>
+<ul>
+    <li>Contextualized Lookup
+        <ul>
+            <li><a href="comparisons.html#comparison-ApacheAvalonanditscontainers" title="Avalon Framework">Avalon
+                                                                                                            Framework</a>
+            </li>
+        </ul>
+    </li>
+    <li><a href="inversion-of-control-history.html" title="IoC History">IoC History</a></li>
+    <li>
+        <ul>
+            <li><a href="injection.html" title="Dependency Injection">Dependency Injection</a>
+                <ul>
+                    <li><a href="constructor-injection.html" title="Constructor Injection">Constructor Injection</a>
+                    </li>
+                    <li><a href="setter-injection.html" title="Setter Injection">Setter Injection</a></li>
+                </ul>
+            </li>
+        </ul>
+    </li>
+</ul>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/javadoc.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/javadoc.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/javadoc.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/javadoc.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,16 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Javadoc</title>
+</head>
+<body>
+
+<p><a href="javadoc/core/index.html">Core</a></p>
+<p><a href="javadoc/gems/index.html">Gems</a></p>
+<p><a href="javadoc/tck/index.html">TCK</a></p>
+
+</body>
+
+
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/lifecycle.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/lifecycle.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/lifecycle.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/lifecycle.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,94 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Lifecycle</title>
+</head>
+<body>
+<p>Lifecycle with configuration and depenedency injection makes
+Inversion of Control (IoC).</p>
+<p>After instantiation, if the component warrants it, a 'start'
+stage may be required. More specifically, if a container has injected
+and instantiated all components in a set, one or more of them may
+require starting in the same order they were instantiated. Later, in
+reverse order, the same component(s) may require stoping. In fact start
+and stop may happen more than one for the life of an application.
+Disposal may happen once only, before the component is eligible for
+garbage collection.</p>
+<p><strong>Lifecycle is really only going to work for Apache Composers that are also caching component instances. Caching was a default in Apache Composer 1.x, but is not for 2.x - be warned!</strong></p>
+<p>Thus lifecycle implies three methods:</p>
+<ul>
+  <li>start</li>
+  <li>stop</li>
+  <li>dispose</li>
+</ul>
+<p>In Apache Composer we think allow a pluggable LifecycleStrategy.</p>
+<h3>Startable</h3>
+<p>Our own interface for startable. We wish it were in the JDK,
+because we're big into making components unecumbered by the trappings of
+containment. In English: we'd rather not make components
+implement/extend/throw anything from our framework. Its a 'transparency'
+thing.</p>
+<p>Here's an example of components fitting that ideal</p>
+<div class="source"><pre>
+public class Apple implements Startable{
+  public void start() {
+    // listen on socket, start thread etc.
+  }
+  public void stop() {
+    // stop listening on socket, kill thread etc.
+  }
+}
+
+
+...
+
+
+pico = new DefaultApache Composer(new StartableLifecycleStrategy());
+pico.addComponent(Apple.class);
+pico.start();
+// start gets called
+
+Apple a = pico.getComponent(Apple.class);
+</pre></div>
+<p>The StartableLifecycleStrategy can be extended if you prefer your
+own interface for Startable. Just override</p>
+<h3>Reflection based start/stop/dispose</h3>
+<p>This works without an interface. Instead it works via reflection,
+and appropriate method names.</p>
+
+<div class="source"><pre>
+public class Apple {
+  public void start() {
+    // listen on socket, start thread etc.
+  }
+  public void stop() {
+    // stop listening on socket, kill thread etc.
+  }
+}
+
+
+...
+
+
+pico = new DefaultApache Composer(new ReflectionLifecycleStrategy());
+pico.addComponent(Apple.class);
+pico.start();
+// start gets called
+
+Apple a = pico.getComponent(Apple.class);
+</pre></div>
+
+<p>If you have other synonyms for start/stop/dispose, just extend
+the ReflectionLifecycleStrategy class and provide them.</p>
+<h3>No Lifecycle</h3>
+<p>DefaultApache Composer does sets StartableLifecycleStrategy by
+default. You can specify NullLifecycleStrategy instead if you are sure
+that no components honor any lifecycle concept..</p>
+<h3>Custom Lifecycles</h3>
+<p>Write a class that implements LifecycleStragegy, there are just
+four methods to implement. See LifecycleStrategy.</p>
+</body>
+
+
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/mock-objects.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/mock-objects.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/mock-objects.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/mock-objects.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,73 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Mock Objects</title>
+</head>
+<body>
+<p>If you have had it with codebases that drag along everything and the kitchen sink, (possibly using the <a href="singleton-antipattern.html">Singleton</a>) you must read this page. Classes that look up or instantiate heavyweight classes themselves are such beasts. As you might have experienced, they are a pain to test. (And ample proof that the authors didn't follow TDD <img src="/images/thumbs_down.gif" width="19" height="19" alt="thumbs down" />). Dependency Injection with Apache Composer and Mock Objects to the rescue!</p>
+<p>Mock Objects are special objects used during testing. Mock Objects and classes that honour <a href="injection.html">Constructor Injection</a> are a <strong>perfect match</strong>, since such classes can be handed mocks during testing and &quot;the real thing&quot; when the application is run.</p>
+<p>This illustration shows how:</p>
+<table border="0">
+  <tr>
+    <td>Unit-Test Time </td>
+    <td>Deployment Time </td>
+  </tr>
+  <tr>
+    <td><img src="/images/mock-needs-stuff.png" width="214" height="306" alt="mock needs stuff" /></td>
+    <td><img src="/images/pico-needs-stuff.png" width="214" height="306" alt="pico needs stuff" /></td>
+  </tr>
+</table>
+<h3>The class
+  </h3>
+  <p>Here is what NeedsStuff might look like:</p>
+<div class="source"><pre>
+public class NeedsStuff {
+  // These are both interfaces.
+  private final BlueStuff bs;
+  private final GreenStuff gs;
+  public NeedsStuff(BlueStuff bs, GreenStuff gs) {
+    this.bs = bs;
+    this.gs = gs;
+  }
+ public String doIt() {
+  return bs.jump() + gs.beatIt();
+  }
+}</pre></div>
+  <p>During test time we'll give NeedsStuff some mocks.</p>
+<p>During prime time (when the final application is running), the NeedsStuff class will be instantiated with a SuperHeavyBlueStuff and a NuclearGreenStuff instance. These require some really heavy infrastructure such as database connections and network access. We don't want to drag along that when we test NeedsStuff! (It can wait till the integration test).</p>
+<h3>Test Time
+</h3>
+<p>Our test becomes like this:</p>
+<div class="source"><pre>
+public class NeedsStuffTestCase extends junit.framework.TestCase {
+  public void testNeedsStuffDoesStuff() {
+    BlueStuff bs = createBlueStuffMockThatReturnsBlahOnJump();
+    GreenStuff gs = createGreanStuffMockThatReturnsHuhOnBeatIt();
+
+    NeedsStuff ns = new NeedsStuff(bs, gs);
+    assertEquals("BlahHuh", ns.doIt());
+
+    // verify mocks.
+  }
+}</pre></div>
+<p>We are testing the doIt() method without having to drag along any heavy dependencies <img src="/images/smile.gif" width="20" height="20" alt="smiley" /></p>
+<p> <img src="/images/information.gif" width="16" height="16" alt="info" /> We won't go into further technical details about mocks, as there are many libraries to choose from. Check out <a href="http://www.jmock.org/">JMock</a> and <a href="http://www.easymock.org/">EasyMock</a>, or read about the ideas at <a href="http://www.mockobjects.com/">MockObjects</a> </p>
+<h3>Prime Time
+</h3>
+<p>It is left to Apache Composer to instantiate NeedsStuff. In order for it to succeed, we must also configure the container with some real BlueStuff and GreanStuff:</p>
+<div class="source"><pre>
+public class AppBootstrapper {
+  public void runapp() {
+    pico = new DefaultApache Composer();
+    pico.addComponent(NeedsStuff.class);
+    pico.addComponent(SuperHeavyBlueStuff.class);
+    pico.addComponent(NuclearGreenStuff.class);
+  }
+}
+</pre></div>
+<p><img src="images/information.gif" width="16" height="16" alt="info" /> It is even possible to do this component wiring using a soft scripting language. See <a href="http://www.nanocontainer.org">NanoContainer</a></p>
+</body>
+
+
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/monitors.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/monitors.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/monitors.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/monitors.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,45 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Component Monitors</title></head>
+<body>
+<p>A ComponentMonitor if injected into DefultApache Composer allows for certain events to me monitored at a container level. We are idealogically opposed to a forced choice of loging framework. If you're hell bent on logging, chose from a  ComponentMonitor imlementation below. For now though consider what events are monitored:</p>
+<ul>
+  <li>instantiating - refering to a component </li>
+  <li>instantiated - refering to a component</li>
+  <li>instantiationFailed - refering to a component</li>
+  <li>invoking - refering to a method on a component </li>
+  <li>invoked - refering to a method on a component </li>
+  <li>invocationFailed - refering to a method on a component </li>
+  <li>lifecycleInvocationFailed - referring to start/stop/dispose methods on a component </li>
+  <li>noComponentFound - referring to getComponent(..) on a Apache Composer instance. </li>
+</ul>
+<p><strong>Return Values </strong></p>
+<p><em>Instantiating</em> returns a Constructor. An implementor of ComponentMonitor can choose to return a different Constructor reference. This is one way that implementations can be replaced or decorated (AOP style) with additional/changed functionality. </p>
+<p><em>noComponentFound</em> returns an Object (default of null in most cases). An implementor can choose to return an instance instead. That instance should be of a type that makes sense to the component that was being sought. The getComponent(..) would have otherwise failed, but this hypothetical ComponentMonitor intercepted that failure and provided something that makes sense. </p>
+<p><strong>General rules</strong></p>
+<ol>
+  <li>ComponentMonitor can generally be chained together. Meaning you can use them in combination. </li>
+  <li>Most have NullComponentMonitor (see below) as their end stop. </li>
+  <li>Any method on ComponentMonitor is open for interpretation. That means they can throw exceptions as well as return different values, making them modify Apache Composer's behavior. </li>
+</ol>
+<h3>Logging or text-centric varieties of ComponentMonitor </h3>
+<p>Hopefully self explanatory:</p>
+<ul>
+  <li>CommonsLoggingComponentMonitor (Gems) </li>
+  <li>Log4JComponentMonitor (Gems) </li>
+  <li>ConsoleComponentMonitor  </li>
+  <li>WriterComponentMonitor</li>
+</ul>
+<h3>NullComponentMonitor</h3>
+<p>This is Apache Composer's default ComponentMonitor. It generally fits the NullObject pattern, but it does add behavior. Specifically if it encounters a lifecycleInvocationFailed(..) method invocation, it throws a LifecycleException in response. If you use something other than NullComponentMonitor (bear in mind the default 'end stop' for most others is also NullComponentMonitor) then you could change the way Apache Composer responds to components it cannot start, stop of dispose of. </p>
+<h3>LifecycleComponentMonitor</h3>
+<p>This  ComponentMonitor stores lifecycle failures and rethrows them later if rethrowLifecycleFailuresException() is called. </p>
+<h3>Future work</h3>
+<p>Implementations that:</p>
+<ul>
+  <li>Record component injections and play them back later (optimised web frameworks) </li>
+</ul>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/news.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/news.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/news.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/news.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,70 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+    <title>News</title>
+</head>
+<body>
+<p><strong>Jan 19, 2008</strong></p>
+<p>Apache Composer 2.0 released (190K jar) </p>
+<p>New (versus beta 2):</p>
+<ul>
+  <li>Binding Annotations support (disambiguation)</li>
+  <li>Newer and rewritten properties backed containers</li>
+  <li>Parameter names can be leveraged for all relevant types of injection</li>
+</ul>
+<p>Changed (versus beta 2):</p>
+<ul>
+  <li>Yet More Java5 generics</li>
+  <li>Build moved to JUnit 4.x and JMock 2.x (does not affect users of Apache Composer)</li>
+  <li>Built-in parameter name access, as opposed jar dependency</li>
+</ul>
+<p><strong>August 26, 2007</strong></p>
+<p>Apache Composer 2.0 beta 2 released (152K jar) </p>
+<p>New (versus beta 1):</p>
+<ul>
+  <li>Rudimentary AOP capability for components built in</li>
+  <li>Method Injection (one method post-construction with multiple arguments)</li>
+  <li>Automatic JNDI exposure</li>
+  <li>Multi Injection (Setter and after Constructor injection)</li>
+  <li>Store behavior (can extract/replace component store per thread)</li>
+  <li>Automatic components (instantiate irrespective of need)</li>
+  <li>Reentrant-Lock version of Synchronizing behavior</li>
+</ul>
+<p>Changed (versus beta 1):</p>
+<ul>
+  <li>Better Java5 generics</li>
+  <li>Renames of behaviors and injectors to more verb-like style</li>
+  <li>Startable interface more easily overridden to own choice</li>
+</ul>
+<p><strong>July 15, 2007</strong></p>
+<p>Apache Composer 2.0 BETA-1 released (128K jar) </p>
+<p>New:</p>
+<ul>
+  <li>Properties for components as they are added to containers makes for increased flexibility</li>
+  <li>Field and Method annotation types of injection in addition to traditional Constructor (recommended) and Setter types </li>
+  <li>Parameters names for constructors can now drive otherwise ambiguous injections, as well as configuration</li>
+  <li>Large sets of configuration can be taken from properties files and command line arguments</li>
+  <li>ContainerBuilder to make a container with desired behavior. </li>
+</ul>
+<p>Changed:</p>
+<ul>
+  <li>Java 5 style (use of generics, varargs, among others)</li>
+  <li>Large scale Refactoring of packages and class names</li>
+  <li>Fluent interface for adding of components to a container</li>
+</ul>
+<p><strong>Mar 18, 2007</strong></p>
+<p>Apache Composer 1.3 released (113K jar) </p>
+<p><strong>January 19, 2006</strong></p>
+<p>Apache Composer 1.2 released (112K jar) </p>
+<p><strong>November 4, 2004</strong></p>
+<p>Apache Composer 1.1 released (75K jar) </p>
+<p><strong>June 5,  2004</strong></p>
+<p>Apache Composer 1.0 released (49K jar) </p>
+<p><strong>June 29,  2003</strong></p>
+<p>Apache Composer 1.0 alpha (25K jar) </p>
+<p></p>
+<p>&nbsp; </p>
+<p>&nbsp;</p>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/patterns.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/patterns.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/patterns.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/patterns.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,50 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Design Patterns</title>
+</head>
+<body>
+<h3>Key Patterns </h3>
+<p><strong>Inversion of Control (IoC). </strong></p>
+<p>The idea that an application is controlled from the top down</p>
+<p><strong>Separation of Concerns (SoC) </strong></p>
+<p>The idea that a class (aspect) should do one job and do it well</p>
+<p><strong>Separation of API (or Interface) from Implementation</strong></p>
+<p>The idea that you define and code to work interfaces</p>
+<p><strong>Aspect Oriented Programming (AOP) </strong></p>
+<p>Mostly lightweight nowadays where you add a chain of interceptors around a method call that can handle orthogonal concerns</p>
+<p><strong>Component Oriented Programming (COP) </strong></p>
+<p>The idea that you decompose your software into components</p>
+<p><strong>Declarative Programming</strong></p>
+<p>Where you use a declarative-style language (usually xml) to determine things like component wiring (i.e. your average tomcat config file, generalized)</p>
+<p><strong>Event Based Programming (EBP) </strong></p>
+<p>Basically making the inter-object method call asynchronous and encapsulating such a call into some kind of event object that can be queued, modified, etc</p>
+<h3>More Thinking </h3>
+<p><strong>Good Citizen: Least surprise, least paranoia</strong></p>
+<p>Authors: Dan North, Aslak Hellesoy</p>
+<p>Imagine a software system where there is no need for you to spend your time programming defensively; your objects will be used responsibly, and your methods will always be passed sensible arguments.</p>
+<p>This low-friction utopia can be approached by establishing some simple programming rules so that every class acts as a 'good citizen' in the society of classes collaborating at runtime.</p>
+<p>This page outlines some rules that we, and others, believe lead to good citizenship. All are aimed at improving clarity, reducing surprise, and promoting basic consistency.</p>
+<p>As a good citizen, I...</p>
+<ul>
+  <li>  Keep a consistent state at all times - init() or populate() is a code smell.</li>
+  <li>Have no static fields or methods</li>
+  <li>Never expect or return null.</li>
+  <li>FailFast - even when constructing.</li>
+  <li>Am Easy to test- all dependent object I use can be passed to me, often in my constructor (typically as Mock Objects).</li>
+  <li>Accept dependent object that can easily be substituted with Mock Objects (I don't use Concrete Class Dependency).</li>
+  <li>Chain multiple constructors to a common place (using this(...)).</li>
+  <li>Always define hashCode() alongside equals()</li>
+  <li>Prefer immutable value objects that I can easily throw away.</li>
+  <li>Have a special value for 'nothing' - e.g. Collections.EMPTY_SET.</li>
+  <li>Raise checked exceptions when the caller asked for something unreasonable - e.g. open a non-existant file.</li>
+  <li>Raise unchecked exceptions when I can't do something reasonable that the caller asked of me - e.g. disk error when reading from an opened file.</li>
+  <li>Only catch exceptions that can be handled fully.</li>
+  <li>Only log information that someone needs to see.</li>
+</ul>
+<p>Classes that are designed for <a href="injection.html">Constructor Injection</a> are better citizens than those that are not.</p>
+</body>
+
+
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/project.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/project.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/project.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/project.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,27 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+    <title>Project</title>
+</head>
+<body>
+<p>Apache Composer is hosted at <a href="http://apache.org">The Apache Software Foundation</a>, presently in its incubator. </p>
+
+<h2>Project links</h2>
+
+<p>Source control root for Apache Composer (you will need Maven2 installed to build):</p>
+
+<p><a
+    href="https://svn.apache.org/repos/asf/incubator/composer/trunk">https://svn.apache.org/repos/asf/incubator/composer/trunk</a>
+</p>
+
+<p>Maven repositories for artifact download : </p>
+
+TBA
+
+<h2>License</h2>
+
+<p>Apache Composer is <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache licensed</a>.
+
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/properties.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/properties.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/properties.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/properties.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,86 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+    <title>Component Properties</title>
+</head>
+<body>
+<p>DefaultApache Composer allows for some properties to be set
+   per component at the time each is added. A convenience class called Characteristics lists the supplied properties. </p>
+
+<p>Properties can be set for a component in a method 'as' on
+   MutableApache Composer. If that is the case then the properties will
+   affect the <strong>next</strong> component added only.</p>
+
+<p>They can also be set in a more persistent manner for the
+   MutableApache Composer in question, using the 'change' method. If so, they will affect all subsequent
+   additions of component.</p>
+
+<p>Some examples :</p>
+
+<div class="source"><pre>
+import static org.picocontainer.Characteristics.SDI;
+import static org.picocontainer.Characteristics.CACHE;
+...
+pico = new DefaultApache Composer();
+pico.as(CACHE).addComponent(Apple.class);
+pico.as(CACHE, SDI).addComponent(Pear.class);
+</pre>
+</div>
+<div class="source"><pre>import static org.picocontainer.Characteristics.SDI;
+import static org.picocontainer.Characteristics.CACHE;
+...
+pico = new DefaultApache Composer();
+pico.change(CACHE).addComponent(Apple.class);
+pico.change(SDI).addComponent(Pear.class);</pre>
+</div>
+<div class="source"><pre>
+pico = new DefaultApache Composer();
+pico.as(Characteristics.CACHE).addComponent(Apple.class);
+pico.as(Characteristics.CACHE,
+    Characteristics.SDI).addComponent(Pear.class);
+</pre>
+</div>
+<div class="source"><pre>pico = new DefaultApache Composer();
+pico.change(Characteristics.CACHE).addComponent(Apple.class);
+pico.change(Characteristics.SDI).addComponent(Pear.class);</pre>
+</div>
+
+<p>Some characteristics are mutually exclusive. For example CDI,
+   SDI. Meaning the last one set via 'as' or 'change' rules. Others are
+   additive like CACHE and HIDE_IMPL. The order of these is not important. </p>
+
+<h3>Appropriate Behavior and Injection Factories.</h3>
+
+<p>Every characteristics set for a component must be handled by a
+   BehaviorFactory or InjectionFactory that recognises it. They are
+   typically chained together. DefaultApache Composer's default
+   BehaviorFactory and InjectionFactory are AdaptiveBehaviorFactory and
+   AdaptiveInjectionFactory. These can handle CDI and SDI as well as CACHE
+   and HIDE_IMPL.</p>
+
+<p>If you setup DefaultApache Composer with a
+   BehaviorFactory/InjectionFactory combination that is unaware of the
+   characteristics you subsequently use, Apache Composer will object by way of an
+   exception as you add the component to the container. See <a href="unprocessed-properties-help.html">Unprocessed Properties</a>. </p>
+<p>Supplied properties (from org.picocontainer.Characteristics) -</p>
+<ul>
+  <li>CDI - added components will be Constructor Dependency Injection.</li>
+  <li>SDI  - added components will be Setter Dependency Injection.</li>
+  <li>METHOD_INJECTION - added components will be Method Injection (a method called inject will list the dependencies).</li>
+  <li>NO_CACHE - no caching for the component to be added (in the case of Caching being the container's default).</li>
+  <li>CACHE - cache the component to be added.</li>
+  <li>NO_JMX - JMX is not to be published for the component.</li>
+  <li>SYNCHRONIZE - ensure that the component to be added will be created only once, even if multiple threads are seeking the component simultaneously.</li>
+  <li>LOCK - an alternate to SYNCHRONIZE that leverages java.lang.concurrent.Lock for the same purpose.</li>
+  <li>SINGLE - synonym for CACHE.</li>
+  <li>HIDE_IMPL - hide the implementation of the component to be added.</li>
+  <li>NO_HIDE_IMPL - don't hide the implementation of the component to be added (in the case of ImplementationHiding being the container's default).</li>
+  <li>PROPERTY_APPLYING - allow for the application of properties for the component in question.</li>
+  <li>AUTOMATIC - instantiate the component when start() is called on the container even if component is not Startable nor depended on.</li>
+  <li>USE_NAMES - use the parameter names of the component's constructor (or injection method) for the binding of configuration or components.</li>
+</ul>
+<h3>Custom Properties</h3>
+<p>You can make your own properties quite easily - check out the source to <a href="http://svn.codehaus.org/picocontainer/java/2.x/trunk/pico/container/src/java/org/picocontainer/Characteristics.java">Characteristics.java</a> and the classes that refer to it in Apache Composer (various implementations of ComponentFactory and ComponentAdapter). </p>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/scopes.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/scopes.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/scopes.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/scopes.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,73 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Scoped Containers</title>
+</head>
+<body>
+<p>Apache Composer's scope hinges on parent/child container
+relationships. From a Apache Composer instance you can make a child
+container via makeChildContainer() or addChildContainer(..).</p>
+<p>These hierarchies of container can be set up with parents and
+children refering to each other, or children referring to parents only,
+or parents referring to children only. This changes the way that things
+work considerably. If a child has its parent registered, then it can
+lean on it for component resolution (but not without). If a parent has
+its child registered asa child, then it can manage it (start, stop,
+dispose cascade into children).</p>
+<p>Web frameworks that leverage Apache Composer typically construct a tree of containers.  For example an application level container maintains components that can be shared across the application. The application container will have child containers to maintain session level components.  These session level containers can resolve dependencies through their parent containers, but the application container will have no visibility into its children.  Additionally these child container do not have visibility into their sibling containers.  With this design, containers can easily be garbage collected at the end of their scope. </p>
+<h2>Simple Examples</h2>
+<p>Here are examples of parent/child setup:</p>
+    <div class="source">
+      <pre>
+parent = new DefaultApache Composer();
+parent.addComponent(Apple.class);
+parent.addComponent(Orange.class);
+parent.addComponent(Pear.class);
+child = parent.makeChildContainer();
+child.addComponent(DependsOnApple.class);
+// this is OK
+parent.start();
+// cascades to child just fine
+</pre>
+</div>
+<div class="source">
+  <pre>
+parent = new DefaultApache Composer();
+parent.addComponent(Apple.class);
+parent.addComponent(Orange.class);
+parent.addComponent(Pear.class);
+child = parent.addChildContainer(new DefaultApache Composer());
+child.addComponent(DependsOnApple.class);
+// this is NOT OK. child can't see parent
+parent.start();
+// cascades to child just fine
+</pre>
+</div>
+<div class="source">
+  <pre>
+parent = new DefaultApache Composer();
+parent.addComponent(Apple.class).addComponent(Orange.class).addComponent(Pear.class);
+child = parent.addChildContainer(new DefaultApache Composer(parent));
+child.addComponent(DependsOnApple.class);
+// this is OK
+parent.start();
+// cascades to child just fine
+</pre>
+</div>
+<div class="source"><pre>parent = new DefaultApache Composer();
+parent.addComponent(Apple.class).addComponent(Orange.class).addComponent(Pear.class);
+child = new DefaultApache Composer(parent);
+child.addComponent(DependsOnApple.class);
+// this is  OK
+parent.start();
+// does NOT cascades to child 
+</pre>
+</div>
+<p>There is no limit to the extent of the chained containers, for example -
+great grandparent, grandparent, parent, child, is OK.</p>
+<p>Garbage collection is the standard way of disposing of scoped containers. If the children refer to the parents, then assign child to null just works. If the parents refer to the children too, then you'll have to do a removeChildContainer(..) first before it will be eligible for garbage collection.</p>
+<b>See  <a href="web-frameworks.html">web frameworks</a></b>
+<b>also.</b>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/setter-injection.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/setter-injection.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/setter-injection.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/setter-injection.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,83 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!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" xml:lang="en">
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title>Setter Injection</title>
+</head>
+<body>
+<h2>Overview</h2>
+
+<p>Setter Dependency Injection (SDI) is where the container or embedder hands dependencies to a component via setter
+   methods after instantiation.</p>
+
+<h2>Example</h2>
+
+<p>Joe Walnes whist working on Java Open Source Programming with other luminaries, started with a Setter Injection
+   IoC design for WebWork2. This is marked up with doclet tags (though that was not hard and fast) :</p>
+
+<div class="source">
+            <pre>public class Shop {
+   StockManager stockManager;
+   String shopZipCode;
+   /**
+    * @service name=&quot;StockManager&quot;
+    */
+   public void setStockManager(StockManager stockManager) {
+       this.stockManager = stockManager;
+   }
+   /**
+    * @config name=&quot;shopZipCode&quot;
+    */
+   public void setStockManager(String shopZipCode) {
+       this.shopZipCode= shopZipCode;
+   }
+   // TODO - Joe - how does setter injector do config ? Same way?
+   public void initialize() {
+       // all setXXXs are now done :-)
+   }
+}</pre>
+</div>
+<p>The container use the meta-information to resolve all the dependencies. Components need not be interface/impl
+   separated. Developer's choice.</p>
+
+<h3><a name="SetterInjection-UsingSetterInjectorComponentsWithoutaContainer."
+       id="SetterInjection-UsingSetterInjectorComponentsWithoutaContainer."></a>Using Setter Injector Components
+                                                                                Without a Container.</h3>
+
+<p>Setter Injection components can be used directly, without any container. The component-using class will
+   continue to compile, but at run time it will be apparent that there are missing dependencies. The downside of
+   this is that a developer may miss a setXXX(..) method invocation if they are using the component directly.
+   That is fairly small as a risk as it would clearly be caught in the development cycle. Caught in the
+   development cycle, but maybe obscurely so with a NullPointerException.</p>
+
+<div class="source">
+              <pre>Shop shop = new Shop();
+shop.setStockManager(myStockManager);</pre>
+</div>
+<h2>Container support</h2>
+
+<p>The Spring Framework project is the best example of a container that favors setter injection. Apache Composer does
+   too, but we really believe that constructor injector is superior.</p>
+
+<h2>Refs + Comparison</h2>
+
+<p><a href="http://www.martinfowler.com/articles/injection.html#SetterInjectionWithSpring">Setter Injection</a> is a
+    <a href="injection.html" title="Dependency Injection">Dependency Injection</a> variant where an object gets all
+                                                                                   dependencies via setter methods.
+                                                                                   Apache Composer support this with
+    <a href="http://www.picocontainer.org/picocontainer/latest/picocontainer/apidocs/org/picocontainer/defaults/SetterInjectionComponentAdapter.html">SetterInjectionComponentAdapter</a>,
+                                                                                                                                                                                         but
+                                                                                                                                                                                         the
+                                                                                                                                                                                         Apache Composer
+                                                                                                                                                                                         team
+                                                                                                                                                                                         recommends
+    <a href="constructor-injection.html" title="Constructor Injection">Constructor Injection</a>.</p>
+
+<p>The advantage of <a href="constructor-injection.html" title="Constructor Injection">Constructor Injection</a> is
+   that the setting is atomic in a sense that either all or none of the dependencies are set and that it can occur
+   once and only once. With Setter Injection there is the possibility to forget to set some of the dependencies</p>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/sitemap.xml
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/sitemap.xml?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/sitemap.xml (added)
+++ incubator/composer/trunk/composer-site/src/site/content/sitemap.xml Sun Feb  3 22:33:20 2008
@@ -0,0 +1,72 @@
+<sitemap>
+    <section>
+        <name>About</name>
+        <page>index.html</page>
+        <page>introduction.html</page>
+        <page>javadoc.html</page>
+        <page>downloads.html</page>
+        <page>news.html</page>
+        <page>faq.html</page>
+        <page>goals.html</page>
+    </section>
+    <section>
+        <name>Core Concepts</name>
+        <page>injection.html</page>
+        <page>behaviors.html</page>
+        <page>fluent-style.html</page>
+        <page>lifecycle.html</page>
+        <page>monitors.html</page>
+        <page>scopes.html</page>
+        <page>builder.html</page>
+        <page>interception.html</page>
+        <page>properties.html</page>
+        <page>disambiguation.html</page>
+       <page>component-configuration.html</page>
+    </section>
+    <section>
+        <name>Architecture</name>
+        <page>patterns.html</page>
+        <page>inversion-of-control.html</page>
+        <page>adapters.html</page>
+        <page>mock-objects.html</page>
+        <page>terminology.html</page>
+        <page>constructor-injection.html</page>
+        <page>setter-injection.html</page>
+        <page>comparisons.html</page>
+        <page>transparency.html</page>
+    </section>
+    <section>
+        <name>Containers</name>
+        <page>DefaultApache Composer.html</page>
+	    <page>CommandLineArgumentsApache Composer.html</page>
+		<page>PropertiesApache Composer.html</page>
+		<page>SystemPropertiesApache Composer.html</page>
+		<page>TransientApache Composer.html</page>
+    </section>
+    <section>
+         <name>Applications</name>
+         <page>web-frameworks.html</page>
+    </section>
+    <section>
+         <name>Anti-patterns</name>
+         <page>antipatterns/propagating-dependency-antipattern.html</page>
+         <page>antipatterns/long-constructor-argument-list-antipattern.html</page>
+         <page>antipatterns/container-dependency-antipattern.html</page>
+         <page>antipatterns/tests-use-container-antipattern.html</page>
+         <page>antipatterns/singleton-antipattern.html</page>
+    </section>
+    <section>
+         <name>Help Pages</name>
+         <page>help/ambiguous-injectable-help.html</page>
+         <page>help/unprocessed-properties-help.html</page>
+     </section>    
+    <section>
+         <name>History</name>
+         <page>inversion-of-control-history.html</page>
+    </section>
+    <section>
+         <name>Project Info</name>
+         <page>project.html</page>
+         <page>team.html</page>
+     </section>
+</sitemap>
\ No newline at end of file

Added: incubator/composer/trunk/composer-site/src/site/content/team.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/team.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/team.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/team.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,92 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Team</title>
+</head>
+<body>
+<p>A project like Apache Composer is always made possible by the effort of a lot of people. Read about the developers and the contributers' names below. All of them have worked together to make Apache Composer the most respected IoC framework.</p>
+<h2>Committers</h2>
+Apache Composer committers introduce themselves in their own words and are listed in alphabetical order.<br />
+<h3>Paul Hammant</h3>
+<p>Paul is 39, has worked for ThoughtWorks  since 2002 and is co-founder of the PicoContainer project (precursor to Apache Composer). He used to freelance but is now very happy at TW. Paul practices XP on client sites and loves open source on which he is chief zealot for TW. He formerly worked at Apache on the Avalon project and remains there working on AltRMI. He loves the simplest thing as a design metaphor, hates too much XML. He loves the lowest common denominator (LCD) as a mechanism for facilitating divergent designs. To that end, he encourages multiple implementations of LCD ideas and APIs. Paul hopes to see Milli, Kilo and Mega implementations of the Pico idea. He hopes to see a myriad of interchangeable Apache Composer Components. He hopes to see standard APIs for components emerge from those implementations, but never be forced when teams cannot agree. It would be fairly easy to guess that Paul does not like big up-front design. That not withstanding the fact that 
 he used to do bucket-loads of it Paul with Aslak, wrote the first lines. Paired, under the influence of a couple of beers, and based on Joe's story of Rachel Davies' comments to his setter injector IoC work at the start of June 2003.</p>
+<p>Paul is also well known for <a href="http://sourceforge.net/projects/eob">Enterprise Object Broker</a> and <a href="http://jesktopapps.sf.net/">Jesktop</a>, the <a href="http://openqa.org/selenium-rc/">original driven side of Selenium</a> and other stupid ideas like <a href="http://sourceforge.net/projects/thicky">Thicky</a> and related <a href="http://paulhammant.com/blog/ruby-versus-javascript-for-web3.0.html">early Web 3.0 references</a></p>
+<h3><p>Konstantin Pribluda</p></h3>
+<p>I'm 32 and live in Wiesbaden. I started programming at the age of 12 and had access to really cool systems ranging from WANG 3200 through PDP 8/11 to System-360 ( actually sovjet clones of them, but who cares? ). My first &quot;paid for&quot; work was in 1988, and from that point I financed my study freelance software development. I developed fiscal management systems, medical video archiving, internet applications for telcos and java applet games ( later was for personal fun )...</p>
+<p>After study I continued to freelance ( this time for better paying, but also fast failing ) companies and started to work on open source software ( xdoclet ). Now I'm permanently hired project leader, and I'am in position to use ( and develop ) whatever technologies I see fit - of course xdoclet, pico, nano and a lot of other stuff.</p>
+<p>My biggest private interest ( besides open source programming ) is mountainbike racing.</p>
+<h3><p>J&ouml;rg Schaible</p></h3>
+<p>I was invited by Paul and Aslak early in 2004 to participate on the development of this project. I am currently 36 and write code for nearly 20 years in several languages and lately also Java. I have experience in AI software, did system programming and developed and maintained a plattform-independent GUI and database framework, and had to deal with CMS programming in JavaScript and J2EE. I was always involved in automated builds and tests for all these projects and one artifact left is JsUnit.</p>
+<p>Pico got my interest after some first steps with IoC using the Avalon framework. I felt in love with Pico from the first moment, because of its simplicity and natural way of programming. Yet, there is a lot of space for further development on top of it and I am happy to be part of it.</p>
+<p>My interests besides programming are my wife (who always gets too less time), reading books (a lot of fantasy and SF stuff), hearing celtic-rooted music (although I like others also lot), and - when in mood - cooking</p>
+<p>Last, but not least, beeing a Christian is a part of my life, where I have my roots.</p>
+<h4>Mauro Talevi</h4>
+<p>I first came across Paul at an XTC (eXtreme Tuesdays Club) on Agile development at the Ol' Bank of England Pub in London. Back then Apache Composer had yet to be born. We were both working with Avalon IoC and in particular the Phoenix microkernel. Ever since discussing all the limitations of the Avalon framework - in particular the dependency on an API - I knew that the way forward was the Pico way.</p>
+<p>I've worked in Java and enterprise systems for several years in various business domains - ranging from space data search portal for ESA to real-time messaging at the BBC - and I've come to appreciate the beauty, elegance and power of CDI.</p>
+<h3>Michael Ward</h3>
+<p>I live in Chicago, or at least that is where all my bills are sent. As it seems to be the lingo, I was assimilated into ThoughtWorks back in 2003. I have been developing professionally since 1997 and have had the great opportunity to work and live in many great locations with some exceptionally talented individuals. I was immediately drawn to Apache Composer because of its simplicity. The API is small and does not force you to define all your configurations in XML. The projects I have worked on are easier to test, refactor, debug and extend because a natural side effect of utilizing CDI is a small and easy to comprehend code base. Mike leads the <a href="http://waffle.codehaus.org/">Waffle web framework</a> project (the easiest for Java we think). </p>
+<p>Have worked/contributed to MicroContainer, the JMX module for NanoContainer, Apache Composer.NET and NanoContainer.NET.</p>
+<h3>Michael Rimov</h3>
+<p>Michael came to the Java world after programming for about eight years in the Windows API.  He dove head first into Java J2EE frameworks by initially working with the popular heavyweight Expresso framework where he introduced unit testing to those developers. During his stint as Lead Developer, the framework's usage numbers exploded.  After about nine years working with J2EE, Michael found the joys of light weight components and Apache Composer and has been reaping the performance benefits of both ever since.  His goal is to see it NanoContainer/NanoWAR grow in the J2EE arena, while keeping Pico perfect for embedding in all applications.</p>
+<p>Michael works for Centerline Computers, Inc in Corvallis Oregon.</p>
+<h3>Jose Peleteiro</h3>
+<p>I live in Rio de Janeiro, Brazil.</p>
+<p>http://www.peleteiro.net</p>
+<p>Jose Peleteiro works for Neoris do Brasil.</p>
+<h2>Emeritus Committers</h2>
+<p>Emeritus committers are those committers who have contributed significantly to the development of the project, but have been inactive for a period amount of time.</p>
+<p> * Thomas Heller</p>
+<h4>Aslak Helles&oslash;y</h4>
+<p>Aslak is very accomplished in the Open Source space and co-founder of Apache Composer. He leads XDoclet, and has taken over QDox from Joe. He wrote most of the impressive MiddleGen, and has refactored Generama out of both. From an observers point of view Aslak is prolific. Aslak was assimilated into ThoughtWorks in 2003. [ Words by Paul ]</p>
+<p> * Mike Hogan</p>
+<p> * Stephen L. Molitor</p>
+<h4>Dan North</h4>
+<p>Dan is a passionate Agile Coach and Developer. He's adept at a huge range of languages, with Ruby being his current favorite. This is his first foray into Open Source. Dan was assimilated into ThoughtWorks in 2002. [ Words by Paul ]</p>
+<p> * Leo Simons</p>
+<p> * Chris Stevenson</p>
+<h4>James Strachan</h4>
+<p>James used to dislike IoC, when the type that forced you to implement interfaces was the only choice. He championed the whole 'beans' effort at Apache, particularly in Jakarta-Commons. Most recently he's one of the the technical figurehead of LogicBlaze and a key in the  Apache Geronimo project. Most exciting of all of James' activities has been as initial lead of the Groovy language (thank god James got off his XML horse - Ed). James refuses to join ThoughtWorks. [ Words by Paul ]</p>
+<h4>Jon Tirs&eacute;n</h4>
+<p>Jon is a passionate fellow who's invidually accomplished in the Open Source space. Nanning is one of his babies, and he's a committer to Prevayler. With Aslak, DamageControl is is latest project. Jon was assimilated into ThoughtWorks in 2003. Latterly in Australia, he leads some of the <a href="http://studios.thoughtworks.com/">ThoughtWorks Studios</a> developments. [ Words by Paul ]</p>
+<h4>Joe Walnes</h4>
+<p>Joe Walnes is one of those high accomplished people, with a trail of &quot;I must work with him&quot; fans and quality Open Source projects behind him. He wrote SiteMesh, and large chunks of OpenSymphony. He started QDox, and XStream. One of the unsung heroes of Java/.Net development. Joe was assimilated into ThoughtWorks in 2002, then Google in 2006. [ Words by Paul ]</p>
+<p>&nbsp;</p>
+<h3></h3>
+<p>&nbsp;</p>
+<p>&nbsp;</p>
+<p>Contributers</p>
+<p>A lot of people have contributed ideas and code to the Apache Composer's code base. See the names in the list below in alphabetical order.</p>
+<p> * Nicolas Averseng<br />
+  * Mathias Bogaert<br />
+  * Rao Chejarla<br />
+  * Jeppe Cramon<br />
+  * Stacy Curl<br />
+  * Laurent Etiemble<br />
+  * Scott Farquhar<br />
+  * Obie Fernandez<br />
+  * Jay Fields<br />
+  * Steve Freeman<br />
+  * Mario Gutierrez<br />
+  * Matt Ho<br />
+  * Jacob Kjome<br />
+  * Rafal Krzewski<br />
+  * Aapo Laakkonen<br />
+  * Graham Lea<br />
+  * Philipp Meier<br />
+  * Zohar Melamed<br />
+  * Kouhei Mori<br />
+  * Mirco Novakovic<br />
+  * Rickard &Ouml;berg<br />
+  * Kevin O'Neill<br />
+  * Miguel A. Paraz<br />
+  * Gilles Philippart<br />
+  * Michael Rettig<br />
+  * Adam Rosien<br />
+  * Pedro Santos<br />
+  * Jens Schumann<br />
+  * Nick Sieger<br />
+  * Paulo Silvera<br />
+  * Vincent Tence<br />
+  * Calvin Yu</p>
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/terminology.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/terminology.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/terminology.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/terminology.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!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" xml:lang="en">
+<head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title>Terminology</title>
+</head>
+<body>
+
+<h2>Overview</h2>
+
+<p>These can be arrived at from the definitions.</p>
+<ul>
+    <li>Everything is an object</li>
+    <li>Everything which is not a Contextualized Lookup component nor a domain-specific object is a POJO</li>
+    <li>A Setter Dependency Injection (SDI) component is a JavaBean, and a JavaBean is an SDI component</li>
+    <li>A Contructor Dependency Injection (CDI) Component is not a JavaBean, but is a POJO</li>
+    <li>A JavaBean can be any of the three types of IoC and domain-specific all at the same time</li>
+    <li>Spring, Apache Composer, XWork and other frameworks all support both Components and Data Objects to some
+        extend. Avalon tries real hard to not support Data Objects, but that is nearly impossible.
+    </li>
+</ul>
+<h2>Terms</h2>
+
+<h3>Object or Instance</h3>
+
+<p>An &quot;object&quot; as per the Java Language Specification.</p>
+
+<h3>Class</h3>
+
+<p>A &quot;class&quot; as per the Java Language Specification.</p>
+
+<h3>POJO
+                                                                                                               (Plain
+                                                                                                               Old
+                                                                                                               Java
+                                                                                                               Object)
+</h3>
+
+<p>An object that does not use nor support any other kind of component/bean specification. It does not implement
+   any lifecycle or marker interfaces, it does not provide any kind of metadata. Will usually follow the minimum
+   requirements for classifying it as a JavaBean though.</p>
+
+<h3>Javabean / Bean</h3>
+
+<p>An object that is a &quot;valid java bean&quot; according to the JavaBean Specification. That is, an object
+   that has a public default constructor, and that supports setting and/or retrieving all or a part of its state
+   using so-called setter and getter methods, which are named getXXX(), setXXX() or isXXX(), where XXX
+   identifies part of its state. The JavaBean specification defines a metadata framework, an event framework,
+   and some other things which are less relevant in this context. A JavaBean may represent both data and
+   functionality.</p>
+
+<h3>Data Object / Entity Bean / Data Bean / PODO</h3>
+
+<p>An object that only represents data, but contains no 'logic' or any kind of other functionality (except for
+   perhaps some utility methods that transform the data into some other form, like getXXXasString(). Will often
+   override equals() and hashCode(); will often be serializable. Does not create threads, does not keep
+   references to non-data objects.</p>
+
+<h3>Component</h3>
+
+<p>An object that only represents functionality. It is a &quot;unit of logic&quot;, that can &quot;do work&quot;.
+   In a well-designed application, the work that a component can do is specified in a work interface. Will
+   usually not override equals() or hashCode(). It typically coexists with other components of the same language in the same application or server process.</p>
+<h3>Service</h3>
+<p>One or more components that communicate with others over the wire. Services, laced together for some large stack, may be from different technologies or languages, and share only the specification of the wire protocol. Service implies remoteness and potential unavailability or outage.</p>
+<h3>Passive Component</h3>
+
+<p>A component that does not use threads (not even indirectly).</p>
+
+<h3>Active Component</h3>
+
+<p>A component that uses threads (possibly indirectly through the use of a Thread Pool or Executor
+   component).</p>
+
+<h3>Contextualized Dependancy Lookup
+                                                                       Component</h3>
+
+<p>A component that has a public default constructor and that usually has its state set up and/or modified
+   through the use of some kind of framework-specific mechanism.</p>
+
+<h3>Setter
+                                                                                                       Injection
+                                                                                                       Component
+</h3>
+
+<p>A component that has a public default constructor and that has its state set up through the use of setter
+   methods.</p>
+
+<h3>Constructor Injection Component</h3>
+
+<p>A component that has one or more public constructors and that has its state set up through the arguments
+   provided in one of these constructors.</p>
+
+<h3>Constructor/ Setter Dependency
+                                                                                Injection Component</h3>
+
+<p>A component that has a public constructor and that has its state set up through the arguments provided in
+   that constructor and through the use of setter methods.</p>
+
+<h3>IoC Component</h3>
+
+<p>A component that does not implement any kind of logic to set up its own state, but completely depends on
+   other parties to provide that state to it.</p>
+
+<h3>Non-IoC Component</h3>
+
+<p>A component that implements some kind of logic to set up its own state. Examples: a component that reads an
+   XML file; a component that looks up dependencies in JNDI; a component that queries system properties.</p>
+
+<h3>Domain-Specific
+                                                                                               Object</h3>
+
+<p>An object that implements a specification that is less generic than Java itself in its applicability.
+   Example: EJB, Servlets.</p>
+
+<h3>Spring-supported
+                                                                                                 Object</h3>
+
+<p>An object that can be 'natively' used in the Spring Framework. Any JavaBean (with some extensions to that
+   specification like &quot;initialization completion&quot; support), any object with a public default
+   constructor that does not require any method calls to set up its state.</p>
+
+<h3>Apache Composer-supported
+                                                                                                               Object
+</h3>
+
+<p>An object that can be 'natively' used in Apache Composer. Any Type-3 component.</p>
+
+<h3>XWork-supported
+                                                                                               Object</h3>
+
+<p>An object that can be 'natively' used in the XWork Framework. Any object with a public default constructor
+   that has its state set up through XXXAware interfaces.</p>
+
+<h3>Fail Fast</h3>
+
+<p>An object that fails fast is an object that indicates as early as possible if it is in an inconsistent or
+   unusable state (by throwing a fatal exception). The fastest possible way to FailFast is to do so during
+   instantiation. This can be handled in an elegant way if the class is a GoodCitizen.</p>
+
+</body>
+</html>

Added: incubator/composer/trunk/composer-site/src/site/content/transparency.html
URL: http://svn.apache.org/viewvc/incubator/composer/trunk/composer-site/src/site/content/transparency.html?rev=618174&view=auto
==============================================================================
--- incubator/composer/trunk/composer-site/src/site/content/transparency.html (added)
+++ incubator/composer/trunk/composer-site/src/site/content/transparency.html Sun Feb  3 22:33:20 2008
@@ -0,0 +1,25 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html>
+<head>
+<title>Transparency</title>
+</head>
+<body>
+<p>Transparency, for Apache Composer, means that components do not have to implement any interface or abstraction in order to be components. Moreover, components do not have to adhere to any naming conventions or bundle any meta-data in order to qualify as components.  </p>
+<p>Constructor Injection is what we recommend, so the minimum definition of a component is a simple class that takes its dependencies in its constructor. For Setter Injection, it is a class with dependencies delivered via simple setters. Your components may be interface / impl separated, but we are not forcing that for interop with Apache Composer.</p>
+<p>If you live with this ideal, you may be able to use the components you design for Apache Composer with other frameworks or containers. I.e. you are not locked in. We suggest you choose other technologies that are similarly light on API and framework, and could be characterised as transparent. Good examples are XStream, Sitemesh and anything that deals with POJOs.</p>
+<p>There are some exceptions, to this goal of ours.</p>
+<h2>Lifecycle</h2>
+<p>Java does not have a Startable interface, nor does it have a Disposable (.Net has IDisposable), so we made our own. You can use ours or your own in a similar design. If you use your own, you may want to extend StartableLifecycleStrategy and override a couple of methods. That's if you need lifecycle at all.</p>
+<p>If a Startable inerface goes into J2SE, then it will probably be supported.</p>
+<h2>Annotations</h2>
+<p>We also support @Inject as an annotation for methods and fields. This is a variation of Setter Injection. The annotations are part of our codebase. Again, you can use your own, or others if you override one of the two classes from Apache Composer's codebase <strong>AnnotatedFieldInjection</strong> and <strong>AnnotatedMethodInjection</strong>.</p>
+<p>Annotations are a break with transparency, so we don't recomend them - stick to vanilla Constructor Injection if you can.</p>
+<p>If a simple @Inject annotation goes into J2SE, then it will probably be supported. </p>
+<p></p>
+<p>&nbsp;</p>
+</body>
+
+
+
+</html>



Mime
View raw message