MentaContainer

Rev

Rev 141 | Rev 143 | 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
/**
108 soliveira 5
 * A IoC container that provides:
2 soliveira 6
 * <ul>
108 soliveira 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>
110 soliveira 17
 * <li>Interceptors for factories: onCreated, onCleared, useful for object pooling</li>
2 soliveira 18
 * </ul>
19
 *
20
 * @author sergio.oliveira.jr@gmail.com
21
 *
22
 */
23
public interface Container {
24
 
25
        /**
108 soliveira 26
         * Get an instance from the container by using the associated factory.
2 soliveira 27
         *
108 soliveira 28
         * The instance will be fully initialized (through constructor and/or setters) and fully wired (all dependencies will be resolved).
2 soliveira 29
         *
108 soliveira 30
         * @param key The key representing the factory to use. The name of the bean in the container.
2 soliveira 31
         * @return The fully initialized and wired bean.
32
         */
135 soliveira 33
        public <T> T get(Object key);
2 soliveira 34
 
108 soliveira 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
         */
141 soliveira 41
        public Class<?> getType(Object key);
91 soliveira 42
 
2 soliveira 43
        /**
44
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
108 soliveira 45
         * An internal factory will be used.
2 soliveira 46
         *
47
         * @param key The key representing the bean to return. The name of the bean in the container.
48
         * @param klass The class used to instantiate the bean, in other words, its implementation.
95 soliveira 49
         * @param scope The scope of the factory.
108 soliveira 50
         * @return The factory created as a ConfigurableFactory. (Fluent API)
57 soliveira 51
         * @see Scope
2 soliveira 52
         */
141 soliveira 53
        public <T> ConfigurableFactory<T> ioc(Object key, Class<T> klass, Scope scope);
2 soliveira 54
 
55
        /**
57 soliveira 56
         * Same as {@link #ioc(String, Class, Scope)} except that it assumes
57
         * there is no scope (Scope.NONE).
2 soliveira 58
         *
59
         * @param key
60
         * @param klass
108 soliveira 61
         * @return The factory created as a ConfigurableFactory. (Fluent API)
57 soliveira 62
         * @see Scope
2 soliveira 63
         */
141 soliveira 64
        public <T> ConfigurableFactory<T> ioc(Object key, Class<T> klass);
2 soliveira 65
 
66
        /**
108 soliveira 67
         * Set up a factory for the given key. The scope assumed is NONE.
2 soliveira 68
         *
39 soliveira 69
         * @param key The key representing the bean to return. The name of the bean in the container.
95 soliveira 70
         * @param factory The factory for the IoC.
108 soliveira 71
         * @return The factory passed as a parameter. (Fluent API)
88 soliveira 72
         * @see Factory
20 soliveira 73
         */
142 soliveira 74
        public <T> Creator<T> ioc(Object key, Creator<T> factory);
20 soliveira 75
 
76
        /**
142 soliveira 77
         * Set up a pool for the given key. The scope assumed is NONE.
78
         *
79
         * @param key The key representing the bean to return. The name of the bean in the container.
80
         * @param pool The pool for the IoC.
81
         * @return The factory passed as a parameter. (Fluent API)
82
         * @see Pool
83
         */
84
        public <T> Pool<T> ioc(Object key, Pool<T> pool);
85
 
86
        /**
108 soliveira 87
         * Set up a factory for the given key in the given scope.
51 soliveira 88
         *
89
         * @param key The key representing the bean to return. The name of the bean in the container.
95 soliveira 90
         * @param factory The factory for the IoC.
91
         * @param scope The scope used by the factory.
108 soliveira 92
         * @return The factory passed as a parameter (Fluent API).
88 soliveira 93
         * @see Factory
57 soliveira 94
         * @see Scope
51 soliveira 95
         */
141 soliveira 96
        public <T> Creator<T> ioc(Object key, Creator<T> factory, Scope scope);
51 soliveira 97
 
98
        /**
142 soliveira 99
         * Set up a pool for the given key in the given scope.
100
         *
101
         * @param key The key representing the bean to return. The name of the bean in the container.
102
         * @param pool The pool for the IoC.
103
         * @param scope The scope used by the factory.
104
         * @return The factory passed as a parameter (Fluent API).
105
         * @see Pool
106
         * @see Scope
107
         */
108
        public <T> Pool<T> ioc(Object key, Pool<T> pool, Scope scope);
109
 
110
        /**
108 soliveira 111
         * Configure a bean dependency to be auto-wired by the container.
112
         * 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.
20 soliveira 113
         *
108 soliveira 114
         * @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
2 soliveira 115
         */
135 soliveira 116
        public void autowire(Object sourceFromContainer);
2 soliveira 117
 
108 soliveira 118
        /**
119
         * Configure a bean dependency to be auto-wired by the container.
120
         * 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.
121
         *
122
         * @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it.
123
         * @param property The name of the property to inject, whey trying auto-wiring by setter.
124
         */
135 soliveira 125
        public void autowire(Object sourceFromContainer, String property);
2 soliveira 126
 
127
        /**
108 soliveira 128
         * Take a given bean and populate its properties with other beans coming from this container.
129
         * You basically checking properties of the given bean and looking for values inside the container.
130
         * And injecting in the given bean, in other words, populating it.
2 soliveira 131
         *
132
         * @param bean The bean to be populated with other beans from the container.
133
         */
103 soliveira 134
        public void inject(Object bean);
4 soliveira 135
 
108 soliveira 136
        /**
137
         * Construct an instance using beans from the container. A constructor will be chosen that has arguments that can be found
138
         * inside the container.
139
         *
140
         * @param klass The class that should be instantiated.
141
         * @return An instantiated bean.
142
         */
141 soliveira 143
        public <T> T construct(Class<T> klass);
102 soliveira 144
 
4 soliveira 145
        /**
58 soliveira 146
         * Check whether the container currently has a value for this key. For example,
147
         * if it is a singleton AND someone has requested it, the container will have it cached.
148
         * The method is useful to check for an instance without forcing her creation.
4 soliveira 149
         *
150
         * @param key The key representing the bean inside the container.
58 soliveira 151
         * @return true if the container has an instance cached in the scope for this key
4 soliveira 152
         */
135 soliveira 153
        public boolean check(Object key);
57 soliveira 154
 
155
        /**
81 soliveira 156
         * Clear all cached instances for that scope. If you have a thread-pool for example you will
157
         * want to clear the THREAD scope when your thread is returned to the pool. Because you have a thread
158
         * pool you will have the SAME thread handling different requests and each request will need its own instances
159
         * from the container. Therefore, each time you are done with a thread and it is returned to your thread-pool
160
         * you can call clear to release the instances allocated and cached by the container. A web container and/or framework
161
         * can use this feature to implement a REQUEST scope which is nothing more than the THREAD scope with clear. If the web
162
         * container was not using a thread-pool, the THREAD scope would be equal to the REQUEST scope as each request would
163
         * always be handled by a different thread.
164
         *  
165
         * 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 166
         *
167
         * @param scope The scope to be cleared.
168
         */
169
        public void clear(Scope scope);
58 soliveira 170
 
171
        /**
172
         * Clear a single key from cache and return the instance that was cached.
173
         *
174
         * @param key The key representing the bean inside the container.
70 soliveira 175
         * @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared
58 soliveira 176
         */
135 soliveira 177
        public <T> T clear(Object key);
2 soliveira 178
}