WebSVN - MentaContainer - Diff - Rev 91 and 93 - /trunk/src/main/java/org/mentacontainer/Container.java


package org.mentacontainer;

/**
 * A very simple container that provides:
 * <ul>
 *   <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.
         *
         * The instance will be fully initialized (constructor and/or setters) and fully wired.
         *
         * @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);
       
        public Class<? extends Object> getType(String key);
       
        /**
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
         *
         * @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 component.
         * @return The component created as a ConfigurableComponent. (Fluent API)
         * @see Scope
         */
        public ConfigurableFactory ioc(String key, Class<? extends Object> klass, Scope scope);
       
        /**
         * Same as {@link #ioc(String, Class, Scope)} except that it assumes
         * there is no scope (Scope.NONE).
         *
         * @param key
         * @param klass
         * @return The component created as a ConfigurableComponent. (Fluent API)
         * @see Scope
         */
        public ConfigurableFactory ioc(String key, Class<?extends Object> klass);
       
        /**
 
         * 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 component for the IoC.
         * @return The component passed as a parameter.
         * @see Factory
         */
 
        public Factory ioc(String key, Factory factory);
       
        /**
         * Set up IoC based on the component passed. Specify the scope of the component.
         *
         * @param key The key representing the bean to return. The name of the bean in the container.
         * @param component The component for the IoC.
         * @param scope The scope used by the component.
         * @return The component passed as a parameter.
         * @see Factory
         * @see Scope
         */
        public Factory ioc(String key, Factory component, Scope scope);
       
        /**
         * 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/>
         *
         * 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 Dependency wire(String property, Class<? extends Object> klass, String source);
       
        /**
         * Same as {@link #wire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,
         * the property name is the same as the bean name that will be injected as the dependency.
         *
         * @param property
         * @param klass
         * @return The container itself. (Fluent API)
         */
        public Dependency wire(String property, Class<? extends Object> klass);
       
        /**
         * Setup a dependency.
         *
         * @param dependency The dependency to setup
         * @return The dependency itself. (Fluent API)
         * @see Dependency
         */
        public Dependency wire(Dependency dependency);
       
        /**
         * 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 Container populate(Object bean);
       
        /**
         * Check whether the container currently has a value for this key. For example,
         * if it is a singleton AND someone has requested it, the container will have it cached.
         * The method is useful to check for an instance without forcing her creation.
         *
         * @param key The key representing the bean inside the container.
         * @return true if the container has an instance cached in the scope for this key
         */
        public boolean check(String key);
       
        /**
         * Clear all cached instances for that scope. If you have a thread-pool for example you will
         * want to clear the THREAD scope when your thread is returned to the pool. Because you have a thread
         * pool you will have the SAME thread handling different requests and each request will need its own instances
         * from the container. Therefore, each time you are done with a thread and it is returned to your thread-pool
         * you can call clear to release the instances allocated and cached by the container. A web container and/or framework
         * can use this feature to implement a REQUEST scope which is nothing more than the THREAD scope with clear. If the web
         * container was not using a thread-pool, the THREAD scope would be equal to the REQUEST scope as each request would
         * always be handled by a different thread.
         *  
         * It does not make sense to clear a NONE scope (the method returns doing nothing). You can clear a SINGLETON scope if necessary.
         *
         * @param scope The scope to be cleared.
         */
        public void clear(Scope scope);
       
        /**
         * Clear a single key from cache and return the instance that was cached.
         *
         * @param key The key representing the bean inside the container.
         * @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared
         */
        public <T> T clear(String key);
}
 

