View Javadoc

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  }