    001package 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 1706239 2015-10-01 13:18:35Z tv $
    035 */
    036public 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 initialization 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 initialization 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}