MentaContainer

Rev

Rev 95 | Rev 101 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

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