01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * 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 <code>{@link BeanDeclaration}</code> 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 Oliver Heger
44: * @version $Id: BeanFactory.java 439648 2006-09-02 20:42:10Z oheger $
45: */
46: public interface BeanFactory {
47: /**
48: * Returns a bean instance for the given class. The bean will be initialized
49: * from the specified bean declaration object. It is up to a concrete
50: * implementation how the bean will be created and initialized.
51: *
52: * @param beanClass the class for the bean
53: * @param data the bean declaration object containing all data about the
54: * bean to be created
55: * @param param an additional parameter that may be passed by calling code;
56: * it is up to a concrete implementation how this parameter is evaluated
57: * @return the new bean instance (should not be <b>null</b>)
58: * @throws Exception if an error occurs (the helper classes for creating
59: * beans will catch this unspecific exception and wrap it in a configuration
60: * exception)
61: */
62: Object createBean(Class beanClass, BeanDeclaration data,
63: Object param) throws Exception;
64:
65: /**
66: * Returns the default bean class of this bean factory. If an implementation
67: * here returns a non <b>null</b> value, bean declarations using this
68: * factory do not need to provide the name of the bean class. In such a case
69: * an instance of the default class will be created.
70: *
71: * @return the default class of this factory or <b>null</b> if there is
72: * none
73: */
74: Class getDefaultBeanClass();
75: }
|