1 package org.apache.turbine.services;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19 /***
20 * Classes that implement this interface can act as a broker for
21 * <code>Initable</code> classes.
22 *
23 * Functionality provided by the broker includes:
24 *
25 * <ul>
26 *
27 * <li>Maintaining a single instance of each <code>Initable</code> in
28 * the system.</li>
29 *
30 * <li>Early initialization of <code>Initables</code> during system
31 * startup.</li>
32 *
33 * <li>Late initialization of <code>Initables</code> before they are
34 * used.</li>
35 *
36 * <li>Providing instances of <code>Initables</code> to requesting
37 * parties.</li>
38 *
39 * <li>Maintainging dependencies between <code>Initables</code> during
40 * early initalization phases, including circular dependencies
41 * detection.</li>
42 *
43 * </ul>
44 *
45 * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
46 * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
47 * @version $Id: InitableBroker.java 264148 2005-08-29 14:21:04Z henning $
48 */
49 public interface InitableBroker
50 {
51 /***
52 * Performs early initialization of an Initable class.
53 *
54 * If your class depends on another Initable being initialized to
55 * perform early initialization, you should always ask your broker
56 * to initialize the other class with the objects that are passed
57 * to you, before you try to retrieve that Initable's instance with
58 * getInitable().
59 *
60 * @param className The name of the class to be initailized.
61 * @param data An object to be used for initialization activities.
62 * @exception InitializationException if initialization of this
63 * class was not successful.
64 */
65 void initClass(String className, Object data)
66 throws InitializationException;
67
68 /***
69 * Shutdowns an Initable class.
70 *
71 * This method is used to release resources allocated by an
72 * Initable class, and return it to initial (uninitailized)
73 * state.
74 *
75 * @param className The name of the class to be uninitialized.
76 */
77 void shutdownClass(String className);
78
79 /***
80 * Provides an instance of Initable class ready to work.
81 *
82 * If the requested class couldn't be instatiated or initialized,
83 * InstantiationException will be thrown. You needn't handle this
84 * exception in your code, since it indicates fatal
85 * misconfigurtion of the system.
86 *
87 * @param className The name of the Initable requested.
88 * @return An instance of requested Initable.
89 * @exception InstantiationException if there was a problem
90 * during instantiation or initialization of the Initable.
91 */
92 Initable getInitable(String className) throws InstantiationException;
93 }