Spring Framework
  1. Spring Framework
  2. SPR-9425

Document @Bean 'lite' mode and annotated classes in the reference manual

    Details

    • Type: Task Task
    • Status: Resolved
    • Priority: Minor Minor
    • Resolution: Complete
    • Affects Version/s: 3.1 GA
    • Fix Version/s: 3.2.2
    • Component/s: [Documentation], Core
    • Labels:
      None
    • Last commented by a User:
      false

      Description

      Overview

      SPR-9051 raised valid concerns about exactly what kinds of classes are supported with AnnotationConfigApplicationContext, AnnotatedBeanDefinitionReader, @ContextConfiguration(classes=...), etc.

      This issue picks up where SPR-9401 left off.


      Deliverables

      The following should be explicitly documented in the Java-based container configuration section of the reference manual.

      1. What types of classes are included in the term annotated classes
        • see @ContextConfiguration Javadoc below
      2. The semantics for @Bean Lite Mode
        • see talking points and @Bean Javadoc below

      Talking Points

      The following is a collection of talking points that can be covered in the reference manual.

      Inter-@Bean method calls are not supported in lite mode. Instead, when one @Bean-method invokes another local @Bean-method, the invocation is a natural Java direct method invocation since Spring does not intercept the invocation. This is analogous to inter-@Transactional method calls where in proxy mode, Spring does not intercept them – Spring does so only in AspectJ mode.

      @Bean lite mode is typically sufficient for straight factory methods that simply do not need any inter-bean references, possibly because they are creating leaf components, possibly because the returned component instances use @Inject-based dependency injection themselves anyway. However, Spring does respect the scoping semantics (e.g., singleton and prototype) for container-driven @Bean factory method calls. Furthermore, Spring also respects lifecycle callbacks for a bean created via an @Bean-method in lite mode.

      The reference manual should not only discuss the above talking points, but it should also mention some of the undesirable side effects that may occur when naïvely using @Bean-methods in lite mode – for example, the issues encountered in SPR-9051.


      Related Documentation

      @Bean Javadoc
      /**
       * <h3>{@code @Bean} <em>Lite</em> Mode</h3>
       *
       * <p>{@code @Bean} methods may also be declared within classes that are <em>not</em>
       * annotated with {@code @Configuration}. For example, bean methods may be declared
       * in a {@code @Component} class or even in a <em>plain old class</em>. In such cases,
       * a {@code @Bean} method will get processed in a so-called <em>'lite'</em> mode.
       *
       * <p>Bean methods in <em>lite</em> mode will be treated as plain <em>factory
       * methods</em> by the container (similar to {@code factory-method} declarations
       * in XML), with scoping and lifecycle callbacks properly applied. The containing
       * class remains unmodified in this case, and there are no unusual constraints for
       * the containing class or the factory methods.
       *
       * <p>In contrast to the semantics for bean methods in {@code @Configuration} classes,
       * <em>'inter-bean references'</em> are not supported in <em>lite</em> mode. Instead,
       * when one {@code @Bean}-method invokes another {@code @Bean}-method in <em>lite</em>
       * mode, the invocation is a standard Java method invocation; Spring does not intercept
       * the invocation via a CGLIB proxy. This is analogous to inter-{@code @Transactional}
       * method calls where in proxy mode, Spring does not intercept the invocation &mdash;
       * Spring does so only in AspectJ mode.
       */
      
      @ContextConfiguration Javadoc
      /**
       * <h3>Annotated Classes</h3>
       *
       * <p>The term <em>annotated class</em> can refer to any of the following.
       *
       * <ul>
       * <li>A class annotated with {@link Configuration @Configuration}</li>
       * <li>A component (i.e., a class annotated with
       * {@link org.springframework.stereotype.Component @Component},
       * {@link org.springframework.stereotype.Service @Service},
       * {@link org.springframework.stereotype.Repository @Repository}, etc.)</li>
       * <li>A JSR-330 compliant class that is annotated with {@code javax.inject} annotations</li>
       * <li>Any other class that contains {@link Bean @Bean}-methods</li>
       * </ul>
       */
      

        Issue Links

          Activity

          Hide
          Juergen Hoeller added a comment -

          Maybe another one for you, Chris? I won't get to it this week.

          Juergen

          Show
          Juergen Hoeller added a comment - Maybe another one for you, Chris? I won't get to it this week. Juergen
          Hide
          Neale Upstone added a comment -

          Just read through the ref docs and knowing this behaviour, it does stand out as a gotcha in that @Bean would seem to work but without lifecycle. Given timelines, if this is to slip to next release, maybe a short update to the ref docs linking to where @Bean Javadoc covers this would be sufficient..?

          Show
          Neale Upstone added a comment - Just read through the ref docs and knowing this behaviour, it does stand out as a gotcha in that @Bean would seem to work but without lifecycle. Given timelines, if this is to slip to next release, maybe a short update to the ref docs linking to where @Bean Javadoc covers this would be sufficient..?
          Hide
          Phil Webb added a comment -

          Assign to Chris to review https://github.com/SpringSource/spring-framework/pull/253 and rework/merge are required.

          Show
          Phil Webb added a comment - Assign to Chris to review https://github.com/SpringSource/spring-framework/pull/253 and rework/merge are required.

            People

            • Assignee:
              Phil Webb
              Reporter:
              Sam Brannen
              Last updater:
              Phil Webb
            • Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:
                Days since last comment:
                1 year, 6 weeks, 2 days ago