1. /*

  2.  * Copyright 2002-2004 the original author or authors.

  3.  * 

  4.  * Licensed under the Apache License, Version 2.0 (the "License");

  5.  * you may not use this file except in compliance with the License.

  6.  * You may obtain a copy of the License at

  7.  * 

  8.  *      http://www.apache.org/licenses/LICENSE-2.0

  9.  * 

  10.  * Unless required by applicable law or agreed to in writing, software

  11.  * distributed under the License is distributed on an "AS IS" BASIS,

  12.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  13.  * See the License for the specific language governing permissions and

  14.  * limitations under the License.

  15.  */ 

  16. 

  17. package org.springframework.beans.factory.access;

  18. 

  19. import org.springframework.beans.BeansException;

  20. 

  21. /**

  22.  * <p>An interface for a class used to lookup/use, and optionally allow the

  23.  * release of a BeanFactory, or BeanFactory subclass such as ApplicationContext.

  24.  *

  25.  * <p>Where this interface is implemented as a singleton class such as

  26.  * SingletonBeanFactoryLocator, the Spring team <strong>strongly</strong>

  27.  * suggests that it be used sparingly and with caution. By far the vast majority

  28.  * of the code inside an application is best written in a Dependency Injection

  29.  * style, where that code is served out of a BeanFactory/ApplicationContext

  30.  * container, and has its own dependencies supplied by the container when it is

  31.  * created. However, even such a singleton implementation sometimes has its use

  32.  * in the small glue layers of code that is sometimes needed to tie other code

  33.  * together. For example, third party code may try to construct new objects

  34.  * directly, without the ability to force it to get these objects out of a 

  35.  * beanfactory. If the object constructed by the third party code is just a

  36.  * small stub or proxy, which then uses an implementation of this class to get a

  37.  * beanfactory from which it gets the real object, to which it delegates, then 

  38.  * proper Dependency Injection has been achieved. As another example, in a complex

  39.  * J2EE app with multiple layers, with each layer having its own

  40.  * ApplicationContext definition (in a hierarchy), a class like

  41.  * SingletonBeanFactoryLocator may be used to demand load these contexts.

  42.  * 

  43.  * @author Colin Sampaleanu

  44.  * @version $Revision: 1.4 $

  45.  * @see org.springframework.beans.factory.BeanFactory

  46.  * @see org.springframework.context.access.DefaultLocatorFactory

  47.  * @see org.springframework.context.ApplicationContext

  48.  */

  49. public interface BeanFactoryLocator {

  50. 

  51.   /**

  52.    * Use the BeanFactory (or derived class such as ApplicationContext) specified

  53.    * by the factoryKey parameter. The definition is possibly loaded/created as needed.

  54.    * @param factoryKey a resource name specifying which BeanFactory the BeanFactoryLocator

  55.    * should return for usage. The actual meaning of the resource name is specific to the

  56.    * actual implementation of BeanFactoryLocator.

  57.    * @return the BeanFactory instance, wrapped as a BeanFactoryReference object

  58.    * @throws BeansException if there is an error loading or accessing the BeanFactory

  59.    */

  60.   BeanFactoryReference useBeanFactory(String factoryKey) throws BeansException;

  61. 

  62. }