    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
    024import org.apache.commons.configuration.Configuration;
    025
    026/**
    027 * Classes that implement this interface can act as a broker for
    028 * <code>Service</code> classes.
    029 *
    030 * Functionality that <code>ServiceBroker</code> provides in addition
    031 * to <code>InitableBroker</code> functionality includes:
    032 *
    033 * <ul>
    034 *
    035 * <li>Maintaining service name to class name mapping, allowing
    036 * plugable service implementations.</li>
    037 *
    038 * <li>Providing <code>Services</code> with <code>Properties</code>
    039 * based on a system wide configuration mechanism.</li>
    040 *
    041 * </ul>
    042 *
    043 * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
    044 * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
    045 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
    046 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
    047 * @version $Id: ServiceBroker.java 615328 2008-01-25 20:25:05Z tv $
    048 */
    049public interface ServiceBroker
    050{
    051    /**
    052     * Determines whether a service is registered in the configured
    053     * <code>TurbineResources.properties</code>.
    054     *
    055     * @param serviceName The name of the service whose existance to check.
    056     * @return Registration predicate for the desired services.
    057     */
    058    boolean isRegistered(String serviceName);
    059
    060    /**
    061     * Performs early initialization of the specified service.
    062     *
    063     * @param name The name of the service.
    064     * @exception InitializationException if the service is unknown
    065     * or can't be initialized.
    066     */
    067    void initService(String name) throws InitializationException;
    068
    069    /**
    070     * Shutdowns a Service.
    071     *
    072     * This method is used to release resources allocated by a
    073     * Service, and return it to initial (uninitailized) state.
    074     *
    075     * @param name The name of the Service to be uninitialized.
    076     */
    077    void shutdownService(String name);
    078
    079    /**
    080     * Shutdowns all Services.
    081     *
    082     * This method is used to release resources allocated by
    083     * Services, and return them to initial (uninitialized) state.
    084     */
    085    void shutdownServices();
    086
    087    /**
    088     * Returns an instance of requested Service.
    089     *
    090     * @param name The name of the Service requested.
    091     * @return An instance of requested Service.
    092     * @exception InstantiationException if the service is unknown or
    093     * can't be initialized.
    094     */
    095    Object getService(String name) throws InstantiationException;
    096
    097    /**
    098     * Returns the configuration of a specific service. Services
    099     * use this method to retrieve their configuration.
    100     *
    101     * @param name The name of the service.
    102     * @return Configuration of the requested service.
    103     */
    104    Configuration getConfiguration(String name);
    105}