Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document @Bean 'lite' mode and annotated classes in the reference manual [SPR-9425] #14061

Closed
2 tasks
spring-projects-issues opened this issue May 18, 2012 · 3 comments
Assignees
Labels
in: core Issues in core modules (aop, beans, core, context, expression) type: documentation A documentation task
Milestone

Comments

@spring-projects-issues
Copy link
Collaborator

spring-projects-issues commented May 18, 2012

Sam Brannen opened SPR-9425 and commented

Overview

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

This issue picks up where #14037 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 #13690.


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>
 */

Affects: 3.1 GA

Issue Links:

Referenced from: commits 5730b8d, 5cd6543

0 votes, 5 watchers

@spring-projects-issues
Copy link
Collaborator Author

Juergen Hoeller commented

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

Juergen

@spring-projects-issues
Copy link
Collaborator Author

Neale Upstone commented

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..?

@spring-projects-issues
Copy link
Collaborator Author

Phil Webb commented

Assign to Chris to review #253 and rework/merge are required.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
in: core Issues in core modules (aop, beans, core, context, expression) type: documentation A documentation task
Projects
None yet
Development

No branches or pull requests

2 participants