Container


1   /*****************************************************************************
2    * Copyright (C) Codehaus.org. All rights reserved.            *
3    * ------------------------------------------------------------------------- *
4    * The software in this package is published under the terms of the BSD      *
5    * style license a copy of which has been included with this distribution in *
6    * the LICENSE.txt file.                                                     *
7    *****************************************************************************/
8   /*
9    * Created on Mar 7, 2005
10   *
11   * Author Ben Yu
12   * ZBS
13   */
14  package jfun.yan;
15  
16  import java.util.List  ;
17  
18  import jfun.yan.factory.Factory;
19  
20  
21  /**
22   * The facade interface which provides the full functionality of yan container.
23   * <p> 
24   * 
25   * Codehaus.org.
26   *
27   * @author Ben Yu
28   *
29   */
30  public interface Container extends Registrar {
31  
32    
33    /**
34     * Instantiate component instance.
35     * The dependencies are resolved in the current container.
36     * @param cc the component to instantiate.
37     * @return the component instance.
38     * @throws AmbiguousComponentResolutionException
39     * if ambiguity happens.
40     * @throws ComponentInstantiationException
41     * wrapper exception for any checked exception thrown out of the actual creation.
42     * @throws CyclicDependencyException
43     * if cyclic dependency is detected.
44     * @throws UnresolvedComponentException
45     * if this component or any dependent component cannot be resolved.
46     * @throws UnsatisfiedComponentException
47     * if some requirement of the component cannot be satisfied.
48     * @throws YanException
49     * for any other exception.
50     */
51    <T> T instantiateComponent(Creator<T> cc)
52    throws AmbiguousComponentResolutionException,
53    ComponentInstantiationException,
54    CyclicDependencyException,
55    UnresolvedComponentException, UnsatisfiedComponentException,
56    YanException;
57    /**
58     * Instantiate component instance.
59     * The dependencies are resolved in the current container.
60     * @param key the key of the component.
61     * @param cc the component to instantiate.
62     * @return the component instance.
63     * @throws AmbiguousComponentResolutionException
64     * if ambiguity happens.
65     * @throws ComponentInstantiationException
66     * wrapper exception for any checked exception thrown out of the actual creation.
67     * @throws CyclicDependencyException
68     * if cyclic dependency is detected.
69     * @throws UnresolvedComponentException
70     * if this component or any dependent component cannot be resolved.
71     * @throws UnsatisfiedComponentException
72     * if some requirement of the component cannot be satisfied.
73     * @throws YanException
74     * for any other exception.
75     */
76    <T> T instantiateComponent(Object   key, Creator<T> cc)
77    throws AmbiguousComponentResolutionException,
78    ComponentInstantiationException,
79    CyclicDependencyException,
80    UnresolvedComponentException, UnsatisfiedComponentException,
81    YanException;
82  
83    
84  
85    /**
86     * Create component instance of the provided type.
87     * @param type the type.
88     * @param cmap the container to resolve dependency.
89     * @return the component instance.
90     * @throws AmbiguousComponentResolutionException
91     * if ambiguity happens.
92     * @throws ComponentInstantiationException
93     * wrapper exception for any checked exception thrown out of the actual creation.
94     * @throws CyclicDependencyException
95     * if cyclic dependency is detected.
96     * @throws UnresolvedComponentException
97     * if this component or any dependent component cannot be resolved.
98     * @throws UnsatisfiedComponentException
99     * if some requirement of the component cannot be satisfied.
100    * @throws YanException
101    * for any other exception.
102    */
103   <T> T getInstanceOfType(Class  <T> type, ComponentMap cmap)
104   throws AmbiguousComponentResolutionException,
105   ComponentInstantiationException,
106   CyclicDependencyException,
107   UnresolvedComponentException, UnsatisfiedComponentException,
108   YanException;
109 
110   /**
111    * Create an instance of {@link Factory} for a component of the provided type.
112    * when {@link Factory#create()} is called, the component is instantiated.
113    * @param type the type.
114    * @param cmap the container to resolve dependency.
115    * @return the factory instance.
116    * @throws AmbiguousComponentResolutionException
117    * if ambiguity happens.
118    * @throws UnresolvedComponentException
119    * if this component cannot be resolved.
120    * @throws YanException
121    * for any other exception.
122    */
123   <T> Factory<T> getFactoryOfType(Class  <T> type, ComponentMap cmap)
124   throws AmbiguousComponentResolutionException,
125   UnresolvedComponentException, YanException;
126   
127 
128   /**
129    * Create component instances of a provided type.
130    * If more than one components are found for the same type,
131    * both are invoked and the results are collected in the list.
132    * @param type the type.
133    * @param cmap the container to resolve dependency.
134    * @return the list containing all the component instances.
135    * @throws ComponentInstantiationException
136    * wrapper exception for any checked exception thrown out of the actual creation.
137    * @throws CyclicDependencyException
138    * if cyclic dependency is detected.
139    * @throws UnresolvedComponentException
140    * if this component or any dependent component cannot be resolved.
141    * @throws UnsatisfiedComponentException
142    * if some requirement of the component cannot be satisfied.
143    * @throws YanException
144    * for any other exception.
145    */
146   <T> List  <T> getInstancesOfType(Class  <T> type, ComponentMap cmap)
147   throws
148   ComponentInstantiationException,
149   CyclicDependencyException,
150   UnresolvedComponentException, UnsatisfiedComponentException,
151   YanException;
152   /**
153    * Create component instance of the provided type.
154    * The dependencies are resolved in the current container.
155    * @param type the type.
156    * @return the component instance.
157    * @throws AmbiguousComponentResolutionException
158    * if ambiguity happens.
159    * @throws ComponentInstantiationException
160    * wrapper exception for any checked exception thrown out of the actual creation.
161    * @throws CyclicDependencyException
162    * if cyclic dependency is detected.
163    * @throws UnresolvedComponentException
164    * if this component or any dependent component cannot be resolved.
165    * @throws UnsatisfiedComponentException
166    * if some requirement of the component cannot be satisfied.
167    * @throws YanException
168    * for any other exception.
169    */
170   <T> T getInstanceOfType(Class  <T> type)
171   throws AmbiguousComponentResolutionException,
172   ComponentInstantiationException,
173   CyclicDependencyException,
174   UnresolvedComponentException, UnsatisfiedComponentException,
175   YanException;
176   
177   /**
178    * Create an instance of {@link Factory} for a component of the provided type.
179    * when {@link Factory#create()} is called, the component is instantiated.
180    * @param type the type.
181    * @return the factory instance.
182    * @throws AmbiguousComponentResolutionException
183    * if ambiguity happens.
184    * @throws UnresolvedComponentException
185    * if this component or any dependent component cannot be resolved.
186    * @throws YanException
187    * for any other exception.
188    */
189   <T> Factory<T> getFactoryOfType(Class  <T> type)
190   throws AmbiguousComponentResolutionException,
191   UnresolvedComponentException, YanException;
192   /**
193    * Create component instances of a provided type.
194    * If more than one components are found for the same type,
195    * both are invoked and the results are collected in the list.
196    * <br>
197    * The dependencies are resolved in the current container.
198    * @param type the type.
199    * @return the list containing all the component instances.
200    * @throws ComponentInstantiationException
201    * wrapper exception for any checked exception thrown out of the actual creation.
202    * @throws CyclicDependencyException
203    * if cyclic dependency is detected.
204    * @throws UnresolvedComponentException
205    * if this component or any dependent component cannot be resolved.
206    * @throws UnsatisfiedComponentException
207    * if some requirement of the component cannot be satisfied.
208    * @throws YanException
209    * for any other exception.
210    */
211   <T> List  <T> getInstancesOfType(Class  <T> type)
212   throws
213   ComponentInstantiationException,
214   CyclicDependencyException,
215   UnresolvedComponentException, UnsatisfiedComponentException,
216   YanException;
217   /**
218    * Create instances of all the components stored in this container.
219    * <br>
220    * The dependencies are resolved in the current container.
221    * @return the list containing all the component instances.
222    * @throws ComponentInstantiationException
223    * wrapper exception for any checked exception thrown out of the actual creation.
224    * @throws CyclicDependencyException
225    * if cyclic dependency is detected.
226    * @throws UnresolvedComponentException
227    * if this component or any dependent component cannot be resolved.
228    * @throws UnsatisfiedComponentException
229    * if some requirement of the component cannot be satisfied.
230    * @throws YanException
231    * for any other exception.
232    */
233   java.util.List   getInstances()
234   throws
235   ComponentInstantiationException,
236   CyclicDependencyException,
237   UnresolvedComponentException, UnsatisfiedComponentException,
238   YanException;
239   
240   /**
241    * Create instances of all the components stored in this container.
242    * The component instances are stored into a java.util.Map object
243    * under the component key.
244    * <br>
245    * The dependencies are resolved in the current container.
246    * @param store the java.util.Map object to save the component instances.
247    * @throws ComponentInstantiationException
248    * wrapper exception for any checked exception thrown out of the actual creation.
249    * @throws CyclicDependencyException
250    * if cyclic dependency is detected.
251    * @throws UnresolvedComponentException
252    * if this component or any dependent component cannot be resolved.
253    * @throws UnsatisfiedComponentException
254    * if some requirement of the component cannot be satisfied.
255    * @throws YanException
256    * for any other exception.
257    */
258   void getInstances(java.util.Map   store)
259   throws
260   ComponentInstantiationException,
261   CyclicDependencyException,
262   UnresolvedComponentException, UnsatisfiedComponentException,
263   YanException;
264   /**
265    * Create instances of all the components stored in this container.
266    * <p>
267    * The dependencies are resolved in the current container.
268    * </p>
269    * @param cmap the container in which to resolve dependency.
270    * @return the list containing all the component instances.
271    * @throws ComponentInstantiationException
272    * wrapper exception for any checked exception thrown out of the actual creation.
273    * @throws CyclicDependencyException
274    * if cyclic dependency is detected.
275    * @throws UnresolvedComponentException
276    * if this component or any dependent component cannot be resolved.
277    * @throws UnsatisfiedComponentException
278    * if some requirement of the component cannot be satisfied.
279    * @throws YanException
280    * for any other exception.
281    */
282   java.util.List   getInstances(ComponentMap cmap)
283   throws
284   ComponentInstantiationException,
285   CyclicDependencyException,
286   UnresolvedComponentException, UnsatisfiedComponentException,
287   YanException;
288 
289   /**
290    * Create instances of all the components stored in this container.
291    * The component instances are stored into a java.util.Map object
292    * under the component key.
293    * <p>
294    * The dependencies are resolved in the current container.
295    * </p>
296    * @param store the java.util.Map object to save the component instances.
297    * @param cmap the container in which to resolve dependency.
298    * @throws ComponentInstantiationException
299    * wrapper exception for any checked exception thrown out of the actual creation.
300    * @throws CyclicDependencyException
301    * if cyclic dependency is detected.
302    * @throws UnresolvedComponentException
303    * if this component or any dependent component cannot be resolved.
304    * @throws UnsatisfiedComponentException
305    * if some requirement of the component cannot be satisfied.
306    * @throws YanException
307    * for any other exception.
308    */
309   void getInstances(java.util.Map   store, ComponentMap cmap)
310   throws
311   ComponentInstantiationException,
312   CyclicDependencyException,
313   UnresolvedComponentException, UnsatisfiedComponentException,
314   YanException;
315 
316   /**
317    * Get the dependency for a component key.
318    * 
319    * @param key the component key.
320    * @return the Dependency object.
321    */
322   Dependency getDependency(Object   key);
323 
324   /**
325    * Get the dependency for a component type.
326    * @param type the component type.
327    * @return the Dependency object.
328    */
329   Dependency getDependencyOfType(Class   type);
330 
331 
332   /**
333    * Verifies the components in this container.
334    * Dependencies are resolved in the current container.
335    * @throws AmbiguousComponentResolutionException
336    * if ambiguity happens.
337    * @throws CyclicDependencyException
338    * if cyclic dependency is detected.
339    * @throws UnresolvedComponentException
340    * if any component cannot be resolved.
341    * @throws UnsatisfiedComponentException
342    * if some requirement of a component cannot be satisfied.
343    * @throws YanException
344    * for any other exception.
345    */
346   void verify()
347   throws AmbiguousComponentResolutionException,
348   CyclicDependencyException,
349   UnresolvedComponentException, UnsatisfiedComponentException,
350   YanException;
351 
352   /**
353    * Verifies that a Component is valid using the current container
354    * in resolving dependency.
355    * @param cc the component to verify.
356    * @return the type of the component.
357    * @throws AmbiguousComponentResolutionException
358    * if ambiguity happens.
359    * @throws CyclicDependencyException
360    * if cyclic dependency is detected.
361    * @throws UnsatisfiedComponentException
362    * if some requirement of a component cannot be satisfied.
363    * @throws YanException
364    * for any other exception.
365    */
366   Class   verifyComponent(Component cc)
367   throws AmbiguousComponentResolutionException,
368   CyclicDependencyException,
369   UnsatisfiedComponentException,
370   YanException;
371   
372   /**
373    * Verifies a component identified by key.
374    * @param key the component key.
375    * @return the component type.
376    * @throws CyclicDependencyException
377    * if cyclic dependency is detected.
378    * @throws UnresolvedComponentException
379    * if the component cannot be resolved.
380    * @throws UnsatisfiedComponentException
381    * if some requirement of the component cannot be satisfied.
382    * @throws YanException
383    * for any other exception.
384    */
385   Class   verifyKey(Object   key)
386   throws
387   CyclicDependencyException,
388   UnresolvedComponentException, UnsatisfiedComponentException,
389   YanException;
390   
391   
392   /**
393    * Verifies a component for a type.
394    * @param type the component type.
395    * @return the component type.
396    * @throws AmbiguousComponentResolutionException
397    * if ambiguity happens.
398    * @throws CyclicDependencyException
399    * if cyclic dependency is detected.
400    * @throws UnresolvedComponentException
401    * if the component cannot be resolved.
402    * @throws UnsatisfiedComponentException
403    * if some requirement of the component cannot be satisfied.
404    * @throws YanException
405    * for any other exception.
406    */
407   Class   verifyType(Class   type)
408   throws AmbiguousComponentResolutionException,
409   CyclicDependencyException,
410   UnsatisfiedComponentException,
411   YanException;
412   
413   /**
414    * Get the type of a component identified by a key.
415    * @param key the component key.
416    * @return the type of the component or null if not found.
417    */
418   Class   getComponentType(Object   key);
419   /**
420    * Create instance for a component identified by a key.
421    * @param key the component key.
422    * @param cmap the container to resolve dependency.
423    * @return the component instance.
424    * @throws ComponentInstantiationException
425    * wrapper exception for any checked exception thrown out of the actual creation.
426    * @throws CyclicDependencyException
427    * if cyclic dependency is detected.
428    * @throws UnresolvedComponentException
429    * if this component or any dependent component cannot be resolved.
430    * @throws UnsatisfiedComponentException
431    * if some requirement of the component cannot be satisfied.
432    * @throws YanException
433    * for any other exception.
434    */
435   Object   getInstance(Object   key, ComponentMap cmap)
436   throws
437   ComponentInstantiationException,
438   CyclicDependencyException,
439   UnresolvedComponentException, UnsatisfiedComponentException,
440   YanException;
441 
442   /**
443    * Create an instance of {@link Factory} for a component identified by a key.
444    * when {@link Factory#create()} is called, the component is instantiated.
445    * @param key the component key.
446    * @param cmap the container to resolve dependency.
447    * @return the factory instance.
448    * @throws UnresolvedComponentException
449    * if this component cannot be resolved.
450    * @throws YanException
451    * for any other exception.
452    */
453   Factory getFactory(Object   key, ComponentMap cmap)
454   throws UnresolvedComponentException, YanException;
455   /**
456    * Create instance for a component identified by a key.
457    * Dependencies are resolved in the current container.
458    * @param key the component key.
459    * @return the component instance.
460    * @throws ComponentInstantiationException
461    * wrapper exception for any checked exception thrown out of the actual creation.
462    * @throws CyclicDependencyException
463    * if cyclic dependency is detected.
464    * @throws UnresolvedComponentException
465    * if this component or any dependent component cannot be resolved.
466    * @throws UnsatisfiedComponentException
467    * if some requirement of the component cannot be satisfied.
468    * @throws YanException
469    * for any other exception.
470    */
471   Object   getInstance(Object   key)throws
472   ComponentInstantiationException,
473   CyclicDependencyException,
474   UnresolvedComponentException, UnsatisfiedComponentException,
475   YanException;
476   /**
477    * Create an instance of {@link Factory} for a component identified by a key.
478    * when {@link Factory#create()} is called, the component is instantiated.
479    * @param key the component key.
480    * @return the factory instance.
481    * @throws UnresolvedComponentException
482    * if this component cannot be resolved.
483    * @throws YanException
484    * for any other exception.
485    */
486   Factory getFactory(Object   key)
487   throws UnresolvedComponentException, YanException;
488   /**
489    * Register a value in the container.
490    * @param key the key of the value.
491    * @param v the value.
492    */
493   void registerValue(Object   key, Object   v);
494 
495   /**
496    * Register a value in the container.
497    * Equivalent as registerValue(v.getClass(), v).
498    * @param v the value.
499    */
500   void registerValue(Object   v);
501 
502   /**
503    * Register a Component object in the container.
504    * Equivalent as registerComponent(cc.getType(), cc).
505    * cc.getType() is not allowed to return null.
506    * @param cc the component.
507    * @throws UnknownComponentTypeException if cc.getType() == null.
508    */
509   void registerComponent(Component cc)
510   throws UnknownComponentTypeException;
511   
512   /**
513    * Register a constructor in the container.
514    * Equivalent as registerConstructor(c, c).
515    * 
516    * @param c the class containing the constructor.
517    */
518   void registerConstructor(Class   c);
519   /**
520    * Register a constructor in the container.
521    * Equivalent as registerComponent(key, Components.ctor(c)).
522    * @param key the component key.
523    * @param c the class containing the constructor.
524    */
525   void registerConstructor(Object   key, Class   c);
526   /**
527    * Register a constructor in the container.
528    * Equivalent as registerConstructor(c, c, param_types).
529    * @param c the class containing the constructor.
530    * @param param_types the parameter types of the constructor.
531    */
532   void registerConstructor(Class   c, Class  [] param_types);
533   /**
534    * Register a constructor in the container.
535    * Equivalent as registerComponent(key, Components.ctor(c, param_types)).
536    * @param key the component key.
537    * @param c the class containing the constructor.
538    * @param param_types the parameter types of the constructor.
539    */
540   void registerConstructor(Object   key, Class   c,
541       Class  [] param_types);
542 
543   /**
544    * Register a component that uses a static method to create component instance.
545    * Equivalent as registerComponent(Components.static_method(c, name)).
546    * @param c the class containing the static method.
547    * @param name the method name.
548    */
549   void registerStaticMethod(Class   c, String   name);
550   /**
551    * Register a component that uses a static method to create component instance.
552    * Equivalent as registerComponent(key, Components.static_method(c, name)).
553    * @param key the component key.
554    * @param c the class containing the static method.
555    * @param name the method name.
556    */
557   void registerStaticMethod(Object   key, Class   c, String   name);
558   /**
559    * Register a component that uses a static method to create component instance.
560    * Equivalent as registerComponent(Components.static_method(c, name, param_types));
561    * @param c the class containing the static method.
562    * @param name the method name.
563    */
564   void registerStaticMethod(Class   c, String   name,
565       Class  [] param_types);
566   /**
567    * Register a component that uses a static method to create component instance.
568    * Equivalent as registerComponent(key, Components.static_method(c, name, param_types)).
569    * @param key the component key.
570    * @param c the class containing the static method.
571    * @param name the method name.
572    * @param param_types the parameter types.
573    */
574   void registerStaticMethod(Object   key, Class   c, String   name,
575       Class  [] param_types);
576 
577   /**
578    * Create a new Container object which represents
579    * "this inherits parent" relationship.
580    * In this new Container, components in the child container
581    * are invisible to the ones in the parent container; while components
582    * in the parent container are visible to the ones in the child container.
583    * 
584    * @param parent the parent registrar.
585    * @return the new Container.
586    */
587   Container inherit(Registrar parent);
588 
589 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags