package com.dpd.general.services;

import org.apache.commons.configuration.Configuration;
import org.apache.commons.configuration.PropertiesConfiguration;

import net.sf.tapestry.ApplicationRuntimeException;

/**
 * <code>Services</code> are <code>Initables</code> that have a name,
 * and a set of properties.
 *
 * @author <a href="mailto:shomburg@hsofttec.com">Sven Homburg</a>
 * @version $Id$
 */
public interface Service
{
    /**
     * The name of this service.
     */
    public static final String SERVICE_NAME = "Service";

    /**
     * Performs late initialization of an Initable.
     *
     * When your class is being requested from an InitableBroker, it
     * will call isInitialized(), and if it returns false, this method
     * will be invoked.  A typical implementation for classes
     * extending {@link org.apache.fulcrum.BaseService} will look
     * something like the following:
     *
     * <blockquote><code><pre>
     * if (!isInitialized())
     * {
     *     try
     *     {
     *         // Your initialization activities ...
     *         setInit(true);
     *     }
     *     catch (Exception e)
     *     {
     *         throw new Exception("Something bad happened " +
     *                             "during " +
     *                             Service.SERVICE_NAME +
     *                             " initialization: " +
     *                             e.getMessage());
     *     }
     * }
     * </pre></code></blockquote>
     *
     * @exception InitializationException, if initialization of this
     * class was not successful.
     */
    public void init(PropertiesConfiguration conf) throws ApplicationRuntimeException;

    /**
     * Returns a <code>Service</code> to an uninitialized state.
     *
     * <p>This method must release all resources allocated by the
     * <code>Initable</code> implementation, and resetting its
     * internal state.  You may chose to implement this operation or
     * not. If you support this operation, {@link #isInitialized()}
     * should return false after successful shutdown of the service.
     */
    public void shutdown();

    /**
     * Returns initialization state.
     *
     * @return Whether the service has been initialized.
     */
    public boolean isInitialized();

    /**
     * ServiceBroker uses this method to pass a Service its name.
     * Service uses its name to ask the broker for an apropriate set
     * of Properties.
     *
     * @param name The name of this Service.
     */
    public void setName(String name);

    /**
     * ServiceBroker uses this method to gets a Service its name.
     * Service uses its name to ask the broker for an apropriate set
     * of Properties.
     *
     * @return The name of this Service.
     */
    public String getName();

    /**
     * Returns the Configuration of this Service.  Every Service has at
     * least one property, which is "classname", containing the name
     * of the class implementing this service.  Note that the service
     * may chose to alter its configuration, therefore they may be
     * different from those returned by ServiceBroker.
     *
     * @return The configuration of this <code>Service</code>.
     */
    public Configuration getConfiguration();

    /**
     * Returns text describing the status of this Service instance.
     *
     * @return Text describing service status.
     */
    public String getStatus() throws ApplicationRuntimeException;
}