1 files changed, 111 insertions, 0 deletions
diff --git a/israfil-foundation-container/src/site/apt/lifecycle.apt b/israfil-foundation-container/src/site/apt/lifecycle.apt
new file mode 100644
index 0000000..3a62be5
--- /dev/null
+++ b/israfil-foundation-container/src/site/apt/lifecycle.apt
@@ -0,0 +1,111 @@
+                                    ------
+                  Israfil Micro-Container : Component Lifecycle
+                                    ------
+                  Christian Edward Gruber
+                                    ------
+                  May 2, 2007
+
+
+  Since one bad pattern in java is to engage in all sorts of side behaviours 
+  during construction, components can separate construction from initialization
+  by implementing the Startable interface.  Startable components are started
+  before they are provided to any caller.
+
+%{toc}
+
+The Startable interface
+
+  The Startable interface is quite simple:
+  
+-------------------
+
+package net.israfil.micro.container;
+
+public interface Startable {
+    
+    public void start();
+    
+    public boolean isRunning();
+    
+}
+
+-------------------
+
+  Implementors should start whatever they need to in order to be ready to
+  accept calls, including marshalling any resources necessary, etc.
+  
+  Care should be taken to time-out appropriately, as the container offers
+  its thread to the component during this initialization, and faulty 
+  initialization can lock the container.
+
+Registering components with dependencies
+
+  Registration of components with dependencies is a bit more complicated, as it
+  requires an adapter:
+
+-------------------
+
+public void registerType(Object key, AutoWiringAdapter componentAdapter);
+
+-------------------
+
+  AutoWiringAdapters can be created on the fly, for instance by using an anonymous
+  inner class that implements AutoWiringAdapter or extending AbstractAutoWiringAdapter:
+
+-------------------
+
+container.registerType(ComponentThree.class,new AbstractAutoWiringAdapter(
+        ComponentThree.class, new Object[] {ComponentOne.class}
+    ) {
+    public Object create(Object[] params) throws IllegalAccessException, InstantiationException {
+        return new ComponentThreeImpl((ComponentOne)params[0]);
+    }
+});
+
+-------------------
+
+  Another option is to create a constant adapter on the component itself
+
+-------------------
+
+public class ComponentThreeImpl implements ComponentThree {
+    public static final AutoWiringAdapter adapter = new AbstractAutoWiringAdapter(
+            ComponentThree.class, new Object[] {ComponentOne.class}
+        ) {
+        public Object create(Object[] params) throws IllegalAccessException, InstantiationException {
+            return new ComponentThreeImpl((ComponentOne)params[0]);
+        }
+    });
+    
+    private final ComponentOne one;
+    
+    public ComponentThreeImpl(ComponentOne one) {
+        this.one = one;
+    }
+    
+    public void doStuff() { one.whatever(); }
+}
+
+-------------------
+
+  Having created this adapter constant, you can then more easily register the 
+  component in the following way:
+  
+-------------------
+
+container.registerType(ComponentThree.class,ComponentThreeImpl.adapter);
+
+-------------------
+
+Retrieving components
+
+  Retrieving components is quite simple, using the getComponent method.  
+  
+-------------------
+
+ComponentThree three = (ComponentThree)container.getComponent(ComponentThree.class);
+three.doStuff();
+
+-------------------
+
+