MentaContainer

Rev

Rev 91 | Rev 94 | Go to most recent revision | Only display areas with differences | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed

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