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 }