1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.configuration.beanutils; 18 19 /** 20 * <p> 21 * Definition of an interface for bean factories. 22 * </p> 23 * <p> 24 * Beans defined in configuration files are not directly created, but by so 25 * called <em>bean factories</em>. This additional level of indirection 26 * provides for high flexibility in the creation process. For instance one 27 * implementation of this interface could be very simple and create a new 28 * instance of the specified class for each invocation. A different 29 * implementation could cache already created beans and ensure that always the 30 * same bean of the given class will be returned - this would be an easy mean 31 * for creating singleton objects. 32 * </p> 33 * <p> 34 * The interface itself is quite simple. There is a single method for creating a 35 * bean of a given class. All necessary parameters are obtained from an also 36 * passed in {@link BeanDeclaration} object. It is also possible 37 * (but optional) for a bean factory to declare the default class of the bean it 38 * creates. Then it is not necessary to specify a bean class in the bean 39 * declaration. 40 * </p> 41 * 42 * @since 1.3 43 * @author <a 44 * href="http://commons.apache.org/configuration/team-list.html">Commons 45 * Configuration team</a> 46 * @version $Id: BeanFactory.java 1208757 2011-11-30 20:38:15Z oheger $ 47 */ 48 public interface BeanFactory 49 { 50 /** 51 * Returns a bean instance for the given class. The bean will be initialized 52 * from the specified bean declaration object. It is up to a concrete 53 * implementation how the bean will be created and initialized. 54 * 55 * @param beanClass the class for the bean 56 * @param data the bean declaration object containing all data about the 57 * bean to be created 58 * @param param an additional parameter that may be passed by calling code; 59 * it is up to a concrete implementation how this parameter is evaluated 60 * @return the new bean instance (should not be <b>null</b>) 61 * @throws Exception if an error occurs (the helper classes for creating 62 * beans will catch this unspecific exception and wrap it in a configuration 63 * exception) 64 */ 65 Object createBean(Class<?> beanClass, BeanDeclaration data, Object param) 66 throws Exception; 67 68 /** 69 * Returns the default bean class of this bean factory. If an implementation 70 * here returns a non <b>null</b> value, bean declarations using this 71 * factory do not need to provide the name of the bean class. In such a case 72 * an instance of the default class will be created. 73 * 74 * @return the default class of this factory or <b>null</b> if there is 75 * none 76 */ 77 Class<?> getDefaultBeanClass(); 78 }