WebSVN - MentaContainer - Blame - Rev 40 - /trunk/src/main/java/org/mentacontainer/Container.java

Rev	Author	Line No.	Line
2	soliveira	1	package org.mentacontainer;
		2
		3	/**
		4	* A very simple container that provides:
		5	* <ul>
		6	* <li> Bean instantiation (duh!)</li>
		7	* <li> Constructor injection for bean setup</li>
		8	* <li> Setter injection for bean setup</li>
		9	* <li> Auto-wiring based on name and type</li>
		10	* <li> Singleton</li>
20	soliveira	11	* <li> Wiring of external beans with the beans configured in this container</li>
25	soliveira	12	* <li> Annotation and XML free (programmatic configuration is the way to go!)
2	soliveira	13	* </ul>
		14	*
		15	* It does not get much simpler than that.
		16	*
		17	* @author sergio.oliveira.jr@gmail.com
		18	*
		19	*/
		20	public interface Container {
		21
		22	/**
		23	* Get an instance from the container.
		24	*
		25	* The instance will be fully initialized (constructor and/or setters) and fully wired.
		26	*
		27	* @param key The key representing the bean to return. The name of the bean in the container.
		28	* @return The fully initialized and wired bean.
		29	*/
		30	public Object get(String key);
		31
		32	/**
		33	* Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
		34	*
		35	* @param key The key representing the bean to return. The name of the bean in the container.
		36	* @param klass The class used to instantiate the bean, in other words, its implementation.
		37	* @param singleton A boolean to indicate if this bean will be a singleton.
20	soliveira	38	* @return The component created. (Fluent API)
2	soliveira	39	*/
20	soliveira	40	public Component ioc(String key, Class<? extends Object> klass, boolean singleton);
2	soliveira	41
		42	/**
21	soliveira	43	* Same as {@link #ioc(String, Class, boolean)} except that it assumes
2	soliveira	44	* singleton is false.
		45	*
		46	* @param key
		47	* @param klass
20	soliveira	48	* @return The component created. (Fluent API)
2	soliveira	49	*/
20	soliveira	50	public Component ioc(String key, Class<?extends Object> klass);
2	soliveira	51
		52	/**
20	soliveira	53	* Set up IoC based on the component passed.
2	soliveira	54	*
39	soliveira	55	* @param key The key representing the bean to return. The name of the bean in the container.
20	soliveira	56	* @param component The component for the IoC.
		57	* @return The component passed as a parameter. (Fluent API)
21	soliveira	58	* @see Component
20	soliveira	59	*/
39	soliveira	60	public Component ioc(String key, Component component);
20	soliveira	61
		62	/**
		63	* Configure a bean dependency to be auto-wired by the container. In general you want the
		64	* type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
		65	*
2	soliveira	66	* Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
		67	* and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
		68	* <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
		69	* so all properties are checked up the class hierarchy, until it reaches Object.
		70	*
		71	* @param property a bean property that will require another bean, in other words, the required
		72	* bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
20	soliveira	73	* @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
2	soliveira	74	* @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
		75	* @return The container itself. (Fluent API)
		76	*/
20	soliveira	77	public Dependency autowire(String property, Class<? extends Object> klass, String source);
2	soliveira	78
		79	/**
21	soliveira	80	* Same as {@link #autowire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,
2	soliveira	81	* the property name is the same as the bean name that will be injected as the dependency.
		82	*
		83	* @param property
		84	* @param klass
		85	* @return The container itself. (Fluent API)
		86	*/
20	soliveira	87	public Dependency autowire(String property, Class<? extends Object> klass);
2	soliveira	88
		89	/**
21	soliveira	90	* Setup a dependency.
2	soliveira	91	*
21	soliveira	92	* @param dependency The dependency to setup
		93	* @return The dependency itself. (Fluent API)
		94	* @see Dependency
2	soliveira	95	*/
20	soliveira	96	public Dependency autowire(Dependency dependency);
2	soliveira	97
		98	/**
		99	* Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.
		100	* You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting
		101	* in the given bean, in other words, populating it.
		102	*
		103	* @param bean The bean to be populated with other beans from the container.
		104	* @return The container itself. (Fluent API)
		105	*/
40	soliveira	106	public Container populate(Object bean);
4	soliveira	107
		108	/**
		109	* Check whether the container is configured to provide a bean with name 'key'.
		110	*
		111	* @param key The key representing the bean inside the container.
		112	* @return true if the container contains this bean.
		113	*/
		114	public boolean contains(String key);
2	soliveira	115	}

MentaContainer

(root)/trunk/src/main/java/org/mentacontainer/Container.java - Rev 40