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