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.configuration2.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 called <em>bean factories</em>. This
25 * additional level of indirection provides for high flexibility in the creation process. For instance one
26 * implementation of this interface could be very simple and create a new instance of the specified class for each
27 * invocation. A different implementation could cache already created beans and ensure that always the same bean of the
28 * given class will be returned - this would be an easy mean for creating singleton objects.
29 * </p>
30 * <p>
31 * The interface itself is quite simple. There is a single method for creating a bean of a given class. All necessary
32 * parameters are obtained from a passed in {@link BeanCreationContext} object. It is also possible (but optional) for a
33 * bean factory to declare the default class of the bean it creates. Then it is not necessary to specify a bean class in
34 * the bean declaration.
35 * </p>
36 *
37 * @since 1.3
38 */
39 public interface BeanFactory {
40
41 /**
42 * Creates a bean instance for the given context object. All information about the bean to be created are contained in
43 * the provided {@code BeanCreationContext} object. This includes a {@link BeanDeclaration} defining the properties of
44 * the bean. It is up to a concrete implementation how the bean is created and initialized.
45 *
46 * @param bcc the context object for the bean to be created
47 * @return the new bean instance (should not be <b>null</b>)
48 * @throws Exception if an error occurs (the helper classes for creating beans will catch this generic exception and
49 * wrap it in a configuration exception)
50 */
51 Object createBean(BeanCreationContext bcc) throws Exception;
52
53 /**
54 * Gets the default bean class of this bean factory. If an implementation here returns a non <b>null</b> value, bean
55 * declarations using this factory do not need to provide the name of the bean class. In such a case an instance of the
56 * default class will be created.
57 *
58 * @return the default class of this factory or <b>null</b> if there is none
59 */
60 Class<?> getDefaultBeanClass();
61 }