001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.configuration.beanutils; 018 019 /** 020 * <p> 021 * Definition of an interface for bean factories. 022 * </p> 023 * <p> 024 * Beans defined in configuration files are not directly created, but by so 025 * called <em>bean factories</em>. This additional level of indirection 026 * provides for high flexibility in the creation process. For instance one 027 * implementation of this interface could be very simple and create a new 028 * instance of the specified class for each invocation. A different 029 * implementation could cache already created beans and ensure that always the 030 * same bean of the given class will be returned - this would be an easy mean 031 * for creating singleton objects. 032 * </p> 033 * <p> 034 * The interface itself is quite simple. There is a single method for creating a 035 * bean of a given class. All necessary parameters are obtained from an also 036 * passed in <code>{@link BeanDeclaration}</code> object. It is also possible 037 * (but optional) for a bean factory to declare the default class of the bean it 038 * creates. Then it is not necessary to specify a bean class in the bean 039 * declaration. 040 * </p> 041 * 042 * @since 1.3 043 * @author Oliver Heger 044 * @version $Id: BeanFactory.java 439648 2006-09-02 20:42:10Z oheger $ 045 */ 046 public interface BeanFactory 047 { 048 /** 049 * Returns a bean instance for the given class. The bean will be initialized 050 * from the specified bean declaration object. It is up to a concrete 051 * implementation how the bean will be created and initialized. 052 * 053 * @param beanClass the class for the bean 054 * @param data the bean declaration object containing all data about the 055 * bean to be created 056 * @param param an additional parameter that may be passed by calling code; 057 * it is up to a concrete implementation how this parameter is evaluated 058 * @return the new bean instance (should not be <b>null</b>) 059 * @throws Exception if an error occurs (the helper classes for creating 060 * beans will catch this unspecific exception and wrap it in a configuration 061 * exception) 062 */ 063 Object createBean(Class beanClass, BeanDeclaration data, Object param) 064 throws Exception; 065 066 /** 067 * Returns the default bean class of this bean factory. If an implementation 068 * here returns a non <b>null</b> value, bean declarations using this 069 * factory do not need to provide the name of the bean class. In such a case 070 * an instance of the default class will be created. 071 * 072 * @return the default class of this factory or <b>null</b> if there is 073 * none 074 */ 075 Class getDefaultBeanClass(); 076 }