MentaContainer

Rev

Rev 58 | Rev 76 | Go to most recent revision | Only display areas with differences | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 58 Rev 70
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> Auto-wiring based on name and type</li>
9
 *   <li> Auto-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
        /**
32
        /**
33
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
33
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
34
         *
34
         *
35
         * @param key The key representing the bean to return. The name of the bean in the container.
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.
36
         * @param klass The class used to instantiate the bean, in other words, its implementation.
37
         * @param scope The scope of the component.
37
         * @param scope The scope of the component.
38
         * @return The component created as a ConfigurableComponent. (Fluent API)
38
         * @return The component created as a ConfigurableComponent. (Fluent API)
39
         * @see Scope
39
         * @see Scope
40
         */
40
         */
41
        public ConfigurableComponent ioc(String key, Class<? extends Object> klass, Scope scope);
41
        public ConfigurableComponent ioc(String key, Class<? extends Object> klass, Scope scope);
42
       
42
       
43
        /**
43
        /**
44
         * Same as {@link #ioc(String, Class, Scope)} except that it assumes
44
         * Same as {@link #ioc(String, Class, Scope)} except that it assumes
45
         * there is no scope (Scope.NONE).
45
         * there is no scope (Scope.NONE).
46
         *
46
         *
47
         * @param key
47
         * @param key
48
         * @param klass
48
         * @param klass
49
         * @return The component created as a ConfigurableComponent. (Fluent API)
49
         * @return The component created as a ConfigurableComponent. (Fluent API)
50
         * @see Scope
50
         * @see Scope
51
         */
51
         */
52
        public ConfigurableComponent ioc(String key, Class<?extends Object> klass);
52
        public ConfigurableComponent ioc(String key, Class<?extends Object> klass);
53
       
53
       
54
        /**
54
        /**
55
         * Set up IoC based on the component passed. The scope assumed is NONE.
55
         * Set up IoC based on the component passed. The scope assumed is NONE.
56
         *
56
         *
57
         * @param key The key representing the bean to return. The name of the bean in the container.
57
         * @param key The key representing the bean to return. The name of the bean in the container.
58
         * @param component The component for the IoC.
58
         * @param component The component for the IoC.
59
         * @return The component passed as a parameter.
59
         * @return The component passed as a parameter.
60
         * @see Component
60
         * @see Component
61
         */
61
         */
62
        public Component ioc(String key, Component component);
62
        public Component ioc(String key, Component component);
63
       
63
       
64
        /**
64
        /**
65
         * Set up IoC based on the component passed. Specify the scope of the component.
65
         * Set up IoC based on the component passed. Specify the scope of the component.
66
         *
66
         *
67
         * @param key The key representing the bean to return. The name of the bean in the container.
67
         * @param key The key representing the bean to return. The name of the bean in the container.
68
         * @param component The component for the IoC.
68
         * @param component The component for the IoC.
69
         * @param scope The scope used by the component.
69
         * @param scope The scope used by the component.
70
         * @return The component passed as a parameter.
70
         * @return The component passed as a parameter.
71
         * @see Component
71
         * @see Component
72
         * @see Scope
72
         * @see Scope
73
         */
73
         */
74
        public Component ioc(String key, Component component, Scope scope);
74
        public Component ioc(String key, Component component, Scope scope);
75
       
75
       
76
        /**
76
        /**
77
         * Configure a bean dependency to be auto-wired by the container. In general you want the
77
         * Configure a bean dependency to be auto-wired by the container. In general you want the
78
         * type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
78
         * type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
79
         *
79
         *
80
         * Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
80
         * Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
81
         * and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
81
         * and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
82
         * <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
82
         * <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
83
         * so all properties are checked up the class hierarchy, until it reaches Object.
83
         * so all properties are checked up the class hierarchy, until it reaches Object.
84
         *
84
         *
85
         * @param property a bean property that will require another bean, in other words, the required
85
         * @param property a bean property that will require another bean, in other words, the required
86
         *                                 bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
86
         *                                 bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
87
         * @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
87
         * @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
88
         * @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
88
         * @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
89
         * @return The container itself. (Fluent API)
89
         * @return The container itself. (Fluent API)
90
         */
