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 <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      /***
49       * Returns a bean instance for the given class. The bean will be initialized
50       * from the specified bean declaration object. It is up to a concrete
51       * implementation how the bean will be created and initialized.
52       *
53       * @param beanClass the class for the bean
54       * @param data the bean declaration object containing all data about the
55       * bean to be created
56       * @param param an additional parameter that may be passed by calling code;
57       * it is up to a concrete implementation how this parameter is evaluated
58       * @return the new bean instance (should not be <b>null</b>)
59       * @throws Exception if an error occurs (the helper classes for creating
60       * beans will catch this unspecific exception and wrap it in a configuration
61       * exception)
62       */
63      Object createBean(Class beanClass, BeanDeclaration data, Object param)
64              throws Exception;
65  
66      /***
67       * Returns the default bean class of this bean factory. If an implementation
68       * here returns a non <b>null</b> value, bean declarations using this
69       * factory do not need to provide the name of the bean class. In such a case
70       * an instance of the default class will be created.
71       *
72       * @return the default class of this factory or <b>null</b> if there is
73       * none
74       */
75      Class getDefaultBeanClass();
76  }