001    package org.apache.turbine.services;
002    
003    
004    /*
005     * Licensed to the Apache Software Foundation (ASF) under one
006     * or more contributor license agreements.  See the NOTICE file
007     * distributed with this work for additional information
008     * regarding copyright ownership.  The ASF licenses this file
009     * to you under the Apache License, Version 2.0 (the
010     * "License"); you may not use this file except in compliance
011     * with the License.  You may obtain a copy of the License at
012     *
013     *   http://www.apache.org/licenses/LICENSE-2.0
014     *
015     * Unless required by applicable law or agreed to in writing,
016     * software distributed under the License is distributed on an
017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
018     * KIND, either express or implied.  See the License for the
019     * specific language governing permissions and limitations
020     * under the License.
021     */
022    
023    
024    /**
025     * Classes that implement this interface can act as a broker for
026     * <code>Initable</code> classes.
027     *
028     * Functionality provided by the broker includes:
029     *
030     * <ul>
031     *
032     * <li>Maintaining a single instance of each <code>Initable</code> in
033     * the system.</li>
034     *
035     * <li>Early initialization of <code>Initables</code> during system
036     * startup.</li>
037     *
038     * <li>Late initialization of <code>Initables</code> before they are
039     * used.</li>
040     *
041     * <li>Providing instances of <code>Initables</code> to requesting
042     * parties.</li>
043     *
044     * <li>Maintainging dependencies between <code>Initables</code> during
045     * early initalization phases, including circular dependencies
046     * detection.</li>
047     *
048     * </ul>
049     *
050     * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
051     * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
052     * @version $Id: InitableBroker.java 615328 2008-01-25 20:25:05Z tv $
053     */
054    public interface InitableBroker
055    {
056        /**
057         * Performs early initialization of an Initable class.
058         *
059         * If your class depends on another Initable being initialized to
060         * perform early initialization, you should always ask your broker
061         * to initialize the other class with the objects that are passed
062         * to you, before you try to retrieve that Initable's instance with
063         * getInitable().
064         *
065         * @param className The name of the class to be initailized.
066         * @param data An object to be used for initialization activities.
067         * @exception InitializationException if initialization of this
068         * class was not successful.
069         */
070        void initClass(String className, Object data)
071                throws InitializationException;
072    
073        /**
074         * Shutdowns an Initable class.
075         *
076         * This method is used to release resources allocated by an
077         * Initable class, and return it to initial (uninitailized)
078         * state.
079         *
080         * @param className The name of the class to be uninitialized.
081         */
082        void shutdownClass(String className);
083    
084        /**
085         * Provides an instance of Initable class ready to work.
086         *
087         * If the requested class couldn't be instatiated or initialized,
088         * InstantiationException will be thrown.  You needn't handle this
089         * exception in your code, since it indicates fatal
090         * misconfigurtion of the system.
091         *
092         * @param className The name of the Initable requested.
093         * @return An instance of requested Initable.
094         * @exception InstantiationException if there was a problem
095         * during instantiation or initialization of the Initable.
096         */
097        Initable getInitable(String className) throws InstantiationException;
098    }