    001package org.apache.turbine.services;
    002
    003/*
    004 * Licensed to the Apache Software Foundation (ASF) under one
    005 * or more contributor license agreements.  See the NOTICE file
    006 * distributed with this work for additional information
    007 * regarding copyright ownership.  The ASF licenses this file
    008 * to you under the Apache License, Version 2.0 (the
    009 * "License"); you may not use this file except in compliance
    010 * with the License.  You may obtain a copy of the License at
    011 *
    012 *   http://www.apache.org/licenses/LICENSE-2.0
    013 *
    014 * Unless required by applicable law or agreed to in writing,
    015 * software distributed under the License is distributed on an
    016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    017 * KIND, either express or implied.  See the License for the
    018 * specific language governing permissions and limitations
    019 * under the License.
    020 */
    021
    022/**
    023 * Interface for telling Turbine that the implementation class
    024 * is an external service provider therefore can be used for looking
    025 * up services not found by the Turbine implementation. It is
    026 * assumed that the referenced service container handles the
    027 * complete lifecycle of its services.
    028 *
    029 * @author <a href="mailto:siegfried.goeschl@it20one.at">Siegfried Goeschl</a>
    030 */
    031public interface TurbineServiceProvider
    032{
    033    /**
    034     * Returns an instance of the requested service. If the
    035     * given service is not available/found we throw a RuntimeException
    036     * since this is less intrusive.
    037     *
    038     * @param roleName the name of the requested service
    039     * @return an instance of the service
    040     * @throws InstantiationException the service could not be instantiated
    041     */
    042    public Object get(String roleName) throws InstantiationException;
    043
    044    /**
    045     * Releases the instance you got before. This is only really
    046     * required when not working with service singletons.
    047     *
    048     * @param component the component to release
    049     */
    050    public void release(Object component);
    051
    052    /**
    053     * Is the service known to the service container?
    054     * @param roleName the name of the requested service
    055     * @return true if the service is known to the provider
    056     */
    057    public boolean exists(String roleName);
    058}