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

Rev	Author	Line No.	Line
2	soliveira	1	package org.mentacontainer;
		2
97	soliveira	3
2	soliveira	4	/**
108	soliveira	5	* A IoC container that provides:
2	soliveira	6	* <ul>
108	soliveira	7	* <li>Programmatic Configuration</li>
		8	* <li>Bean Instantiation through constructors</li>
		9	* <li>Bean Initialization through setters</li>
		10	* <li>Dependency Injection through constructors</li>
		11	* <li>Dependency Injection through setters</li>
		12	* <li>Auto-wiring through constructors and setters (very simple!)</li>
		13	* <li>Injection through setters so you can populate any external object with objects from the container</li>
		14	* <li>Instantiation through constructors so you can instantiate any external class with objects from the container</li>
		15	* <li>Support for SINGLETON and THREAD scopes, plus you can easily create REQUEST and SESSION scopes for web projects</li>
		16	* <li>Generic Factories so you can easily turn anything into a object factory</li>
110	soliveira	17	* <li>Interceptors for factories: onCreated, onCleared, useful for object pooling</li>
2	soliveira	18	* </ul>
		19	*
		20	* @author sergio.oliveira.jr@gmail.com
		21	*
		22	*/
		23	public interface Container {
		24
		25	/**
108	soliveira	26	* Get an instance from the container by using the associated factory.
2	soliveira	27	*
108	soliveira	28	* The instance will be fully initialized (through constructor and/or setters) and fully wired (all dependencies will be resolved).
2	soliveira	29	*
108	soliveira	30	* @param key The key representing the factory to use. The name of the bean in the container.
2	soliveira	31	* @return The fully initialized and wired bean.
		32	*/
135	soliveira	33	public <T> T get(Object key);
2	soliveira	34
108	soliveira	35	/**
		36	* Get the type of the instances returned by the associated factory.
		37	*
		38	* @param key The factory
		39	* @return The type returned by this factory
		40	*/
148	soliveira	41	public Class<?> getType(Object key);
91	soliveira	42
2	soliveira	43	/**
		44	* Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
108	soliveira	45	* An internal factory will be used.
2	soliveira	46	*
		47	* @param key The key representing the bean to return. The name of the bean in the container.
		48	* @param klass The class used to instantiate the bean, in other words, its implementation.
95	soliveira	49	* @param scope The scope of the factory.
108	soliveira	50	* @return The factory created as a ConfigurableFactory. (Fluent API)
57	soliveira	51	* @see Scope
2	soliveira	52	*/
148	soliveira	53	public ConfigurableFactory ioc(Object key, Class<?> klass, Scope scope);
2	soliveira	54
		55	/**
57	soliveira	56	* Same as {@link #ioc(String, Class, Scope)} except that it assumes
		57	* there is no scope (Scope.NONE).
2	soliveira	58	*
		59	* @param key
		60	* @param klass
108	soliveira	61	* @return The factory created as a ConfigurableFactory. (Fluent API)
57	soliveira	62	* @see Scope
2	soliveira	63	*/
146	soliveira	64	public ConfigurableFactory ioc(Object key, Class<?extends Object> klass);
2	soliveira	65
		66	/**
108	soliveira	67	* Set up a factory for the given key. The scope assumed is NONE.
2	soliveira	68	*
39	soliveira	69	* @param key The key representing the bean to return. The name of the bean in the container.
95	soliveira	70	* @param factory The factory for the IoC.
108	soliveira	71	* @return The factory passed as a parameter. (Fluent API)
88	soliveira	72	* @see Factory
20	soliveira	73	*/
146	soliveira	74	public Factory ioc(Object key, Factory factory);
20	soliveira	75
		76	/**
108	soliveira	77	* Set up a factory for the given key in the given scope.
51	soliveira	78	*
		79	* @param key The key representing the bean to return. The name of the bean in the container.
95	soliveira	80	* @param factory The factory for the IoC.
		81	* @param scope The scope used by the factory.
108	soliveira	82	* @return The factory passed as a parameter (Fluent API).
88	soliveira	83	* @see Factory
57	soliveira	84	* @see Scope
51	soliveira	85	*/
146	soliveira	86	public Factory ioc(Object key, Factory factory, Scope scope);
51	soliveira	87
		88	/**
108	soliveira	89	* Configure a bean dependency to be auto-wired by the container.
		90	* 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.
20	soliveira	91	*
108	soliveira	92	* @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
2	soliveira	93	*/
135	soliveira	94	public void autowire(Object sourceFromContainer);
2	soliveira	95
108	soliveira	96	/**
		97	* Configure a bean dependency to be auto-wired by the container.
		98	* 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.
		99	*
		100	* @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
		101	* @param property The name of the property to inject, whey trying auto-wiring by setter.
		102	*/
135	soliveira	103	public void autowire(Object sourceFromContainer, String property);
2	soliveira	104
		105	/**
108	soliveira	106	* Take a given bean and populate its properties with other beans coming from this container.
		107	* You basically checking properties of the given bean and looking for values inside the container.
		108	* And injecting in the given bean, in other words, populating it.
2	soliveira	109	*
		110	* @param bean The bean to be populated with other beans from the container.
		111	*/
103	soliveira	112	public void inject(Object bean);
4	soliveira	113
108	soliveira	114	/**
		115	* Construct an instance using beans from the container. A constructor will be chosen that has arguments that can be found
		116	* inside the container.
		117	*
		118	* @param klass The class that should be instantiated.
		119	* @return An instantiated bean.
		120	*/
148	soliveira	121	public <T> T construct(Class<?> klass);
102	soliveira	122
4	soliveira	123	/**
58	soliveira	124	* Check whether the container currently has a value for this key. For example,
		125	* if it is a singleton AND someone has requested it, the container will have it cached.
		126	* The method is useful to check for an instance without forcing her creation.
4	soliveira	127	*
		128	* @param key The key representing the bean inside the container.
58	soliveira	129	* @return true if the container has an instance cached in the scope for this key
4	soliveira	130	*/
135	soliveira	131	public boolean check(Object key);
57	soliveira	132
		133	/**
81	soliveira	134	* Clear all cached instances for that scope. If you have a thread-pool for example you will
		135	* want to clear the THREAD scope when your thread is returned to the pool. Because you have a thread
		136	* pool you will have the SAME thread handling different requests and each request will need its own instances
		137	* from the container. Therefore, each time you are done with a thread and it is returned to your thread-pool
		138	* you can call clear to release the instances allocated and cached by the container. A web container and/or framework
		139	* can use this feature to implement a REQUEST scope which is nothing more than the THREAD scope with clear. If the web
		140	* container was not using a thread-pool, the THREAD scope would be equal to the REQUEST scope as each request would
		141	* always be handled by a different thread.
		142	*
		143	* It does not make sense to clear a NONE scope (the method returns doing nothing). You can clear a SINGLETON scope if necessary.
57	soliveira	144	*
		145	* @param scope The scope to be cleared.
		146	*/
		147	public void clear(Scope scope);
58	soliveira	148
		149	/**
		150	* Clear a single key from cache and return the instance that was cached.
		151	*
		152	* @param key The key representing the bean inside the container.
70	soliveira	153	* @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared
58	soliveira	154	*/
135	soliveira	155	public <T> T clear(Object key);
2	soliveira	156	}

MentaContainer

(root)/trunk/src/main/java/org/mentacontainer/Container.java @ 70 - Rev 148