90
         */
91
        public Dependency autowire(String property, Class<? extends Object> klass, String source);
91
        public Dependency autowire(String property, Class<? extends Object> klass, String source);
92
       
92
       
93
        /**
93
        /**
94
         * Same as {@link #autowire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,
94
         * Same as {@link #autowire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,
95
         * the property name is the same as the bean name that will be injected as the dependency.
95
         * the property name is the same as the bean name that will be injected as the dependency.
96
         *
96
         *
97
         * @param property
97
         * @param property
98
         * @param klass
98
         * @param klass
99
         * @return The container itself. (Fluent API)
99
         * @return The container itself. (Fluent API)
100
         */
100
         */
101
        public Dependency autowire(String property, Class<? extends Object> klass);
101
        public Dependency autowire(String property, Class<? extends Object> klass);
102
       
102
       
103
        /**
103
        /**
104
         * Setup a dependency.
104
         * Setup a dependency.
105
         *
105
         *
106
         * @param dependency The dependency to setup
106
         * @param dependency The dependency to setup
107
         * @return The dependency itself. (Fluent API)
107
         * @return The dependency itself. (Fluent API)
108
         * @see Dependency
108
         * @see Dependency
109
         */
109
         */
110
        public Dependency autowire(Dependency dependency);
110
        public Dependency autowire(Dependency dependency);
111
       
111
       
112
        /**
112
        /**
113
         * Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.
113
         * Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.
114
         * You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting
114
         * You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting
115
         * in the given bean, in other words, populating it.
115
         * in the given bean, in other words, populating it.
116
         *
116
         *
117
         * @param bean The bean to be populated with other beans from the container.
117
         * @param bean The bean to be populated with other beans from the container.
118
         * @return The container itself. (Fluent API)
118
         * @return The container itself. (Fluent API)
119
         */
119
         */
120
        public Container populate(Object bean);
120
        public Container populate(Object bean);
121
       
121
       
122
        /**
122
        /**
123
         * Check whether the container currently has a value for this key. For example,
123
         * Check whether the container currently has a value for this key. For example,
124
         * if it is a singleton AND someone has requested it, the container will have it cached.
124
         * if it is a singleton AND someone has requested it, the container will have it cached.
125
         * The method is useful to check for an instance without forcing her creation.
125
         * The method is useful to check for an instance without forcing her creation.
126
         *
126
         *
127
         * @param key The key representing the bean inside the container.
127
         * @param key The key representing the bean inside the container.
128
         * @return true if the container has an instance cached in the scope for this key
128
         * @return true if the container has an instance cached in the scope for this key
129
         */
129
         */
130
        public boolean check(String key);
130
        public boolean check(String key);
131
       
131
       
132
        /**
132
        /**
133
         * Clear all cached instances for that scope. If you have a thread pool for example you will
133
         * Clear all cached instances for that scope. If you have a thread pool for example you will
134
         * have to clear the THREAD scope when your thread is returned to the pool.
-
 
-
 
134
         * have to clear the THREAD scope when your thread is returned to the pool. It does not make
-
 
135
         * sense to clear a NONE scope (the method returns doing nothing).
135
         *
136
         *
136
         * @param scope The scope to be cleared.
137
         * @param scope The scope to be cleared.
137
         */
138
         */
138
        public void clear(Scope scope);
139
        public void clear(Scope scope);
139
       
140
       
140
        /**
141
        /**
141
         * Clear a single key from cache and return the instance that was cached.
142
         * Clear a single key from cache and return the instance that was cached.
142
         *
143
         *
143
         * @param key The key representing the bean inside the container.
144
         * @param key The key representing the bean inside the container.
144
         * @return The value that was cached and it is not anymore (was cleared)
-
 
-
 
145
         * @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared
145
         */
146
         */
146
        public <T> T clear(String key);
147
        public <T> T clear(String key);
147
}
148
}
148
 
149