Rev 146 | 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 | */ |
||
148 | 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 | */ |
148 | soliveira | 53 | public ConfigurableFactory ioc(Object key, Class<?> 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 | */ |
146 | soliveira | 64 | public ConfigurableFactory ioc(Object key, Class<?extends Object> 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 | */ |
146 | soliveira | 74 | public Factory ioc(Object key, Factory factory); |
20 | soliveira | 75 | |
76 | /** |
||
108 | soliveira | 77 | * Set up a factory for the given key in the given scope. |
51 | soliveira | 78 | * |
79 | * @param key The key representing the bean to return. The name of the bean in the container. |
||
95 | soliveira | 80 | * @param factory The factory for the IoC. |
81 | * @param scope The scope used by the factory. |
||
108 | soliveira | 82 | * @return The factory passed as a parameter (Fluent API). |
88 | soliveira | 83 | * @see Factory |
57 | soliveira | 84 | * @see Scope |
51 | soliveira | 85 | */ |
146 | soliveira | 86 | public Factory ioc(Object key, Factory factory, Scope scope); |
51 | soliveira | 87 | |
88 | /** |
||
108 | soliveira | 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. |
||
20 | soliveira | 91 | * |
108 | soliveira | 92 | * @param sourceFromContainer The bean inside the container that will be wired automatically inside any other bean the depends on it. |
2 | soliveira | 93 | */ |
135 | soliveira | 94 | public void autowire(Object sourceFromContainer); |
2 | soliveira | 95 | |
108 | soliveira | 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 | */ |
||
135 | soliveira | 103 | public void autowire(Object sourceFromContainer, String property); |
2 | soliveira | 104 | |
105 | /** |
||
108 | soliveira | 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. |
||
2 | soliveira | 109 | * |
110 | * @param bean The bean to be populated with other beans from the container. |
||
111 | */ |
||
103 | soliveira | 112 | public void inject(Object bean); |
4 | soliveira | 113 | |
108 | soliveira | 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 | */ |
||
148 | soliveira | 121 | public <T> T construct(Class<?> klass); |
102 | soliveira | 122 | |
4 | soliveira | 123 | /** |
58 | soliveira | 124 | * Check whether the container currently has a value for this key. For example, |
125 | * if it is a singleton AND someone has requested it, the container will have it cached. |
||
126 | * The method is useful to check for an instance without forcing her creation. |
||
4 | soliveira | 127 | * |
128 | * @param key The key representing the bean inside the container. |
||
58 | soliveira | 129 | * @return true if the container has an instance cached in the scope for this key |
4 | soliveira | 130 | */ |
135 | soliveira | 131 | public boolean check(Object key); |
57 | soliveira | 132 | |
133 | /** |
||
81 | soliveira | 134 | * Clear all cached instances for that scope. If you have a thread-pool for example you will |
135 | * want to clear the THREAD scope when your thread is returned to the pool. Because you have a thread |
||
136 | * pool you will have the SAME thread handling different requests and each request will need its own instances |
||
137 | * from the container. Therefore, each time you are done with a thread and it is returned to your thread-pool |
||
138 | * you can call clear to release the instances allocated and cached by the container. A web container and/or framework |
||
139 | * can use this feature to implement a REQUEST scope which is nothing more than the THREAD scope with clear. If the web |
||
140 | * container was not using a thread-pool, the THREAD scope would be equal to the REQUEST scope as each request would |
||
141 | * always be handled by a different thread. |
||
142 | * |
||
143 | * 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 | 144 | * |
145 | * @param scope The scope to be cleared. |
||
146 | */ |
||
147 | public void clear(Scope scope); |
||
58 | soliveira | 148 | |
149 | /** |
||
150 | * Clear a single key from cache and return the instance that was cached. |
||
151 | * |
||
152 | * @param key The key representing the bean inside the container. |
||
70 | soliveira | 153 | * @return The value that was cached and it is not anymore (was cleared) or null if nothing was cleared |
58 | soliveira | 154 | */ |
135 | soliveira | 155 | public <T> T clear(Object key); |
2 | soliveira | 156 | } |