    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    import 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     */
    049    public 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    }