<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xml:id="beans-factory-extension">
  <title>Container Extension Points</title>

  <para>Typically, an application developer does not need to subclass
    <interfacename>ApplicationContext</interfacename> implementation classes.
    Instead, the Spring IoC container can be extended by plugging in
    implementations of special integration interfaces. The next few sections
    describe these integration interfaces.</para>

  <section id="beans-factory-extension-bpp">
    <title>Customizing beans using a
      <interfacename>BeanPostProcessor</interfacename></title>

    <para>The <interfacename>BeanPostProcessor</interfacename> interface defines
      <firstterm>callback methods</firstterm> that you can implement to provide
      your own (or override the container's default) instantiation logic,
      dependency-resolution logic, and so forth. If you want to implement some
      custom logic after the Spring container finishes instantiating,
      configuring, and initializing a bean, you can plug in one or
      more <interfacename>BeanPostProcessor</interfacename>
      implementations.</para>

    <para>You can configure multiple <literal>BeanPostProcessor</literal>
      instances, and you can control the order in which these
      <literal>BeanPostProcessor</literal>s execute by setting the
      <literal>order</literal> property. You can set this property only if the
      <interfacename>BeanPostProcessor</interfacename> implements the
      <interfacename>Ordered</interfacename> interface; if you write your own
      <interfacename>BeanPostProcessor</interfacename> you should consider
      implementing the <interfacename>Ordered</interfacename> interface too. For
      further details, consult the Javadoc for the
      <interfacename>BeanPostProcessor</interfacename> and
      <interfacename>Ordered</interfacename> interfaces. See also the note below on
      <link linkend="beans-factory-programmatically-registering-beanpostprocessors">
      programmatic registration of <interfacename>BeanPostProcessors</interfacename>
      </link></para>

    <note>
      <para><literal>BeanPostProcessor</literal>s operate on bean (or object)
        <emphasis>instances</emphasis>; that is to say, the Spring IoC container
        instantiates a bean instance and <emphasis>then</emphasis>
        <literal>BeanPostProcessor</literal>s do their work.</para>

      <para><literal>BeanPostProcessor</literal>s are scoped
        <emphasis>per-container</emphasis>. This is only relevant if you are
        using container hierarchies. If you define a
        <interfacename>BeanPostProcessor</interfacename> in one container, it
        will <emphasis>only</emphasis> post-process the beans in that
        container. In other words, beans that are defined in one container are not
        post-processed by a <literal>BeanPostProcessor</literal> defined in another
        container, even if both containers are part of the same hierarchy.</para>

      <para>To change the actual bean definition (i.e., the
        <emphasis>blueprint</emphasis> that defines the bean), you instead need to use a
        <interfacename>BeanFactoryPostProcessor</interfacename> as described
        in <xref linkend="beans-factory-extension-factory-postprocessors"
        />.</para>
    </note>

    <para>The
      <interfacename>org.springframework.beans.factory.config.BeanPostProcessor</interfacename>
      interface consists of exactly two callback methods. When such a class is
      registered as a post-processor with the container, for each bean instance
      that is created by the container, the post-processor gets a callback from
      the container both <emphasis>before</emphasis> container initialization
      methods (such as InitializingBean's <emphasis>afterPropertiesSet()</emphasis>
      and any declared init method) are called as well as <emphasis>after</emphasis>
      any bean initialization callbacks. The post-processor can take
      any action with the bean instance, including ignoring the callback
      completely. A bean post-processor typically checks for callback
      interfaces or may wrap a bean with a proxy. Some Spring AOP
      infrastructure classes are implemented as bean post-processors in order
      to provide proxy-wrapping logic.</para>

    <para>An <interfacename>ApplicationContext</interfacename>
      <emphasis>automatically detects</emphasis> any beans that are defined in
      the configuration metadata which implement the
      <interfacename>BeanPostProcessor</interfacename> interface. The
      <interfacename>ApplicationContext</interfacename> registers these beans as
      post-processors so that they can be called later upon bean creation.
      Bean post-processors can be deployed in the container just like any other
      beans.</para>

    <anchor id="beans-factory-programmatically-registering-beanpostprocessors"/>
    <note>
      <title>Programmatically registering <interfacename>BeanPostProcessors
        </interfacename></title>
      <para>
         While the recommended approach for <interfacename>BeanPostProcessor
         </interfacename> registration is through <interfacename>ApplicationContext
         </interfacename> auto-detection (as described above), it is also
         possible to register them <emphasis>programmatically</emphasis>
         against a <interfacename>ConfigurableBeanFactory</interfacename> using the
         <methodname>addBeanPostProcessor</methodname> method. This can be useful
         when needing to evaluate conditional logic before registration, or even
         for copying bean post processors across contexts in a hierarchy.  Note
         however that <interfacename>BeanPostProcessors</interfacename> added
         programmatically <emphasis>do not respect the <interfacename>Ordered
         </interfacename> interface</emphasis>. Here it is the <emphasis>order of
         registration</emphasis> that dictates the order of execution.  Note also
         that <interfacename>BeanPostProcessors</interfacename> registered
         programmatically are always processed before those registered through
         auto-detection, regardless of any explicit ordering.
      </para>
    </note>

    <note>
      <title><interfacename>BeanPostProcessors</interfacename> and AOP
        auto-proxying</title>

      <para>Classes that implement the
        <interfacename>BeanPostProcessor</interfacename> interface are
        <emphasis>special</emphasis> and are treated differently by the
        container. All <interfacename>BeanPostProcessors</interfacename>
        <emphasis>and beans that they reference directly</emphasis> are
        instantiated on startup, as part of the special startup phase of the
        <interfacename>ApplicationContext</interfacename>. Next, all
        <interfacename>BeanPostProcessors</interfacename> are registered in a
        sorted fashion and applied to all further beans in the container.
        Because AOP auto-proxying is implemented as a
        <interfacename>BeanPostProcessor</interfacename> itself, neither
        <interfacename>BeanPostProcessors</interfacename> nor the beans they reference
        directly are eligible for auto-proxying, and thus do not have aspects woven
        into them.</para>

      <para>For any such bean, you should see an informational log message:
        <quote><emphasis>Bean foo is not eligible for getting processed by all
        BeanPostProcessor interfaces (for example: not eligible for
        auto-proxying)</emphasis></quote>.</para>
    </note>

    <para>The following examples show how to write, register, and use
      <literal>BeanPostProcessors</literal> in an
      <interfacename>ApplicationContext</interfacename>.</para>

    <section id="beans-factory-extension-bpp-examples-hw">
      <title>Example: Hello World,
        <interfacename>BeanPostProcessor</interfacename>-style</title>

      <para>This first example illustrates basic usage. The example shows a
        custom <interfacename>BeanPostProcessor</interfacename> implementation
        that invokes the <methodname>toString()</methodname> method of each bean
        as it is created by the container and prints the resulting string to the
        system console.</para>

      <para>Find below the custom
        <interfacename>BeanPostProcessor</interfacename> implementation class
        definition:</para>

      <programlisting language="java">package scripting;

import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.beans.BeansException;

public class InstantiationTracingBeanPostProcessor implements BeanPostProcessor {

  <lineannotation>// simply return the instantiated bean as-is</lineannotation>
  public Object postProcessBeforeInitialization(Object bean, String beanName)
                                                                     throws BeansException {
      return bean; <lineannotation>// we could potentially return any object reference here...</lineannotation>
  }

  public Object postProcessAfterInitialization(Object bean, String beanName)
                                                                     throws BeansException {
      System.out.println("Bean '" + beanName + "' created : " + bean.toString());
      return bean;
  }
}</programlisting>

      <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:lang="http://www.springframework.org/schema/lang"
     xsi:schemaLocation="http://www.springframework.org/schema/beans
         http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
         http://www.springframework.org/schema/lang
         http://www.springframework.org/schema/lang/spring-lang-3.0.xsd"&gt;

  &lt;lang:groovy id="messenger"
        script-source="classpath:org/springframework/scripting/groovy/Messenger.groovy"&gt;
      &lt;lang:property name="message" value="Fiona Apple Is Just So Dreamy."/&gt;
  &lt;/lang:groovy&gt;

  <lineannotation>&lt;!--
      when the above bean (messenger) is instantiated, this custom
      <interfacename>BeanPostProcessor</interfacename> implementation will output the fact to the system console
   --&gt;</lineannotation>
  &lt;bean class="scripting.InstantiationTracingBeanPostProcessor"/&gt;

&lt;/beans&gt;</programlisting>

      <para>Notice how the
        <classname>InstantiationTracingBeanPostProcessor</classname> is simply
        defined. It does not even have a name, and because it is a bean it can
        be dependency-injected just like any other bean. (The preceding
        configuration also defines a bean that is backed by a Groovy script. The
        Spring 2.0 dynamic language support is detailed in the chapter entitled
        <xref linkend="dynamic-language"/>.)</para>

      <para>The following simple Java application executes the preceding code and
        configuration:</para>

      <programlisting language="java">import org.springframework.context.ApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;
import org.springframework.scripting.Messenger;

public final class Boot {

  public static void main(final String[] args) throws Exception {
      ApplicationContext ctx = new ClassPathXmlApplicationContext("scripting/beans.xml");
      Messenger messenger = (Messenger) ctx.getBean("messenger");
      System.out.println(messenger);
  }
}</programlisting>

      <para>The output of the preceding application resembles the
        following:</para>

      <programlisting>Bean 'messenger' created : org.springframework.scripting.groovy.GroovyMessenger@272961
org.springframework.scripting.groovy.GroovyMessenger@272961</programlisting>
    </section>

    <section id="beans-factory-extension-bpp-examples-rabpp">
      <title>Example: The
        <classname>RequiredAnnotationBeanPostProcessor</classname></title>

      <para>Using callback interfaces or annotations in conjunction with a
        custom <interfacename>BeanPostProcessor</interfacename> implementation
        is a common means of extending the Spring IoC container. An example is
        Spring's <classname>RequiredAnnotationBeanPostProcessor</classname> &#151; a
        <interfacename>BeanPostProcessor</interfacename> implementation that
        ships with the Spring distribution which ensures that JavaBean
        properties on beans that are marked with an (arbitrary) annotation are
        actually (configured to be) dependency-injected with a value.</para>
    </section>
  </section>

  <section id="beans-factory-extension-factory-postprocessors">
    <title>Customizing configuration metadata with a
      <interfacename>BeanFactoryPostProcessor</interfacename></title>

    <para>The next extension point that we will look at is the
      <interfacename>org.springframework.beans.factory.config.BeanFactoryPostProcessor</interfacename>.
      The semantics of this interface are similar to those of the
      <interfacename>BeanPostProcessor</interfacename>, with one major
      difference: <literal>BeanFactoryPostProcessor</literal>s operate on the
      <emphasis>bean configuration metadata</emphasis>; that is, the Spring IoC
      container allows <literal>BeanFactoryPostProcessors</literal> to read the
      configuration metadata and potentially change it
      <emphasis>before</emphasis> the container instantiates any beans other
      than <literal>BeanFactoryPostProcessors</literal>.</para>

    <para>You can configure multiple
      <literal>BeanFactoryPostProcessors</literal>, and you can control the order in
      which these <literal>BeanFactoryPostProcessors</literal> execute by
      setting the <literal>order</literal> property. However, you can only set
      this property if the
      <interfacename>BeanFactoryPostProcessor</interfacename> implements the
      <interfacename>Ordered</interfacename> interface. If you write your own
      <interfacename>BeanFactoryPostProcessor</interfacename>, you should
      consider implementing the <interfacename>Ordered</interfacename> interface
      too. Consult the Javadoc for the
      <interfacename>BeanFactoryPostProcessor</interfacename> and
      <interfacename>Ordered</interfacename> interfaces for more details.</para>

    <note>
      <para>If you want to change the actual bean <emphasis>instances</emphasis>
        (i.e., the objects that are created from the configuration metadata), then you
        instead need to use a <interfacename>BeanPostProcessor</interfacename>
        (described above in <xref linkend="beans-factory-extension-bpp"/>). While
        it is technically possible to work with bean instances within a
        <interfacename>BeanFactoryPostProcessor</interfacename> (e.g., using
        <methodname>BeanFactory.getBean()</methodname>), doing so causes
        premature bean instantiation, violating the standard container lifecycle.
        This may cause negative side effects such as bypassing bean post
        processing.</para>

      <para>Also, <literal>BeanFactoryPostProcessors</literal> are scoped
        <emphasis>per-container</emphasis>. This is only relevant if you are
        using container hierarchies. If you define a
        <interfacename>BeanFactoryPostProcessor</interfacename> in one
        container, it will <emphasis>only</emphasis> be applied to the bean
        definitions in that container. Bean definitions in one container
        will not be post-processed by
        <literal>BeanFactoryPostProcessors</literal> in another container, even
        if both containers are part of the same hierarchy.</para>
    </note>

    <para>A bean factory post-processor is executed automatically when it is
      declared inside an <interfacename>ApplicationContext</interfacename>,
      in order to apply changes to the configuration metadata that define the
      container. Spring includes a number of predefined bean factory
      post-processors, such as <classname>PropertyOverrideConfigurer</classname>
      and <classname>PropertyPlaceholderConfigurer</classname>. A custom
      <interfacename>BeanFactoryPostProcessor</interfacename> can also be used,
      for example, to register custom property editors.</para>

    <anchor id="beans-factory-autodetect-beanfactorypostprocessors"/>

    <para>An <interfacename>ApplicationContext</interfacename> automatically
      detects any beans that are deployed into it that implement the
      <interfacename>BeanFactoryPostProcessor</interfacename> interface. It
      uses these beans as bean factory post-processors, at the
      appropriate time. You can deploy these post-processor beans as you
      would any other bean.</para>

    <note>
      <para>As with <interfacename>BeanPostProcessor</interfacename>s, you typically
        do not want to configure <interfacename>BeanFactoryPostProcessor</interfacename>s
        for lazy initialization. If no other bean references a
        <interfacename>Bean(Factory)PostProcessor</interfacename>,
        that post-processor will not get instantiated at all. Thus, marking it for
        lazy initialization will be ignored, and the 
        <interfacename>Bean(Factory)PostProcessor</interfacename> will be
        instantiated eagerly even if you set the <literal>default-lazy-init</literal>
        attribute to <literal>true</literal> on the declaration of your
        <code>&lt;beans /&gt;</code> element.</para>
    </note>

    <section id="beans-factory-placeholderconfigurer">
      <title>Example: the
        <interfacename>PropertyPlaceholderConfigurer</interfacename></title>

      <para>You use the
        <interfacename>PropertyPlaceholderConfigurer</interfacename> to
        externalize property values from a bean definition in a separate
        file using the standard Java <classname>Properties</classname> format.
        Doing so enables the person deploying an application to customize
        environment-specific properties such as database URLs and passwords,
        without the complexity or risk of modifying the main XML definition file
        or files for the container.</para>

      <!-- MLP: Beverly to review following 2 paragraphs -->

      <para>Consider the following XML-based configuration metadata fragment,
        where a <interfacename>DataSource</interfacename> with placeholder
        values is defined. The example shows properties configured from an
        external <classname>Properties</classname> file. At runtime, a
        <classname>PropertyPlaceholderConfigurer</classname> is applied to the
        metadata that will replace some properties of the DataSource. The values
        to replace are specified as <emphasis>placeholders</emphasis> of the form
        ${property-name} which follows the Ant / log4j / JSP EL style.</para>

      <programlisting language="xml">&lt;bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"&gt;
  &lt;property name="locations" value="classpath:com/foo/jdbc.properties"/&gt;
&lt;/bean&gt;

&lt;bean id="dataSource" destroy-method="close"
    class="org.apache.commons.dbcp.BasicDataSource"&gt;
  &lt;property name="driverClassName" value="${jdbc.driverClassName}"/&gt;
  &lt;property name="url" value="${jdbc.url}"/&gt;
  &lt;property name="username" value="${jdbc.username}"/&gt;
  &lt;property name="password" value="${jdbc.password}"/&gt;
&lt;/bean&gt;</programlisting>

      <para>The actual values come from another file in the standard Java
        <classname>Properties</classname> format:</para>

      <programlisting>jdbc.driverClassName=org.hsqldb.jdbcDriver
jdbc.url=jdbc:hsqldb:hsql://production:9002
jdbc.username=sa
jdbc.password=root</programlisting>

      <para>Therefore, the string <literal>${jdbc.username}</literal> is replaced
        at runtime with the value 'sa', and the same applies for other placeholder
        values that match keys in the properties file. The
        <classname>PropertyPlaceholderConfigurer</classname> checks for
        placeholders in most properties and attributes of a bean definition.
        Furthermore, the placeholder prefix and suffix can be customized.</para>

      <para>With the <literal>context</literal> namespace introduced in Spring
        2.5, it is possible to configure property placeholders with a dedicated
        configuration element. One or more locations can be provided as a
        comma-separated list in the <literal>location</literal>
        attribute.</para>

      <programlisting language="xml">&lt;context:property-placeholder location="classpath:com/foo/jdbc.properties"/&gt;</programlisting>

      <para>The <classname>PropertyPlaceholderConfigurer</classname> not only
        looks for properties in the <classname>Properties</classname> file
        you specify. By default it also checks against the Java
        <classname>System</classname> properties if it cannot find a property
        in the specified properties files. You can customize this behavior by setting the
        <literal>systemPropertiesMode</literal> property of the configurer with
        one of the following three supported integer values:
        <!--What property is it overriding and what will replace the overridden value?-->
        <!--MLP: override a value in the Properties with one from the 'systemProperties' -->
        </para>

        <itemizedlist>
        	<listitem>
	        	<para><emphasis>never</emphasis> (0): Never check system properties</para>
        	</listitem>
        	<listitem>
	        	<para><emphasis>fallback</emphasis> (1): Check system properties if not resolvable in the specified properties files. This is the default.</para>
        	</listitem>
        	<listitem>
	        	<para><emphasis>override</emphasis> (2): Check system properties first, before trying the specified properties files. This allows system properties to override any other property source.</para>
        	</listitem>
        </itemizedlist>

      <para>
        Consult the Javadoc for the <classname>PropertyPlaceholderConfigurer</classname>
        for more information.</para>

      <tip>
        <title>Class name substitution</title>

        <para>You can use the
          <classname>PropertyPlaceholderConfigurer</classname> to substitute
          class names, which is sometimes useful when you have to pick a
          particular implementation class at runtime. For example:</para>

        <programlisting language="xml">&lt;bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"&gt;
  &lt;property name="locations"&gt;
      &lt;value&gt;classpath:com/foo/strategy.properties&lt;/value&gt;
  &lt;/property&gt;
  &lt;property name="properties"&gt;
      &lt;value&gt;custom.strategy.class=com.foo.DefaultStrategy&lt;/value&gt;
  &lt;/property&gt;
&lt;/bean&gt;

&lt;bean id="serviceStrategy" class="${custom.strategy.class}"/&gt;</programlisting>

        <para>If the class cannot be resolved at runtime to a valid class,
          resolution of the bean fails when it is about to be created, which is
          during the <methodname>preInstantiateSingletons()</methodname> phase
          of an <interfacename>ApplicationContext</interfacename> for a
          non-lazy-init bean.</para>
      </tip>
    </section>

    <section id="beans-factory-overrideconfigurer">
      <title>Example: the
        <classname>PropertyOverrideConfigurer</classname></title>

      <para>The <classname>PropertyOverrideConfigurer</classname>, another bean
        factory post-processor, resembles the
        <interfacename>PropertyPlaceholderConfigurer</interfacename>, but unlike
        the latter, the original definitions can have default values or no
        values at all for bean properties. If an overriding
        <classname>Properties</classname> file does not have an entry for a
        certain bean property, the default context definition is used.</para>

      <para>Note that the bean definition is <emphasis>not</emphasis> aware of
        being overridden, so it is not immediately obvious from the XML
        definition file that the override configurer is being used. In case of
        multiple <classname>PropertyOverrideConfigurer</classname> instances
        that define different values for the same bean property, the last one
        wins, due to the overriding mechanism.</para>

      <para>Properties file configuration lines take this format:</para>

      <programlisting language="java">beanName.property=value</programlisting>

      <para>For example:</para>

      <programlisting language="java">dataSource.driverClassName=com.mysql.jdbc.Driver
dataSource.url=jdbc:mysql:mydb</programlisting>

      <para>This example file can be used with a container definition that
        contains a bean called <emphasis>dataSource</emphasis>, which has
        <emphasis>driver</emphasis> and <emphasis>url</emphasis>
        properties.</para>

      <para>Compound property names are also supported, as long as every
        component of the path except the final property being overridden is
        already non-null (presumably initialized by the constructors). In this
        example...</para>

      <programlisting>foo.fred.bob.sammy=123</programlisting>

      <para>... the <literal>sammy</literal> property of the
        <literal>bob</literal> property of the <literal>fred</literal> property
        of the <literal>foo</literal> bean is set to the scalar value
        <literal>123</literal>.</para>

      <note>
        <para>Specified override values are always <emphasis>literal</emphasis>
          values; they are not translated into bean references. This convention
          also applies when the original value in the XML bean definition
          specifies a bean reference.</para>
      </note>

      <para>With the <literal>context</literal> namespace introduced in Spring
        2.5, it is possible to configure property overriding with a dedicated
        configuration element:</para>

      <programlisting language="xml">&lt;context:property-override location="classpath:override.properties"/&gt;</programlisting>

    </section>
  </section>

  <section id="beans-factory-extension-factorybean">
    <title>Customizing instantiation logic with a
      <interfacename>FactoryBean</interfacename></title>

    <para>Implement the
      <interfacename>org.springframework.beans.factory.FactoryBean</interfacename>
      interface for objects that <emphasis>are themselves
      factories</emphasis>.</para>

    <para>The <interfacename>FactoryBean</interfacename> interface is a point of
      pluggability into the Spring IoC container's instantiation logic. If you
      have complex initialization code that is better expressed in Java as
      opposed to a (potentially) verbose amount of XML, you can create your own
      <interfacename>FactoryBean</interfacename>, write the complex
      initialization inside that class, and then plug your custom
      <interfacename>FactoryBean</interfacename> into the container.</para>

    <para>The <interfacename>FactoryBean</interfacename> interface provides
      three methods:</para>

    <itemizedlist>
      <listitem>
        <para><methodname>Object getObject()</methodname>: returns an instance
          of the object this factory creates. The instance can possibly be
          shared, depending on whether this factory returns singletons or
          prototypes.</para>
      </listitem>

      <listitem>
        <para><methodname>boolean isSingleton()</methodname>: returns
          <literal>true</literal> if this
          <interfacename>FactoryBean</interfacename> returns singletons,
          <literal>false</literal> otherwise.</para>
      </listitem>

      <listitem>
        <para><methodname>Class getObjectType()</methodname>: returns the object
          type returned by the <methodname>getObject()</methodname> method or
          <literal>null</literal> if the type is not known in advance.</para>
      </listitem>
    </itemizedlist>

    <para>The <interfacename>FactoryBean</interfacename> concept and interface
      is used in a number of places within the Spring Framework; more than 50
      implementations of the <interfacename>FactoryBean</interfacename>
      interface ship with Spring itself.</para>

    <para>When you need to ask a container for an actual
      <interfacename>FactoryBean</interfacename> instance itself instead of the bean
      it produces, preface the bean's id with the ampersand symbol
      (<literal>&amp;</literal>) when calling the
      <methodname>getBean()</methodname> method of the
      <interfacename>ApplicationContext</interfacename>. So for a given
      <interfacename>FactoryBean</interfacename> with an id of
      <literal>myBean</literal>, invoking <literal>getBean("myBean")</literal>
      on the container returns the product of the
      <interfacename>FactoryBean</interfacename>; whereas, invoking
      <literal>getBean("&amp;myBean")</literal> returns the
      <interfacename>FactoryBean</interfacename> instance
      itself.<!--Moved ApplicationContext section to almost the end of the doc, right before BeanFactory and renamed it Additional Capabilities of.--></para>
  </section>
</section>
