View Javadoc

1   package org.apache.turbine.services;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
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  }