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  }