    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 need initialization before
    026     * they can work.
    027     *
    028     * These classes rely also on an <code>InitableBroker</code> that
    029     * ensures that there is only one instance of the class in the system,
    030     * and handles dependencies between <code>Initables</code>.
    031     *
    032     * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
    033     * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
    034     * @version $Id: Initable.java 615328 2008-01-25 20:25:05Z tv $
    035     */
    036    public interface Initable
    037    {
    038        /**
    039         * Provides an Initable with a reference to the InitableBroker
    040         * that instantiated this object, so that it can access other
    041         * Initables.
    042         *
    043         * @param broker The InitableBroker that instantiated this object.
    044         */
    045        void setInitableBroker(InitableBroker broker);
    046
    047        /**
    048         * Performs early initailization of an Initable
    049         *
    050         * During the startup of the system, different objects may be
    051         * passed to your class using this method.  It should ignore any
    052         * objects that it doesn't need or understand.
    053         *
    054         * After the class changes its internal state so that getInit()
    055         * returns true, this method will be called no more, and late
    056         * initialization will not be performed.
    057         *
    058         * If your class relies on early initialization, and the object it
    059         * expects was not received, you can use late initialization to
    060         * throw an exception and complain.
    061         *
    062         * @param data An Object to use for initialization activities.
    063         * @exception InitializationException if initilaization of this
    064         * class was not successful.
    065         */
    066        void init(Object data) throws InitializationException;
    067
    068        /**
    069         * Performs late initialization of an Initable.
    070         *
    071         * When your class is being requested from an InitableBroker, it
    072         * will call getInit(), and if it returns false, this method will
    073         * be invoked.
    074         *
    075         * @exception InitializationException if initialization of this
    076         * class was not successful.
    077         */
    078        void init() throws InitializationException;
    079
    080        /**
    081         * Returns an <code>Initable</code> to an uninitialized state.
    082         *
    083         * <p>This method must release all resources allocated by the
    084         * <code>Initable</code> implementation, and resetting its internal state.
    085         * You may chose to implement this operation or not. If you support
    086         * this operation, getInit() should return false after successful
    087         * shutdown of the service.
    088         */
    089        void shutdown();
    090
    091        /**
    092         * Returns initialization status of an Initable.
    093         *
    094         * @return Initialization status of an Initable.
    095         */
    096        boolean getInit();
    097    }