MentaContainer

Rev

Rev 103 | Rev 110 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 103 Rev 108
Line 4... Line 4...
4
/**
4
/**
5
 * A very simple container that provides:
-
 
-
 
5
 * A IoC container that provides:
6
 * <ul>
6
 * <ul>
7
 *   <li> Bean instantiation (duh!)</li>
-
 
8
 *   <li> Constructor injection for bean setup</li>
-
 
9
 *   <li> Setter injection for bean setup</li>
-
 
10
 *   <li> Wiring based on name and type</li>
-
 
11
 *   <li> Scopes: Singleton and ThreadLocal</li>
-
 
12
 *   <li> Wiring of external beans with the beans configured in this container</li>
-
 
13
 *   <li> Annotation and XML free (programmatic configuration is the way to go!)
-
 
-
 
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>
-
 
17
 * <li>Interceptors for factories: onCreated, onDestroyed, useful for object pooling</li>
14
 * </ul>
18
 * </ul>
15
 *
19
 *
16
 * It does not get much simpler than that.
-
 
17
 *
-
 
18
 * @author sergio.oliveira.jr@gmail.com
20
 * @author sergio.oliveira.jr@gmail.com
19
 *
21
 *
20
 */
22
 */
21
public interface Container {
23
public interface Container {
22
       
24
       
23
        /**
25
        /**
24
         * Get an instance from the container.
-
 
-
 
26
         * Get an instance from the container by using the associated factory.
25
         *
27
         *
26
         * The instance will be fully initialized (constructor and/or setters) and fully wired.
-
 
-
 
28
         * The instance will be fully initialized (through constructor and/or setters) and fully wired (all dependencies will be resolved).
27
         *
29
         *
28
         * @param key The key representing the bean to return. The name of the bean in the container.
-
 
-
 
30
         * @param key The key representing the factory to use. The name of the bean in the container.
29
         * @return The fully initialized and wired bean.
31
         * @return The fully initialized and wired bean.
30
         */
32
         */
31
        public <T> T get(String key);
33
        public <T> T get(String key);
32
       
34
       
-
 
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
         */
33
        public Class<? extends Object> getType(String key);
41
        public Class<? extends Object> getType(String key);
34
       
42
       
35
        /**
43
        /**
36
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
44
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
-
 
45
         * An internal factory will be used.
37
         *
46
         *
38
         * @param key The key representing the bean to return. The name of the bean in the container.
47
         * @param key The key representing the bean to return. The name of the bean in the container.
39
         * @param klass The class used to instantiate the bean, in other words, its implementation.
48
         * @param klass The class used to instantiate the bean, in other words, its implementation.
40
         * @param scope The scope of the factory.
49
         * @param scope The scope of the factory.
41
         * @return The factory created as a Configurablefactory. (Fluent API)
-
 
-
 
50
         * @return The factory created as a ConfigurableFactory. (Fluent API)
42
         * @see Scope
51
         * @see Scope
43
         */
52
         */
44
        public ConfigurableFactory ioc(String key, Class<? extends Object> klass, Scope scope);
53
        public ConfigurableFactory ioc(String key, Class<? extends Object> klass, Scope scope);
45
       
54
       
46
        /**
55
        /**
47
         * Same as {@link #ioc(String, Class, Scope)} except that it assumes
56
         * Same as {@link #ioc(String, Class, Scope)} except that it assumes
48
         * there is no scope (Scope.NONE).
57
         * there is no scope (Scope.NONE).
49
         *
58
         *
50
         * @param key
59
         * @param key
51
         * @param klass
60
         * @param klass
52
         * @return The factory created as a Configurablefactory. (Fluent API)
-
 
-
 
61
         * @return The factory created as a ConfigurableFactory. (Fluent API)
53
         * @see Scope
62
         * @see Scope
54
         */
63
         */
55
        public ConfigurableFactory ioc(String key, Class<?extends Object> klass);
64
        public ConfigurableFactory ioc(String key, Class<?extends Object> klass);
56
       
65
       
57
        /**
66
        /**
58
         * Set up IoC based on the factory passed. The scope assumed is NONE.
-
 
-
 
67
         * Set up a factory for the given key. The scope assumed is NONE.
59
         *
68
         *
60
         * @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.
61
         * @param factory The factory for the IoC.
70
         * @param factory The factory for the IoC.
62
         * @return The factory passed as a parameter.
-
 
-
 
71
         * @return The factory passed as a parameter. (Fluent API)
63
         * @see Factory
72
         * @see Factory
64
         */
73
         */
65
        public Factory ioc(String key, Factory factory);
74
        public Factory ioc(String key, Factory factory);
66
       
75
       
67
        /**
76
        /**
68
         * Set up IoC based on the factory passed. Specify the scope of the factory.
-
 
-
 
77
         * Set up a factory for the given key in the given scope.
69
         *
78
         *
70
         * @param key The key representing the bean to return. The name of the bean in the container.
79
         * @param key The key representing the bean to return. The name of the bean in the container.
71
         * @param factory The factory for the IoC.
80
         * @param factory The factory for the IoC.
72
         * @param scope The scope used by the factory.
81
         * @param scope The scope used by the factory.
73
         * @return The factory passed as a parameter.
-
 
-
 
82
         * @return The factory passed as a parameter (Fluent API).
74
         * @see Factory
83
         * @see Factory
75
         * @see Scope
84
         * @see Scope
76
         */
85
         */
77
        public Factory ioc(String key, Factory factory, Scope scope);
86
        public Factory ioc(String key, Factory factory, Scope scope);
78
       
87
       
79
        /**
88
        /**
80
         * Configure a bean dependency to be auto-wired by the container. In general you want the
-
 
81
         * type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
-
 
-
 
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.
82
         *
91
         *
83
         * Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
-
 
84
         * and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
-
 
85
         * <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
-
 
86
         * so all properties are checked up the class hierarchy, until it reaches Object.
-
 
87
         *
-
 
88
         * @param property a bean property that will require another bean, in other words, the required
-
 
89
         *                                 bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
-
 
90
         * @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
-
 
91
         * @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
-
 
92
         * @return The container itself. (Fluent API)
-
 
-
 
92
         * @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
93
         */
93
         */
94
        public void autowire(String sourceFromContainer);
94
        public void autowire(String sourceFromContainer);
95
       
95
       
-
 
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
         */
96
        public void autowire(String sourceFromContainer, String property);
103
        public void autowire(String sourceFromContainer, String property);
97
       
104
       
98
        /**
105
        /**
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.
-
 
-
 
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.
102
         *
109
         *
103
         * @param bean The bean to be populated with other beans from the container.
110
         * @param bean The bean to be populated with other beans from the container.
104
         * @return The container itself. (Fluent API)
-
 
105
         */
111
         */
106
        public void inject(Object bean);
112
        public void inject(Object bean);
107
       
113
       
-
 
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
         */
108
        public <T> T construct(Class<? extends Object> klass);
121
        public <T> T construct(Class<? extends Object> klass);
109
       
122
       
110
        /**
123
        /**
111
         * Check whether the container currently has a value for this key. For example,
124
         * Check whether the container currently has a value for this key. For example,
112
         * if it is a singleton AND someone has requested it, the container will have it cached.
125
         * if it is a singleton AND someone has requested it, the container will have it cached.