3 files changed, 262 insertions, 0 deletions
diff --git a/israfil-foundation-container/src/site/apt/index.apt b/israfil-foundation-container/src/site/apt/index.apt
new file mode 100755
index 0000000..10a0281
--- /dev/null
+++ b/israfil-foundation-container/src/site/apt/index.apt
@@ -0,0 +1,45 @@
+                                     ------
+                  Israfil Micro-Container
+                                    ------
+                  Christian Edward Gruber
+                                    ------
+                  May 2, 2007
+
+Overview
+
+   The micro-container is an extremely lightweight IoC container supporting
+   dependency injection.  It is built with the principles in mind that 
+   spawned {{{http://www.picocontainer.org/} pico-container}} but with the
+   explicit constraints to which J2ME applications centered around the 
+   CLDC 1.1 are bound.  This includes a complete absence of any constructor
+   or method lookup (reflection) or dynamic proxy support. 
+   
+   Like pico-container, Israfil's micro-container only handles the 
+   registration and vending of components, not additional services such as 
+   persistence, and the like.  
+
+Isn't Micro bigger than Pico?
+
+   Yes, but micro-container wasn't as taken, and israfil-micro is a placeholder
+   for any further frameworks that might be developed in the J2ME footprint.
+   I briefly considered femto-container, but it was too obscure even for me.
+   
+Can I use this in commercial or other software?
+
+   Yes.  The micro-container, as with all Israfil Micro and Foundation libraries
+   are licensed under the terms of the BSD license, which provides you with a 
+   license to distribute with or without modification, and to prepare derivative
+   works, with the sole exception that you retain the notice (specific terms
+   are available in the license page linked from the menu.)  The short answer
+   is yes, go for it, it won't cost you a penny, and you won't be obliged to 
+   show anyone your code.
+
+How do I use it?
+
+   I recommend looking at pico-container's site for really good theoretical
+   presentations of this kind of software. Tapestry5 also contains an ioc
+   framework par-excellence, and it has some ok docs.  Some specific usage
+   documentation for this framework (around staging the container and getting
+   things set up in a practical application) are available in the usage page
+   linked from the menu.   
+   
+\ No newline at end of file
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();
+
+-------------------
+
+
diff --git a/israfil-foundation-container/src/site/apt/usage.apt b/israfil-foundation-container/src/site/apt/usage.apt
new file mode 100644
index 0000000..54ce418
--- /dev/null
+++ b/israfil-foundation-container/src/site/apt/usage.apt
@@ -0,0 +1,106 @@
+                                    ------
+                  Israfil Micro-Container : Usage
+                                    ------
+                  Christian Edward Gruber
+                                    ------
+                  May 2, 2007
+
+
+  The default container is an auto-wiring container which allows for registration
+  of components quite simply, if they have no dependencies.  Components with 
+  dependencies require the use of an adapter which explicitly declares the 
+  dependencies, and provides a builder method which receives the dependencies and
+  explicitly constructs the component, avoiding any use of reflection, which is
+  not supported in the CLDC 1.1 profile. 
+
+%{toc}
+
+Setting up the auto-wiring container.
+
+  Setting up the container should be done early in your entry-point code.
+  The default container auto-wires components on first use of the component,
+  unless configured to pre-initialize them.  This allows for early creation 
+  of the container and registration of components without incurring the 
+  up-front performance cost.
+  
+  Registration for independent components works quite simply:
+
+-------------------
+
+AutoWiringAdaptableContainer container = new DefaultAutoWiringAdaptablecContainer();
+container.registerType(ComponentOne.class,ComponentOneImpl.class);
+container.registerType(ComponentTwo.class,ComponentTwoImpl.class);
+
+-------------------
+
+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();
+
+-------------------
+
+