1 package org.apache.turbine.services;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 /**
25 * Classes that implement this interface can act as a broker for
26 * <code>Initable</code> classes.
27 *
28 * Functionality provided by the broker includes:
29 *
30 * <ul>
31 *
32 * <li>Maintaining a single instance of each <code>Initable</code> in
33 * the system.</li>
34 *
35 * <li>Early initialization of <code>Initables</code> during system
36 * startup.</li>
37 *
38 * <li>Late initialization of <code>Initables</code> before they are
39 * used.</li>
40 *
41 * <li>Providing instances of <code>Initables</code> to requesting
42 * parties.</li>
43 *
44 * <li>Maintaining dependencies between <code>Initables</code> during
45 * early initialization phases, including circular dependencies
46 * detection.</li>
47 *
48 * </ul>
49 *
50 * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
51 * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
52 * @version $Id$
53 */
54 public interface InitableBroker
55 {
56 /**
57 * Performs early initialization of an Initable class.
58 *
59 * If your class depends on another Initable being initialized to
60 * perform early initialization, you should always ask your broker
61 * to initialize the other class with the objects that are passed
62 * to you, before you try to retrieve that Initable's instance with
63 * getInitable().
64 *
65 * @param className The name of the class to be initialized.
66 * @param data An object to be used for initialization activities.
67 * @throws InitializationException if initialization of this
68 * class was not successful.
69 */
70 void initClass(String className, Object data)
71 throws InitializationException;
72
73 /**
74 * Shutdowns an Initable class.
75 *
76 * This method is used to release resources allocated by an
77 * Initable class, and return it to initial (uninitialized)
78 * state.
79 *
80 * @param className The name of the class to be uninitialized.
81 */
82 void shutdownClass(String className);
83
84 /**
85 * Provides an instance of Initable class ready to work.
86 *
87 * If the requested class couldn't be instatiated or initialized,
88 * InstantiationException will be thrown. You needn't handle this
89 * exception in your code, since it indicates fatal
90 * misconfigurtion of the system.
91 *
92 * @param className The name of the Initable requested.
93 * @return An instance of requested Initable.
94 * @throws InstantiationException if there was a problem
95 * during instantiation or initialization of the Initable.
96 */
97 Initable getInitable(String className) throws InstantiationException;
98 }