MentaContainer

Compare Revisions

Ignore whitespace Rev 108 → Rev 107

/trunk/src/main/java/org/mentacontainer/Container.java
2,52 → 2,43
 
 
/**
* A IoC container that provides:
* A very simple container that provides:
* <ul>
* <li>Programmatic Configuration</li>
* <li>Bean Instantiation through constructors</li>
* <li>Bean Initialization through setters</li>
* <li>Dependency Injection through constructors</li>
* <li>Dependency Injection through setters</li>
* <li>Auto-wiring through constructors and setters (very simple!)</li>
* <li>Injection through setters so you can populate any external object with objects from the container</li>
* <li>Instantiation through constructors so you can instantiate any external class with objects from the container</li>
* <li>Support for SINGLETON and THREAD scopes, plus you can easily create REQUEST and SESSION scopes for web projects</li>
* <li>Generic Factories so you can easily turn anything into a object factory</li>
* <li>Interceptors for factories: onCreated, onDestroyed, useful for object pooling</li>
* <li> Bean instantiation (duh!)</li>
* <li> Constructor injection for bean setup</li>
* <li> Setter injection for bean setup</li>
* <li> Wiring based on name and type</li>
* <li> Scopes: Singleton and ThreadLocal</li>
* <li> Wiring of external beans with the beans configured in this container</li>
* <li> Annotation and XML free (programmatic configuration is the way to go!)
* </ul>
*
* It does not get much simpler than that.
*
* @author sergio.oliveira.jr@gmail.com
*
*/
public interface Container {
/**
* Get an instance from the container by using the associated factory.
* Get an instance from the container.
*
* The instance will be fully initialized (through constructor and/or setters) and fully wired (all dependencies will be resolved).
* The instance will be fully initialized (constructor and/or setters) and fully wired.
*
* @param key The key representing the factory to use. The name of the bean in the container.
* @param key The key representing the bean to return. The name of the bean in the container.
* @return The fully initialized and wired bean.
*/
public <T> T get(String key);
/**
* Get the type of the instances returned by the associated factory.
*
* @param key The factory
* @return The type returned by this factory
*/
public Class<? extends Object> getType(String key);
/**
* Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
* An internal factory will be used.
*
* @param key The key representing the bean to return. The name of the bean in the container.
* @param klass The class used to instantiate the bean, in other words, its implementation.
* @param scope The scope of the factory.
* @return The factory created as a ConfigurableFactory. (Fluent API)
* @return The factory created as a Configurablefactory. (Fluent API)
* @see Scope
*/
public ConfigurableFactory ioc(String key, Class<? extends Object> klass, Scope scope);
58,66 → 49,62
*
* @param key
* @param klass
* @return The factory created as a ConfigurableFactory. (Fluent API)
* @return The factory created as a Configurablefactory. (Fluent API)
* @see Scope
*/
public ConfigurableFactory ioc(String key, Class<?extends Object> klass);
/**
* Set up a factory for the given key. The scope assumed is NONE.
* Set up IoC based on the factory passed. The scope assumed is NONE.
*
* @param key The key representing the bean to return. The name of the bean in the container.
* @param factory The factory for the IoC.
* @return The factory passed as a parameter. (Fluent API)
* @return The factory passed as a parameter.
* @see Factory
*/
public Factory ioc(String key, Factory factory);
/**
* Set up a factory for the given key in the given scope.
* Set up IoC based on the factory passed. Specify the scope of the factory.
*
* @param key The key representing the bean to return. The name of the bean in the container.
* @param factory The factory for the IoC.
* @param scope The scope used by the factory.
* @return The factory passed as a parameter (Fluent API).
* @return The factory passed as a parameter.
* @see Factory
* @see Scope
*/
public Factory ioc(String key, Factory factory, Scope scope);
/**
* Configure a bean dependency to be auto-wired by the container.
* It wires by constructor and by setter. By constructor is uses the type of sourceFromContainer. By setter it assumes the property is also named sourceFromContainer.
* Configure a bean dependency to be auto-wired by the container. In general you want the
* type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
*
* @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
* Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
* and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
* <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
* so all properties are checked up the class hierarchy, until it reaches Object.
*
* @param property a bean property that will require another bean, in other words, the required
* bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
* @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
* @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
* @return The container itself. (Fluent API)
*/
public void autowire(String sourceFromContainer);
/**
* Configure a bean dependency to be auto-wired by the container.
* It wires by constructor and by setter. By constructor is uses the type of sourceFromContainer. By setter it looks for a property with the given name and try to inject.
*
* @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
* @param property The name of the property to inject, whey trying auto-wiring by setter.
*/
public void autowire(String sourceFromContainer, String property);
/**
* Take a given bean and populate its properties with other beans coming from this container.
* You basically checking properties of the given bean and looking for values inside the container.
* And injecting in the given bean, in other words, populating it.
* Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.
* You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting
* in the given bean, in other words, populating it.
*
* @param bean The bean to be populated with other beans from the container.
* @return The container itself. (Fluent API)
*/
public void inject(Object bean);
/**
* Construct an instance using beans from the container. A constructor will be chosen that has arguments that can be found
* inside the container.
*
* @param klass The class that should be instantiated.
* @return An instantiated bean.
*/
public <T> T construct(Class<? extends Object> klass);
/**
/trunk/src/main/java/org/mentacontainer/ConfigurableFactory.java
1,7 → 1,7
package org.mentacontainer;
 
/**
* An IoC factory that knows how to create instances and
* An IoC factory that knows how to create instances of itself and
* can be configured by accepting values for its constructor
* and properties (setters). It can also be intercepted right
* after it creates an instance and right before it destroys/releases an instance