Rev 91		Rev 93
1	package org.mentacontainer;	1	package org.mentacontainer;
2		2
3	/**	3	/**
4	* A very simple container that provides:	4	* A very simple container that provides:
5	* <ul>	5	* <ul>
6	* <li> Bean instantiation (duh!)</li>	6	* <li> Bean instantiation (duh!)</li>
7	* <li> Constructor injection for bean setup</li>	7	* <li> Constructor injection for bean setup</li>
8	* <li> Setter injection for bean setup</li>	8	* <li> Setter injection for bean setup</li>
9	* <li> Wiring based on name and type</li>	9	* <li> Wiring based on name and type</li>
10	* <li> Scopes: Singleton and ThreadLocal</li>	10	* <li> Scopes: Singleton and ThreadLocal</li>
11	* <li> Wiring of external beans with the beans configured in this container</li>	11	* <li> Wiring of external beans with the beans configured in this container</li>
12	* <li> Annotation and XML free (programmatic configuration is the way to go!)	12	* <li> Annotation and XML free (programmatic configuration is the way to go!)
13	* </ul>	13	* </ul>
14	*	14	*
15	* It does not get much simpler than that.	15	* It does not get much simpler than that.
16	*	16	*
17	* @author sergio.oliveira.jr@gmail.com	17	* @author sergio.oliveira.jr@gmail.com
18	*	18	*
19	*/	19	*/
20	public interface Container {	20	public interface Container {
21		21
22	/**	22	/**
23	* Get an instance from the container.	23	* Get an instance from the container.
24	*	24	*
25	* The instance will be fully initialized (constructor and/or setters) and fully wired.	25	* The instance will be fully initialized (constructor and/or setters) and fully wired.
26	*	26	*
27	* @param key The key representing the bean to return. The name of the bean in the container.	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.	28	* @return The fully initialized and wired bean.
29	*/	29	*/
30	public <T> T get(String key);	30	public <T> T get(String key);
31		31
32	public Class<? extends Object> getType(String key);	32	public Class<? extends Object> getType(String key);
33		33
34	/**	34	/**
35	* Configure a bean to be returned with the given implementation when {@link #get(String)} is called.	35	* Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
36	*	36	*
37	* @param key The key representing the bean to return. The name of the bean in the container.	37	* @param key The key representing the bean to return. The name of the bean in the container.
38	* @param klass The class used to instantiate the bean, in other words, its implementation.	38	* @param klass The class used to instantiate the bean, in other words, its implementation.
39	* @param scope The scope of the component.	39	* @param scope The scope of the component.
40	* @return The component created as a ConfigurableComponent. (Fluent API)	40	* @return The component created as a ConfigurableComponent. (Fluent API)
41	* @see Scope	41	* @see Scope
42	*/	42	*/
43	public ConfigurableFactory ioc(String key, Class<? extends Object> klass, Scope scope);	43	public ConfigurableFactory ioc(String key, Class<? extends Object> klass, Scope scope);
44		44
45	/**	45	/**
46	* Same as {@link #ioc(String, Class, Scope)} except that it assumes	46	* Same as {@link #ioc(String, Class, Scope)} except that it assumes
47	* there is no scope (Scope.NONE).	47	* there is no scope (Scope.NONE).
48	*	48	*
49	* @param key	49	* @param key
50	* @param klass	50	* @param klass
51	* @return The component created as a ConfigurableComponent. (Fluent API)	51	* @return The component created as a ConfigurableComponent. (Fluent API)
52	* @see Scope	52	* @see Scope
53	*/	53	*/
54	public ConfigurableFactory ioc(String key, Class<?extends Object> klass);	54	public ConfigurableFactory ioc(String key, Class<?extends Object> klass);
55		55
56	/**	56	/**
57	* Set up IoC based on the component passed. The scope assumed is NONE.	-
-		57	* Set up IoC based on the factory passed. The scope assumed is NONE.
58	*	58	*
59	* @param key The key representing the bean to return. The name of the bean in the container.	59	* @param key The key representing the bean to return. The name of the bean in the container.
60	* @param component The component for the IoC.	-
-		60	* @param factory The component for the IoC.
61	* @return The component passed as a parameter.	61	* @return The component passed as a parameter.
62	* @see Factory	62	* @see Factory
63	*/	63	*/
64	public Factory ioc(String key, Factory component);	-
-		64	public Factory ioc(String key, Factory factory);
65		65
66	/**	66	/**
67	* Set up IoC based on the component passed. Specify the scope of the component.	67	* Set up IoC based on the component passed. Specify the scope of the component.
68	*	68	*
69	* @param key The key representing the bean to return. The name of the bean in the container.	69	* @param key The key representing the bean to return. The name of the bean in the container.
70	* @param component The component for the IoC.	70	* @param component The component for the IoC.
71	* @param scope The scope used by the component.	71	* @param scope The scope used by the component.
72	* @return The component passed as a parameter.	72	* @return The component passed as a parameter.
73	* @see Factory	73	* @see Factory
74	* @see Scope	74	* @see Scope
75	*/	75	*/
76	public Factory ioc(String key, Factory component, Scope scope);	76	public Factory ioc(String key, Factory component, Scope scope);
77		77
78	/**	78	/**
79	* Configure a bean dependency to be auto-wired by the container. In general you want the	79	* Configure a bean dependency to be auto-wired by the container. In general you want the
80	* type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>	80	* type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
81	*	81	*
82	* Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>	82	* Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
83	* and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named	83	* and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
84	* <i>source</i> and injects it inside the first bean it is returning. This approach is recursive	84	* <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
85	* so all properties are checked up the class hierarchy, until it reaches Object.	85	* so all properties are checked up the class hierarchy, until it reaches Object.
86	*	86	*
87	* @param property a bean property that will require another bean, in other words, the required	87	* @param property a bean property that will require another bean, in other words, the required
88	* bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)	88	* bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
89	* @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)	89	* @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
90	* @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean	90	* @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
91	* @return The container itself. (Fluent API)	91	* @return The container itself. (Fluent API)
92	*/	92	*/
93	public Dependency wire(String property, Class<? extends Object> klass, String source);	93	public Dependency wire(String property, Class<? extends Object> klass, String source);
94		94
95	/**	95	/**
96	* Same as {@link #wire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,	96	* Same as {@link #wire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,
97	* the property name is the same as the bean name that will be injected as the dependency.	97	* the property name is the same as the bean name that will be injected as the dependency.
98	*	98	*
99	* @param property	99	* @param property
100	* @param klass	100	* @param klass
101	* @return The container itself. (Fluent API)	101	* @return The container itself. (Fluent API)
102	*/	102	*/
103	public Dependency wire(String property, Class<? extends Object> klass);	103	public Dependency wire(String property, Class<? extends Object> klass);
104		104
105	/**	105	/**
106	* Setup a dependency.	106	* Setup a dependency.
107	*	107	*
108	* @param dependency The dependency to setup	108	* @param dependency The dependency to setup
109	* @return The dependency itself. (Fluent API)	109	* @return The dependency itself. (Fluent API)
110	* @see Dependency	110	* @see Dependency
111	*/	111	*/
112	public Dependency wire(Dependency dependency);	112	public Dependency wire(Dependency dependency);
113		113
114	/**	114	/**
115	* Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.	115	* Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.
116	* You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting	116	* You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting
117	* in the given bean, in other words, populating it.	117	* in the given bean, in other words, populating it.
118	*	118	*
119	* @param bean The bean to be populated with other beans from the container.	119	* @param bean The bean to be populated with other beans from the container.
120	* @return The container itself. (Fluent API)	120	* @return The container itself. (Fluent API)
121	*/	121	*/
122	public Container populate(Object bean);	122	public Container populate(Object bean);
123		123
124	/**	124	/**
125	* Check whether the container currently has a value for this key. For example,	125	* Check whether the container currently has a value for this key. For example,
126	* if it is a singleton AND someone has requested it, the container will have it cached.	126	* if it is a singleton AND someone has requested it, the container will have it cached.
127	* The method is useful to check for an instance without forcing her creation.	127	* The method is useful to check for an instance without forcing her creation.
128	*	128	*
129	* @param key The key representing the bean inside the container.	129	* @param key The key representing the bean inside the container.
130	* @return true if the container has an instance cached in the scope for this key	130	* @return true if the container has an instance cached in the scope for this key
131	*/	131	*/
132	public boolean check(String key);	132	public boolean check(String key);
133		133
134	/**	134	/**
135	* Clear all cached instances for that scope. If you have a thread-pool for example you will	135	* Clear all cached instances for that scope. If you have a thread-pool for example you will
136	* want to clear the THREAD scope when your thread is returned to the pool. Because you have a thread	136	* want to clear the THREAD scope when your thread is returned to the pool. Because you have a thread
137	* pool you will have the SAME thread handling different requests and each request will need its own instances	137	* pool you will have the SAME thread handling different requests and each request will need its own instances
138	* from the container. Therefore, each time you are done with a thread and it is returned to your thread-pool	138	* from the container. Therefore, each time you are done with a thread and it is returned to your thread-pool
139	* you can call clear to release the instances allocated and cached by the container. A web container and/or framework	139	* you can call clear to release the instances allocated and cached by the container. A web container and/or framework
140	* can use this feature to implement a REQUEST scope which is nothing more than the THREAD scope with clear. If the web	140	* can use this feature to implement a REQUEST scope which is nothing more than the THREAD scope with clear. If the web
141	* container was not using a thread-pool, the THREAD scope would be equal to the REQUEST scope as each request would	141	* container was not using a thread-pool, the THREAD scope would be equal to the REQUEST scope as each request would
142	* always be handled by a different thread.	142	* always be handled by a different thread.
143	*	143	*
144	* It does not make sense to clear a NONE scope (the method returns doing nothing). You can clear a SINGLETON scope if necessary.	144	* It does not make sense to clear a NONE scope (the method returns doing nothing). You can clear a SINGLETON scope if necessary.
145	*	145	*
146	* @param scope The scope to be cleared.	146	* @param scope The scope to be cleared.
147	*/	147	*/
148	public void clear(Scope scope);	148	public void clear(Scope scope);
149		149
150	/**	150	/**
151	* Clear a single key from cache and return the instance that was cached.	151	* Clear a single key from cache and return the instance that was cached.
152	*	152	*
153	* @param key The key representing the bean inside the container.	153	* @param key The key representing the bean inside the container.
154	* @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared	154	* @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared
155	*/	155	*/
156	public <T> T clear(String key);	156	public <T> T clear(String key);
157	}	157	}
158		158

MentaContainer

(root)/trunk/src/main/java/org/mentacontainer/Container.java - Rev 91 → 93