Rev 91 | Rev 94 | Go to most recent revision | Only display areas with differences | Ignore 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 |