1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20 package net.mchaplin.ioc;
21
22 import java.util.List;
23 import java.util.Map;
24
25 import net.mchaplin.ioc.component.ComponentFactoryI;
26 import net.mchaplin.ioc.component.ComponentI;
27 import net.mchaplin.ioc.exp.ContainerException;
28
29 /***
30 * Container interface. Components can be
31 * registered & retrieved from a Container,
32 * which manages instances lookup & lifecycle
33 *
34 * @see net.mchaplin.ioc.DefaultContainer
35 *
36 * @author mchaplin@users.sourceforge.net
37 *
38 * $Header:
39 * $Revision:
40 * $Date:
41 *
42 */
43 public interface ContainerI extends ComponentI {
44
45 /***
46 * Register a Component into the Container
47 *
48 * @param component the component to register
49 */
50 void registerComponentImplementation(Class component);
51
52 /***
53 * Register a Factory for later use.
54 *
55 * @param factory the factory to register
56 */
57 void registerFactoryImplementation(Class factory);
58
59 /***
60 * Component registration. Will try a newInstance() call on it &
61 * register if not already present.
62 *
63 * @param component the component Class to register
64 * @param simple if true, will try a newInstance() call only. Otherwise, will
65 * introspect potential constructors for already known components
66 * & try to instanciate through reflection
67 * @param type optional, the type to register this instance as. If set, the
68 * Component will be registered under its fully qualified class
69 * name
70 */
71 void registerComponentImplementation(Class component, String type);
72
73 /***
74 * Custom component registration. The factory will be instanciated through a
75 * Factory() Constructor. The component will then be instanciated
76 * through the Factory.retrieveInstance() method
77 *
78 * @param component the component to register
79 * @param factory the factory to register
80 *
81 * @see net.mchaplin.ioc.ContainerI#registerComponentImplementation(java.lang.Class,
82 * java.lang.Class)
83 */
84 void registerComponentImplementation(Class component, Class factory) throws ContainerException;
85
86 /***
87 * Custom component registration. The factory will be instanciated through a
88 * Factory() Constructor. The component will then be instanciated
89 * through the Factory.retrieveInstance() method
90 *
91 * @param component the component to register
92 * @param factory the factory to register
93 * @param type the type to register this instance as. If set, the
94 * Component will be registered under its fully qualified class
95 * name
96 * @throws ContainerException
97 *
98 * @see net.mchaplin.ioc.ContainerI#registerComponentImplementation(java.lang.Class,
99 * java.lang.Class)
100 */
101 void registerComponentImplementation(Class component, Class factory, String type) throws ContainerException;
102
103 void registerComponentInstance(ComponentI instance);
104
105 void registerComponentInstance(ComponentI instance, String key);
106
107 /***
108 * Lookup for to see if a given component is currently registered in this
109 * Container, its parent or sons. Use if you have no knowledge of where the
110 * component is located
111 *
112 * @param classType
113 * the Class type to lookup for.
114 * @return the name of the container where a Component instance has been
115 * found or null.
116 */
117 String lookupComponent(Class classType);
118
119 /***
120 * Lookup for to see if a given component is currently registered.
121 *
122 *
123 * @param classType the Class type to lookup for.
124 * @param where where to lookup the component : here, parent or sons
125 *
126 * @return the name of the container where a Component instance has been
127 * found or null.
128 */
129 String lookupComponent(Class classType, int where);
130
131 /***
132 * Retrieve the first instance in List of given type.
133 *
134 * @param classType the Class type to retrieve an instance of.
135 * @return an instance of ComponentI, whose Class match classType
136 */
137 ComponentI retrieveComponentInstance(Class classType);
138
139 /***
140 * Retrieve the first instance in List of given type.
141 *
142 * @param key the component type to retrieve an instance of
143 * @return an instance of ComponentI, whose full name match key
144 */
145 ComponentI retrieveComponentInstance(String key);
146
147 /***
148 * Retrieve the first instance in List of given type.
149 *
150 * @param key the component type to retrieve an instance of
151 * @param location the location of the container where the component
152 * should be retrieved from.
153 * @return an instance of ComponentI, whose full name match key
154 */
155 ComponentI retrieveComponentInstance(String key, String location);
156
157 /***
158 * Retrieve the first instance in List of given type.
159 *
160 * @param classType the Class type to retrieve an instance of.
161 * @return an instance of ComponentI, whose Class match classType
162 */
163 ComponentFactoryI retrieveFactoryInstance(Class classType);
164
165 /***
166 * Retrieve the first instance in List of given type.
167 *
168 * @param key the key to retrieve associated Factory instance.
169 * @return an instance of ComponentI, whose full name match key
170 */
171 ComponentFactoryI retrieveFactoryInstance(String key);
172
173 /***
174 * Retrieve a list of registered components for the given key
175 *
176 */
177 List retrieveComponentInstances(String key);
178
179 /***
180 * Retrieve a list of all registered components
181 *
182 */
183 void retrieveComponentInstances();
184
185 /***
186 * Gives back a Component when you stop using it. TODO : manage component
187 * lock/unlock mode
188 *
189 */
190 void makeComponentAvailable();
191
192 void unregisterComponentInstance(ComponentI instance);
193
194 /***
195 * Return the current state of a Container instance, as formatted text.
196 *
197 * @return the current Container State as formatted text.
198 */
199 String getState();
200
201 /***
202 * @see net.mchaplin.ioc.ContainerI#setParent(net.mchaplin.ioc.ContainerI)
203 */
204 void setParent(ContainerI aParent);
205
206 /***
207 * @return Returns the instanceName.
208 */
209 String getInstanceName();
210
211 /***
212 * @param instanceName
213 * The instanceName to set.
214 */
215 void setInstanceName(String instanceName);
216
217 /***
218 * @see net.mchaplin.ioc.ContainerI#getParent()
219 */
220 ContainerI getParent();
221
222 /***
223 * @return Returns the registeredTypes.
224 */
225 Map<String,List<ComponentI>> getRegisteredTypes();
226
227 /***
228 * @return Returns the sons.
229 */
230 ContainerI[] getSons();
231
232 /***
233 * @return Returns the sons.
234 */
235 void addSon(ContainerI container);
236
237 /***
238 * @see net.mchaplin.ioc.ComponentI#getContainer()
239 */
240 ContainerI getContainer();
241
242 /***
243 * @see net.mchaplin.ioc.ComponentI#reset()
244 */
245 void reset();
246 }